📚 Tutorials

This page provides step-by-step tutorials for common configuration tasks in EssentialsPlus.

Chat Formatting Tutorial

EssentialsPlus offers multiple ways to configure chat formatting:

• Without Permission Plugins - Use Hytale's native permissions.json for simple setups
• With Permission Plugins - Advanced permission management with native integration (recommended for larger servers)

Permission plugins like LuckPerms provide more features and flexibility. While other permission plugins exist, EssentialsPlus has native integration specifically with LuckPerms.

---

Without Permission Plugins

Configure chat formats using only EssentialsPlus built-in features.

How It Works

1. Default Groups:

   • OPs are automatically assigned to the OP group
   • Non-OP players are assigned to the Adventure group by default
   • Players without any specific group fall into the Default group

2. Configuration Files:

   • mods/fof1092_EssentialsPlus/config.json - Contains chat format definitions in chat.groups
   • permissions.json - (Located in the main server directory) Defines player permissions

3. Group Priority:

   • When a player has multiple groups, groupPriorities determines which format is displayed
   • Higher priority value = higher precedence

Step-by-Step Configuration

CRITICAL: Group Configuration

Every group defined in chat.groups MUST also exist in groupSystem.groups!

If a group is missing from groupSystem.groups, players in that group will display the default chat format instead of their custom format. Always ensure both sections are synchronized.

1. Edit config.json:

{
  "chat": {
    "enabled": true,
    "groups": {
      "op": "<#FF5555><bold>[<#FFFFFF>OP</#FFFFFF>] {player}: </bold></#FF5555><#AAAAAA>{message}</#AAAAAA>",
      "adventure": "<#00AA00><bold>[<#FFFFFF>Player</#FFFFFF>] {player}: </bold></#00AA00><#AAAAAA>{message}</#AAAAAA>",
      "default": "<#00AA00><bold>[<#FFFFFF>Default</#FFFFFF>] {player}: </bold></#00AA00><#AAAAAA>{message}</#AAAAAA>",
    }
  },
  "groupSystem": {
    "syncWithLuckPerms": true,
    "fallbackGroup": "default",
    "groups": [
      {
        "name": "op",
        "priority": 100,
        "prefix": "<#FF5555>",
        "suffix": "</#FF5555>",
        "tag": "<#FF5555><bold>[<#FFFFFF>OP</#FFFFFF>]</bold></#FF5555>"
      },
      {
        "name": "adventure",
        "priority": 10,
        "prefix": "<#00AA00>",
        "suffix": "</#00AA00>",
        "tag": "<#00AA00><bold>[<#FFFFFF>Player</#FFFFFF>]</bold></#00AA00>"
      },
      {
        "name": "default",
        "priority": 0,
        "prefix": "<#00AA00>",
        "suffix": "</#00AA00>",
        "tag": "<#00AA00><bold>[<#FFFFFF>Default</#FFFFFF>]</bold></#00AA00>"
      }
    ]
  },
}

2. Configure permissions.json (in main server directory):

DANGER

The permissions.json file can only be edited when the server is stopped. Changes made while the server is running will be overwritten!

Add custom groups to players:

{
  "users": {
    "79f4de26-a0a0-42ce-903e-581716430dcd": {
      "groups": [
        "VIP",
        "Adventure"
      ]
    },
    "c3f13aae-432d-4627-9892-e8901144c63b": {
      "groups": [
        "OP",
        "Adventure"
      ]
    }
  },
  "groups": {
    "Default": [],
    "OP": [
      "*"
    ],
    "Adventure": [
      "essentialsplus.home.self",
      "essentialsplus.sethome",
      "essentialsplus.spawn.self",
      "essentialsplus.warp",
      "essentialsplus.tpa"
    ],
    "VIP": [
      "essentialsplus.fly.self",
      "essentialsplus.rtp",
      "essentialsplus.sethome.limit.10"
    ]
  }
}

3. Restart the server

Chat Format Placeholders

Required Placeholders:

