EssentialsX 2.19.0 - The Cacophony Update Part 1

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

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

Thanks to @JRoy, @triagonal, @pop4959, @jpenilla and all our other contributors who contributed to 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 dozens of supporters on Patreon, GitHub Sponsors and Ko-fi!
A particular shoutout goes to our Hero tier supporters, including:

• AKP
• @aternosorg
• ...and 2 other anonymous Heroes

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.16.5 and 1.17.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, and 1.15.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, /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.19.0

If you're upgrading from 2.18.2, you can keep your current EssentialsX config file. However, 2.19.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.18.1 or older versions of EssentialsX? See the previous update changelogs.

New module: EssentialsX Discord! (#3844) 🎉

EssentialsX now has a Discord addon, which lets you easily bridge your Minecraft server with Discord with a bloat free and easy to understand configuration! You can read more about EssentialsX Discord 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.

Teleport requests can be dropped in rare cases

Due to a long-standing bug with teleport requests, in very rare cases teleport requests (/tpa, /tpahere, /tpaall) may expire instantly. We're working on an overhaul of the teleport request system with new features. If you encounter this bug on your server, it should be fixed in a future release.

Important changes

Userdata format changes (#4072)

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

Currency symbol handling improvements (#3628, #3946, #3987)

Some handling of currency symbols has been improved to be more consistent. If you encounter issues with kits.yml or currency on signs after updating to 2.19.0, you may need to update them to match the format set in your config (or simply change them to $123.45, which should always work).

You can also now set the currency symbol to empty and use translation keys to handle currency formatting, if you prefer.

New features

EssentialsX now supports 1.17.1 (#4211, #4324)

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

EssentialsX also no longer warns when installed on 1.16.5 servers.

New mail features (#3710)

The entire mail system has been rewritten to add support for temporary mails, read status, and the abiltiy to clear individual mails.

You can use /mail sendtemp <player> <expire time> <message> to send message which will expire at the given time or /mail clear <number> to clear the mail at the given position.

New /warpinfo command (#3820)

You can now use /warpinfo to view information about a warp:

New cancel-afk-on-chat setting (#3863)

You can now control whether chat cancels AFK for players separate to other types of interaction:

# Should we automatically remove afk status when a player sends a chat message?
cancel-afk-on-chat: true

New kit-auto-equip setting to auto equip armor from kits (#3704)

You can now set kit-auto-equip to true in config.yml to automatically equip armor when players redeem kits.

# When enabled, armor from kits will automatically be equipped as long as the player's armor slots are empty.
kit-auto-equip: false

New jail-online-time setting (#3705)

You can now set jail-online-time to true in config.yml to only count down time for jailed players while they're online.

# Whether or not jail time should only be counted while the user is online.
# If true, a jailed player's time will only decrement when they are online.
jail-online-time: false

Option to disable EssentialsX's custom full server message (#3899)

You can now disable EssentialsX's custom "This server is full!" message and restore the vanilla message by setting use-custom-server-full-message to false in config.yml:

# Should Essentials override the vanilla "Server Full" message with its own from the language file?
# Set to false to keep the vanilla message.
use-custom-server-full-message: true

Option to disable message social spy (#3910)

You can now disable private messages showing in social spy by setting socialspy-messages to false in config.yml:

# Whether social spy should spy on private messages or just the commands from the list above.
# If false, social spy will only monitor commands from the list above.
socialspy-messages: true

This is useful if you only want to monitor specific commands in social spy.

New /kitreset command to reset kit cooldowns (#3909)

You can now run /kitreset <kit> to reset the cooldown for a kit. If you have the essentials.kitreset.others permission, you can also reset kits for other players with /kitreset <kit> [player].

You can combine this command with single-use kits to more precisely control when players are allowed to claim kits.

EssentialsX Chat: world aliases (#3912)

You can now configure aliases for worlds in config.yml. If an alias is configured, EssentialsX will use it in place of the world's name when formatting chat. For example:

chat:
  ...
  # World aliases allow you to replace the world name with something different in the chat format.
  world-aliases:
    world: "&dmain&r"

/editsign copy and /editsign paste (#3989)

You can now copy and paste signs using /editsign copy and /editsign paste. This also checks formatting permissions to ensure players can't bypass their formatting permissions.

New command signs for virtual crafting commands (#3961)

You can now create [workbench] signs, and if you're running Paper 1.15.2 or newer, you can also now create [anvil], [cartography], [grindstone], [loom] and [smithing] signs. These can be enabled from the config and use the same permissions as other command signs.

EssentialsX Chat: new /toggleshout command (#3965)

If you use EssentialsX Chat's local chat system, you can now enable /toggleshout on your server to let players toggle between global and local chat.

EssentialsX update checker (#3855)

EssentialsX now automatically checks for updates, and can notify you if a new release is available. If you're running dev builds, it will also notify you about new dev builds.

Privacy note: the update checker uses the public APIs for Jenkins and GitHub, and does not send any identifying data about your server or players to any services. Nevertheless, if you want to disable update checking entirely, you can do so in config.yml.

More keywords in EssentialsX Chat, /info text commands, custom books and custom join/quit messages (#4098, #4169)

EssentialsX Chat now supports the {NICKNAME} placeholder in chat formatting, in case you want to exclude the player's prefix/suffix.

You can also now use {NICKNAME}, {PREFIX}, {SUFFIX}, {GROUP} and {PLAYTIME} in EssentialsX's text commands and books. Click here for a full list of keywords supported by EssentialsX.

Finally, you can now use {PREFIX} and {SUFFIX} in the custom-join-message and custom-quit-message settings in config.yml. See the config comments for other placeholders you can use.

Enhanced command usage messages (#4057, #4396)

EssentialsX now has enhanced command usage messages, showing the various different syntaxes that different commands support. These new usage messages are also fully translatable!

These can be disabled with the verbose-command-usages in the config.yml

If you spot any issues with the command usage messages in English, please open an issue on EssentialsX. For translated messages, please report incorrect translations and suggest improves ones on Crowdin.

/createkit now saves written book pages (#4048)

Previously, /createkit would only saved the title and author for written books, but it now saves the pages inside books as well. This means you can now create kits with written books fully in-game!

This also works for book and quills.

kits:
  mykit:
    delay: 0
    items:
    - written_book 1 title:My_Epic_Book author:JRoyLULW page1:My_epic_page page2:It's_been_like_a_year_since_the_last_release_lol
      page3:page3.ogg

Option to ignore vanished players from the vanilla sleep requirement (#4200)

By default, vanished players no longer have to sleep to skip the night. You can disable this behaviour by changing sleep-ignores-vanished-player to false in config.yml:

# Should vanished players be ignored when other players are trying to sleep?
# When this setting is false, player's won't be able to skip the night if vanished players are not sleeping.
# Users with the permission node essentials.sleepingignored will always be ignored.
sleep-ignores-vanished-player: true

Option to hide negative and zero balances from /baltop (#4226)

You can now set the show-zero-baltop option to false in config.yml to hide players from /baltop if they have a zero or negative balance:

# Whether or not users with a balance less than or equal to $0 should be shown in balance-top.
# Setting to false will not show people with balances <= 0 in balance-top.
# NOTE: After reloading the config, you must also run '/baltop force' for this to appear
show-zero-baltop: true

Home cleanup utility (#4244)

You can now use the /ess homes command to fix and/or purge all homes:

• /ess homes fix deletes all homes that are in worlds that don't exist or are unloaded.
• /ess homes delete deletes all existing homes on your server.
• /ess homes delete <worldname> deletes all homes set inside a specific world.

/createkit now supports optional NBT serialization (#3248)

You can now create exact NBT clones of items in /createkit! Rather than using EssentialsX's item meta system, these kits are stored as NBT in base64 format and can be identified with the @ at the start. You can turn this on using the use-nbt-serialization-in-createkit option in config.yml.

use-nbt-serialization-in-createkit: false

kits:
  mykit:
    delay: 0
    items:
    - written_book 1 title:My_Epic_Book author:JRoyLULW page1:My_epic_page page2:It's_been_like_a_year_since_the_last_release_lol
      page3:page3.ogg

use-nbt-serialization-in-createkit: true

kits:
  mykit:
    delay: 0
    items:
    - "@H4sIAAAAAAAA/22OvU4DMRCEJ0SHzIGoELQrN3Q0dKHjpwCFBilQRpvL5rKKsSN7IzihvBBPyV2T\r\
      \ninI0881MDYxx+sjG75KLpgjUvw5HusTlp0ZpMq9s8pXVTOJ8kdKmxti4PUG15VaKw1Bw9eNNvs1P\r\
      \n/GtHstWGBtPvcXcwnu260EIkUtCNEFMnnKlobIRsLRS4GGUJwqUXKfTwxQEe2m5vUtv6vcP5SoNJ\r\
      \nluXc1ILgrN98Gjbv+3cOx7yzdcpwL2+pm86mHw7VP0GMUD2kXbQR/gCsjqo1BAEAAA==\r\n"

Note that these kits cannot be edited by hand. If you need to edit kits by hand, you can turn this option off. In addition, this only works on Paper 1.15.2+, as Spigot does not expose item NBT methods.

Other additions

• Translations have been updated with the latest community contributions on Crowdin.
• The name used for messages from the console can now be translated using the consoleName key. (#3700)
• trade.log now includes the resulting balance after transactions take place. (#3721)
• Players can now middle-click while in viewing another player's armor with /invsee. (#3893)
• Players can no longer take off hats that have the Curse of Binding using allow-direct-hat unless they have the essentials.hat.ignore-binding permission. (#3895)
• Players can now pay offline players with /pay if they have the essentials.pay.offline permission. (#3625)
• EssentialsX now considers 1.16.5 a supported version. (#3923)
• EssentialsX now warns you about more potential server software incompatibilities. (#3812)
• You can now use /alts <username> to look up potential alts of a player. (#3931)
• [enchant] signs can now include material tags to allow enchanting multiple types of items. (#3694)
• /jail will now infer the jail name if only one jail has been set on the server. (#3911)
• /itemdb now shows custom aliases added in custom_items.yml. (#3907)
• EssentialsX now includes new warnings if issues with userdata or usermap are detected. (#3969)
• command-cooldowns can now be applied to aliases created using Bukkit's commands.yml. (#3744)
• /seen now displays UUIDs for players. (#3906)
• /spawner now requires the essentials.spawner.delay permission to change a spawner's delay. (#3964)
• You can now spawn mobs carrying netherite swords and armor using /spawnmob. (#4031)
• Commands in disabled-commands are now unregistered from the Bukkit command map. (#4026, #4108, #4399)
• Trade signs now validate sign line length more consistently. (#4056)
• /pay no longer works on vanished players. (#4114)
• [time] and [weather] signs can now display the current time and weather respectively if the rest of the sign is blank. (#4131)
• You can now limit /itemname to specific items using essentials.itemname.prevent-type.<item> permissions. (#4133)
• Fireworks, firework charges, potions and banners can now be enchanted in /give, /item and kits. (#3882)
• You can now use /ice to temporarily apply the "freezing" effect to players. (#4211)
• Custom item aliases are no longer case sensitive. (#4295)
• You can now set a seperate join message for when a player changes their name using the custom-new-username-message option in config.yml. (#4290)
• You can now show nicknames in tab completion instead of usernames by changing the change-tab-complete-name option. (#4432)
• Spawn: You can now set respawn-at-home-bed: false in the config.yml to prevent players respawning at their bed. (#3802, #4071)
• XMPP: TLS is now enabled by default. (#4002)
• XMPP: The configuration is now fully documented. (#4002)

Bug fixes

Bugs fixed from 2.18.2 and older versions

• Links in config.yml have been updated to point to the new EssentialsX domain. (#3779)
• EssentialsX now starts up properly on unexpected 1.8.8-R0.2 versions. (#3817)
• EssentialsX now hands over to commands dynamically registered by other plugins at runtime. (#3816)
• /me now calculates the chat radius correctly. (#3848)
• API events no longer share a common handler list. (#3853)
• EssentialsX now includes a special workaround to relay the /t command to Towny (previously Towny did not allow us to relay this command properly). (#3856)
• /list no longer shows the user's real name in brackets if they don't have a nickname. (#3858)
• /depth usage messages now include the correct command alias. (#3832)
• /tpoffline now has a /etpoffline alias. (#3832)
• /warp no longer says the player is about to teleport when the teleport is cancelled by a cooldown. (#3696)
• /sell blocks and /worth blocks now filter items in the player's inventory correctly. (#3691)
• EssentialsX no longer displays usage messages for its own commands when it relays commands to other plugins. (#3904)
• /ess commands no longer displays the plugin namespace twice for relayed commands. (#3904)
• EssentialsX can now detect enchantments registered with Bukkit with improper names. (#3900)
• bPermissions is now properly flagged as unsupported. (#3928)
• Firework item meta is now serialised and deserialised properly, including fixing meta for firework charges. (#3905)
• /nick now prevents duplicate nicknames when players' display names are modified (eg prefixes/suffixes). (#3922)
• AFK toggle messages are no longer sent if the AFK event is cancelled by another plugin. (#3915)
• Some previously-unresolved teleports are now completed properly. (#4016, #4066)
• /list no longer exposes groups whose players are all hidden. (#4032)
• /createkit with pastebin-createkit: true now uploads kits to paste.gg instead of hastebin.com. (#4049)
• Permission-based item spawning now works correctly again (the first time since EssentialsX 2.15). (#4100)
• /createkit now converts formatted item names and lore back to & code formatting. (#4095)
• custom_items.yml no longer suggests using a nonexistent command to manage it. (#4152)
• /ptime, /pweather, /time and /unlimited now include spacing in comma-separated lists. (#4157)
• EssentialsX now adds a custom NBT tag to avoid converting spawners created by other plugins. (#3963)
• /book now supports multi-word book titles and authors. (#4180)
• /back now tracks previous locations from teleports once more if players have the essentials.back.onteleport permission. (#4264)
• /powertool a:<command> and /powertool r:<command> no longer throw errors if the powertool list doesn't exist. (#4276)
• The tab completion for /itemlore and /itemname have been improved to reflect their actual behavior. (#4280)
• Invalid enchant names now have a nicer error message. (#4297)
• Players' logout locations is now properly set on server shutdown. (#4318)
• Spawn eggs which were missing on legacy versions have now been re-added. (#4320)
• Teleporting to offline players without the essentials.tpoffline permission in /tp no longer has a vaugue error. (#4332)
• Teleport cooldowns are now respected again for /spawn. (#4335)
• EssentialsX now sanitizes usernames when generating NPC UUIDs. (#4484)
• EssentialsX now cleans up broken NPC accounts from the older Vault integration. (#4490)
• AntiBuild: Block replacements (ie using Eyes of Ender on an End Portal Frame) are no longer considered block placements. (#3914)
• AntiBuild: Players with the essentials.build.* permission can now pickup items. (#4273)
• Geo: Dependencies are now correctly relocated. (#3976)
• Geo: Messages displayed on join now include the player's displayname rather than just their unformatted username. (#3968)
• Protect: protect.prevent.respawn-anchor-explosion now prevents respawn anchor explosions in more cases. (#3778)
• Protect: protect.prevent.tnt-playerdamage no longer prevents damage from bed explosions. (#3874)
• XMPP: Commands executed from XMPP are now dispatched on the main thread. (#3803)

Regressions fixed from 2.19.0 dev builds

• Spam has been removed from Spanish translations. (2342d53)
• /delwarp now shows the "warp deleted" message as it did before #3875. (#3927)
• Jail time is now formatted correctly in /seen, /whois and /togglejail again. (#3917, #3941)
• bStats now initialises after the update checker to fix an issue with branch reporting. (#4037)
• Update checks no longer fail if the commit count is greater than 2 digits. (#4069)
• kit-auto-equip now works on versions below Minecraft 1.14. (#4130)
• EssentialsX no longer recursively resolves its own commands as alternatives to themselves. (#4128)
• The Vault integration now also looks up accounts using legacy NPC:<accountname> UUIDs, in case a plugin generated NPC accounts on an older version of EssentialsX. (#4178, #4188)
• GitHub Actions builds of EssentialsX now embed the correct branch name. (#4193)
• EssentialsX now creates economy accounts as needed for players who last joined before EssentialsX was installed. (#4199)
• sleep-ignores-vanished-player no longer overrides the essentials.sleepingignored permission. (#4201)
• Various issues from the Configurate refactor have been fixed. (#4203, #4206, #4208, #4209, #4210, #4213, #4214, #4216, #4217, #4218, #4219, #4230, #4234, #4237, #4240, #4249, #4251, #4264, #4294, #4305, #4341, #4345, #4428, #4475)
• show-zero-baltop: false now hides zero and negative balances, not positive balances. (#4228)
• The Vault economy provider now properly loads 3rd party economies. (#4303)
• Headless JREs no longer throw an error when using hex color codes.(#4312)
• Force disabling teleport safety also disables the world border check. (#4371)
• The update check is no longer dependent on the MOTD being enabled. (#4410, #4411, #4454)
• /ess dump now works on 1.8.8, which ships an ancient version of Gson. (#4489)
• NBT serialized items in kits now also respect the kit-auto-equip option. (#4491)
• Chat: World aliases now actually check the world aliases config option, and not the entire config file. (#4000)
• Discord: Vanilla commands now work as expected in the Discord /execute command. (#4293)

Changes for developers

EssentialsX is now built with Gradle (#3720, #4148, #4202, #4496)

Thanks to @JRoy and @jpenilla, we've converted the EssentialsX build setup to use Gradle. This has sped up build times considerably. In addition, thanks to the awesome jpenilla/run-paper Gradle plugin, developers working on EssentialsX can now spin up a Paper test server by running ./gradlew runServer.

EssentialsX now has a dedicated Maven repo (#3720)

Starting with 2.19.0, EssentialsX now has a dedicated Maven repository. To depend on snapshots, you'll need to update your build scripts to use the URL https://repo.essentialsx.net/snapshots/, or for releases you'll need to use the URL https://repo.essentialsx.net/releases/. New builds and releases will no longer be available from the old repository, so you'll need to update to use new APIs.

EssentialsX now publishes Javadocs (#4083, #4140, #4141)

Starting with 2.19.0, EssentialsX now publishes browseable Javadocs at jd-v2.essentialsx.net. You can also see Javadocs for other modules by adding the name of the module (for example, jd-v2.essentialsx.net/essentialsdiscord to view docs for EssentialsX Discord).

Please bear in mind that although these Javadocs cover the entire plugin, many classes are internal and subject to change. We recommend only using classes inside the com.earth2me.essentials.api, net.ess3.api and net.essentialsx.api.v2 packages where possible, as these are designated API and unlikely to break between versions (though parts of legacy APIs in the com.earth2me.essentials and net.ess3 packages could still break in future 2.x versions).

Item names passed to ItemResolvers are no longer automatically lowercased (#3636)

You can now resolve case-sensitive item names in your plugins' ItemResolvers. If your plugin does not already lowercase entries, you may need to update your plugin to handle mixed-case item names.

New BalanceTop API (#3702)

EssentialsX now exposes the /baltop system as an API service. You can obtain an instance of this and use it like so:

final BalanceTop baltop = Bukkit.getServicesManager().load(BalanceTop.class);
baltop.calculateBalanceTopMapAsync().thenAccept(finish -> {
        processCache(baltop.getBalanceTopCache());
});

Economy integration rewrite (#3975, #4147, #4149, #4151, #4484, #4490)

EssentialsX's economy integrations have been rewritten from scratch. This aims to improve compatibility with problematic plugins such as Towny. If your plugin integrates with EssentialsX's economy directly or via Vault, please test your plugin with EssentialsX 2.19.0 to ensure that users do not lose any data when they update.

EssentialsX now uses the Configurate library (#4072)

EssentialsX's config and data storage now use the Configurate library! This replaces the legacy Bukkit and Essentials 3 code.

If you maintain a plugin that hooks into EssentialsX's configuration or data code, beware that many legacy config methods and classes may have been deprecated and/or removed. You should use proper EssentialsX APIs instead of hooking directly into the configuration where possible.

New events

EssentialsX 2.19.0 introduces several new events:

• TransactionEvent is fired when players pay money to other players with EssentialsX's /pay command. (#3649)
• UserKickEvent is fired when players are kicked using EssentialsX's /kick command. (#3490)
• WarpModifyEvent is fired when a warp is created, updated or deleted with /setwarp or /delwarp. (#3875)
• UserTeleportSpawnEvent is fired when a player is about to be teleported to a spawn due to /spawn. (#4328)

Other changes

• Plugins can now register their custom Bukkit enchantments with EssentialsX's /enchant command. (#3669)

For a full commit log, click here.