EssentialsX config.yml: the settings that matter

EssentialsX's config.yml is about 1,400 lines long, and on a typical survival server you need to change perhaps twenty of them. The ones that matter are the teleport cooldown and warm-up, the sethome-multiple home ranks, the economy block (starting-balance, currency-symbol, min-money, max-money), the chat format and group-formats, and the spawn keys that decide where a new player lands. Several sections do nothing unless the matching module jar is installed, and most changes apply with /essentials reload - but not all of them. This guide goes through the file in the order you will actually edit it, with the real defaults from the current 2.x config, and points out where the comments in the file are easy to misread.

Where config.yml lives, and the modules it configures#

After the first start, EssentialsX creates its folder beside every other plugin:

plugins/Essentials/  config.yml      the file this guide is about  kits.yml        kit contents, including the 'tools' first-join kit  worth.yml       sell prices for /sell and /worth  spawn.yml       spawn points set with /setspawn  userdata/       one YAML file per player: balance, homes, nickname  warps/          one file per warp

The core jar does the bulk of the work: homes, warps, teleports, kits, the economy, nicknames, AFK, mail. Everything else is a separate module jar, downloaded from the same place as the core and kept at exactly the same version. A mismatched module is a common cause of a stack trace at startup after an update.

The important thing about that table is the right-hand column. The chat: section is in the core config whether or not you have the Chat module, and editing it with no Chat jar installed does nothing at all - there is no warning, the setting is simply never read. If a change seems to be ignored, check the module is in plugins/ before you check anything else. Install only the modules you use; each one registers listeners on a server that runs its game logic on one thread. The broader question of what to install is in Minecraft plugins worth installing.

The file header lists the YAML rules worth knowing before your first edit: spaces only, never tabs; indentation is the structure; an apostrophe inside single-quoted text is written twice (don''t); text with symbols goes in quotes; and the file must be saved as UTF-8, not ANSI, if you use any accented letter or currency symbol other than $.

Teleports: cooldowns, warm-ups and safety#

Four keys control how teleporting feels, and they are the first thing players notice.

teleport-safety: trueteleport-cooldown: 0teleport-delay: 0teleport-invulnerability: 4tpa-accept-cancellation: 120

teleport-cooldown is the gap, in seconds, required between teleports. It is one shared timer across /home, /tp, /spawn, /warp and the rest, not a separate timer per command, so a 30-second cooldown means a player who just went home cannot also /spawn for 30 seconds. On a survival server a value between 10 and 60 stops teleport spam without feeling punitive.

teleport-delay is the warm-up: the player stands still for that many seconds before the teleport happens, and moving or being attacked cancels it. This is the setting that stops someone escaping a fight with /home, and on a PvP server it matters far more than the cooldown. Three to five seconds is the usual range; anything above ten and players stop using homes and start building nether highways, which may be what you want.

teleport-invulnerability gives a few seconds in which the player cannot be hurt by other players, or hurt them, after a command teleport. It is there so a /tpa into a fight is not an instant death, and so it cannot be used as an ambush.

teleport-safety decides what happens when the destination is unsafe - lava, a drop, inside a block. With true, Essentials moves the player to the nearest safe spot; with false, the teleport is cancelled with a warning. Leave it on. tpa-accept-cancellation is how long a /tpa request waits before it expires.

Three permissions bend these rules for staff:

Give them to groups, not individuals - the LuckPerms guide covers inheritance, so that a VIP group that skips the warm-up does not quietly pass the bypass on to a group you did not intend.

If you want different cooldowns for different commands, teleport-cooldown is the wrong tool. The newer command-cooldowns block sets one per command, works for commands from other plugins too, and by default survives a restart (command-cooldown-persistence: true):

command-cooldowns:  home: 30  spawn: 10  tpr: 600

Commands are written without the slash. Wildcards work, and a key that starts with ^ is treated as a regular expression.

Homes and the sethome-multiple limits#

The home limit is the setting most often configured wrongly, because it depends on two permissions rather than one.

sethome-multiple:  default: 3  vip: 5  staff: 10

The names under sethome-multiple are home ranks, and they do not need to match your permission groups. A player gets more than one home only if they have essentials.sethome.multiple; with that node alone they get the default number. To get a rank's number they need both essentials.sethome.multiple and essentials.sethome.multiple.vip. A player who has the rank node but not the base node stays on one home, which is the source of nearly every "I set VIP to 5 homes and they still have 1" thread. essentials.sethome.multiple.unlimited removes the limit entirely.

