EssentialsX Complete Configuration Guide: Commands, Kits, Warps, Economy and Moderation

EssentialsX is the most installed plugin on Paper servers. It provides over 100 commands covering teleportation, kits, warps, homes, economy, chat formatting and moderation. This guide walks through every major section of the configuration and explains the decisions you need to make for a production server.

Installation and modules

EssentialsX ships as multiple jars:

• EssentialsX — core, required. Contains commands, economy, homes, warps, kits.
• EssentialsXChat — chat formatting. Install if you want custom chat format with prefix/suffix from LuckPerms.
• EssentialsXSpawn — spawn command and first-join spawn location.
• EssentialsXAntiBuild — optional build protection that integrates with permission nodes.
• EssentialsXGeoIP — optional geographic lookup for players (requires license).

Drop all jars you want into plugins/ and restart. Each module creates its own subfolder.

config.yml — the main configuration file

Located at plugins/Essentials/config.yml. This single file controls nearly everything. Key sections:

Basic server settings

ops-name-color: '4'
nickname-prefix: '~'
max-nick-length: 15
change-displayname: true
change-tab-complete-name: true
add-prefix-suffix: true        # reads prefix/suffix from Vault/LuckPerms

newbies:
  announce-format: '&dWelcome {DISPLAYNAME} to the server!'
  kit: starter                 # give the 'starter' kit on first join
  spawnpoint: spawn            # teleport to warp named 'spawn' on first join

Economy settings

economy:
  start-amount: 500            # starting balance for new players
  currency-symbol: '$'
  currency-symbol-suffix: false
  minimum-pay-amount: 1.0
  max-money: 10000000000000    # 10 trillion cap
  command-costs:               # charge players for using commands
    /warp: 5
    /tpa: 0

Teleportation

teleport-delay: 3              # seconds players must stand still before /tpa completes
teleport-cooldown: 30          # seconds between /tpa uses per player
tpa-accept-cancels-others: true
teleport-back-when-die: true   # /back works after death

Home limits by group

# Uses permission essentials.sethome.multiple.<name>
# Or use the per-group-homes approach below:
sethome-multiple:
  default: 1
  vip: 3
  vip+: 5
  mvp: 10
  mvp+: 20
  staff: 50

Give the corresponding permission to LuckPerms groups: essentials.sethome.multiple.vip for the vip group, etc.

Creating kits

Kits are defined in plugins/Essentials/kits.yml. You can edit this file directly or use the in-game kit creation command:

/kit create starter 0

This creates a kit from the items currently in your inventory, with a cooldown of 0 seconds (one-time use). To add more items, edit kits.yml directly:

kits:
  starter:
    delay: 0
    items:
    - stone_sword 1 0 name:&aStarter_Sword lore:Good_luck!
    - cooked_beef 32
    - torch 64
    - wooden_pickaxe 1
    - leather_chestplate 1
  daily:
    delay: 86400          # 24 hours in seconds
    items:
    - cooked_beef 32
    - experience_bottle 5
    - emerald 3
  vip:
    delay: 86400
    items:
    - golden_apple 3
    - experience_bottle 16
    - iron_ingot 32
    - diamond 2

Permissions for kits follow the format essentials.kit.<kitname>. Assign them in LuckPerms:

/lp group default permission set essentials.kit.starter true
/lp group default permission set essentials.kit.daily true
/lp group vip permission set essentials.kit.vip true

Warps

Set a warp with /setwarp <name>. Warps are stored in plugins/Essentials/warps/ as individual YAML files. The /warp list shows all warps the player has permission to use.

Restrict warps to certain groups using LuckPerms permissions:

/lp group vip permission set essentials.warp.vipzone true
/lp group default permission set essentials.warp.vipzone false

Or leave all warps open and rely on WorldGuard to protect the destinations.

Chat formatting with EssentialsXChat

In plugins/Essentials/config.yml, find the chat section:

chat:
  format: '&8[&r{GROUP}&8] &r{DISPLAYNAME}&8: &f{MESSAGE}'
  group-formats:
    default: '&8[&7Default&8] &7{DISPLAYNAME}&8: &f{MESSAGE}'
    vip: '&8[&aVIP&8] &a{DISPLAYNAME}&8: &f{MESSAGE}'
    mvp: '&8[&6MVP&8] &6{DISPLAYNAME}&8: &f{MESSAGE}'
    admin: '&8[&cAdmin&8] &c{DISPLAYNAME}&8: &f{MESSAGE}'

Available tokens: {DISPLAYNAME}, {USERNAME}, {PREFIX}, {SUFFIX}, {GROUP}, {MESSAGE}, {WORLD}. The {PREFIX} and {SUFFIX} tokens read from Vault, which pulls from LuckPerms — this means the prefix you set with /lp group vip meta setprefix appears in chat automatically.

Mute, ban and kick — moderation commands

EssentialsX provides a complete moderation toolkit:

Muting players

/mute <player> [duration] [reason]
/mute BadPlayer 1h Spamming chat
/unmute BadPlayer

Muted players see their own messages but no one else does. Duration supports s (seconds), m (minutes), h (hours), d (days).

Banning players

/ban <player> [reason]
/ban <player> Hacking - fly exploit detected
/tempban <player> 7d Using xray mods
/unban <player>

IP banning

/banip <player or IP> [reason]
/unbanip <IP>

Kick

/kick <player> [reason]
/kickall [reason]

All moderation actions are logged in plugins/Essentials/userdata/ and can be viewed with /seen <player> which shows last login, playtime and if the player is banned/muted.

Social spy and mail

/socialspy         # toggle seeing all private messages
/mail send <player> <message>
/mail read
/mail clear

Social spy requires essentials.socialspy permission. It is on by default for admins but should be explicitly granted in LuckPerms so it persists across sessions.

Signs — shop and command signs

EssentialsX supports special sign types that run commands or teleport players. Enable them in config.yml:

enabledSigns:
  - color
  - warp
  - buy
  - sell
  - info
  - command
  - clearinventory
  - kit

Place a sign with [warp] on the first line (brackets included) and the warp name on the second line. Players right-click to teleport. Buy/sell signs require Vault and an economy plugin.

Signs — essentials economy interaction

Buy sign format (on four lines):

[Buy]
1
DIAMOND
100

Right-click charges the player $100 and gives one diamond. Sell signs work in reverse.

Useful config.yml miscellaneous settings

per-warp-permission: true      # require essentials.warps.<name> per warp
allow-silent-join: false
login-attackers-within: 5      # seconds after login before PvP is possible
protect:
  prevent:
    spawn:
      lightning: true
      ice: false
      soil: false

Common mistakes

• Not pairing EssentialsXSpawn with a spawn warp. If you install EssentialsXSpawn but do not set a spawn, players are dumped at 0,0 on first join.
• Using essentials.* wildcard in LuckPerms. This grants ban, mute, socialspy and all management commands to whoever has it. Grant permissions explicitly.
• Forgetting to reload after kit changes. Run /ess reload or restart after editing kits.yml. The file is not re-read at runtime automatically.
• Setting kit delay to 0 for paid kits. A zero delay means players can use the kit infinite times. For paid donor kits, set a 24 or 48 hour delay.

See these configs in action: Astroworld MC, IP play.astroworldmc.com, Java + Bedrock.