🎉 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.

Note: Looking for addons? See the full EssentialsX collection on Modrinth!

🎉 EssentialsX 2.21.2 is here, bringing with it 1.21.8 support, support for content from Chase the Skies, and a handful of bug fixes.

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, @ImDarkLaw, @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:

• ✅ 1.21.8 - 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, and 1.20.6 - 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 or forks of it - 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.21.2

If you're upgrading from 2.21.1, you can keep your current EssentialsX config file. There are no new changes to configuration files in this release.

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 1.21.8 (#6166, #6196, #6224)

EssentialsX now officially supports Paper 1.21.8.

Other additions

• The /tpr command now sends a message before the teleport commences. (#6205)

Bug fixes

Bugs fixed from 2.21.1 and older versions

• The /tpr command no longer allows players to bypass max and minimum range. (#6205)
• The /tpr command works again on legacy versions. (#6212)
• Nicknames that use hex color codes now properly respect the max-nickname-length setting when ignore-colors-in-max-nick-length is enabled. (#6185)
• Creating new player heads with the /skull command now works on 1.20.4 and above. (#6188)
• The description of the /whois command is now less misleading. (#6187)
• Canceling the SignChangeEvent from the /editsign paste command no longer erroneously informs the player that the paste was successful. (#6136)
• Unsupported permissions plugins no longer cause bStats to error during startup. (#6190)
• When confirm to /clear is enabled, the command passed to the confirmClear message no longer has a trailing space. (#6213)
• Translation messages with arguments now properly respect the per-player-locale setting. (#6227)
• EssentialsX no longer considers the hidden body and saddle inventory slots to be part of the inventory. (#6218)
• AntiBuild: Various issues related to breaking signs without permission have been fixed. (#6186)
• Chat: Chat messages sent with URLs that have TLDs longer than three characters are now properly censored. (#6184)
• Chat: Shout or question message types can no longer have blank space in front of them. (#6192)
• Chat: Formatting for local chat no longer clips off color codes. (#6226)
• Discord: Custom bot names can be set without also setting show-avatar: true. (#6239)

Regressions fixed from 2.21.2 dev builds

The following bugs from 2.21.2 development builds have been fixed:
* The player-commands feature now works again. (#6214)

For a full commit log, click here.

Note: Looking for addons? See the full EssentialsX collection on Modrinth!

🎉 EssentialsX 2.21.1 is here, bringing with it 1.21.5 support and several bug fixes.

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, @ImDarkLaw, @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:

• ✅ 1.21.5 - 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, and 1.20.6 - 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 or forks of it - 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 - 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.21.1

If you're upgrading from 2.21.0, you can keep your current EssentialsX config file. However, 2.21.1 adds new options that you may want to configure, and reorganises the config file with improved comments for clarity. You can add these options to the existing config files, or rename your current config files in order to generate a fresh one.

Upgrading from 2.20.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 1.21.5 (#6109)

EssentialsX now officially supports Paper and Spigot 1.21.5.

New allowed-nicks-regex setting (#5200)

You can now change the regex pattern which determines which nicknames are allowed. The essentials.nick.allowunsafe permission
can still be used to bypass this check.

# The regex pattern used to determine if a requested nickname should be allowed for use.
# If the a request nickname does not matched this pattern, the nickname will be rejected.
# Users with essentials.nick.allowunsafe will be able to bypass this check.
allowed-nicks-regex: '^[a-zA-Z_0-9§]+$'
 ```

### Discord: Support for SocialSpy with new `private-chat` message type (#5620)

You can now relay SocialSpy messages to Discord using the new `private-chat` message type.  
This is sent whenever a user sends a private message on the Minecraft server, unless they also have the `essentials.chat.spy.exempt` permission.

```yml
# Configure which Discord channels different messages will be sent to.
# You can either use the names of the channels listed above or just the id of a channel.
# If an invalid channel is used, the primary channel will be used instead.
#
# To disable a message from showing, use 'none' as the channel name.
message-types:
  ...
  # Message sent when a private message (/msg, /whisper, etc.) is sent on the Minecraft Server.
  private-chat: none

# The following entries allow you to customize the formatting of messages sent by the plugin.
# Each message has a description of how it is used along with placeholders that can be used.
messages:
  ...
  # This is the message that is used to relay minecraft private messages in Discord.
  # The following placeholders can be used here:
  # - {sender-username}: The username of the player sending the message
  # - {sender-displayname}: The display name of the player sending the message (This would be their nickname)
  # - {receiver-username}: The username of the player receiving the message
  # - {receiver-displayname}: The display name of the player receiving the message (This would be their nickname)
  # - {message}: The content of the message being sent
  pms-to-discord: "[SocialSpy] {sender-username} -> {receiver-username}: {message}"

Other additions

• Translations have been updated with the latest community contributions on Crowdin. (#6089, #6131)
• EssentialsX's config files have been tidied up, with better wording in comments for clarity. (#6108)

Bug fixes

Bugs fixed from 2.21.0 and older versions

• Various issues from the Adventure text refactor have resolved. (#6114)
• Further issues with trade signs have been resolved. (#6116)
• The /baltop command works again on versions 1.15.2 and below. (#6115)
• Various typos in the English translation files have been fixed. (#6135, #6140)
• /delhome no longer sends an extra message when deleting a home that doesn't exist. (#6150)
• Discord Link: Unlinking your account from Discord while offline no longer causes an error. (#6111)

Regressions fixed from 2.21.1 dev builds

The following bugs from 2.21.1 development builds have been fixed:

• The /spawnmob command works again on versions 1.21.5 and below. (#6121)
• You can sleep in a bed once again, regardless of whether you have essentials.sethome.bed or not. (#6151)

Changes for developers

New events

EssentialsX 2.21.1 introduces a new event:

• SignTransactionEvent is fired when a player is about to use a buy or sell sign. (#6071)

New methods

• There is now a method to retrieve the most recent activity time of a User: IUser#getLastActivityTime. (#6101)

Other changes

• GlobalChatEvent is now fired for every chat message that EssentialsX Chat processes regardless of whether a chat radius has been set. (#6113)
• TranslatableException#getMessage now returns plaintext once again, not unparsed MiniMessage tags. (#6134)

For a full commit log, click here.

Note: Looking for addons? See the full EssentialsX collection on Modrinth!

At long last, 🎉 EssentialsX 2.21.0 is here! This release comes with support for Minecraft 1.21.4 and content from The Garden Awakens drop, a rework of text throughout the plugin to add initial support for rich text components with MiniMessage, and a handful of new features and bug fixes!

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, @ImDarkLaw, @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 shout out to our supporters on Patreon and GitHub Sponsors!
A special thanks goes to our Hero tier supporters:

• AKP
• @jharrison123
• @aternosorg
• @pebblehost

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:

• ✅ 1.21.4 - 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, and 1.20.6 - 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 or forks of it - 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 - 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.21.0

If you're upgrading from 2.20.1, you can keep your current EssentialsX config file. However, 2.21.0 adds several new options that you may want to configure. Read on for the list of new configuration options.

Upgrading from 2.20.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)

Important Changes

Adventure Refactor (#4717)

EssentialsX 2.21.0 has undergone a complete overhaul of our translation system to add support for chat components (Adventure/MiniMessage).
This brings with it the addition of per-player-locale translations and support for MiniMessage inside our messages.properties files.

All messages should remain nearly identical than they were before this update. A future update will add hover and click events to some of our commands.
Message files have been moved from plugins/Essentials/ to plugins/Essentials/messages/ in this release. When upgrading to 2.21.0, any custom message files will be converted and moved to the new location automatically.

Chat: Using Paper events with other chat plugins (#6033, #6050)

By default, EssentialsX 2.21.0 now uses the modern AsyncChatEvent from Paper instead of Bukkit's legacy AsyncPlayerChatEvent. This will allow EssentialsX to support rich text components in chat formats in the future.

However, if you use any plugins that rely on the legacy AsyncPlayerChatEvent, you may run into compatibility issues when upgrading to 2.21.0.
For now, you can switch back to the legacy events by setting chat.paper-chat-events to false in config.yml, but be aware this config option is not intended to be used long-term and could be removed in the future.
You should aim to replace any incompatible plugins with ones that support Paper's chat events.

New features

EssentialsX now supports 1.21.4 and The Garden Awakens content (#5522, #5592, #5783, #5834, #5900, #5961, #5985)

EssentialsX now officially supports Paper and Spigot 1.21.4, and content from The Garden Awakens feature drop.
Support for Minecraft 1.21.5 and Spring to Life will be added in a future patch release.

New per-player-locale setting. (#4717)

EssentialsX can now send messages in a player's native language.

# Should EssentialsX use player's language instead of the server's when sending messages?
# This is useful if you want to use a different language for your server than for your players.
# For example, if you have your server set to English and a player who speaks French, you can set this to true
# and EssentialsX will send messages in French to the player and messages in the console as English.
# If a player's language is not known, the server's language will be used.
per-player-locale: false

New message-colors settings. (#4717)

You can now customize the color scheme of EssentialsX without having to modify messages.properties files.

# Change the default primary and secondary colours used in EssentialsX messages.
# Some messages may use custom colours, which will need to be edited in the appropriate message files.
# For more information on customising messages, see https://essentialsx.net/wiki/Locale.html
message-colors:
  primary: '#ffaa00'
  secondary: '#ff5555'

Multipliers for /sell and sell signs (#4770)

Players with certain permissions can now be given a customizable multiplier to the value of items they sell through /sell or [Sell] signs. The multipliers can be configured in the config.yml like so:

# Allow players to receive multipliers for items sold with /sell or the sell sign.
# You can set the default multiplier using the 'default' rank below.
# To grant different multipliers to different people, you need to define a 'multiplier-rank' below.
# Create the 'multiplier-rank' below, and give the matching permission: essentials.sell.multiplier.<multiplier-rank>
sell-multipliers:
  default: 1.0
  double: 2.0
  triple: 3.0

The /mail command now allows for clearing other people's mail. (#4878)

Players with essentials.mail.clear.others can clear other player's mail with /mail clear <player> and players with essentials.mail.clearall can clear the mail of all users with /mail clearall.

The /skull command can now give skulls from texture urls. (#5120)

You can now use /skull <texture> to give skulls with a texture url or base64 encoded texture data.

Option to limit the total number of lore lines for /itemlore. (#4773)

You can now impose a limit to the number of lore lines players can add using the /itemlore command. Players with the essentials.itemlore.bypass permission will bypass this limit.

# Set the maximum amount of lore lines a user can set with the /itemlore command.
# Users with the essentials.itemlore.bypass permission will be able to bypass this limit.
max-itemlore-lines: 10

New socialspy-uses-displaynames setting. (#5613)

You can now specify if EssentialX should use usernames over nicknames in socialspy.

# Whether social spy should use formatted display names which may include color.
# If false, social spy will use only the actual player names.
socialspy-uses-displaynames: true

Various improvements to random teleport. (#4271, #5990)

There have been a number of additions related to random teleport. Including, a [RandomTeleport] sign, the ability to run /tpr from the console, as well as the following new config options:

# If configured, users will spawn at the random spawn location instead of the newbies spawnpoint.
random-spawn-location: "none"

# If configured, when users die, they will respawn at the random respawn location.
random-respawn-location: "none"

Define requirements for /balancetop. (#5394)

Server admins can now define a minimum balance or time played be met for a player to appear on the /balancetop list with the following config.yml options:

# Requirements which must be met by the player to get their name shown in the balance top list.
# Playtime is in seconds.
baltop-requirements:
  minimum-balance: 0
  minimum-playtime: 0

Discord: Option to ignore certain roles for {color} and {role} placeholders. (#5157)

You can now define a list of roles which should be ignored by the {color} and {role} placeholders.

# A list of roles which should be ignored by the {color} and {role} placeholders.
# for the Discord->MC chat format.
discord-role-blacklist:
  - "123456789012345678"
  - "Members"

Discord: Option to define role aliases. (#5157)

You can now replace role names with whatever you want for the Discord to MC chat relay

# Role aliases allow you to replace the role names with something different in the Discord->MC chat relay format.
# If you are using role aliases, make sure to remove the '#' at the start to allow the setting to be read.
discord-roles-aliases:
#  "123456789012345678": "&c&lAdmin"
#  "Members": "Member"

Other additions

• Translations have been updated with the latest community contributions from Crowdin.
• Our feature provider system has been fully rewritten. (#5087, #6081)
• Our dependencies and build tools have been updated to their latest versions. (#5685, #5704)
• Kits now support items with custom model data. (#5433)
• Waxed signs can no longer be edited with /editsign without essentials.editsign.waxed.exempt. (#5492)
• The /pay command now supports abbreviations for thousand (k), millions (m), billions (b), and trillions (t). (#5457)
• The /whois and /seen commands now display if a player is whitelisted or not. (#5486)
• The excluded-biomes setting in tpr.yml now supports custom biomes. (#5703)
• Jailing offline players with the jail-online-time option enabled now jails the player for the proper amount of time. (#5701)
• The /fireball command can be used to fire wind charges. (#5951)
• The /delhome command now supports * wildcards. (#5919)
• You can now give a skull directory to other players with /skull. Requires the essentials.skull.spawn.others permission. (#5822, #6008)
• A translation key was added for /alts to customize its output. (#5595)
• The /ess dump command now uses pastes.dev. (#6011)
• Chat formats can now per customized per type (normal/question/shout). (#5337)
• Discord: The Discord module now also supports Paper's chat events. (#5908)
• Discord: The link in /discord is now clickable. (#5934)
• Discord: The server-start message now has a {starttimeseconds} placeholder to display the server startup time. (#5686)
• Spawn: The /spawn command no longer sends its message before the teleport occurs. (#6025)

Bug fixes

Bugs fixed from 2.20.1 and older versions

• A duplication glitch with /clearinventory was resolved. (#5899, #5901)
• Various issues with Trade signs have been resolved. (#5574, #5874, #6076)
• The correct permission node is now used for potions in /potion. (#5552)
• Players can no longer /ignore themselves. (#5488)
• Books given from book.txt file no longer give a invalid book. (#4920)
• Custom quit messages now show the correct number of online players. (#5541)
• A potential memory leak arising from unregistering commands has been fixed. (#5572)
• The give command no longer gives potions when trying to give tipped arrows. (#5627)
• Banner patterns are no longer ignored in kits. (#5723)
• The heal sign now accounts for the player's max health attribute. (#5752)
• The /eco give command now has a more consistent color scheme. (#5738)
• The /pay command now supports commas/periods based on the player's locale. (#5962)
• An issue with respawn logic when respawn-at-home-bed was enabled has been resolved. (#5825)
• Extraneous code in our command preprocessing has been removed. (#5981)
• Flight is now once again preserved when teleporting between worlds. (#6012)
• Player loot tables are now dropped even when a player has essentials.keepinv. (#6036)
• The /book command can now lock/unlock books again on 1.20+. (#6064)
• Expired /mail messages no longer show up in the alert when joining. (#6063)
• AntiBuild: Destroying End Crystals are now protection on 1.8.8. (#6009)

Regressions fixed from 2.21.0 dev builds

The following bugs from 2.21.0 development builds have been fixed:

• Various issues from the Adventure refactor have been fixed. (#5632, #5635, #5636, #5637, #5648, #5650, #5659, #5666, #5687, #5688, #5692, #5705, #5700, #5699, #5698, #5702, #5711, #5719, #5722, #5726, #5740, #5737, #5739, #5736, #5761, #5769, #5771, #5776, #5819, #5872, #5913, #5952, #5957, #5956, #5967, #5972, #5921, #6015, #6018, #6076)
• Various issues with Spigot incompatibility have been fixed. (#5820, #5872, #5934, #5934)
• Denomination abbreviations in /pay are now more strictly parsed to prevent trolling. (#5638)
• First time EssentialsX installs no longer fail when there isn't an existing tpr.yml file. (#6004)
• Trying to use a kit with splash potions no longer results in an error in 1.8.8. (#6047, #6055)
• Flight is no longer preserved for those who do not have permission to fly in their destination world. (#6065, #6079, #6079)
• The /baltop command no longer hides all players in certain conditions. (#6074)
• The correct SpawnerBlockProvider is now selected for 1.21+. (#6080)
• Chat: Various issues from the Paper chat event refactor have been fixed. (#6060, #6067, #6075)

Changes for developers

Synchronous teleport APIs have been removed.

EssentialsX 2.18.0 replaced the legacy synchronous Teleport, TimedTeleport, IUser#getTeleport, and IJails#sendToJail(IUser, String) APIs with new, asynchronous replacements that support Paper's async chunk loading.

The legacy synchronous teleport APIs have not been fully functional for some time, and in 2.21.0, they have now been removed.
Any plugins relying on these were likely already broken, but those plugins will no longer compile against or work with 2.21.0.

InvalidWorldException is deprecated for removal. (#5984)

This exception is no longer thrown by any method in the Essentials API and will be removed in a future version. Please update your code.

New Events

EssentialsX 2.21.0 introduces a new event:
* HelpopMessageSentEvent is fired when a player sends a message through /helpop (#5490)

New Methods

• DiscordLink: There is now a method to get a list of players with a linked Discord account: DiscordLinkService#getAllLinkedPlayers. (#5896)

For a full commit log, click here.

🎉 EssentialsX 2.20.1 is here, bringing with it 1.20.1 support and several bug fixes.

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 @triagonal, @JasonHorkles, @Evidentsinger14, @ImDarkLaw, @Chew, @Laarryy 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
• Vestria MC
• @aternosorg
• @pebblehost

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 CraftBukkit, Spigot, and Paper server software. Specifically, EssentialsX is designed to work on the following Minecraft versions:

• ✅ 1.19.4 and 1.20.1 - EssentialsX actively develops against and supports these versions.
• ⚠️ 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, and 1.18.2 - these versions are still supported, but are not a 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 or forks of it - 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 - 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 - EssentialsX is built for the Bukkit API, which does not properly support mods.
  For modded servers, use SpongeForge and Nucleus, or an alternative mod for Forge or Fabric.
• 🛑 1.7.10 or below.

Upgrading to 2.20.1

If you're upgrading from 2.20.0, you can keep your current EssentialsX config file. There are no new changes to configuration files in this release.

Upgrading from 2.19.7 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. (#4325)

On Minecraft 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. This will be fixed in a future version of Essentials.

New features

EssentialsX now supports 1.20.1 (#5389)

EssentialsX now officially supports Paper, Spigot, and CraftBukkit 1.20.1.

Other additions

• Translations have been updated with the latest community contributions from Crowdin.
• Our dependencies and build tools have been updated to their latest versions. (#5383)
• Added the ability to get the recipe of the item you're holding with /recipe hand. (#5346)

Bug fixes

Bugs fixed from 2.20.0 and older versions

• An exception is no longer raised during new joins when using LuckPerms contexts. (#5364)
• Shout and question prefixes now work when using the /toggleshout command. (#5367)
• Underscores in kit placeholders no longer are removed upon receiving the kit. (#5366)
• Invalid decimal values provided in configuration files now return proper default values. (#5373)
• An exception is no longer raised when doing operations on some offline players. (#5375, #5466)
• Invalid material names in /unlimited user data values no longer prevent user data from loading. (#5438)
• Trade signs no longer break when setting currency-symbol-suffix to true in the config. (#5441)
• The enchant command now supports items held in the offhand. (#5449)
• The book command now works properly with other items held in the offhand. (#5449)
• Various issues related to offline player lookups have been fixed. (#5462)
• AntiBuild: AntiBuild checks are no longer ran for NPCs. (#5365)
• Discord: Console messages and webhook messages should no longer spam console or die out after spam. (#4786)
• Discord: The quit message online player count placeholder is no longer off by one. (#5440)
• Discord: The console relay now properly filters all formatting codes. (#5454)
• Discord Link: Player link data is no longer saved to disk when no data has changed. (#5388)
• Discord Link: Discord roles and minecraft groups are now removed instantly upon unlink. (#5388)

Regressions fixed from 2.20.1 dev builds

The following bugs from 2.20.1 development builds have been fixed:

• Commands in kits no longer replace spaces with underscores. (#5377)
• Empty lines in kits no longer raise an exception. (#5378)
• Kits no longer only replace spaces with underscores in commands. (#5379)

Changes for developers

New events

EssentialsX 2.20.1 introduces a new event:

• KitPreExpandItemsEvent is fired before players are about to receive kit items. (#5407)

For a full commit log, click here.

After months of hard work from our contributors, EssentialsX 2.20.0 is here! 🎉

This release contains a new Discord Link addon, 1.19.4 support, a few new features, bug fixes and internal improvements. Keep reading to see all the new additions!

Thanks to all our contributors who contributed to this release (all 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 @triagonal, @JasonHorkles, @Evidentsinger14, @ImDarkLaw, @Chew, @Laarryy 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
• Vestria MC
• @aternosorg
• @pebblehost

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 CraftBukkit, Spigot, and Paper server software. Specifically, EssentialsX is designed to work on the following Minecraft versions:

• ✅ 1.18.2 and 1.19.4 - EssentialsX actively develops against and supports these versions.

• ⚠️ 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, and 1.17.1 - these versions are still supported, but are not a 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, /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:

• 🛑 "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 - 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 - EssentialsX is built for the Bukkit API, which does not properly support mods.
  For modded servers, use SpongeForge and Nucleus, or an alternative mod for Forge or Fabric.
• 🛑 1.7.10 or below.

Upgrading to 2.20.0

If you're upgrading from 2.19.3 or above, you can keep your current EssentialsX config file. However, 2.20.0 adds several new options that you may want to configure, and to do so you'll need to either update your config or add the new settings to your existing config. Read on for a list of changes and new config options.

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

New module: EssentialsX Discord Link! 🎉

EssentialsX Discord now has the Discord Link addon, which lets your users easily link their Discord and Minecraft accounts! You can synchronize Discord roles with Vault groups, as well as optionally requiring players to link to Discord before playing, all with a bloat-free and easy-to-understand configuration!

You can read more about EssentialsX Discord Link and see how to get started here.

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.

Minecraft: Trails and Tales content not yet supported in commands

EssentialsX 2.20.0 doesn't yet support blocks, items and mobs from Minecraft: Trails and Tales in 1.19.x or 1.20. As a result, some commands and features (including /give, /spawnmob and /editsign) won't recognise the new content yet.

We plan to release a 2.20.1 update once Minecraft 1.20 has released, which will add support for the new content.

Important changes

Usermap storage and cache changes

EssentialsX 2.20 overhauls the user caching system, fixing issues with third-party plugins such as Towny.

Due to a large overhaul in data format, once you upgrade to 2.20.0, you will not be able to downgrade your userdata to older versions. We strongly recommend taking a full backup of your plugins/Essentials/usermap.csv file before you update from 2.19.7 to 2.20.0 if you ever wish to downgrade in the future.

New features

EssentialsX now supports 1.19.4

EssentialsX now officially supports CraftBukkit, Spigot and Paper for 1.19.4.

New /renamehome command

You can now use /renamehome to change the name of your existing home. If you have the essentials.renamehome.others permission, you can rename the homes of other players.

New /bottom command

You can now use /bottom to teleport to the lowest safe location in their current position.

Discord: New first-join message type

A new Minecraft -> Discord message type, sent when a player joins the server for the first time.

# Configure which Discord channels different messages will be sent to.
# You can either use the names of the channels listed above or just the id of a channel.
# If an invalid channel is used, the primary channel will be used instead.
#
# To disable a message from showing, use 'none' as the channel name.
message-types:
  ...

  # Join messages sent when a player joins the Minecraft server for the first time. This type is sent instead of the join type.
  first-join: primary

# The following entries allow you to customize the formatting of messages sent by the plugin.
# Each message has a description of how it is used along with placeholders that can be used.
messages:
  ...

  # This is the message sent to Discord when a player joins the minecraft server for the first time.
  # The following placeholders can be used here:
  # - {username}: The name of the user joining
  # - {displayname}: The display name of the user joining
  # - {joinmessage}: The full default join message used in game
  # - {online}: The amount of players online
  # - {unique}: The amount of unique players to ever join the server
  # ... PlaceholderAPI placeholders are also supported here too!
  first-join: ":arrow_right: :first_place: {displayname} has joined the server for the first time!"

Discord: New local, question, and shout message types

A few new Minecraft -> Discord message types and configuration options have been added in order to support local, question and shout chat.

# Whether to use Essentials Chat events instead of normal chat event.
# This allows you to filter chat by its type (local, question, shout).
use-essentials-events: false

# Configure which Discord channels different messages will be sent to.
# You can either use the names of the channels listed above or just the id of a channel.
# If an invalid channel is used, the primary channel will be used instead.
#
# To disable a message from showing, use 'none' as the channel name.
message-types:
  ...

  # Message sent when a player talks in local chat.
  # use-essentials-events must be set to "true" for this to work.
  local: none

  # Message sent when a player asks a question in global chat.
  # use-essentials-events must be set to "true" for this to work.
  question: primary

  # Message sent when a player talks in global chat.
  # use-essentials-events must be set to "true" for this to work.
  shout: primary

# The following entries allow you to customize the formatting of messages sent by the plugin.
# Each message has a description of how it is used along with placeholders that can be used.
messages:
  ...

  # This is the message that is used to relay minecraft local chat in Discord.
  # The following placeholders can be used here:
  # - {username}: The username of the player sending the message
  # - {displayname}: The display name of the player sending the message (This would be their nickname)
  # - {message}: The content of the message being sent
  # - {world}: The name of the world the player sending the message is in
  # - {prefix}: The prefix of the player sending the message
  # - {suffix}: The suffix of the player sending the message
  # ... PlaceholderAPI placeholders are also supported here too!
  mc-to-discord-local: "**[Local]** {displayname}: {message}"

  # This is the message that is used to relay questions from minecraft chat in Discord.
  # The following placeholders can be used here:
  # - {username}: The username of the player sending the message
  # - {displayname}: The display name of the player sending the message (This would be their nickname)
  # - {message}: The content of the message being sent
  # - {world}: The name of the world the player sending the message is in
  # - {prefix}: The prefix of the player sending the message
  # - {suffix}: The suffix of the player sending the message
  # ... PlaceholderAPI placeholders are also supported here too!
  mc-to-discord-question: "**[Question]** {displayname}: {message}"

  # This is the message that is used to relay minecraft global chat in Discord.
  # The following placeholders can be used here:
  # - {username}: The username of the player sending the message
  # - {displayname}: The display name of the player sending the message (This would be their nickname)
  # - {message}: The content of the message being sent
  # - {world}: The name of the world the player sending the message is in
  # - {prefix}: The prefix of the player sending the message
  # - {suffix}: The suffix of the player sending the message
  # ... PlaceholderAPI placeholders are also supported here too!
  mc-to-discord-shout: "**[Shout]** {displayname}: {message}"

Discord: Configurable webhook name

You can now change the webhook name format for messages sent to Discord.

# The following entries allow you to customize the formatting of messages sent by the plugin.
# Each message has a description of how it is used along with placeholders that can be used.
messages:
  ...

  # This is the bot's name which appears in Discord when sending player-specific messages.
  # The following placeholders can be used here:
  # - {username}: The username of the player sending the message
  # - {displayname}: The display name of the player sending the message (This would be their nickname)
  # - {world}: The name of the world the player sending the message is in
  # - {prefix}: The prefix of the player sending the message
  # - {suffix}: The suffix of the player sending the message
  # - {botname}: Name of the Discord bot
  # ... PlaceholderAPI placeholders are also supported here too!
  mc-to-discord-name-format: "{botname}"

Other additions

• Translations have been updated with the latest community contributions from Crowdin.
• Added tab completions for the /mail clear command.
• Added the essentials.nick.hideprefix permission to hide the nickname prefix for those with it.
• Added per command cooldown permissions: essentials.commandcooldowns.bypass.<command name>.

Bug fixes

Bugs fixed from 2.19.7 and older versions

• Further duplication glitches were fixed in /recipe.
• Various performance issues with NPCs and jails have been fixed.
• Playtime statistics in /whois no longer overflow.
• Various offhand and inventory related issues have been fixed.
• Doubles are now supported for coordinates in the /tppos command in the console.
• Trade signs no longer accept water bottles as a valid trade for a potion.
• An exception is no longer raised in /tpoffline when the player's last location is not known.
• Sulk sensors no longer detect vanished players.
• The /top command now sends feedback once again.
• The /editsign command now calls the SignChangeEvent.
• Commands preformed on offline players no longer raise a NullPoinerException in some cases.
• Discord: The console relay no longer stops working after /ess reload in some cases.
• Discord: Webhooks should no longer hang the server during shutdown in some cases.
• Discord: Translated Discord command descriptions are now properly truncated to account for Discord character limits.

Regressions fixed from 2.20.0 dev builds

The following bugs from 2.20.0 development builds have been fixed:

• NPC users are once again added to the UserMap properly.
• Servers with large amounts of user data no longer hang for minutes on startup.
• The offhand is no longer used for /hat.
• The /createkit command works on 1.8.8 once again.
• Sending a mail to all online players works once again.
• The user map now properly expels users from cache after a while.
• Discord: Webhook names are no longer sanitized for markdown.
• Discord Link: The /link Discord command no longer requires administrator privileges.
• Discord Link: Synchronizing offline players no longer raises a NullPointerException

Changes for developers

Viewers can now be modified for DiscordRelayEvent

DiscordRelayEvent now has a getViewers() method which returns a mutable list of viewers for the relayed message.

Discord Link Module API

With the addition of the Discord Link Module, there is now an API service to access information about a player's Discord account that they have linked. You can obtain an instance of this and use it in tandem with the Discord module API like so:

// Gets the API service for EssentialsX Discord Link
final DiscordLinkService linkApi = Bukkit.getServicesManager().load(DiscordLinkService.class);
final String discordId = linkApi.getDiscordId(player.getUniqueId());

if (discordId == null) {
    // The player has no Discord account linked.
    return;
}

// Gets the API service for EssentialsX Discord which we will use to get the actual user
final DiscordService discordApi = Bukkit.getServicesManager().load(DiscordService.class);
final InteractionMember member = discordApi.getMemberById(discordId).join();
final String userTag = member == null ? null : member.getTag();

New events

EssentialsX 2.20.0 introduces several new events:

• GlobalChatEvent is fired when players send a message in global chat.
• LocalChatEvent is fired when players send a message in local chat.
• HomeModifyEvent is fired when a home is created, updated or deleted.

For a full commit log, click here.

EssentialsX 2.19.7 is here! 🎉 This release has several bug fixes for chat and other issues. Keep reading to see all the changes!

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

Finally, a massive thanks to our community members who have assisted countless people on GitHub and MOSS, including @triagonal, @JasonHorkles, @Evidentsinger14, @Chew, @Laarryy and many others.

In addition, a shoutout to our supporters on Patreon, GitHub Sponsors and Ko-fi. A special thanks goes to our Hero tier supporters:

• AKP
• Vestria MC
• @aternosorg
• @pebblehost

Want to be listed here? You can join our Hero tier on Patreon or GitHub at the links above!

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:

Supported server versions

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

• ✅ 1.18.2 and 1.19.2 - EssentialsX actively develops against and supports these versions.
• ⚠️ 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, and 1.17.1 - these versions are still supported, but are not a 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, /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 properly shows colours in EssentialsX's console log messages, including EssentialsX Chat messages.
• Paper contains countless overall performance optimisations over CraftBukkit and Spigot.
• Paper supports all properly-written plugins for CraftBukkit and Spigot.

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

• 🛑 "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 - 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 - EssentialsX is built for the Bukkit API, which does not properly support mods. For modded servers, use SpongeForge and Nucleus, or an alternative mod for Forge or Fabric.
• 🛑 1.7.10 or below.

Upgrading to 2.19.7

If you're upgrading from 2.19.3 or above, you can keep your current EssentialsX config file. There have been no changes to the configuration since that release.

Upgrading from 2.19.2 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.

Vanilla signed chat commands may show EssentialsX formatting on 1.19.1+

If you use any vanilla commands that send secure chat messages (including /minecraft:msg or /minecraft:me), you may see formatting from EssentialsX Chat in these messages. This is due to an implementation quirk in Spigot, which forces plugins to handle all secure previews for vanilla chat commands as if they were public chat messages. There is no known workaround for this at this time, but you can continue to use unsigned commands from EssentialsX and other plugins as normal.

Bug fixes

Bugs fixed from 2.19.6 and older versions

• Using /sudo to send a chat message as another user will no longer send their previewed message. (#5062)
• To prevent item loss, users can no longer use /invsee on themselves. (#5061)
• The /ess dump command no longer errors on 1.8.8. (#5067)
• Various notifications (including bans/kicks/mutes and /helpop) now show colors properly in the console. (#5075)
• Users with RGB permissions but without color permissions can now use RGB color codes properly. (#5076)
• Backup scripts now properly log errors again. (#5077)
• The /baltop command now works in command blocks. (#5078)
• Chat: Local chat messages are no longer sent globaly. (#5062)

Regressions fixed from 2.19.7 dev builds

There are no known regressions in 2.19.7 dev builds.

Changes for developers

There are no API changes in this release!

For a full commit log, click here.

EssentialsX 2.19.6 is here! 🎉 This release features slight additions, support for Minecraft 1.19.2, and several bug fixes. Keep reading to see all the changes!

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

Finally, a massive thanks to our community members who have assisted countless people on GitHub and MOSS, including @triagonal, @JasonHorkles, @Evidentsinger14, @Chew, @Laarryy and many others.

In addition, a shoutout to our supporters on Patreon, GitHub Sponsors and Ko-fi. A special thanks goes to our Hero tier supporters:

• AKP
• @aternosorg
• @pebblehost

Want to be listed here? You can join our Hero tier on Patreon or GitHub at the links above!

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:

Supported server versions

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

• ✅ 1.18.2 and 1.19.2 - EssentialsX actively develops against and supports these versions.
• ⚠️ 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, and 1.17.1 - these versions are still supported, but are not a 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, /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 properly shows colours in EssentialsX's console log messages, including EssentialsX Chat messages.
• Paper contains countless overall performance optimisations over CraftBukkit and Spigot.
• Paper supports all properly-written plugins for CraftBukkit and Spigot.

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

• 🛑 "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 - 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 - EssentialsX is built for the Bukkit API, which does not properly support mods. For modded servers, use SpongeForge and Nucleus, or an alternative mod for Forge or Fabric.
• 🛑 1.7.10 or below.

Upgrading to 2.19.6

If you're upgrading from 2.19.3 or above, you can keep your current EssentialsX config file. There have been no changes to the configuration since that release.

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

Important change: EssentialsX Chat now supports secure chat (#5030)

Minecraft 1.19.1 introduced a new Player Reporting feature on the client, allowing players to report chat messages to Mojang in-game. The server now has a secure chat system which allows players to preview and "sign" their chat messages, which ensures players can't use client mods to fabricate reports with fake messages. If the game can't verify a message, it will show a yellow warning indicator.

As of 2.19.6, EssentialsX Chat supports chat previews. Once you enable chat previews in your server.properties file, EssentialsX Chat will send back previews to players so they can send secure "signed" messages without the yellow warning indicator.

Players will need to accept previews when they join the server. They will also need to wait a second between finishing their message and pressing Enter to ensure their message gets previewed and signed.

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.

Vanilla signed chat commands may show EssentialsX formatting on 1.19.1+

If you use any vanilla commands that send secure chat messages (including /minecraft:msg or /minecraft:me), you may see formatting from EssentialsX Chat in these messages. This is due to an implementation quirk in Spigot, which forces plugins to handle all secure previews for vanilla chat commands as if they were public chat messages. There is no known workaround for this at this time, but you can continue to use unsigned commands from EssentialsX and other plugins as normal.

New features

EssentialsX now supports 1.19.2 (#4932, #4966, #5026, #5027, #5035)

EssentialsX now has full support for Minecraft 1.19.2, including support for the new Wild Update items in /give, /item and kits, new mobs, and new NMS/OBC mappings for accessing internal CraftBukkit code.

EssentialsX also no longer warns when installed on 1.19.2 servers.

Other additions

• Translations have been updated with the latest community contributions on Crowdin. (#4823)
• Console colors are once supported again on Paper. (#4941)
• Reduced the amount of user lookups during LuckPerms context calculations. (#4869)
• The /playtime command will now no longer appear to progress for vanished users. (#4918)

Bug fixes

Bugs fixed from 2.19.4 and older versions

• The /tpa command no longer double charges a user with /tpauto on. (#4862)
• The /nick off command can now be used by users with only essentials.nick.changecolors permissions. (#4876)
• The TeleportWarmupEvent event now has the correct teleporter. (#4913)
• Users who are flying while afk while freeze-afk-players is set to true will no longer be teleported to the ground. (#4944)
• Path and farmland blocks are no longer considered solid blocks. (#4915)
• The minecraft: namespace no longer gives an error in the /give command. (#4960)
• The /unlimited command no longer floods user's inventory when changing stack sizes. (#4877)
• Users who stop being afk no longer fail to count towards the sleep count in some cases. (#4985)
• The /nick command now shows your nickname even with change-displayname disabled in the config. (#4980)
• /ess dump no longer reports offline mode for servers behind Velocity on Paper 1.19 and above. (#5052)
• Discord: Console messages in Paper 1.18.2+ properly filter ANSI color codes once again. (#4942)
• Discord: Numerous discord formatting issues have been fixed in relation to slash commands. (#4945)
• Discord: Roles defined in the allowed-roles section of the config will no longer resolve to roles with the same name as another role's id. (#4983)
• Discord: Leave messages are no longer sent to discord when the user was vanished. (#5009)

Regressions fixed from 2.19.5 and 2.19.6 dev builds

• Essentials no longer fails to load on versions 1.8.8 through 1.12.2. (#4975)
• Local chat allows you to send messages that are 1 character long without sending in public chat. (#5041)

Changes for developers

There are no API changes in this release!

Note: 2.19.5 had an issue with proxy detection on Paper. 2.19.6 has been released to address this issue.

For a full commit log, click here.