EssentialsX

🎉 At long last, EssentialsX 2.22.0 is here! This release brings support for content from The Copper Age, Mounts of Mayhem and Tiny Takeover drops on servers running Minecraft 26.1.2 and 1.21.11, as well as a healthy handful of new features, bug fixes and new API for developers!

EssentialsX 2.22.0 fixes several item duplication and server crash exploits. All users should upgrade to this release.

Thanks to everyone who has contributed code to this release (many of whom are listed at the bottom of this release), as well as to everyone who has contributed to translations on Crowdin!

In addition, a massive thanks to our community members who have assisted countless people with using EssentialsX across GitHub and MOSS, including @Evidentsinger14, @JasonHorkles, @Chew and many others.

The EssentialsX project is powered by the community. If you want to help us out, you can contribute by;

• Updating or reviewing translations on Crowdin
• Help users in our support channel on Discord
• Fixing bugs or offering new features on GitHub

Finally, a shoutout to our supporters on Patreon and GitHub Sponsors!
A special thanks goes to our Hero tier supporters:

• AKP
• @aternosorg
• @pebblehost
• and one anonymous supporter!

Your support helps us to continue spending hours of our free time working on and improving EssentialsX for everyone. If you've got any spare change, you can click one of the buttons below to support the EssentialsX project with a one-off or monthly pledge:

Supported server versions

EssentialsX officially supports the Paper server software. Specifically, EssentialsX is designed to work on the following Minecraft versions:

• ✅ 26.1.2 - EssentialsX actively develops for and supports this version.
• ⚠️ 1.8.8, 1.9.4, 1.10.2, 1.11.2, 1.12.2, 1.13.2, 1.14.4, 1.15.2, 1.16.5, 1.17.1, 1.18.2, 1.19.4, 1.20.6 and 1.21.11 - these versions are still supported, but are not a priority for us, and may be dropped in a future release.
• ⚠️ Spigot is still supported but is a low priority for us, and may be dropped in a future release.

We recommend using the latest version of Paper. EssentialsX includes significant improvements that require Paper, including:

• Paper's async chunk loading reduces lag spikes during player teleports.
  CraftBukkit and Spigot do not support async chunk loading from plugins.
• /anvil, /grindstone, /cartographytable, /loom, /smithingtable, and /stonecutter are only supported on Paper.
  CraftBukkit and Spigot do not support the API needed for these.
• /recipe on 1.12+ requires Paper to avoid a dupe bug introduced by CraftBukkit and Spigot.
• Paper contains countless overall performance optimisations over CraftBukkit and Spigot.

EssentialsX does not support the following Minecraft versions or server software:

• ℹ️ Folia is not supported yet. We are working on proper Folia support.
  Do not attempt to use current versions of EssentialsX on Folia, nor on forks of Folia - you may lose userdata.
• 🛑 "Ultra-performance" Paper forks including Akarin, Yatopia, and similar projects.
  These often perform non-standard behaviour and can break your worlds and installed plugins.
• 🛑 Mohist and its associated projects - The Mohist project is known to be sketchy, and has, in the past, tricked users into deleting official EssentialsX jars and installing an unofficial build.
  We cannot guarantee the safety or functionality of unofficial builds of EssentialsX; you should avoid using Mohist where possible.
• 🛑 Other Forge/Bukkit hybrid servers including Cauldron, Thermos, Magma, CatServer, Arclight - EssentialsX is built for the Bukkit API, which does not properly support mods.
  For modded servers running Minecraft Forge, NeoForge or Fabric, you should use FTB Essentials.
• 🛑 1.7.10 or below.

Upgrading to 2.22.0

If you're upgrading from 2.21.1 or 2.21.2, you can keep your current EssentialsX config file. However, 2.22.0 adds new options that you may want to configure. You can add these options to the existing config files, or rename your current config files in order to generate a fresh one. Read on for details on the new config options.

Upgrading from 2.21.0 or older versions of EssentialsX? See the previous update changelogs.

Known issues

Anchor charges deplete on Spigot even when EssentialsX Spawn overrides the spawn location

On CraftBukkit and Spigot, anchor charges will deplete regardless of the respawn-at-anchor due to an unfixed bug in CraftBukkit. This bug has been patched in Paper.

Fly mode is reset when teleporting between worlds on Spigot

