EssentialsX 2.22.0 - The Tiny Copper Mayhem Update

[mdcfe]

🎉 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. (Add tipped arrow support to /potion #6191)
• The /heal command now restores your oxygen levels. (Reset oxygen with /heal #6201)
• The economy-log-uuids setting now allows you to print UUIDs to the trade.log file rather than usernames. (Add option to use UUIDs over usernames in trade.log #6252)
• The essentials.seen.firstlogin permission now allows the /seen command to show the date a player first joined the server. (Add first login date to /seen #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. (Add support for LuckPerms group names #6229)
• You can now use @s and @p selectors in EssentialsX commands to refer to the player executing the command. (Add @s and @p selector support #6110)
• Armor trim patterns are now supported in /give, /item and kit metadata. (Adds support for armor trims inside kits #6155)
• EssentialsX now uses Paper's configuration phase APIs to async load user data before a player joins the world. (Switch to configuration based events on Paper #6248)
• The /recipe command can now show recipes for crafting_transmute recipes, such as recolouring bundles with dye. (Add support for transmute recipes in /recipe #6302)
• You can now suppress the standard "CONSOLE issued server command: ..." message for console and RCON messages using the log-console-commands config option. (Add config option for logging console/RCON commands #6337)
• When a user tries to join after being temporarily IP banned, they will now see the expiration time in the ban message. (Show expiration on temporary IP ban kick message #6407)
• The /essentials command has been significantly refactored to improve code quality. (Command Trees v2 #6230, Add alias "ver" for the "version" subcommand #6481)
• The /gc command is now faster to call on Paper servers. (Improve gc command performance #6439)
• EssentialsX now directly uses Paper's native Adventure API functions where available. (Move away from adventure-platform for Paper #6220)
• You can now block players from fishing while AFK using the cancel-afk-on-fish config option. (Add option to allow fishing when afk #6465)
• EssentialsX can now restore custom flight mode settings when a player rejoins the server after quitting while in flight. (fix(fly): persist fly mode and restore on join #6403)
• The default nickname length limit has been increased from 15 to 16 to align with Minecraft's username length limit. (Change default max-nick-length to 16 #6484)
• You can now modify the formatting used when displaying player commands in SocialSpy by setting the socialSpyCmdFormat key in your locale file. (Add socialSpyCmdFormat message key for command social spy #6489)
• You can now disable picking up items in /vanish mode by granting the essentials.vanish.pickup permission. (Add permission cache system + permission for vanish item pickup #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. (Fix incorrect teleport safety message #6486)
• Vanished players will no longer broadcast advancement messages. This feature requires a server running Paper. (Suppress advancement broadcast for vanished players on Paper #6513)
• Discord: You can now use PlaceholderAPI placeholders inside the avatar-url config option. (Discord: Add PAPI support to avatar-url #6189)
• Discord: You can now configure an HTTP proxy through which the plugin will connect to Discord using the http-proxy-server config option. (Discord: Add setting to configure an HTTP Proxy for JDA #6275)
• Discord: The plugin now warns you when permissions are missing from the Discord bot. (Add message when discord bot is missing permissions #6228)
• Discord: The console relay filter now also applies to the logger name. (Use Discord name instead of tag for /msg sender #6383)
• Geo: Join messages are now printed to the console, not just to admins. (Send geoip join messages to console #6523)
• Protect: You can now disable the knockback effect from wind charges with by setting protect.prevent.windcharge-explosion to false. (Add wind charge explosion protect config #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. (Ignore cancelled PlayerDeathEvents #6179)
• Players can no longer use click-and-drag to move items around when in /invsee, preventing potential item loss. (Prevent dragging items outside of invsee #5902)
• EssentialsX can now parse Minecraft version names for snapshots and for Mojang and Paper's new version naming schemes. (Add support for snapshots in VersionUtil #6265, Minecraft 26.1 #6473, Support new PaperMC versioning scheme in VersionUtil #6480, Fix version comparison logic for pre-release/snapshot/rc variants #6483, Fix version parsing for local paper builds #6501)
• Read-only /invsee access will no longer degrade to full modify permissions after heavy garbage collection. (Able to manipulate /invsee without modify permissions #6241, Maintain strong reference for online users #6247)
• The /potion command now properly parses -1 as an infinite duration for potion effects. (Fix potion command not supporting infinite durations #6236)
• Fuzzy/partial name resolution in command arguments is now more reliable. (Fix matching players with similar names #6263)
• The /tpr command now correctly resets its cached location list after /settpr has run and changed the /tpr settings. (Fixes stale cached locations after using /settpr #6305)
• EssentialsX no longer replaces the vanilla join message when no custom message has been set, allowing the vanilla translated message to show correctly. (Fix updating join message when not needed #6312)
• Various issues with the Configurate refactor have been resolved. (Improve memory resilience with Configurate #6266)
• The UUID cache now buffers disk reads and writes. (Buffer reads/writes to uuid cache #6338)
• The /heal command no longer sends a duplicate message when running it on yourself. (Fix double messages when running /heal on self #6347)
• Checking the server state on Spigot no longer fails. (Fix Spigot 1.21.10+ ReflServerStateProvider #6377)
• The /helpop command now correctly shows messages when run from the console. (Messages /helpop not visible if the sender console. #6342)
• /balance no longer reveals when players are vanished. (Vanished players matched by nickname/online only commands #6085)
• Getting permissions handlers no longer throws a NullPointerException. (Fix NPE in PermissionsHandler#getGroups(OfflinePlayer) #6398)
• Getting the player locale for an offline player no longer throws a NullPointerException. (Prevent NPE in getPlayerLocale for offline players #6435)
• The /nick command now correctly shows the appropriate message when a players' nickname is removed. (Fixed unreachable nickNoMore Message in /nick command. Not a huge change.  #6442)
• The /give command can no longer be used to freeze the server. (Fix server freezing with /give #6449)
• The /burn and /more commands are now more resilient against integer overflow exploits. (Fix integer overflow with /burn + /more & fix % in chat formats #6452)
• The /thunder command now correctly displays MiniMessage in its output. (Add MiniMessage support for thunder enabled / disabled #6454)
• The /recipe command can no longer be used while the player is asleep to spawn in infinite diamonds. (Prevent running recipe command while sleeping #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. (Reject Windows reserved filenames in /setwarp #6487)
• The /walkspeed and /flyspeed (and similar aliases) now always modify walking or flight speed specifically. (Make /flyspeed and /walkspeed force the correct speed type #6485)
• The /eco command now respects locale-specific decimal separators, including per-player locales if enabled. (Fix /eco ignoring locale-specific decimal separators #6511)
• The /time command no longer overrides a player's own /ptime setting. (Fix /time overriding player's /ptime setting #6509)
• Command descriptions are now printed in /help and usage messages using the player's locale. (Fix command descriptions not using player's locale #6508)
• The player's display name formatting no longer bleeds beyond the player name when printing local chat in SocialSpy. (Fix SocialSpy local chat color bleeding from player display name #6507)
• Commands in kits no longer wrongly translate underscores to spaces during keyword replacement. (Fix {USERNAME} underscore escaping in kit items #6514)
• The console name is now read from the consoleName translation key properly. (Fix consoleName translation key not working #6506)
• Running /home bed now correctly ensures the player has the essentials.home.bed permission before teleporting the player. (Fix essentials.home.bed permission being ignored #6516)
• Economy deposits (balance increases) are no longer rejected when the player's balance is below the minimum. (Fix deposits rejected when account has negative balance #6515)
• The nonexistent essentials.jail permission has been removed from plugin.yml. (Remove unused essentials.jail perm #6539)
• AntiBuild: Shear interactions are now handled correctly. (AntiBuild: Properly handle shear interactions #6262)
• Chat: % symbols will no longer cause chat processing to throw exceptions. (Fix integer overflow with /burn + /more & fix % in chat formats #6452)
• Discord: Advancement messages are no longer sent to Discord if the announceAdvancements gamerule is set to false. (Discord: Respect game rule for advancement message type #6195)
• Discord: Sending a private message from Discord to Minecraft no longer includes an empty discriminator tag. (Use Discord name instead of tag for /msg sender #6383)
• Discord: Webhooks are now far less likely to trigger Discord ratelimits (HTTP error 429). (Mitigate Discord 429s #6461)
• Discord: Fake join and quit messages no longer throw a NullPointerException due to a historical parameter mixup. (Fix VanishStatusChangeEvent NPE and document parameter inversion #6510)
• Discord Link: Role syncis is now far less likely to trigger Discord ratelimits (HTTP error 429). (Mitigate Discord 429s #6461)
• Discord Link: Role syncing no longer leaves a thread running in the background when the plugin shuts down. (Fix Discord Link RoleSyncManager thread leak #6512)
• Spawn: Getting the player's respawn location no longer throws an exception on Minecraft 1.16.x-1.20.3. (Fixed NoSuchMethodException Player.getRespawnLocation() #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. (Do not lowercase afk timeout commands #6255)
• The essentials.powertoollist is no longer omitted from plugin.yml. (Fix missing powertoollist permission #6250)
• Players are now evicted from the online user cache, not the persisted UUID map, when they log out. (Fix issue with offline player data #6284, Fix issue with "Fix issue with offline player data" #6286)
• EssentialsX no longer throws exceptions when players join for the first time. (Fix exception during first time joins #6327)
• The TeleportWarmupCancelledEvent now tracks the thread it was called from to prevent throwing an exception every time it fires. (Fix event thread assignment in TeleportWarmupCancelledEvent #6371)
• Players without the essentials.joinfullserver permission are no longer kicked even when the server isn't full. (Fix preventing joins when server isn't actually full #6426)
• The /ess reload command is available once more. (Fix /ess reload #6444)
• Bukkit-level plugin reloads are less likely to break the /essentials command. (fix(commands): propagate Essentials and module to tree nodes #6445)
• Flight is no longer re-enabled when the player logs in while in water. (Don't enable fly mode on login when player is in water #6490)
• EssentialsX no longer double-wraps URLs in click handlers, which would otherwise log an error on Paper. (Remove extractUrls from default legacy serializer #6492)
• The /list command now parses MiniMessage tags in players' displaynames. (Fix minimessage parsing in playerlist keyword replacement #6505)
• Discord: The emoji-java library is now correctly included in the plugin once more. (Fix stale shadow include group ID for emoji-java in EssentialsDiscord #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.

---

This discussion was created from the release EssentialsX 2.22.0 - The Tiny Copper Mayhem Update.