Download File

🎉 At long last, **EssentialsX 2.22.0 is here**! This release brings support for content from [The Copper Age](https://mdcfe.dev/mc-changes?ver=1.21.9), [Mounts of Mayhem](https://mdcfe.dev/mc-changes?ver=1.21.11) and [Tiny Takeover](https://mdcfe.dev/mc-changes?ver=26.1) 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](https://translate.essentialsx.net)! 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](https://translate.essentialsx.net) * Help users in our support channel on [Discord](https://discord.gg/casfFyh) * Fixing bugs or offering new features on [GitHub](https://github.com/EssentialsX/Essentials/blob/2.x/CONTRIBUTING.md) Finally, a shoutout to our supporters on [Patreon](https://www.patreon.com/essentialsx) and [GitHub Sponsors](https://github.com/sponsors/EssentialsX/)! 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: [](https://www.patreon.com/essentialsx) [](https://github.com/sponsors/EssentialsX/) ## Supported server versions EssentialsX officially supports the [Paper](https://papermc.io) 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.](https://essentialsx.net/do-not-use-mohist.html)** 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](https://www.curseforge.com/minecraft/mc-mods/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](https://github.com/EssentialsX/Essentials/releases). ## 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](https://hub.spigotmc.org/jira/browse/SPIGOT-5989). 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. ```yaml # 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: <img width="1560" height="135" alt="powertoollist" src="https://github.com/user-attachments/assets/a17a7ec2-9c3b-49b3-8d9a-2d89d6d30864" /> ### 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. ```yaml # 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. ```yaml # 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. ```yaml 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. ```yaml # 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](https://essentialsx.net/wiki/translations). (#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](https://essentialsx.net/wiki/translations). (#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](https://github.com/EssentialsX/Essentials/pull/6370) 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](https://github.com/EssentialsX/Essentials/compare/2.21.1...2.21.2).