So a working setup for three tiers looks like this, in LuckPerms terms:

$ lp group default permission set essentials.sethome.multiple true$ lp group vip permission set essentials.sethome.multiple.vip true$ lp group staff permission set essentials.sethome.multiple.staff true

Lowering a limit later does not delete homes a player has already set; it only stops them setting more. If you are cutting the limit as part of a wipe or a rebalance, say so in advance.

The other home keys are small but worth a decision:

• spawn-if-no-home: true sends a player who types /home with no home set to spawn. Set it to false if /home should simply fail.
• confirm-home-overwrite: false - turn this on, because /sethome with an existing name replaces it without asking, and players do it by accident.
• world-home-permissions: false - set to true with essentials.worlds.<worldname> to stop people using /home to cross into a world they should not reach. On a server with a creative world beside survival, that is how inventories leak between them; running multiple worlds with Multiverse covers the wider problem.

Charging for homes belongs in command-costs, covered next.

The economy block#

The economy is part of the core jar. The design side - Vault, shop plugins, faucets and sinks, moving balances to a database - is covered in the EssentialsX and Vault economy guide. This section is just the keys and their defaults.

starting-balance: 0command-costs:  home: 50  sethome: 500  back: 100  kit-tools: 1500currency-symbol: '$'currency-symbol-suffix: falsemax-money: 10000000000000min-money: -10000economy-log-enabled: falseminimum-pay-amount: 0.001

starting-balance is paid once, when a player's userdata file is created on their first join. Changing it later does nothing for anyone who has already joined.

currency-symbol can be any character, provided the file is saved as UTF-8 - a pound or euro sign in a file saved as ANSI appears in game as a question mark or garbage. For symbols written after the number, set currency-symbol-suffix: true. Number formatting is separate: uncomment currency-format: "#,##0.00" to control decimals, and currency-symbol-format-locale (for example de-DE for 1.234,50) for which character separates thousands.

min-money defaults to -10000, and its comment explains what that means: a player can only go negative if they hold essentials.eco.loan. So by default nobody is in debt, but the floor is there for anyone you grant loans to. Setting it to 0 disables overdrafts completely, whatever the permissions say. max-money defaults to ten trillion; the file itself warns that extremely large numbers can have unintended consequences, and a ceiling a player could actually reach is a more useful number.

command-costs charges per use. The key is the command name, and kits use kit-<name>. The Chat module's shout and question modes can be charged as chat-shout and chat-question. Anyone with essentials.nocommandcost.<command> or essentials.nocommandcost.all pays nothing, and a wildcard such as essentials.* on a staff group includes those - so test prices with an ordinary account.

The rest of the block, briefly:

The file's own comment on economy-log-update-enabled says it fills the log quickly and is meant for testing; leave it off in normal running. After changing show-zero-baltop, run /baltop force, because the list is cached.

sell-multipliers lets a rank sell for more than the worth.yml price: default: 1.0, double: 2.0, and the permission essentials.sell.multiplier.<rank>. It is a faucet. A 2x multiplier on a farmable item doubles the rate at which money enters the server, so price it with that in mind.

Chat formatting with EssentialsX Chat#

None of this works without the Chat module. With it installed, the chat: section controls the format and range of every message.

chat:  radius: 0  format: '<{DISPLAYNAME}> {MESSAGE}'  group-formats:    default: '&7{DISPLAYNAME}&7:&r {MESSAGE}'    admin: '&c[{GROUP}]&r {DISPLAYNAME}&7:&f {MESSAGE}'  world-aliases:    world_nether: "&cN&r"

radius: 0 is global chat. Any other number makes chat local to that many blocks. Players with essentials.chat.shout can still reach everyone by starting a message with !, those with essentials.chat.question with ?, and essentials.chat.spy sees everything regardless of distance. Local chat changes a server's character more than any other single setting - quiet servers feel empty with it on, so turn it on only if there are enough people for nearby conversations to happen.

The placeholders you will actually use are {DISPLAYNAME}, {USERNAME}, {NICKNAME}, {PREFIX}, {SUFFIX}, {GROUP}, {WORLDNAME} and {WORLD} (the alias from world-aliases), plus {MESSAGE}.

