config.yml best practices for Minecraft plugins

The config.yml file is what makes a plugin usable for someone who did not write it. A plugin with everything hard-coded needs a new build for every small change, so good plugins keep settings out of the code.

Put these in the config

• Every message the player sees.
• Numbers: cooldowns, limits, prices, distances, delays.
• Lists: allowed worlds, blocked items, kit contents.
• Switches for features that some servers will not want.

Group and name keys clearly

# How long a teleport takes
teleport:
  delay-seconds: 3
  cancel-on-move: true

messages:
  no-permission: "&cYou may not do that."
  cooldown: "&eWait %seconds% more seconds."

Use lowercase with hyphens, group related keys under a heading, and add a comment above anything that is not obvious. Comments are for the owner who will edit the file later.

Color codes and placeholders

Classic Minecraft colour codes use the ampersand, so &a is green and &c is red, and the plugin translates them. Placeholders like %player% or %seconds% are replaced in the code. Say in your description which placeholders you want in which message.

Defaults and missing keys

A plugin should save its default config on first start and fall back to a built-in value when a key is missing, so an old config does not crash a new version.

Reloading

Ask for a reload command with its own permission, for example /myplugin reload. A full restart is still the safest way to apply a change that touches data files.

Do not put these in the config

• Player data. Use a separate data file so the config stays small and readable.
• Secrets such as passwords, unless the owner is told to protect the file.

A before and after example

Before: the countdown of three seconds is written in the Java code, so changing it means a new build. After: the file has teleport.delay-seconds: 3, the code reads it on start and a reload command re-reads it. The result is the same for players, but you control it without a developer.

A checklist for a good config

• Every message and number is in the file.
• Keys are short, lowercase and grouped.
• Comments explain anything that is not obvious.
• Defaults are safe if a key is missing.
• A reload command applies changes.
• Player data lives in a separate file.

Frequently asked questions

Can the file be in another language?

Yes. All messages are text in the file, so you can translate them freely.

Why did my edits disappear?

Some plugins rewrite the file on shutdown. Stop the server before editing the file.

How do I use color?

Use the ampersand codes such as &a for green. The plugin translates them when it sends a message.