• {player} - Player's username
• {message} - The actual chat message
• {group} - The Player's Group

Commonly Used Placeholders:

• {world} - Current world name
• {x}, {y}, {z} - Player's coordinates
• {uuid} - Player's UUID
• {time} - Current time (HH:mm:ss)
• {date} - Current date (yyyy-MM-dd)
• {online} - Number of online players

For the complete placeholder reference:

See the Placeholder Tutorial for:

• All built-in placeholders ({player}, {world}, {x}, etc.) - Work without additional mods
• All PlaceholderAPI placeholders (requires PlaceholderAPI-Hytale mod):
  • Economy data (%essentialsplus_player_balance_formatted%)
  • Player statistics (%essentialsplus_player_playtime%, %essentialsplus_player_session_time%)
  • AFK status (%essentialsplus_player_afk_tag%, %essentialsplus_player_afk_time%)
  • Home system (%essentialsplus_player_homes_count%, %essentialsplus_player_homes_max%)
  • Server statistics (%essentialsplus_server_homes_total%, %essentialsplus_server_warps_total%)
  • And many more...

The tutorial includes detailed explanations, usage examples, and the differences between both placeholder types.

Example Results

• OP Player: [Admin] F_o_F_1092: Hello everyone!
• VIP Player: [VIP] Alex: Hi there!
• Other Player: [Default] Tim: Hey!

Priority System Example

If a player has both VIP (priority 50) and Adventure (priority 1) groups:

• The VIP format will be used because it has higher priority (50 > 1)

---

With LuckPerms

LuckPerms integration provides advanced permission management with powerful group systems.

How It Works

1. Primary Group Detection:

   • EssentialsPlus automatically reads the player's primary group from LuckPerms
   • The primary group name is used to match a format in chat.groups (config.json)

2. Automatic Group Synchronization (syncWithLuckPerms):

   • Enabled by default (syncWithLuckPerms: true)
   • Automatically syncs group names and priorities from LuckPerms to groupSystem.groups
   • When you create/modify groups in LuckPerms, run /essentialsplus reload to sync them
   • Manual customization: prefix, suffix, and tag fields can be freely customized and won't be overwritten
   • Disable sync: Set syncWithLuckPerms: false to manage groups manually in config.json

3. Priority Handling:

   • LuckPerms manages group priorities internally via weight system
   • EssentialsPlus respects LuckPerms' group weight system
   • Priority values in groupSystem.groups are synced from LuckPerms weights

4. Dynamic Updates:

   • Chat format updates immediately when group changes in LuckPerms
   • After modifying LuckPerms groups, run /essentialsplus reload to sync changes
   • No server restart required

Step-by-Step Configuration

1. Install LuckPerms:

Download and install LuckPerms for your Hytale server.

2. Configure config.json:

CRITICAL: Group Configuration

Every group defined in chat.groups MUST also exist in groupSystem.groups!

If a group is missing from groupSystem.groups, players in that group will display the default chat format instead of their custom format. Always ensure both sections are synchronized.

Automatic Synchronization

With syncWithLuckPerms: true (default), group names and priorities are automatically synced from LuckPerms. After creating groups in LuckPerms, run /essentialsplus reload to sync them. The prefix, suffix, and tag fields can be customized freely.

Set up chat formats matching your LuckPerms groups:

