Bukkit.yml

This page has been suggested for inclusion in the Official Documentation This page has been marked for inclusion in the Bukkit Official Documentation section, Docs. You can deliberate about its inclusion on its Talk page.

Bukkit.yml is a file that provides you with a wide variety of options for configuring your CraftBukkit server.

Sections in the YAML

The headings listed below are the top-level keys in the YAML file.

settings

General CraftBukkit server options.

allow-end

Is the End enabled. (boolean)

Default: false

warn-on-overload

Does the server show "[WARNING] Can't keep up! Did the system time change, or is the server overloaded?" messages. (boolean)

Default: true

permissions-file

The name of your custom permissions file. (string, filename)

Default: permissions.yml

update-folder

The name of the folder to put updated plugins in, which will be moved upon restart. (string, foldername) NOTE: The folder MUST be in the plugins folder. Absolute paths do NOT work.

Default: update.

ping-packet-limit

Currently disabled. Previously: How much packets a second the ingame ping list can use, maximum. (integer, packets/sec)

Default: 100

use-exact-login-location

Since Minecraft added the feature of pushing entities out whenever they are stuck inside a block, players have often found themselves above the location they logged out of when logging back in (especially if they were in a cave). This setting allows servers to disable or enable this behavior. If true, we will bypass Vanilla's behaviour of checking for collisions and moving the player if needed when they login. If false, we will continue to follow Vanilla's behaviour and move players that 'collide' with objects when they login.

Default: false

world-container

The name of a folder to store all the world directories in. If not included in your file, defaults to the current working directory. (string, foldername)

plugin-profiling

Allows the use of the command /timings. Used to measure time taken by plugin for events.

Default: false

connection-throttle

The delay before a client is allowed to connect again after a recent connection attempt. A value of 0 disables the connection throttle but leaves your server susceptible to attacks (only recommended for test servers). (long, milliseconds)

Default: 4000

query-plugins

Does the server return the list of plugins when queried remotely. (boolean)

Default: true

deprecated-verbose

Does the server show warnings when a plugin registers a deprecated event. A 'true'/'false' value works as a toggle for these warnings, while 'default' will always show a warning unless the event in question has been tagged by a developer as not requiring a warning when it is registered. (string)

Default: default

shutdown-message

This is the message displayed to clients when the server stops

Default: Server closed

spawn-limits

CraftBukkit server options that determine how many animals or mobs can spawn per-world.

monsters

This bukkit.yml setting allows servers to set the amount of monsters that can spawn per-world.

Minecraft default: 70.

animals

This bukkit.yml setting allows servers to set the amount of animals that can spawn per-world.

Minecraft default: 15.

water-animals

This bukkit.yml setting allows servers to set the amount of water animals that can spawn per-world.

Minecraft default: 5.

ambient

This bukkit.yml setting allows servers to set the amount of ambient creatures (aka, bats) that can spawn per-world.

Minecraft default: 15.

Note: Mob spawned animals or monsters do not follow these limits. They have their own limits they follow.

Note: These limits only apply to animals or monsters in loaded chunks - it does not account for entities stored in unloaded chunks.

chunk-gc

CraftBukkit will check for chunks that should have been unloaded but for some reason failed to do so.

period-in-ticks

The ticks between each chunk garbage collection consideration. If set to 0, chunk gc will be disabled.

Bukkit default: 600.

load-threshold

Number of chunks that need to be loaded since the last garbage collection before considering garbage collection. If set to 0, chunk gc will be disabled.

Bukkit default: 0.

ticks-per

CraftBukkit server options that determine the tick delay for specific features

animal-spawns

This bukkit.yml setting allows servers to set the tick delay for animal spawns.

Example Usage:

• A value of 1 will mean the server will attempt to spawn animals every tick.
• A value of 400 will mean the server will attempt to spawn animals every 400th tick.
• A value below 0 will be reset back to Minecraft's default.

Note: If set to 0, animals spawning will be disabled. We recommend using spawn-animals to control this instead.

Minecraft default: 400.

monster-spawns

This bukkit.yml setting allows servers to set the tick delay for monster spawns.

Example Usage:

• A value of 1 will mean the server will attempt to spawn monsters every tick.
• A value of 400 will mean the server will attempt to spawn monsters every 400th tick.
• A value below 0 will be reset back to Minecraft's default.

