EssentialsX kits, warps, homes and spawn: full setup

EssentialsX kits live in plugins/Essentials/kits.yml, each with an item list and a delay in seconds, and a player may only claim a kit if they hold essentials.kits.<name>. Warps are made with /setwarp and become individually lockable once per-warp-permission is switched on. Home limits come from the sethome-multiple table in config.yml, matched against essentials.sethome.multiple.<tier> nodes. /spawn is not in the main jar at all - it needs the separate EssentialsX Spawn module. Those four facts explain nearly every "the kit does not work" message on a fresh Paper server, and the rest of this guide is the detail behind them.

Balances, /pay, worth.yml and shops are covered in the EssentialsX and Vault economy guide. This post is about the movement and starter-gear half of the plugin, which is where most survival servers actually spend their configuration time.

Where EssentialsX keeps kits, warps, homes and spawns#

EssentialsX is several jars. The main EssentialsX jar contains kits, warps, homes, teleport requests and the economy. EssentialsXSpawn is a separate download that adds /spawn, /setspawn, first-join handling and respawn rules. Install the main jar and only the modules you actually use - each one adds event listeners to a server whose main thread is shared by everything.

Each feature stores its data in a different place, and knowing which file holds what saves a lot of guessing when something goes missing:

plugins/Essentials/  config.yml        settings for everything, including sethome-multiple  kits.yml          kit definitions and delays  spawn.yml         spawn points, written by /setspawn (Spawn module)  warps/    mine.yml        one file per warp    shop.yml  userdata/    <uuid>.yml      each player's homes and kit cooldown timestamps

Three consequences follow. Homes belong to the player file, so deleting a player's userdata file wipes their homes and kit cooldowns along with their balance. Warps are one small file each, so you can copy a warp from a test server by copying its file. And kits are definitions only - who has claimed what, and when, is recorded per player, not in kits.yml.

Older EssentialsX versions kept kits under a kits: section inside config.yml. Current builds read kits.yml and move an old section across when they upgrade. If you are following an old tutorial that tells you to edit kits in config.yml, that is why nothing changes.

Writing kits in kits.yml#

A kit is a name, a delay and a list of items. The default file ships with one kit called tools, which is a good template:

kits:  tools:    delay: 10    items:      - stone_pickaxe 1      - stone_shovel 1      - stone_axe 1  starter:    delay: -1    items:      - iron_sword 1 sharpness:2 name:&bStarter_Sword lore:Given_on_day_one      - bread 16      - torch 32      - leather_chestplate 1 color:139,69,19      - $250      - /broadcast {player} has started their journey

Each item line is the same item syntax /give uses in EssentialsX: the material name, the amount, then optional metadata.

• Enchantments are enchantment:level pairs such as sharpness:2 or efficiency:4. Use the modern enchantment names on current versions.
• `name:` sets the display name. Spaces are written as underscores, and & colour codes work.
• `lore:` sets lore lines. Underscores become spaces and a | starts a new line.
• `color:` takes an RGB triple for leather armour.
• A line starting with `$` gives money through the economy, so $250 pays the player 250 on claim. That needs a working economy, which the main jar provides.
• A line starting with `/` runs as a console command when the kit is claimed. {player} is replaced with the player's name. This is how you give items from other plugins, grant a permission, or announce something.

Material names must match the server version. A kit written for 1.20 that names an item renamed or added later will fail to load that line, and the console says so on startup or on claim. The kit itself still loads, minus the broken line, which is why players sometimes report "the kit is missing the sword" rather than "the kit is broken".

Edits to kits.yml take effect after /essentials reload or a restart. Reload is fine for kits; it is not a general-purpose tool for other plugins.

Making kits in game with /createkit

Writing NBT-heavy items by hand is tedious, so EssentialsX can capture your inventory instead. Fill your inventory with exactly what the kit should contain, then run:

/createkit starter -1/createkit daily 86400

The first argument is the kit name, the second the delay in seconds. The command needs essentials.createkit. With pastebin-createkit: false in config.yml (the default on current builds) the kit is written straight into kits.yml; with it set to true, the plugin uploads the kit to a paste service and gives you a link to copy from, which is what older guides describe.

/createkit keeps enchantments, names, lore and most item data. Recent builds on Paper can also store kit items in a serialised form that preserves everything an item carries, including data from other plugins; whether yours does depends on the EssentialsX version and an option in config.yml, so check your own file rather than relying on a tutorial. Either way, open kits.yml after creating a kit and read what was written. It is the only way to be certain a custom item survived the trip.

The other kit commands:

Kit delays, one-time kits and costs#

delay is measured in seconds from the moment of the last claim. A few values come up constantly:

The cooldown is stored in the player's userdata file under timestamps, keyed by kit name. That has two practical effects. Renaming a kit resets every player's cooldown on it, because the old timestamp no longer matches anything. And a one-time kit is only one-time while the player file exists; wiping userdata hands every starter kit out again.

Players with essentials.kit.exemptdelay ignore the delay entirely. Give that to staff testing kits, never to a donor rank by accident through inheritance - an unlimited daily kit is an item duplicator with a permission node on it.

