How to Install and Configure EssentialsX
Install EssentialsX on your Paper Minecraft server: homes, warps, teleportation, kits, economy and chat, with the right LuckPerms permissions.
On this page
EssentialsX adds the commands players expect to your server: /home, /spawn, /tpa, /warp, /msg, plus kits and an economy. This guide explains how to install it on Paper, grant the right permissions and adjust the most useful options.
Prerequisites
- A Paper server, with the
mc-consolecommand set up in the Install and Update Plugins on Paper guide - LuckPerms installed, with the groups from the Manage Ranks and Permissions with LuckPerms guide
In this guide, Steve is an example: replace it with a real username.
Choose the Right Version
The version to install depends on your Minecraft version. Check it with sudo mc-console version.
| Minecraft | EssentialsX to install |
|---|---|
| 26.2 or 26.3 | 2.22.1 development build |
| 26.1.2 or 1.21.11 | 2.22.0 stable release |
Choose the Modules
EssentialsX is split into several files, and only the first one is required.
| Module | Role | In this guide |
|---|---|---|
| EssentialsX | Core commands, kits, economy | Required |
| EssentialsX Spawn | Spawn point, /spawn, /setspawn |
Installed |
| EssentialsX Chat | Chat format, prefixes and suffixes | Installed |
| EssentialsX AntiBuild | Allow or deny building through permissions | Optional |
| EssentialsX Protect | World settings: creeper damage, fire spread | Optional |
| EssentialsX GeoIP | Approximate player location | Optional |
| EssentialsX Discord and Discord Link | Discord bridge and linking | Optional |
| EssentialsX XMPP | XMPP bridge, legacy module | Optional |
Install Vault and EssentialsX
Vault allows EssentialsX to read LuckPerms groups and prefixes. Without it, prefixes and group-related features do not work.
Download Vault, then the three modules from the development build, suited to Minecraft 26.3:
sudo -u minecraft bash
cd /opt/minecraft/server/plugins
curl -fL -o Vault.jar https://github.com/MilkBowl/Vault/releases/latest/download/Vault.jar
BASE="https://ci.ender.zone/job/EssentialsX/lastSuccessfulBuild"
for MODULE in EssentialsX EssentialsXSpawn EssentialsXChat; do
FICHIER=$(curl -fsSL "$BASE/api/json?tree=artifacts%5BfileName%5D" | jq -r --arg m "$MODULE" '.artifacts[].fileName | select(startswith($m + "-"))')
curl -fL -o "$FICHIER" "$BASE/artifact/jars/$FICHIER"
done
ls -l Vault.jar EssentialsX*.jar
exitFor Minecraft 26.1.2 or 1.21.11, use the stable release instead, in place of the loop above:
BASE="https://github.com/EssentialsX/Essentials/releases/download/2.22.0"
for MODULE in EssentialsX EssentialsXSpawn EssentialsXChat; do
curl -fLO "$BASE/$MODULE-2.22.0.jar"
doneRestart the server and wait for the Done line:
sudo systemctl restart minecraft.service
sudo journalctl -u minecraft.service -fVerify the Installation
Exit the log view with Ctrl+C, then run:
sudo mc-console plugins
sudo mc-console vault-info
sudo mc-console 'essentials version'You should find:
Essentials,EssentialsChat,EssentialsSpawn,LuckPermsandVaultin the plugin listPermission: LuckPermsandChat: LuckPermsin thevault-inforesponseEconomy: Essentials Economyin that same response- the same version for all modules in
essentials version
The configuration files are located in /opt/minecraft/server/plugins/Essentials.
Grant Permissions to Players
Operators have access to everything. Other players have no access to any EssentialsX command until you grant them the corresponding permission.
Give the common commands to all players:
for PERM in spawn home sethome delhome tpa tpaccept tpdeny back warp warp.list msg afk list motd rules help balance pay kit kits.tools; do
sudo mc-console "lp group default permission set essentials.$PERM true"
doneThen complete the higher ranks:
for PERM in sethome.multiple sethome.multiple.vip fly; do
sudo mc-console "lp group vip permission set essentials.$PERM true"
done
for PERM in tp tphere kick mute tempban; do
sudo mc-console "lp group moderator permission set essentials.$PERM true"
done
for PERM in setspawn setwarp delwarp eco createkit; do
sudo mc-console "lp group admin permission set essentials.$PERM true"
done| Command | Effect | Permission |
|---|---|---|
/spawn |
Return to the spawn point | essentials.spawn |
/sethome [name] and /home [name] |
Create a home and go to it | essentials.sethome, essentials.home |
/delhome <name> |
Delete a home | essentials.delhome |
/tpa <player> |
Request to teleport to a player | essentials.tpa |
/tpaccept and /tpdeny |
Accept or decline a request | essentials.tpaccept, essentials.tpdeny |
/back |
Return to the previous position | essentials.back |
/warp [name] |
List warps or go to one | essentials.warp, essentials.warp.list |
/msg <player> <message> and /r <message> |
Private message and reply | essentials.msg |
/balance and /pay <player> <amount> |
Balance and payment | essentials.balance, essentials.pay |
/kit [name] |
List kits or receive one | essentials.kit, essentials.kits.<name> |
The full list of permissions is available on the project's website.
Adjust the Configuration
Open the file as the minecraft user:
sudo -u minecraft nano /opt/minecraft/server/plugins/Essentials/config.ymlIn nano, Ctrl+W lets you search for an option. Edit the existing lines instead of adding new ones, and use only spaces for indentation.
# Message language (this line is commented out by default)
locale: en
# Wait between two teleports, in seconds
teleport-cooldown: 30
# Delay before teleporting, canceled if the player moves or is attacked
teleport-delay: 3
# Starting balance and currency
starting-balance: 100
currency-symbol: '€'
currency-symbol-suffix: trueThe number of homes is set per rank. A player without essentials.sethome.multiple can only have one. With this permission, they get the default value, and essentials.sethome.multiple.vip gives them the vip value:
sethome-multiple:
default: 3
vip: 5
staff: 10Apply your changes without restarting:
sudo mc-console 'essentials reload'Set the Spawn Point and Warps
These commands are typed in-game, at the desired location, with an operator account or a member of the admin group:
/setspawn
/setspawn newbies
/setwarp boutique/setspawn sets the general spawn point. /setspawn newbies sets the one for new players, used through the newbies option in config.yml:
newbies:
announce-format: '&dWelcome {DISPLAYNAME}&d to the server!'
spawnpoint: newbies
kit: toolsThe specified kit is given on first connection, without checking permissions. Set kit: '' to disable it.
Create a Kit
Kits are stored in plugins/Essentials/kits.yml:
sudo -u minecraft nano /opt/minecraft/server/plugins/Essentials/kits.ymlAdd your kit to the kits: section. delay is the waiting time in seconds between two uses, and -1 makes it usable only once:
kits:
depart:
delay: 86400
items:
- stonesword 1
- stonepickaxe 1
- bread 16Reload the configuration and allow the kit:
sudo mc-console 'essentials reload'
sudo mc-console 'lp group default permission set essentials.kits.depart true'Display Ranks in Chat
With EssentialsX Chat, Vault and LuckPerms, the chat format is set in the chat section of config.yml:
chat:
radius: 0
format: '{DISPLAYNAME}&7:&r {MESSAGE}'{DISPLAYNAME} already contains the LuckPerms prefix and suffix, so do not add {PREFIX} next to it, or the prefix will appear twice. radius: 0 sends messages to the whole server.
Apply with sudo mc-console 'essentials reload', then write a message in-game: the prefix defined in LuckPerms should be displayed.
Manage the Economy
From the console, you can change the balance of a player who has already connected:
sudo mc-console 'eco give Steve 100'
sudo mc-console 'eco take Steve 25'
sudo mc-console 'balance Steve'Thanks to Vault, other compatible plugins can use this economy.
Verify the Result
Connect with a non-operator account that is a member of the default group, then try:
/sethome maison
/home maison
/spawn
/kit tools
/balanceEach command should work without the You do not have access to that command message. If you enabled locale: en, replies are displayed in English.
Back Up and Update
The plugins/Essentials folder contains the configuration, player data and warps:
sudo tar -czf /opt/minecraft/backups/essentials-$(date +%F-%H%M).tar.gz -C /opt/minecraft/server/plugins EssentialsAlways update all modules at the same time, as they must have the same version. For a development build:
sudo -u minecraft bash
mkdir -p /opt/minecraft/server/plugins/update
cd /opt/minecraft/server/plugins/update
BASE="https://ci.ender.zone/job/EssentialsX/lastSuccessfulBuild"
for MODULE in EssentialsX EssentialsXSpawn EssentialsXChat; do
FICHIER=$(curl -fsSL "$BASE/api/json?tree=artifacts%5BfileName%5D" | jq -r --arg m "$MODULE" '.artifacts[].fileName | select(startswith($m + "-"))')
curl -fL -o "$FICHIER" "$BASE/artifact/jars/$FICHIER"
done
exit
sudo systemctl restart minecraft.serviceTroubleshooting
"You are running an unsupported server version!"
This version of EssentialsX does not support your Minecraft version. Install the build indicated in the table at the beginning of this guide.
"Version mismatch! Please update all Essentials jars to the same version"
The modules do not all have the same version. Replace them together, then restart the server. Check that no module still has two files with ls /opt/minecraft/server/plugins.
"You do not have access to that command"
The player does not have the permission. Check it, for example for /home:
sudo mc-console 'lp user Steve permission check essentials.home'/r uses the essentials.msg permission, and /spawn requires the EssentialsX Spawn module.
"You cannot set more than 1 homes"
The player has reached their limit. Give them essentials.sethome.multiple and, if needed, a rank such as essentials.sethome.multiple.vip.
"Detected supported permissions plugin LuckPerms without Vault installed"
Vault is missing or did not load. Check that it appears in sudo mc-console plugins, then check the output of sudo mc-console vault-info.
"The file is broken and Essentials can't open it"
A YAML file contains an error, often a tab or incorrect indentation. The logs show which file is affected. Fix it or restore your backup, then restart the server.
A command from another plugin is overridden
If two plugins provide the same command, use the full form, for example /essentials:home. To permanently give priority to the other plugin, add the command to disabled-commands in config.yml.
To go further, see the official EssentialsX wiki.