On Spigot 1.17.1 and greater, player's fly mode will be reset regardless of the world-change-fly-reset setting due to behavior change in vanilla. A fix for this is in place for Paper servers. (#6012)

New features

EssentialsX now supports 26.1.2 and 1.21.11 (#6299, #6364, #6473, #6534)

EssentialsX now officially supports Paper 26.1.2 and 1.21.11, including all the new blocks, items, mobs and enchantments added in Minecraft's latest feature drops.

New config.yml option: afk-timeout-command (#6169)

You can now specify one or more commands to run after the AFK timeout expires. This replaces the classic auto-afk-kick config option.

# After this timeout in seconds, the player will either be kicked from
# the server or commands in 'afk-timeout-commands' will be executed.
# The 'essentials.afk.kickexempt' permission overrides this feature.
# Set to -1 for no timeout.
auto-afk-timeout: -1

# A list of commands to be executed instead of kicking the player once the
# threshold defined above in 'afk-auto-timeout' is reached. If this list is empty 
# and 'afk-auto-timeout' is not set to -1, Essentials will default to
# kicking the player once they reach the timeout threshold.
#
# WARNING: You must include a command here that either removes the player from the server
# or stops them from being AFK. Otherwise, these commands will run every second
# until the player is no longer AFK!
#
# Available placeholders:
# {USERNAME} - The player's username.
# {KICKTIME} - The time, in minutes, the player has been AFK for.
afk-timeout-commands:
  - eco take {USERNAME} 10
  - kick {USERNAME} You have been kicked for being inactive for {KICKTIME} minutes! You lost $10.

If you want to maintain the classic behaviour that kicks players with a standard message, you can continue to set a timeout duration under auto-afk-timeout but leave the afk-timeout-commands list empty.

New command: /powertoollist (#6096)

You can now list all commands assigned to tools via /powertool by running the /powertoollist command:

New permission: essentials.whitelist.bypass (#6232)

You can now grant the essentials.whitelist.bypass to allow a player to bypass the whitelist when enabled. This works even if the player is not in the whitelist.

New config.yml option: gamemode-change-preserve-flying

You can now choose whether EssentialsX will preserve a player's flight mode if they change from a flying gamemode (spectator or creative) to a non-flying gamemode (survival or adventure) while flying.

# Should Essentials preserve a player's flight status when they change game modes?
# When enabled, if a player is flying when switching game modes, their flight will be maintained.
# This will only work if the player has the 'essentials.fly' permission.
gamemode-change-preserve-flying: false

New config.yml option: baltop-entry-limit (#6300, #6306)

You can now limit the number of entries stored by /balancetop to reduce memory usage on servers with high lifetime playercounts.

# Limit the number of cached balance top entries. 
# Recommended for servers with a large number of players, as it reduces memory usage. 
# Set to -1 to disable the limit.
baltop-entry-limit: -1

Kits now support placing items in specific slots (#5794)

You can now add slot:<id> to the start of an item definition in a kit to place the item in a specific inventory slot.
This works when using /createkit, both when using NBT serialization and classic ItemMeta syntax. You can also add it to an existing kit.

kits:
  meleeminer:
    delay: 10
    items:
    - slot:0 diamond_sword 1
    - slot:1 netherite_spear 1
    - slot:2 torch 64
    - slot:3 cooked_beef 12
    - slot:6 golden_pickaxe 1
    - slot:7 cobblestone 32
    - slot:8 white_wool 32

New command: /unmute (#6491)

Previously, to unmute a player, you had to run /mute <player> again. This was a problem for scripting as it would toggle the player's mute status, potentially unintentionally muting the player.
You can now run /unmute <player> which will never mute them by mistake.

New command: /jailedplayers (#6517)

The new /jailedplayers command shows a full list of currently-jailed players.

New config option: reset-nick-on-name-change (#6470)

You can now have a player's nickname on your server reset when they log in after changing their Minecraft username.

# When this option is enabled, any nickname set by a player will be reset when their Minecraft account name changes.
# This prevents old nicknames (including RGB-formatted ones) from persisting after a name change.
reset-nick-on-name-change: false

Other additions

• The /potion command now allows applying potion effects to tipped arrows. (#6191)
• The /heal command now restores your oxygen levels. (#6201)
• The economy-log-uuids setting now allows you to print UUIDs to the trade.log file rather than usernames. (#6252)
• The essentials.seen.firstlogin permission now allows the /seen command to show the date a player first joined the server. (#6258)
• EssentialsX now reads group names directly from LuckPerms's API when installed, rather than relying on the LuckPerms Vault integration. Old group names are added to the list for backwards compatibility. (#6229)
• You can now use @s and @p selectors in EssentialsX commands to refer to the player executing the command. (#6110)
• Armor trim patterns are now supported in /give, /item and kit metadata. (#6155)
• EssentialsX now uses Paper's configuration phase APIs to async load user data before a player joins the world. (#6248)
• The /recipe command can now show recipes for crafting_transmute recipes, such as recolouring bundles with dye. (#6302)
• You can now suppress the standard "CONSOLE issued server command: ..." message for console and RCON messages using the log-console-commands config option. (#6337)
• When a user tries to join after being temporarily IP banned, they will now see the expiration time in the ban message. (#6407)
• The /essentials command has been significantly refactored to improve code quality. (#6230, #6481)
• The /gc command is now faster to call on Paper servers. (#6439)
• EssentialsX now directly uses Paper's native Adventure API functions where available. (#6220)
• You can now block players from fishing while AFK using the cancel-afk-on-fish config option. (#6465)
• EssentialsX can now restore custom flight mode settings when a player rejoins the server after quitting while in flight. (#6403)
• The default nickname length limit has been increased from 15 to 16 to align with Minecraft's username length limit. (#6484)
• You can now modify the formatting used when displaying player commands in SocialSpy by setting the socialSpyCmdFormat key in your locale file. (#6489)
• You can now disable picking up items in /vanish mode by granting the essentials.vanish.pickup permission. (#6488)
• The default message shown to a player when their teleport destination would be unsafe has been improved. This can be modified as usual in the locale file. (#6486)
• Vanished players will no longer broadcast advancement messages. This feature requires a server running Paper. (#6513)
• Discord: You can now use PlaceholderAPI placeholders inside the avatar-url config option. (#6189)
• Discord: You can now configure an HTTP proxy through which the plugin will connect to Discord using the http-proxy-server config option. (#6275)
• Discord: The plugin now warns you when permissions are missing from the Discord bot. (#6228)
• Discord: The console relay filter now also applies to the logger name. (#6383)
• Geo: Join messages are now printed to the console, not just to admins. (#6523)
• Protect: You can now disable the knockback effect from wind charges with by setting protect.prevent.windcharge-explosion to false. (#6183)

Bug fixes

Bugs fixed from 2.21.2 and older versions

• Death locations for /back are no longer overwritten when another plugin has cancelled the death event. (#6179)
• Players can no longer use click-and-drag to move items around when in /invsee, preventing potential item loss. (#5902)
• EssentialsX can now parse Minecraft version names for snapshots and for Mojang and Paper's new version naming schemes. (#6265, #6473, #6480, #6483, #6501)
• Read-only /invsee access will no longer degrade to full modify permissions after heavy garbage collection. (#6241, #6247)
• The /potion command now properly parses -1 as an infinite duration for potion effects. (#6236)
• Fuzzy/partial name resolution in command arguments is now more reliable. (#6263)
• The /tpr command now correctly resets its cached location list after /settpr has run and changed the /tpr settings. (#6305)
• EssentialsX no longer replaces the vanilla join message when no custom message has been set, allowing the vanilla translated message to show correctly. (#6312)
• Various issues with the Configurate refactor have been resolved. (#6266)
• The UUID cache now buffers disk reads and writes. (#6338)
• The /heal command no longer sends a duplicate message when running it on yourself. (#6347)
• Checking the server state on Spigot no longer fails. (#6377)
• The /helpop command now correctly shows messages when run from the console. (#6342)
• /balance no longer reveals when players are vanished. (#6085)
• Getting permissions handlers no longer throws a NullPointerException. (#6398)
• Getting the player locale for an offline player no longer throws a NullPointerException. (#6435)
• The /nick command now correctly shows the appropriate message when a players' nickname is removed. (#6442)
• The /give command can no longer be used to freeze the server. (#6449)
• The /burn and /more commands are now more resilient against integer overflow exploits. (#6452)
• The /thunder command now correctly displays MiniMessage in its output. (#6454)
• The /recipe command can no longer be used while the player is asleep to spawn in infinite diamonds. (#6455)
• The /setwarp command no longer allows players to hang or crash servers running on Windows by trying to print their warp coordinates to a printer connected to the server machine. (#6487)
• The /walkspeed and /flyspeed (and similar aliases) now always modify walking or flight speed specifically. (#6485)
• The /eco command now respects locale-specific decimal separators, including per-player locales if enabled. (#6511)
• The /time command no longer overrides a player's own /ptime setting. (#6509)
• Command descriptions are now printed in /help and usage messages using the player's locale. (#6508)
• The player's display name formatting no longer bleeds beyond the player name when printing local chat in SocialSpy. (#6507)
• Commands in kits no longer wrongly translate underscores to spaces during keyword replacement. (#6514)
• The console name is now read from the consoleName translation key properly. (#6506)
• Running /home bed now correctly ensures the player has the essentials.home.bed permission before teleporting the player. (#6516)
• Economy deposits (balance increases) are no longer rejected when the player's balance is below the minimum. (#6515)
• The nonexistent essentials.jail permission has been removed from plugin.yml. (#6539)
• AntiBuild: Shear interactions are now handled correctly. (#6262)
• Chat: % symbols will no longer cause chat processing to throw exceptions. (#6452)
• Discord: Advancement messages are no longer sent to Discord if the announceAdvancements gamerule is set to false. (#6195)
• Discord: Sending a private message from Discord to Minecraft no longer includes an empty discriminator tag. (#6383)
• Discord: Webhooks are now far less likely to trigger Discord ratelimits (HTTP error 429). (#6461)
• Discord: Fake join and quit messages no longer throw a NullPointerException due to a historical parameter mixup. (#6510)
• Discord Link: Role syncis is now far less likely to trigger Discord ratelimits (HTTP error 429). (#6461)
• Discord Link: Role syncing no longer leaves a thread running in the background when the plugin shuts down. (#6512)
• Spawn: Getting the player's respawn location no longer throws an exception on Minecraft 1.16.x-1.20.3. (#6460)

Regressions fixed from 2.22.0 dev builds

The following bugs from 2.22.0 development builds have been fixed:

• Commands listed in afk-timeout-commands are no longer forcibly lowercased. (#6255)
• The essentials.powertoollist is no longer omitted from plugin.yml. (#6250)
• Players are now evicted from the online user cache, not the persisted UUID map, when they log out. (#6284, #6286)
• EssentialsX no longer throws exceptions when players join for the first time. (#6327)
• The TeleportWarmupCancelledEvent now tracks the thread it was called from to prevent throwing an exception every time it fires. (#6371)
• Players without the essentials.joinfullserver permission are no longer kicked even when the server isn't full. (#6426)
• The /ess reload command is available once more. (#6444)
• Bukkit-level plugin reloads are less likely to break the /essentials command. (#6445)
• Flight is no longer re-enabled when the player logs in while in water. (#6490)
• EssentialsX no longer double-wraps URLs in click handlers, which would otherwise log an error on Paper. (#6492)
• The /list command now parses MiniMessage tags in players' displaynames. (#6505)
• Discord: The emoji-java library is now correctly included in the plugin once more. (#6467)

Changes for developers

New API: custom item transformers (#4871)

At long last, you can now register custom item metadata types from external plugins. These metadata types will be recognised in /give, /item and kits. See MetaItemStack#registerItemTransformer for more information.

EssentialsX catches the PlayerDeathEvent later and ignores cancelled events (#6179)

EssentialsX now listens to the PlayerDeathEvent on EventPriority.HIGH and ignores cancelled events. This means it will no longer set a death message for death events that have been cancelled.

It is still possible to cancel or modify the event after EssentialsX has modified them using EventPriority.HIGHEST.

New event: TeleportWarmupCancelledEvent (#6351, #6371)

The new TeleportWarmupCancelledEvent fires when a teleport warmup has been cancelled (ie by a player moving during the warmup period).

New event: PreTransactionEvent (#6370)

The new PreTransactionEvent fires before a transaction takes place between players. You can modify the value of the transaction or cancel the event to block the transaction using the event. See the original pull request for an example of how to use this event.

Notice: Wrong parameters in VanishStatusChangeEvent (#6510)

The value of VanishStatusChangeEvent#getController and VanishStatusChangeEvent#getAffected have always been incorrectly swapped.
To preserve compatibility with existing plugins that use these functions, we have not changed their return values. Instead, this incorrect behaviour is now documented on the class itself for reference.

Since correcting this mistake would be a breaking change, it will only be corrected after a major API increment.

For a full commit log, click here.