Personal tools

Configuration file

From Essentials

Jump to: navigation, search

Essentials ships with a configuration file (config.yml) that is generated on first run of the server after Essentials is installed. Below is an explanation of specific settings within that config file.

You can view the default configuration file here.

[string] denotes the entry needs to be enclosed in single quotes (').

[boolean] denotes the entry will accept only true or false.

[int] denotes entry accepts only digits.

[list] denotes the entry is list-based.

Essentials (Global)

ops-name-color: string (0-9 | a-f | k-o (text formatting) | none)

Specify a colour or a text formatter (bold, italic etc) for users who have 'op' status. Use the guide here for reference, but omit the preceeding ampersand symbol. Set to 'none' to disable.

nickname-prefix: string

The character(s) to prefix user nicknames. This allows them to be identified as such so that you know they are not true usernames. Note: True usernames from nicknames can be obtained through /realname and /whois.

max-nick-length: int

How long a user's nickname length is limited to, including prefix.

change-displayname: boolean

Set this to false if you have any other plugin that modifies the displayname of a user.

#change-playerlist: boolean

When this option is enabled, the player list (accessed via the tab key by default) will be updated with the displayname. The value of 'change-displayname' (above) has to be true. This setting is commented out by default, the hash at the start must be removed for it to function.

#add-prefix-suffix: boolean

When Essentials Chat isn't used, force Essentials to add the prefix and suffix from permission plugin to displayname. This setting is ignored if Essentials Chat is used, and defaults to 'true'. This setting is commented out by default, the hash at the start must be removed for it to function. The value of 'change-displayname' (above) has to be true. Do not edit this setting unless you know what you are doing!

teleport-cooldown: int (seconds)

The delay, in seconds, before teleport-based commands, such as /home, /spawn, and /warp, can be used again.

teleport-delay: int (seconds)

The delay, in seconds, before a player actually teleports. If the player moves or gets attacked within this time frame, the teleport never occurs.

teleport-invulnerability: int (seconds)

The delay, in seconds, before a player can be attacked by other players after they have been teleported by a command. This will also prevent the player attacking other players.

heal-cooldown: int (seconds)

The delay, in seconds, before /heal can be used again.

item-spawn-blacklist: item id

What to prevent from /i and /give e.g item-spawn-blacklist: 46,11,10 Note: you cannot use data values here, 17:3 will block ALL log types, not just jungle logs.

permission-based-item-spawn: boolean

Set this to true if you want permission based item spawn rules. You can then stipulate which items a user can spawn by using specific permissions. Note: If enabled the blacklist above will be ignored.

For more information, visit the Spawning page.

spawnmob-limit: int

How many mobs should be spawned per command execution for /spawnmob

warn-on-smite: boolean

If enabled, display "Thou hast been smitten!" to recipient in chat. This text can be overriden using custom locales.

overridden-commands: list (commands)

When a command conflicts with another plugin, by default, Essentials will try to force the OTHER plugin to take priority. Commands in this list will tell Essentials to 'not give up' the command to other plugins. In this state, which plugin 'wins' appears to be almost random.

If you have two plugins with the same command and you wish to force Essentials to take over, you need an alias. To force essentials to take 'god' alias 'god' to 'egod'.

See for more information.

disabled-commands: list (commands)

Prevent Essentials from handling the specified commands. Generally these apply to Essentials only commands.

socialspy-commands: list (commands)

These commands will be shown to players with socialSpy enabled. You can add commands from other plugins you may want to track or remove commands that are used for something you don't want to spy on.

player-commands: list (perms)

If you're not using a permission system, you can define a list of 'player perms' below. This list has no effect if you are using a supported permissions system. If you're using an unsupported permissions system, simply delete this section. These are the permissions with the "essentials." part omitted.

kits: list

Define custom kits here. All kit items MUST be followed by a quantity and all kit names should be lower case and will be treated as such in permissions/costs. The syntax to use is as follows:

itemID[:DataValue/Durability] Amount [Enchantment:Level].. [itemmeta:value]...

'delay' refers to the time between each kit usage specified in seconds. There is currently no way to define a 'one-off' kit other than providing extreme delays. 31556926 seconds (1 year) is usually sufficient in this case.

enabledSigns: list

See the Sign tutorial for instructions on how to use these. To enable specific signs, remove the # (comment) symbol. To disable all signs, comment/remove each sign. Essentials colored sign support will be enabled when any sign types are enabled. Enable 'Color' when you want standard non Essentials signs only, but WITH colour support. Remember to provide the appropriate permissions.

sign-use-per-second: int (seconds)

How many times per second signs can be interacted with, per player. Values should be between 1-20. Lower numbers will reduce the possibility of lag, but too low a setting may irritate players.


This is where you configure your backup options. Unless you add a valid script, this command is useless. If you wish to save your world without backing up, use /save-all instead.

per-warp-permission: boolean

Set to true to enable permissions per warp. This also allows fine grained control over warps and also warps listed with /warp. If, for example, you create a warp called 'mywarp' and you want to provide access to it, you can assign the associated permission 'essentials.warps.mywarp'.


You can sort the output of the /list command by groups here. For more information see the List page

debug: boolean

Provide debug output to the console, useful for checking permissions and command costs/usage. This is functionally identical to /ess debug but additionally outputs debug info on server startup.

remove-god-on-disconnect: boolean

Force god mode to be disabled when those users who have it enabled disconnect.

auto-afk: int (seconds)

How long in seconds until the player is automatically set to AFK. The player must have the '' permission node for this to work. Set to -1 to disable automatic AFK.

auto-afk-kick: int (seconds)

After the time specified (in seconds) the user will be kicked from the server. The 'essentials.afk.kickexempt' permission node overrides this feature. Set to -1 to disable auto AFK kick.

freeze-afk-players: boolean

Set this to true if you want to freeze the player while they are AFK, essentially providing a temporary god mode. Other players or monsters can't push the recipient to force them out of AFK mode. The /afk command or chat input will be needed to remove the player from AFK mode.

disable-item-pickup-while-afk: boolean

Disable the ability for players to pickup items when AFK. Enable this when, for example, you don't want people idling in mob traps.

cancel-afk-on-interact: boolean

This setting controls if a player is removed from AFK upon interaction. This could be any mouse click/item use or selection, but does not include movement, there is a separate option for that below. When this is set to false, you will need to manually exit AFK mode using the /afk command.

cancel-afk-on-move: boolean

Set to true to automatically remove AFK status when the player moves. Player will be removed from AFK on chat/command regardless of this setting. Disable this to reduce server lag.

death-messages: boolean

Show death messages from Minecraft. Set to false to suppress.

allow-silent-join-quit: boolean

If true, operators and users with the permission node essentials.silentjoin can join the server without a join message.

custom-join-message: string (message|none)

A custom join message for all users can be set here. Set to "none" to use default join message. In the message, you may use color codes, {USERNAME} the player's name or {PLAYER} for the player's display name.

custom-quit-message: string (message|none)

A custom quit message for all users can be set here. Set to "none" to use default quit message. In the message, you may use color codes, {USERNAME} the player's name or {PLAYER} for the player's display name.

no-god-in-worlds: list

Worlds listed here will disable the usage of god mode in that specific world. If entering the world with god mode enabled, it will be turned off.

world-teleport-permissions: boolean

Set to true to enable per-world permissions for teleporting between worlds with essentials commands. This applies to /world, /back, /tp[a|o][here|all], but not warps. Give someone permission to teleport to a world with essentials.worlds.<worldname> This does not affect the /home command, there is a separate toggle below for this.

default-stack-size: int

The number of items given if the quantity parameter is left out in /item or /give. If this number is below 1, the maximum stack size size is given. If over-sized stacks are not enabled, any number higher than the maximum stack size results in more than one stack.

oversized-stacksize: int

Over-sized stacks are stacks that ignore the normal max stack size. They can be obtained using /give and /item, if the player has essentials.oversizedstacks permission. How many items should be in an over-sized stack is set here.

repair-enchanted: boolean

Allow repair of enchanted weapons and armor. If you set this to false, you can still allow it for certain players using the permission

unsafe-enchantments: boolean

Allow 'unsafe' enchantments in kits and item spawning. Warning: Mixing and overleveling some enchantments can cause issues with clients, servers and plugins.

register-back-in-listener: boolean

Do you want essentials to keep track of previous location for /back in the teleport listener? If you set this to true, any plugin that uses teleport will have the previous location registered.

login-attack-delay: int (seconds)

The delay before anyone can attack a player who just logged in.

max-fly-speed: int (0.1-1.0)

The maximum flying speed.

mails-per-minute: int

The maximum number of mails that can be sent within a minute.

max-tempban-time: int (seconds)

The maximum length of time a player without the permission node essentials.tempban.unlimited can tempban someone for. Set to -1 to disable.

Essentials Home

update-bed-at-daytime: boolean

This setting, when true, allows people to update their bed during the day.

world-home-permissions: boolean

Set to true to enable per-world permissions for using homes to teleport between worlds. This applies to the /home command only.


 default: 3
 vip: 5
 staff: 10

Set how many homes people can have. Players need essentials.sethome.multiple before they can have more than 1 home, which defaults to 'default'. In this case, players with essentials.sethome.multiple can have 3 homes. In order for them to have 5 or 10 homes as set in config here, they would need or essentials.sethome.multiple.staff (respectively) in addition to essentials.sethome.multiple.

tpa-accept-cancellation: int (seconds)

How long a player has to respond to a teleportation request before he can no longer respond to it.


For more information, visit

starting-balance: int

How much money a player who just joined starts out with.


 example: 1000
 kit-tools: 1500

How much a command costs per use. In this case, the fictional command /example would cost 1000 units of currency, while /kit tools costs 1500 units.

currency-symbol: string

What symbol your unit of currency uses. If you use anything other than letters, numbers, spaces, and the $ character, odds are you WILL NEED to save the file as UTF-8 to avoid parsing errors. If you have 1000 units of currency and you set this to $, you will have $1000, whereas if you set it to € you will have €1000, if you set it to £ you will have £1000, etc.

If you wish to change which side of the amount of money your currency symbol goes on, you will need to edit your locale file. See the Locale page for more info as well as an example.

max-money: int, positive

The max amount of money that a player can have. Players will be unable to get more money than either this or 10,000,000,000,000 units, whichever they hit first.

Players will be unable to get more than 10 trillion units of currency due to Java limitations.

min-money: int, negative

The minimum amount of money can have, or the maximum amount of money a player can overdraft. Setting this to 0 will not allow players to overdraft. This number must be closer to zero than max-money is. Players need to overdraft.

economy-log-enabled: boolean

Logs all transaction with signs, as well as /buy and /sell.


non-ess-in-help: boolean

Set this to true if you want other plugins to show up in Essentials' /help command.

hide-permissionless-help: boolean

Hides plugins from /help if they do not show permissions. You can override a true value here for a single plugin by adding a permission to a user/group with the permission<plugin> - anyone with essentials.* or '*' will see all help regardless. You can use negative permissions to remove access to just a single plugin's help if the following is enabled.



 radius: 0



   # Monsters won't follow players.
   # permission essentials.protect.entitytarget.bypass disables this.
   # Prevent the spawning of creatures.



Essentials Spawn / New Players