To charge for a kit, use command-costs in config.yml. The key is kit- followed by the kit name:

command-costs:  kit-tools: 0  kit-daily: 500  warp: 10  home: 25

The cost is taken through the economy on each use, and a player who cannot afford it is refused. Charging a little for a repeatable kit is a quiet way to stop it becoming a farm, and the same section prices teleports, which comes up again below.

Kit permissions and the first-join kit#

Kit access is two nodes, and most broken setups have only one of them:

• essentials.kit allows the /kit command itself.
• essentials.kits.<name> allows that particular kit. essentials.kits.* allows all of them.

A player with essentials.kit but no kit nodes sees an empty list. A player with essentials.kits.starter but no essentials.kit cannot run the command. In LuckPerms, a sensible split looks like this:

/lp group default permission set essentials.kit true/lp group default permission set essentials.kits.starter true/lp group default permission set essentials.kits.tools true/lp group vip permission set essentials.kits.vip true/lp group admin permission set essentials.kit.exemptdelay true

If vip inherits from default, VIPs get the starter and tools kits as well, which is usually what you want. The LuckPerms guide explains inheritance and why setting nodes on groups rather than individual players keeps this auditable.

To hand a kit out automatically on a player's first join, use the newbies section of config.yml. It belongs to EssentialsX Spawn, so it does nothing unless that module is installed:

newbies:  announce-format: '&dWelcome {DISPLAYNAME}&d to the server!'  spawnpoint: newbies  kit: starter

kit names the kit given on first join, regardless of the player's kit permissions. Set it to an empty string to give nothing. spawnpoint names a spawn set with /setspawn newbies, so new players can arrive at a tutorial area while everyone else respawns at the main spawn. If you give the starter kit this way, make the same kit delay: -1 and leave its permission off the default group, or new players will claim it a second time from /kit.

Warps: /setwarp and per-warp permissions#

A warp is a named location anyone with permission can teleport to. Stand where the warp should land, facing the way players should face on arrival, and run /setwarp <name>. The position, including pitch and yaw, is saved to warps/<name>.yml.

By default, anyone with essentials.warp can use every warp. That is fine for a server with a shop, a mine and an end portal, and wrong the moment you have a staff area or a donor island. Switch per-warp access on in config.yml:

per-warp-permission: true

From then on each warp needs its own node, essentials.warps.<name>, and essentials.warps.* grants all of them. The warp list only shows warps the player can use, which is the main reason to turn this on even if every warp is public: you can add a hidden staffroom without it appearing in everyone's list.

/lp group default permission set essentials.warps.spawn true/lp group default permission set essentials.warps.shop true/lp group default permission set essentials.warps.mine true/lp group vip permission set essentials.warps.vipisland true/lp group mod permission set essentials.warps.* true

/setwarp on an existing name silently moves the warp. Keep essentials.setwarp with the people who build the server, and keep essentials.delwarp narrower still. A warp pointed at a world that is no longer loaded - common after removing a Multiverse world - fails with an error about the world rather than the warp, which is a clue worth knowing; running multiple worlds with Multiverse covers loading and unloading worlds cleanly.

Homes and the sethome-multiple limits#

/sethome saves a named location to the player's own file, and /home returns to it. With one home the name is optional and defaults to home. With several, players name them: /sethome base, /sethome farm, /home farm. Running /home with several homes and no name lists them.

The limit is controlled by this table in config.yml, shown here with its shipped values:

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

The keys are arbitrary names, not group names. Each one maps to a permission node:

• essentials.sethome.multiple - required before a player can have more than one home at all.
• essentials.sethome.multiple.<key> - grants that tier's number, so essentials.sethome.multiple.vip allows 5.
• essentials.sethome.multiple.unlimited - no limit.

A player with several tier nodes gets the highest number among them, so inheritance does not cause a VIP to fall back to 3. A player without essentials.sethome.multiple gets one home, whatever the table says. That single missing node is behind most "my rank should have five homes" tickets. Add your own tiers freely - legend: 15 together with essentials.sethome.multiple.legend on the right group is all it takes.

/lp group default permission set essentials.sethome true/lp group default permission set essentials.home true/lp group default permission set essentials.delhome true/lp group default permission set essentials.sethome.multiple true/lp group vip permission set essentials.sethome.multiple.vip true/lp group mod permission set essentials.home.others true

essentials.home.others lets staff visit a player's home with /home <player>:<homename>, which is useful for investigating grief reports and unnecessary for anyone else.

A few related settings in the same file are worth deciding on deliberately:

• spawn-if-no-home - when true, /home with no homes set sends the player to spawn rather than erroring.
• update-bed-at-daytime - lets players set their bed spawn by clicking a bed during the day, so /home bed points somewhere sensible.
• world-home-permissions - when true, a home in a world requires permission for that world. Useful for keeping homes out of a resource world you reset.

Homes are a convenience that changes how a survival server plays. Unlimited free homes turn the world into a set of teleport destinations, and nobody builds roads. The usual compromise is a low count for new players, a few more for ranks, and a small home cost in command-costs.

/spawn with EssentialsX Spawn#

