Configuring Bukkit's bukkit.yml Quick and Easy for 1.17

By Paul

July 01, 2021

3 min read

Bukkit is a Mod for Minecraft that provides a plugin API for the Minecraft Server that came out in 2011. It provides an easy way to customize the Vanilla experience, allowing you to install plugins that can change every bit of the server. While previously being maintained at https://bukkit.org, the project is now primarily maintained by SpigotMC.

Configuring Bukkit can be a little difficult, so here’s a full breakdown of configuring the bukkit.yml that’s generated by default when you run Bukkit.

Quick Definitions:

Ticks: a tick is 1/20th of a second, or 50 milliseconds. The Minecraft Server attempts to update mobs, chunks, and the world at this rate.
TPS: ticks per second, or how many of these ticks successfully ran in a second.

`settings`

settings:
  allow-end: true
  warn-on-overload: true
  permissions-file: permissions.yml
  update-folder: update
  plugin-profiling: false
  connection-throttle: 4000
  query-plugins: true
  deprecated-verbose: default
  shutdown-message: Server closed
  minimum-api: none

This section is used to define generic settings that the Minecraft Server will follow. None of these settings will improve performance, and are just configuration for Bukkit.

`settings.allow-end` (default: `true`)

Bukkit provides this as a way to disable the end world. If you don’t need this world and would like the entire end system disabled, you can set this option to false.

`settings.warn-on-overload` (default: `true`)

This configuration option is added by Bukkit to alert you when your server is running behind. It will send a message that looks like:

Can't keep up! Is the server overloaded? Running 5000ms or 250 ticks behind

To disable these messages, you can set warn-on-overload to false.

`settings.permission-file` (default: `permissions.yml`)

This setting sets the default permission file, which is generally used to group permission nodes together. We’re not going to go in-depth on the file format here, but you can find the Bukkit Wiki article here.

`settings.update-folder` (default: `update`)

Bukkit provides a way to automatically update plugins before they get loaded. For example if you wanted to update WorldEdit.jar, simply put the new version in update/WorldEdit.jar, and the next time the server restarts Bukkit will automatically copy the updated plugin into the plugins folder!

`settings.plugin-profiling` (default: `false`)

This option will enable the use of Timings to profile plugins, the implementation of this profiler will depend on the Minecraft Server JAR you’re using. If you’re using Paper or a fork of it, then this option is overwritten by paper.yml.

`settings.connection-throttle` (default: `4000`)

If you have the issue of players rejoining the server too frequently, this will let you control how often players can join, logout, and join again. The value is in milliseconds, so if you wanted players to only be able to rejoin every 10s, you would set it to 10000.

`settings.query-plugins` (default: `true`)

This option is used when the Minecraft Server is asked about what plugins it has installed in two different spots:

When the Minecraft Server creates a report
When rcon is used to query the status of the server.

`settings.deprecated-verbose` (default: `default`)

This option is used in several places regarding whether the server will report on a plugin doing deprecated actions. It should be left to default unless you have a reason to use it in another mode (off / on).

`settings.shutdown-message` (default: `Server closed`)

Bukkit allows you to configure the message sent to players when the server shuts down. If you’d like to use custom colors, you can add them by using the § prefix like so: §6Shutting Down.

`settings.minimum-api` (default: `none`)

To maintain compatibility with old plugins, Bukkit has developed a system that allows plugins to define which version of Bukkit they’re based off. If you’d like to disallow old plugins without a defined API version, or plugins that have defined an older API version, you can set the minimum here. Valid values as of 1.17 are: 1.13, 1.14, 1.15, 1.16, 1.17.

`spawn-limits`

spawn-limits:
  monsters: 70
  animals: 10
  water-animals: 15
  water-ambient: 20
  ambient: 15

This section is used to define how many of each entity type can spawn in the world. This can be used to improve performance a lot, especially because ambient (bats) and water-animals/water-ambient mobs do not need as high of a count as these defaults. Reducing these values can reduce the amount of entities that are attempted to be spawned, improving performance.

`chunk-gc`

chunk-gc:
  period-in-ticks: 600

The chunk-gc.period-in-ticks allows you to configure how long a chunk loaded by a plugin stays loaded. Generally this shouldn’t need to be changed.

`ticks-per`

ticks-per:
  animal-spawns: 400
  monster-spawns: 1
  water-spawns: 1
  water-ambient-spawns: 1
  ambient-spawns: 1
  autosave: 6000

This section is used to define how often certain systems in the game get ticked. It can be used to tune your server performance, specifically reducing how much mob spawning hurts the performance.

`ticks-per.<entity>-spawns`

These settings have a few possible options for configuration.

If you’d like to completely disable the spawning of a certain type of entity, you can set the value to 0.
If you’d like to have them attempted to be spawned every tick (20 times/second) you can have it set to 1.

Beyond that, you can raise how often certain types of entities are attempted to be spawned. For example, I would personally raise water-spawns, water-ambient-spawns, and ambient-spawns to be higher, as quick spawning of those entities does not change the experience much.

`ticks-per.autosave` (default: `6000`)

Bukkit allows you here to configure how often the worlds and player data is saved. You should set this value as high as you can tolerate data loss, which the default 5 minute (6000 ticks) is generally a good default for this.

If for some reason you’d like to not save this data, you can set it to 0 to disable the autosave.

`aliases`

aliases: now-in-commands.yml

This originally was used to define aliases for commands, but like the current value says, has been moved to commands.yml. You can find the Bukkit Wiki article on that here.