Two traps catch nearly everyone:

• Double prefixes. {DISPLAYNAME} already includes the prefix and suffix from your permissions plugin. A format of {PREFIX} {DISPLAYNAME} prints the rank twice. Use {DISPLAYNAME} alone, or {PREFIX}{NICKNAME}{SUFFIX} if you want to place them yourself.
• Group names are case-sensitive. The key under group-formats must match the group name exactly - and if a LuckPerms group has a display name set, the display name is what Essentials sees. A format that never applies is almost always a capital letter or a display name.

Prefixes come from LuckPerms through Vault, so both need to be installed for {PREFIX} to show anything. Colour codes in the format string use &; whether players can use colours in their own messages is a separate set of permissions. paper-chat-events: true uses Paper's modern chat events and is the one chat setting that needs a full restart to change - switch it off only if another chat plugin conflicts.

If you bridge chat to Discord, the Discord side keeps its own format; DiscordSRV and Discord integration covers the alternative to the Essentials module.

Spawn, first join and respawning#

The Spawn module owns three moments: a player's first join, every join after that, and respawn after death.

newbies:  announce-format: '&dWelcome {DISPLAYNAME}&d to the server!'  spawnpoint: newbies  kit: toolsspawn-on-join: falserespawn-at-home: falserespawn-at-home-bed: truerespawn-at-anchor: falserespawn-listener-priority: highspawn-join-listener-priority: high

Set the spawns in game rather than in the file. Stand where everyone should appear and run /setspawn; stand at the new-player arrival point and run /setspawn newbies. That second name is what spawnpoint: newbies refers to. If you do not want a separate new-player spawn, set spawnpoint: none and new players use the world's spawn. /setspawn <group> works for any group name, which is how staff can arrive somewhere different from everyone else.

kit: tools hands out the tools kit from kits.yml on first join, regardless of cost, permissions or the kit's cooldown. Check that kit actually contains what you want; the default is a starter set, and a first-join kit is a small faucet in its own right. announce-format set to '' turns the welcome broadcast off.

spawn-on-join is the "spawn on join" setting people search for. true sends every player to spawn on every login; it also accepts a group name or a list of groups, so you can send only default players to spawn while ranked players log in where they left:

spawn-on-join:  - default  - guests

Anyone with essentials.spawn-on-join.exempt is left where they logged out. On a lobby or hub this should be true; on a survival server it is usually false, because being pulled back to spawn on every login is irritating once people have a base.

Respawning is decided by the respawn-at- keys. respawn-at-home: true sends a dead player to their first home, or to their bed if respawn-at-home-bed is also true. respawn-at-anchor controls whether respawn anchors in the Nether are honoured.

The two listener priorities are where Essentials meets other plugins that also move players around. If Multiverse or a lobby plugin should decide where players respawn, set respawn-listener-priority: lowest; none gives vanilla behaviour; highest forces Essentials to win. Both priorities only change on a full restart.

AntiBuild and GeoIP#

AntiBuild is the module that locks people out of their own server. Its main switches sit under protect: in the core config:

protect:  disable:    build: true    use: true    warn-on-build-disallow: true  alert:    on-placement: LAVA,TNT,LAVA_BUCKET    on-use: LAVA_BUCKET    on-break:  blacklist:    placement: LAVA,TNT,LAVA_BUCKET    usage: LAVA_BUCKET    break:    piston:    dispenser:

With the AntiBuild jar installed and build: true (the default), anyone without essentials.build cannot place or break blocks, and with use: true cannot use items either. That is correct for a server where new players must be accepted before they build, and a disaster if you dropped the jar in because it came in the same download. Either grant essentials.build to the default group, or set both build and use to false and keep AntiBuild only for its blacklists.

The blacklists take Bukkit material names, comma separated. placement and usage default to lava and TNT; break can protect something like BEDROCK, and piston and dispenser block those machines from moving or firing a material. essentials.protect.exemptplacement, exemptusage and exemptbreak let staff through. The alert lists send a message to anyone with essentials.protect.alerts when someone places or uses a listed material, which is a cheap early warning for lava griefing. For finer control there are per-material nodes such as essentials.build.place.<material>. AntiBuild is a blunt instrument; for real grief protection with claims and block logs, see grief protection and anti-cheat.