{
  "chat": {
    "enabled": true,
    "ignoreChatCancellations": true,
    "groups": {
      "admin": "<#FF5555><bold>[<#FFFFFF>Admin</#FFFFFF>] {player}: </bold></#FF5555><#AAAAAA>{message}</#AAAAAA>",
      "moderator": "<#5555FF><bold>[<#FFFFFF>Moderator</#FFFFFF>] {player}: </bold></#5555FF><#AAAAAA>{message}</#AAAAAA>",
      "vip": "<#e89d1f><bold>[<#FFFFFF>VIP</#FFFFFF>] <gradient:#e89d1f:#e4e95d:#e89d1f>{player}</gradient>: </bold></#e89d1f><#AAAAAA>{message}</#AAAAAA>",
      "default": "<#00AA00><bold>[<#FFFFFF>Default</#FFFFFF>] {player}: </bold></#00AA00><#AAAAAA>{message}</#AAAAAA>"
    }
  },
  "groupSystem": {
    "syncWithLuckPerms": true,
    "fallbackGroup": "default",
    "groups": [
      {
        "name": "admin",
        "priority": 90,
        "prefix": "<#FF5555>",
        "suffix": "</#FF5555>",
        "tag": "<#FF5555><bold>[<#FFFFFF>Admin</#FFFFFF>]</bold></#FF5555>"
      },
      {
        "name": "moderator",
        "priority": 80,
        "prefix": "<#5555FF>",
        "suffix": "</#5555FF>",
        "tag": "<#5555FF><bold>[<#FFFFFF>Moderator</#FFFFFF>]</bold></#5555FF>"
      },
      {
        "name": "vip",
        "priority": 50,
        "prefix": "<#e89d1f>",
        "suffix": "</#e89d1f>",
        "tag": "<#e89d1f><bold>[<#FFFFFF>VIP</#FFFFFF>]</bold></#e89d1f>"
      },
      {
        "name": "default",
        "priority": 0,
        "prefix": "<#00AA00>",
        "suffix": "</#00AA00>",
        "tag": "<#00AA00><bold>[<#FFFFFF>Default</#FFFFFF>]</bold></#00AA00>"
      }
    ]
  }
}

3. Create Groups in LuckPerms:

/lp creategroup admin
/lp creategroup moderator
/lp creategroup vip
/lp creategroup default

4. Set Group Weights (Priority):

Higher weight = higher priority

/lp group admin setweight 100
/lp group moderator setweight 80
/lp group vip setweight 50
/lp group default setweight 0

5. Assign permissions

/lp group admin permission set *
/lp group moderator permission set essentialsplus.moderate.*
/lp group vip permission set essentialsplus.clearinventory
/lp group default permission set essentialsplus.warp

/lp group moderator parent set vip
/lp group vip parent set default

6. Assign Players to Groups:

/lp user <player> parent set <group>
/lp user Steve parent set admin
/lp user Alex parent set vip

Group Name Matching

Important: Group names in config.json must exactly match LuckPerms group names (case-insensitive).

Example:

• LuckPerms group: vip → Config key: "vip": "..."
• LuckPerms group: Admin → Config key: "admin": "..." or "Admin": "..."

Troubleshooting

Chat format not displaying:

1. Check group synchronization: Ensure the group exists in BOTH chat.groups AND groupSystem.groups
2. Run /essentialsplus reload after modifying LuckPerms groups (if syncWithLuckPerms: true)
3. Check group name spelling in both LuckPerms and config.json (case-insensitive)
4. Verify player's primary group: /lp user <player> info

Wrong format showing:

1. Check group weights in LuckPerms: /lp group <group> info
2. Verify priorities in groupSystem.groups match LuckPerms weights
3. Make sure primary group is set correctly in LuckPerms
4. Run /essentialsplus reload to sync latest changes

Format not updating after LuckPerms changes:

1. Run /essentialsplus reload to sync group changes from LuckPerms
2. Check LuckPerms sync: /lp sync
3. If syncWithLuckPerms: false, manually update groupSystem.groups in config.json

Groups not syncing from LuckPerms:

1. Verify syncWithLuckPerms: true in groupSystem section
2. Run /essentialsplus reload after creating/modifying LuckPerms groups
3. Check server console for sync errors

LuckPerms Documentation

For comprehensive LuckPerms documentation, visit:

• Official Wiki: https://luckperms.net/wiki
• Commands Reference: https://luckperms.net/wiki/Command-Usage
• Permission Reference: https://luckperms.net/wiki/Permissions

Additional Resources

• Configuration Guide - Complete configuration reference
• Commands Reference - All available commands
• Permissions Guide - Permission nodes and setup
• Known Issues - Known limitations and workarounds