Note: If set to 0, monsters spawning will be disabled. We recommend using spawn-monsters to control this instead.

Minecraft default: 1.

autosave

This bukkit.yml setting allows servers to set the number of ticks for each save-all event.

Example Usage:

• A value of 1 will mean the server will attempt to autosave the world every tick.
• A value of 6000 will mean the server will attempt to autosave the world every 5 minutes.
• A value below 0 will be reset back to Bukkit's default.

Minecraft default: 6000.

Bukkit default: 0.

Note: Many Bukkit servers already run autosave plugins which generate save-all tasks, thus it was decided to disable this feature in Bukkit, as the Minecraft default setting was causing a lot of lag for many servers, and was found redundant. If you wish to enable this, remember the setting is per tick, and thus should be set to a reasonably high number (6000 = 5 minutes at peak server efficiency).

auto-updater

Controls the built in update checker.

• enabled: (boolean) Is the update checker enabled. Default: true
• on-broken: (string array) What to do if the version the server is on is known to have a large bug or exploit. Can be "warn-ops" and/or "warn-console". Default: [warn-console, warn-ops]
• on-update: (string array) What to do if the version the server is on is out of date. Can be "warn-ops" and/or "warn-console". Default: [warn-console, warn-ops]
• preferred-channel: (string) Which release channel is preferred for this server. Can be "rb", "beta" or "dev". Default: rb
• host: (string) The update checker location. You probably should never change this, unless you know what you're doing. Default: dl.bukkit.org

aliases

This section allows you to map aliases to commands. Example:

aliases:
    # This creates a new command called "canihasbukkit", which when used it actually performs "version"
    canihasbukkit: version
    
    # And this will execute both "save-all" and then "stop" when you type "savestop"
    savestop: [save-all, stop]
    
    # If a command already exists called "give", it will be rewritten. This is handy if you've two plugins
    # fighting for the same name.
    give: somepluginsgive

For more information about aliases, check out Commands.yml.

database

This section lets you set various database-related configuration options, for the database which will be shared by plugins that use the internal eBeans server. Most plugins do not use this, so whether or not you need to configure it is up to you. Changing these properties will change how all plugins that use the eBeans server integrated with Bukkit connect to their database.

• username: (string) Username to connect to database. May be ignored depending on driver.
• password: (string) Password to connect to database. May be ignored depending on driver.
• isolation: (one of SERIALIZABLE, ...) Generally leave this alone unless advised otherwise.
• driver: (string, JDBC class name) The JDBC driver class that should be used. See the documentation for your database's Java driver for this value.
• url: (string, JDBC database URL) The URL to connect to the database. For MySQL/PostgreSQL or other server-client databases, this will generally include the hostname, port and database name. For file-based databases, such as SQLite, this will usually include the filename.

The following are examples of what each configuration would look like for the two most commonly used database applications.

SQLite Configuration (default):

database:
  username: bukkit
  isolation: SERIALIZABLE
  driver: org.sqlite.JDBC
  password: walrus
  url: jdbc:sqlite:{DIR}{NAME}.db

Note: the {DIR} and {NAME} words represent the directory of the plugin data folder and the name of the individual db file. They are actual variable names Bukkit uses, therefore changing these settings are not recommended.

MySQL Configuration example:

database:
  username: {USERNAME}
  isolation: SERIALIZABLE
  driver: com.mysql.jdbc.Driver
  password: {PASSWORD}
  url: jdbc:mysql://{IP}:{PORT}/{DATABASENAME}

Note: {USERNAME}, {PASSWORD}, {IP}, {PORT}, and {DATABASENAME} are not actual variable names that Bukkit uses like in the SQLite example. They just represent data you should change to get the MySQL configuration to work correctly.

*OPTIONAL* worlds

This section lets you define the generators for the worlds that bukkit loads by default.

Prereqs: You MUST have the generator installed already, and the generator's developer must have {{{load: startup}}} in their plugin.yml.

If you want your world, named 'world1' (the same thing you have as 'level-name' in server.properties) and wanted to use the CleanroomGenerator with no params, you could do this:

 settings:
   ...
 aliases:
   ...
 database:
   ...
 worlds:
   world1:
     generator: CleanroomGenerator

If you wanted some custom params:

 settings:
   ...
 aliases:
   ...
 database:
   ...
 worlds:
   world1:
     generator: CleanroomGenerator:10,stone,20,dirt,1,grass