The Protect module shares the same protect: section, under prevent: and the damage switches in disable: (fall, pvp, drown, lavadmg and others). Turning off PvP for the whole server is protect.disable.pvp: true.

GeoIP has its own file, plugins/EssentialsGeoIP/config.yml:

database:  show-cities: false  download-if-missing: true  license-key: ""  update:    enable: true    by-every-x-days: 30show-on-login: trueshow-on-whois: true

It uses MaxMind's GeoLite2 database, which can no longer be downloaded anonymously. Create a free MaxMind account, generate a licence key, and paste it into license-key; without it the download fails and the module logs an error on every start. Once it works, staff with essentials.geoip.show see each player's country on login and in /whois, and essentials.geoip.hide keeps a player's location out of it.

Think before installing it. Showing staff where players connect from is personal data, it is rarely needed on a small server, and behind a proxy it reports the proxy's location for everyone unless player IPs are forwarded - the setup in Velocity proxy networks handles that.

Reloading, and when a restart is needed#

The file header says it plainly: after editing, run /essentials reload (or /ess reload). From the server console, the command has no slash - essentials reload - because the console is the server's input, not a chat box. This re-reads config.yml, kits, worth and the language files without touching the rest of the server.

Some changes do not apply on reload:

• respawn-listener-priority and spawn-join-listener-priority - their comments say restart.
• chat.paper-chat-events - restart.
• Adding, removing or updating any module jar - restart.
• show-zero-baltop - reload, then /baltop force.

What you should never use is the server-wide /reload, or a plugin manager that hot-loads jars. It reloads every plugin at once, Essentials included, and leaves listeners and tasks half-registered in ways that look like bugs in whichever plugin breaks first. Paper warns about it in the console for good reason. A restart takes seconds.

A reload that seems to do nothing usually means the YAML did not parse. Watch the console as you run it: a tab character, a missing space after a colon or an unescaped apostrophe produces an error naming the line, and Essentials will not have applied your edit. On RE:NODE the file manager's editor highlights YAML syntax, which catches most indentation mistakes before you save, and the console shows the reload output live. Take a backup from the panel before a large edit - it is one button to restore - and keep a copy of the working config.yml beside it. Backing up and restoring a Minecraft world covers what else belongs in that backup.

Troubleshooting#

A setting is ignored completely. Its module is not installed, or the YAML did not parse. The chat:, newbies: and protect: sections all depend on module jars.

Players have one home whatever the rank. They have the rank node, such as essentials.sethome.multiple.vip, without the base node essentials.sethome.multiple. They need both.

Ranks appear twice in chat. The format uses {PREFIX} and {DISPLAYNAME} together. Drop {PREFIX}.

A group format never applies. Capitalisation, or a LuckPerms display name. Run lp user <name> info and copy the group name exactly.

Nobody can build after an update. AntiBuild was installed with the other modules. Grant essentials.build to default or set protect.disable.build and use to false.

The currency symbol shows as a question mark. The file was saved as ANSI. Save it as UTF-8 and reload.

Teleports keep being cancelled. That is teleport-delay working: the player moved or was hit. Give staff essentials.teleport.timer.move if they need to keep moving.

New players do not arrive at the new-player spawn. /setspawn newbies was never run, or another plugin handles join location. Check spawn-join-listener-priority and restart after changing it.

FAQ#

Is EssentialsX economy enabled by default?

Yes. The economy is part of the core jar and works from the first start, with no module to install. Balances, /pay, /balance and /baltop work immediately; other plugins reach it through Vault.

Does /essentials reload apply every change?

Most of them. Listener priorities, paper-chat-events and any change to the installed module jars need a full restart. Everything in the economy, teleport, home and chat format sections applies on reload.

How do I stop players using /back after death?

Death locations are recorded for /back only for players with essentials.back.ondeath. Leave that node off the default group, or put a price on back in command-costs if you want it available but expensive.

Can I set a different spawn for each rank?

Yes. Stand at each point and run /setspawn <group> with the group name. Players are sent to the spawn of their group, falling back to the default spawn.

Do I need the GeoIP module?

Rarely. It shows staff each player's country, which helps with ban evasion on a large public server and is personal data you then hold. It also needs a MaxMind licence key to download its database.