Without the Spawn module there is no /spawn command from EssentialsX. Download EssentialsXSpawn at the same version as the main jar - mismatched versions are a common cause of startup errors - and put both in plugins/.

Then stand at your spawn and run /setspawn. That writes the location to spawn.yml. /setspawn <group> sets a separate spawn for one permission group, so a VIP group can arrive at its own hub, and /setspawn newbies creates the first-join point the newbies section refers to.

The module also takes over where players arrive after death and on join. The settings that matter:

respawn-at-home: falsespawn-on-join: falserespawn-listener-priority: highspawn-join-listener-priority: high

What each one decides:

• respawn-at-home sends dead players to their home instead of spawn. Most survival servers leave it off and let the bed decide.
• spawn-on-join sends players to spawn every time they log in. It accepts true, false, or a group name or list of groups, so you can send only default players to spawn while ranks log in where they left. Staff with essentials.spawn-on-join.exempt are skipped.
• The two listener priorities decide who wins when another plugin also wants to move players on respawn or join. If a lobby plugin or Multiverse keeps overriding your spawn, this is the dial.

That last point catches many servers: players cannot break blocks somewhere that looks like open countryside, because the invisible 16-block protection square sits around the original world spawn, not the one EssentialsX uses. server.properties explained covers spawn-protection and why it only ever applies to non-operators.

Teleport delays, cooldowns and safety#

Every EssentialsX teleport - /home, /warp, /spawn, /tpa, /back - runs through the same settings, so tune them once:

teleport-cooldown: 0teleport-delay: 0teleport-invulnerability: 4teleport-safety: true

A short teleport-delay, three to five seconds, is the single most effective setting against combat logging by teleport: the player has to stand still while being hit, and moving cancels it. Staff can bypass it with essentials.teleport.timer.bypass, and the cooldown with essentials.teleport.cooldown.bypass. Leave teleport-safety on; it stops a home set over lava, or a warp whose floor somebody mined out, from killing whoever uses it.

Combined with command-costs, these settings decide how much the world map matters on your server. Free, instant, unlimited teleports make distance meaningless. A few seconds of delay and a small fee keep most of the convenience while making a long walk occasionally the better option.

Backing up homes, warps and kits#

Everything in this guide is small YAML under plugins/Essentials/, and none of it is part of the world folder. A world backup alone restores the terrain and loses every home, warp and kit cooldown since the plugin data was last saved; a plugin backup alone does the reverse. Back up the two together. Minecraft world backup and restore covers what to include and how to roll back safely.

On RE:NODE, Minecraft servers run Paper with the matching Java version, and EssentialsX jars go in through the file manager or SFTP like any other plugin. The file manager has a syntax-highlighting editor for kits.yml and config.yml, which helps with YAML indentation, and backup slots on every game plan cover the whole server directory, plugin data included. Take one before switching on per-warp-permission or editing sethome-multiple on a live server.

Troubleshooting#

"You do not have permission to use that kit." The player has essentials.kit but not essentials.kits.<name>. Check the exact kit name in the node; it is the key in kits.yml, lowercase.

The kit list is empty. Same cause from the other side: no essentials.kits.* nodes at all, or the kits failed to load. Look for a YAML error on startup; a tab character or a missing space after a colon stops the whole file loading.

Edits to kits in `config.yml` do nothing. Kits moved to kits.yml. Edit that file and run /essentials reload.

A kit item is missing on claim. One item line uses a material name the server version does not know. The console names the line.

Players are stuck at one home. They lack essentials.sethome.multiple. The tier node alone is not enough.

`/spawn` is an unknown command. EssentialsX Spawn is not installed, or failed to load because its version does not match the main jar.

Players respawn at the wrong place. Another plugin is handling respawn at a higher priority, or respawn-at-home is on. Check Multiverse and any lobby plugin, then adjust respawn-listener-priority.

A warp says the world does not exist. The world it points at was renamed or unloaded. Recreate the warp in a loaded world.

FAQ#

How do I make a kit that can only be claimed once?

Set delay: -1 on it, or create it with /createkit <name> -1. The claim is recorded in the player's userdata file, so it stays one-time unless that file is deleted or the kit is renamed.

Can I give a kit automatically to new players?

Yes, with EssentialsX Spawn installed: set kit: in the newbies section of config.yml to the kit name. It is given on first join whatever the player's kit permissions are.

How do I give a rank more homes?

Add a line to sethome-multiple, for example vip: 5, then give that rank both essentials.sethome.multiple and essentials.sethome.multiple.vip. The player gets the highest tier they hold.

Can I hide some warps from the warp list?

Turn on per-warp-permission. Players then see and use only the warps they hold essentials.warps.<name> for, so a staff warp without a public node is invisible to everyone else.

Do I need EssentialsX Spawn if I use another spawn plugin?

No, and running two plugins that both handle join and respawn locations invites conflicts. Pick one. If you keep EssentialsX Spawn, adjust its listener priorities rather than fighting the other plugin.

Why can players not break blocks near spawn even though it is not protected?

Vanilla spawn-protection is centred on the world spawn, not the EssentialsX spawn. Move the world spawn with /setworldspawn or set spawn-protection=0.