📚 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

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
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
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:

json

{
  "chat": {
    "enabled": true,
    "ignoreChatCancellations": true,
    "syncWithGroupSystem": false,
    "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": false,
    "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>"
      }
    ]
  },
}

Group Synchronization

When not using LuckPerms, set syncWithLuckPerms: false and syncWithGroupSystem: false to manage all groups manually in config.json.

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:

json

{
  "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

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)
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
Automatic Chat Group Synchronization (syncWithGroupSystem):
- New in v1.16.0 - Automatically syncs chat groups with GroupSystem
- Enabled by default for new servers (syncWithGroupSystem: true)
- Disabled for updates to preserve existing chat configurations
- When enabled, chat groups are synced automatically:
  - New groups from GroupSystem are added with generated formats
  - Groups not in GroupSystem are removed
  - Existing chat formats are never modified - only new groups get defaults
- How to enable: Set syncWithGroupSystem: true in config.json and run /essentialsplus reload
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
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

Complete Synchronization Workflow

When both syncWithLuckPerms and syncWithGroupSystem are enabled:

LuckPerms → GroupSystem - Groups and priorities are synced from LuckPerms
GroupSystem → Chat Groups - Chat groups are automatically synced with GroupSystem
Result - Your entire group structure stays synchronized automatically!

This means you only need to manage groups in LuckPerms, and everything else updates automatically when you run /essentialsplus reload.

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. With syncWithGroupSystem: true (default for new servers), chat groups are automatically synced with GroupSystem. After creating groups in LuckPerms, run /essentialsplus reload to sync everything. The prefix, suffix, and tag fields can be customized freely.

Set up chat formats matching your LuckPerms groups:

json

{
  "chat": {
    "enabled": true,
    "ignoreChatCancellations": true,
    "syncWithGroupSystem": 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:

bash

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

4. Set Group Weights (Priority):

Higher weight = higher priority

bash

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

5. Assign permissions

bash

/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:

bash

/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:

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

Wrong format showing:

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

Format not updating after LuckPerms changes:

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

Groups not syncing from LuckPerms:

Verify syncWithLuckPerms: true in groupSystem section
Run /essentialsplus reload after creating/modifying LuckPerms groups
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

⚙️ Configuration

🎓 Tutorials

📚 Tutorials

Chat Formatting Tutorial

Without Permission Plugins

How It Works

Step-by-Step Configuration

Chat Format Placeholders

Example Results

Priority System Example

With LuckPerms

How It Works

Step-by-Step Configuration

Group Name Matching

Troubleshooting

LuckPerms Documentation

Additional Resources

📚 Tutorials ​

Chat Formatting Tutorial ​

Without Permission Plugins ​

How It Works ​

Step-by-Step Configuration ​

Chat Format Placeholders ​

Example Results ​

Priority System Example ​

With LuckPerms ​

How It Works ​

Step-by-Step Configuration ​

Group Name Matching ​

Troubleshooting ​

LuckPerms Documentation ​

Additional Resources ​

📚 Tutorials

Chat Formatting Tutorial

Without Permission Plugins

How It Works

Step-by-Step Configuration

Chat Format Placeholders

Example Results

Priority System Example

With LuckPerms

How It Works

Step-by-Step Configuration

Group Name Matching

Troubleshooting

LuckPerms Documentation

Additional Resources