EssentialsX/Essentials 2.18.0

EssentialsX 2.18.0 - The RGB Update

on GitHub

After many months of hard work, EssentialsX 2.18.0 is here! 🎉
This is the biggest EssentialsX release yet, and comes with tons of new features, brand new API and full support for 1.16.1, including RGB colours!

Thanks to @JRoy, @pop4959, @triagonal, @darbyjack, @latiku, @zml2008, @JasonHorkles and many other people who have contributed to this release!

In addition, thanks to our donors, in particular our Hero tier supporters on Patreon:

• AKP
• Wasted Ticks
• and 1 anonymous Hero

If your server makes money and you'd like to support the hard work that goes into EssentialsX, you can join our Patreon to support on a monthly basis, or make a one-off donation on Ko-fi.

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.15.2 and 1.16.1 - EssentialsX targets these versions as a priority.
• ⚠️ 1.8.8, 1.9.4, 1.10.2, 1.11.2, 1.12.2, 1.13.2 and 1.14.4 - these versions are still supported, but are not a priority for us.

We recommend using the latest version of Paper, as it includes several performance enhancements over Spigot. EssentialsX 2.18.0 includes significant improvements which are only effective on Paper, in particular async chunk loading and the return of /recipe.

Upgrading to 2.18.0

If you're upgrading from 2.17.2 or a recent dev build, you don't need to update your EssentialsX config. However, 2.18.0 adds several new features which you may want to configure, and to do so you'll need to update your config. Read on for a list of changes and new config options.

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

New features

EssentialsX now supports 1.16.1! (#3408, #3394, #3422)

EssentialsX has been updated to support the new items and mobs in 1.16.1! You can now spawn in new items using the new aliases in 2.18.0, and the new Nether mobs can be spawned in using /spawnmob.

In addition, you can now use RGB colours throughout EssentialsX using the &#RRGGBB format, including in chat, on signs, in /itemname and /itemlore, and in nicknames, prefixes and suffixes:

EssentialsX now supports async chunk loading for teleports on Paper! (#3102)

EssentialsX now performs teleport safety checks by loading chunks asynchronously where possible. This significantly reduces TPS drops from teleportation when EssentialsX is installed on Paper 1.9+. CraftBukkit and Spigot don't support these async chunk loading APIs, so if you're using CraftBukkit or Spigot, you should consider switching to Paper to take advantage of these improvements.

New /editsign command (#3415)

You can now update the content of signs you've already placed using the /editsign command. For example:

• Running /editsign set 1 &#b8ffbaMint green! while looking at a sign will set the first line of the sign to Mint green!
• Running /editsign clear 1 will clear the first line of the sign
• Running /editsign clear will clear the entire sign.

Note: to use formatting in /editsign, you need the essentials.editsign.<format> permissions - see the Color Permissions wiki page for more information.

New /itemlore command (#3331)

You can now create and modify lore on items using the /itemlore command! For example:

• Running /itemlore add [text] will add text to a new line at the end of the current lore on your currently-held item
• Running /itemlore set 1 [text] will replace the first line of the lore with new text
• Running /itemlore clear will clear the lore from the item

New /rest command to reset phantoms (#3205)

You can now use the /rest command to reset your last sleep time and stop phantoms from spawning.

messages.properties now supports UTF-8 properly (#3358)

At last, you can now type section signs (§) and non-Latin characters straight into your messages files, without needing to use \uXXXX escape codes!

Before:

deleteHome=\u00a76Home\u00a7c {0} \u00a76has been removed.
deleteJail=\u00a76Jail\u00a7c {0} \u00a76has been removed.
deleteKit=\u00a76Kit\u00a7c {0} \u00a76has been removed.
deleteWarp=\u00a76Warp\u00a7c {0} \u00a76has been removed.

After:

deleteHome=§6Home§c {0} §6has been removed.
deleteJail=§6Jail§c {0} §6has been removed.
deleteKit=§6Kit§c {0} §6has been removed.
deleteWarp=§6Warp§c {0} §6has been removed.

messages.properties now includes command usage and descriptions (#3284)

You can now customise and translate command usage and description messages in your messages.properties file by using the <command>CommandUsage and <command>CommandDescription keys. For example:

balancetopCommandDescription=Gets the top balance values.
balancetopCommandUsage=/<command> <page>
banCommandDescription=Bans a player.
banCommandUsage=/<command> <player> [reason]

These strings are also on Crowdin, and translators have started to translate the commands already. If you'd like to contribute to translations, you can contribute on Crowdin.

Note: don't remove or translate /<command> in usage strings, as this will break the usage message. If you notice this in any Crowdin translations, it would help if you could change these to include /<command> and report the string so we can fix it.

EssentialsX now supports LuckPerms contexts! (#3320, #3476)

EssentialsX now includes several LuckPerms permission contexts, allowing you to do complex conditional permission setups! You can now set certain permissions to only apply when a user is/isn't AFK, muted, vanished or jailed, as well as setting specific permissions for players in specific jails.

The full list of contexts is as follows:

• essentials:afk=<true/false>
• essentials:muted=<true/false>
• essentials:vanished=<true/false>
• essentials:jailed=<true/false>
• essentials:jail=<jail name>

Note: you need to install LuckPerms 5.0 or newer and Vault to use this feature.

Option to always run backups even if users haven't logged in (#3258)

In the past, EssentialsX's server backup system only ran if players had been online since the last backup. However, you can now configure it to always run a backup even if no players have logged in:

backup:
  #...
  # If true, the backup task will run even if there are no players online.
  always-run: false

/heal removing potion effects is now optional (#2754)

Previously, running /heal would always clear potion effects for players. This can now be disabled by setting the remove-effects-on-heal to false in config.yml.

Temporary mutes can now have a length limit (#2807)

Similar to temporary bans, you can now set a maximum length for tempmutes using the max-mute-time config option:

# Set the maximum time /mute can be used for in seconds.
# Set to -1 to disable, and essentials.mute.unlimited can be used to override.
max-mute-time: -1

Jailed players can now build if given specific permissions (#2503)

You can now use the following permissions to allow players to build while jailed:

• essentials.jail.allow-break to allow breaking blocks
• essentials.jail.allow-place to allow placing blocks
• essentials.jail.allow-block-damage to allow hitting blocks
• essentials.jail.allow-interact to allow interacting with blocks (usually right-clicking)

Teleporting to offline players (#2505)

You can now teleport to where a user last logged out using the /tpoffline <player> command (or /otp).

New EssentialsX Protect settings (#3111, #3210, #2504)

EssentialsX Protect now has several new config options to limit item damage, ender crystal explosions and various mob behaviours:

protect:
  prevent:
    # ...
    # Prevents the following events destroying dropped items
    lava-itemdamage: false
    tnt-itemdamage: false
    tnt-minecart-itemdamage: false
    fireball-itemdamage: false
    witherskull-itemdamage: false
    creeper-itemdamage: false
    # Prevents ender crystals from exploding
    ender-crystal-explosion: false
    # Prevents beds and respawn anchors from exploding
    bed-explosion: false
    respawn-anchor-explosion: false
    # Prevents zombies from breaking down doors
    zombie-door-break: false
    # Prevents Ravagers from stealing blocks
    ravager-thief: false
    # Prevents sheep from turning grass to dirt
    sheep-eat-grass: false

Option to dismount passengers before teleporting (#3069)

Players cannot teleport while they have passengers. Previously, teleports would silently fail, but you can now configure this behaviour:

# If a player has any passengers, the teleport will fail. Should their passengers be dismounted before they are teleported?
# If this is set to true, Essentials will dismount the player's passengers before teleporting.
# If this is set to false, attempted teleports will be canceled with a warning.
teleport-passenger-dismount: true

You can add the hidden force-passenger-teleport: true option to your config to revert this behaviour.

Option to show real names on /list (#3117)

You can now optionally configure /list to show players' real names in brackets in /list:

# Displays real names in /list next to players who are using a nickname.
real-names-on-list: false

Option to control whether AFK messages are broadcast (#2780)

You can now control whether AFK messages are broadcast to the whole server or only shown to the player they affect:

# When a player enters or exits AFK mode, should the AFK notification be broadcast
# to the entire server, or just to the player?
# When this setting is false, only the player will be notified upon changing their AFK state.
broadcast-afk-message: true

Option to control whether EssentialsX changes flight status and speed when changing worlds (#2546)

You can now toggle whether or not EssentialsX should handle disabling player flight/speed when they switch to a new world:

# The following settings listen for when a player changes worlds.
# If you use another plugin to control speed and flight, you should change these to false.

# When a player changes world, should EssentialsX reset their flight?
# This will disable flight if the player does not have essentials.fly.
world-change-fly-reset: true

# When a player changes world, should we reset their speed according to their permissions?
# This resets the player's speed to the default if they don't have essentials.speed.
# If the player doesn't have essentials.speed.bypass, this resets their speed to the maximum specified above.
world-change-speed-reset: true

This is useful if you use another plugin to manage these, such as Multiverse-Inventories.

Option to show currency symbol as suffix (#3066)

You can now configure EssentialsX to display the currency symbol as a suffix rather than a prefix:

# Enable this to make the currency symbol appear at the end of the amount rather than at the start.
# For example, the euro symbol typically appears after the current amount.
currency-symbol-suffix: false

Clearing specific item types using /clearinventory (#3263)

Before 2.16.0, you could clear specific item types using the /clearinventory command. This has now been re-added, so you can clear specific items once more! For example, /clear <player> stone,cobblestone will remove all stone and cobblestone from a player's inventory.

Option to display coordinates when a player dies (#3207)

You can now set the send-info-after-death option to true to display a player's coordinates when they die:

# When players die, should they receive the coordinates they died at?
send-info-after-death: false

Option to block /pay from players ignored using /ignore (#3273)

You can now configure EssentialsX to prevent ignored players from sending money through /pay:

# Enable this to block users who try to /pay another user which ignore them.
pay-excludes-ignore-list: false

New /tempbanip command (#3291)

You can now temporarily ban IP addresses from your server using /tempbanip:

Ability to change inventory title on [disposal] signs (#3269)

You can now set a custom name for [disposal] sign inventories:

Hats now respect the Curse of Binding (#3299)

You can no longer remove items with the Curse of Binding using /hat by default. To override this, give players the essentials.hat.ignore-binding.

Option to allow selling named items in /sell (#3314)

You can now set the allow-selling-named-items to true to allow players to sell custom named items:

# Allow selling of items with custom names with the /sell command.
# This may be useful to prevent players accidentally selling named items.
allow-selling-named-items: false

Options to customise how essentials.keepinv handles the Curse of Binding and Curse of Vanishing (#3328)

You can now configure how the essentials.keepinv permission behaves when players die while holding items with the Curse of Binding or Curse of Vanishing:

# How should essentials handle players with the essentials.keepinv permission who have items with
# curse of vanishing when they die?
# You can set this to "keep" (to keep the item), "drop" (to drop the item), or "delete" (to delete the item).
# Defaults to "keep"
vanishing-items-policy: keep

# How should essentials handle players with the essentials.keepinv permission who have items with
# curse of binding when they die?
# You can set this to "keep" (to keep the item), "drop" (to drop the item), or "delete" (to delete the item).
# Defaults to "keep"
binding-items-policy: keep

/sethome can now be configured to prompt before overwriting an existing home

You can now configure /sethome to prompt players to repeat the command before overwriting an existing home:

# Should players be asked to provide confirmation for homes which they attempt to overwrite?
confirm-home-overwrite: false

/recipe now works on Paper 1.15.2+ (#3404)

You can now use /recipe once again on Paper 1.15.2+. This feature was previously disabled on 1.12+ due to a missing Spigot API causing item dupes, but this has been addressed in Paper 1.15.2 and 1.16.1, meaning you can use /recipe once more.

New random teleport (RTP) feature (#3418)

EssentialsX now includes an RTP command called /tpr. EssentialsX will find and cache random locations, avoiding long delays while finding a safe spot to teleport to. This also supports finding safe spots to teleport to in the Nether and The End.

You can configure settings for /tpr using the /settpr command, including the teleport range, centre point, biome blacklist and cache settings. Third-party plugins can also hook into this using UserRandomTeleportEvent - see below for details.

/more now supports specifying an amount (#3302)

You can now specify what amount /more should increase stacks to by running /more [amount], or you can continue to use /more to set the stack to the maximum stack size as before.

Option to hide join/quit messages when the player count exceeds a limit (#3464)

You can now configure EssentialsX to hide join and quit messages when the player count exceeds a configurable limit:

# You can disable join and quit messages when the player count reaches a certain limit.
# When the player count is below this number, join/quit messages will always be shown.
# Set this to -1 to always show join and quit messages regardless of player count.
hide-join-quit-messages-above: -1

Other additions

• You can now hide yourself from /near by granting yourself the essentials.near.exclude permission. (#3049)
• /whois now includes the player's speed. (#2952)
• Attempting to run commands disabled in the disabled-commands section of the config will display an error message. (#2721)
• There are now separate meSender/meRecipient translation keys for "me" depending on the case for languages that vary "me" depending on sentence position. (#2805)
• You can now use the {UPTIME} placeholder in text commands. (#3120)
• You can now use /ecreative as an alias of /gmc to set your gamemode to creative mode. (#3101)
• [enchant] signs now default the enchantment level to 1 if no level is provided. (#3070)
• You can now control whether or not players can extinguish other players in /ext using essentials.ext.others. (#2826)
• You can now view the offhand slot in /invsee equip. (#3265)
• You can now use percentages in /eco. (#3080)
• Revoking the essentials.back.onteleport permission will prevent EssentialsX from storing the player's last location for /back. (#3272)
• /exp now has take and reset subcommands, similar to /eco. (#3335)
• You can no longer send /tpa and /tpahere requests to players if they don't have permission to /tpaccept them. (#3361, #3478)
• Commands and money in kits are now processed after items, preventing scenarios where players can claim parts of kits while lacking the inventory space. (#3434)
• Temporary mutes now show how long the player is muted for when they try to talk. (#3329)
• AntiBuild: Now supports permission checks and warnings for item frames, armour stands and ender crystals (#3270)
• XMPP: Now includes a more informative error message for the 8000 people who installed XMPP by accident and don't need it. (#3247)

API additions

EssentialsX 2.18.0 comes with various API additions for plugins that integrate with EssentialsX.

New AsyncTeleport API, and Teleport deprecation notice

As part of our effort to switch to async chunk loading, the Teleport and TimedTeleport classes has been deprecated. These APIs rely on synchronous chunk loads and can pause the main thread. If you'd like to continue using EssentialsX's teleport handling in your plugin, you should switch to AsyncTeleport and AsyncTimedTeleport, which use async chunk loading when run on Paper 1.13+.

New and improved events

AfkStatusChangeEvent now has a Cause enum (#3063)

You can now determine the cause of a AFK status change using AfkStatusChangeEvent#getCause, allowing you to identify why players enter/exit AFK mode.

MuteStatusChangeEvent now exposes the mute reason and timestamp (#3068)

You can now access the reason for a player's mute using MuteStatusChangeEvent#getReason. You can also access the timestamp at which their mute will be lifted using MuteStatusChangeEvent#getTimestamp (if the mute is permanent, this will return an empty Optional).

New teleport warmup and pre-teleport events (#3192)

You can now intercept EssentialsX teleports using the TeleportWarmupEvent to listen before the teleport warmup starts, and PreTeleportEvent to listen after the warmup and immediately before the teleport commences. You can also alter the warmup delay or even cancel the teleport using these events.

New event for teleporting to homes (#3403)

You can also now use the UserTeleportHomeEvent to intercept a player attempting to teleport to their home. This event is useful as it allows you to filter and cancel attempts to teleport to homes based on the home name, unlike PreTeleportEvent.

New KitClaimEvent (#3197)

You can block a player from redeeming a kit using the new KitClaimEvent, which is fired when a kit is being expanded for a player. You can also view the contents of the kit in the EssentialsX item meta format.

New pre-send and delivered private message events (#3260, #3432)

You can now intercept private messages before they're delivered or block certain private messages using the PrivateMessagePreSendEvent. This allows you to add custom filters in your plugin.

You can also listen for successfully-delivered private messages using the PrivateMessageSentEvent, which allows you to add custom notification effects like sounds or particles.

Event for filtering random teleport destinations (#3418)

You can listen to UserRandomTeleportEvent to intercept random teleports. This is useful if you maintain a land claiming plugin, and don't want players to be able to random teleport into towns or private builds.

UUID- and User-based economy methods (#3085)

The com.earth2me.essentials.api.Economy API now has methods to access the economy using player UUIDs and User instances, and the previous String-based methods have been deprecated. This does not currently affect Vault, however a new Vault provider is planned in the future.

ItemResolvers can now support /createkit (#3307)

If you use the ItemResolver API to add custom items to the items database, you can now implement the ItemResolver#serialize method to store these items when users run /createkit to create a kit.

Bug fixes

• /kit now respects the drop-items-if-full config option. (#2820)
• /fireball now works properly on all versions of Minecraft. (#3040)
• /exp, /spawnmob, /home and /suicide now have proper tab completion. (#3051, #2661, #3206, #3388)
• User#payUser now forwards the provided cause to the subsequent UserBalanceUpdateEvent event. (#3064)
• Local chat messages are now only logged once in the server console, not twice. (#2755)
• You can now set bed homes on older versions of Minecraft. (#3048)
• Several permissions are now defaulted to false for supported permissions plugins. (#3141, #3029)
• The register-back-in-listener config option and the vanish/godmode PvP checks now ignore Citizens NPCs. (#2833, #3389)
• Arrows and tridents fired by /fireball can no longer be picked up. (#3149)
• The default book.txt no longer has broken text formatting. (#3173)
• /balance no longer reveals vanished users. (#3218)
• Ignored players are now stored as UUIDs, preventing /ignore evasion through username changes. (#3209)
• Player logout times are now saved when the server shuts down. (#3157)
• The server now waits for ongoing backup tasks to finish before shutting down. (#3258)
• /depth is now based on the current world's sea level, rather than a fixed sea level of 63. (#3268)
• You can now /msg users who have 1-character-long names. (#3264)
• /tree and /bigtree now target blocks better. (#3271)
• ServerListPingEvents fired by CloudNet v3 are now silently ignored by EssentialsX. (#3288)
• /eco reset no longer requires an additional argument. (#3340)
• Players can no longer send empty shout/question messages. (#3341)
• Date diffs are now shown correctly throughout the plugin, including teleport warmups, tempmutes and tempbans. (#3292)
• worth.yml now encourages you to use the in-game /setworth command. (#3364)
• The /heal cooldown and teleport cooldown messages now have a red . instead of an erroneous gold . at the end. (#3366)
• /suicide and /kill now trigger PlayerDeathEvents with the correct DamageCauses. (#3388)
• /delkit is now case-insensitive, in line with /kit. (#3396)
• EssentialsX now warns in the console if other plugins include modified bStats Metrics classes which do not respect the bStats enabled: false config option. (#3451)
• /remove now removes skeleton horses that were spawned by a trap and tamed to skeletons. (#3477)
• GeoIP: The plugin now respects locale: zh and displays names in the zh-CN locale. (#3052)
• Spawn/XMPP: Commands are now hidden in 1.13+ autocomplete. (#3473)

Click here for the full commit log.