Configuration and Versioning

Configuration & Config Versioning

This is the most important page if you're updating PlainBase or maintaining a config over multiple versions. Read this before reporting a config-related bug.

How configuration is structured

PlainBase splits its configuration into a main file and one file per module:

• plugins/PlainBase/config.yml — only lists which modules are enabled (modules: <name>: true/false). It has no feature settings itself.
• plugins/PlainBase/modules/<name>.yml — one file per module (spawn.yml, teleport.yml, messages.yml, joinitems.yml, vanish.yml, menu.yml, moderation.yml), each holding that module's settings.

Module files are only created on disk once the module has been loaded at least once (i.e. after you enable it and reload/restart, or on first successful startup for modules already true in code).

Enabling/disabling a module

Two ways:

1. Edit config.yml → modules.<name>: true, then /plainbase reload or restart.
2. Live-toggle with /plainbase toggle <module> (requires plainbase.admin) — flips the value in config.yml, saves it, and reloads modules immediately. No restart needed either way.

Note on defaults: in the shipped config.yml every module defaults to false (opt-in). If a module entry is missing entirely from your config.yml (e.g. after a manual edit), the plugin's internal code fallback is true for that lookup — so always check config.yml explicitly rather than assuming a module is off just because you don't remember enabling it.

The version system (how it works)

Every config file PlainBase ships — config.yml and every file in modules/ — ends with:

# DO NOT EDIT BELOW UNLESS YOU KNOW WHAT YOU ARE DOING
version: X.Y

This is not a cosmetic comment. On every plugin startup:

1. PlainBase's code keeps a hardcoded map of the latest known version for every config file (config.yml, spawn.yml, teleport.yml, etc.), one entry per file, bundled with that specific plugin build.
2. It reads the version: value at the bottom of your file on disk.
3. If your version is lower than the latest known version, PlainBase logs a warning to the console:

   !!! OUTDATED CONFIG: modules/spawn.yml !!!
   Your version: 1.0 | Required: 1.2
   Please check GitHub for the latest version and update your file.
   

4. Every time an OP joins the server, they additionally get an in-game warning message (red, bold [PlainBase] prefix) for every outdated file — main config and every module file are checked independently.

What PlainBase does not do

• It does not automatically merge, migrate or rewrite your config file.
• It does not add new keys to your existing file for you.
• It does not block the module from loading just because the version is old — the module still runs with whatever values it can read (missing keys fall back to safe in-code defaults, but new features tied to new keys simply won't be configurable until you update the file).

What you should do when you see the warning

1. Get the corresponding default file for the version you just installed — links below always point at the current main branch (i.e. whatever the latest release ships).
2. Manually port over your custom values (item names, locations, messages, cooldowns, etc.) into the new structure, then copy the new version: line as-is.
3. /plainbase reload — the warning disappears once your on-disk version matches the required one.

🛠 A config updater/migration tool is in development — the plan is for a future PlainBase version to diff your on-disk config against the current default and let you merge/apply the missing keys automatically (/plainbase update-config or similar), instead of manual copy-pasting. Not available yet; this page will be updated once it ships.

Current default config files (always up to date with main)

File	Link
config.yml	View on GitHub
modules/spawn.yml	View on GitHub
modules/teleport.yml	View on GitHub
modules/messages.yml	View on GitHub
modules/joinitems.yml	View on GitHub
modules/vanish.yml	View on GitHub
modules/menu.yml	View on GitHub
modules/moderation.yml	View on GitHub

Click "Raw" on any of those pages to get a direct download link for that file. Each module page below also links directly to its own config file.

Why versions bump

A config file's version number only increases when its structure changes (new keys, removed keys, renamed keys) — not for every release. A module can go through several PlainBase releases without its config version changing at all if nothing about its config structure changed.

Current latest versions (as of the version this page was written for)

File	Latest Version
config.yml	1.6
modules/spawn.yml	1.2
modules/teleport.yml	1.0
modules/messages.yml	1.0
modules/joinitems.yml	1.1
modules/vanish.yml	1.1
modules/menu.yml	1.0
modules/moderation.yml	2.0

These numbers change over time as PlainBase evolves. Always trust the in-game/console warning over this table — it always reflects the exact jar you're running.

Reload cycle

/plainbase reload, /plainbase toggle <module> and plugin startup all funnel through the same internal reload:

1. Stop all currently active modules (cancel scheduled broadcasts, unregister listeners).
2. Re-read every module config file from disk.
3. Re-run the setup for every module that is currently enabled.

This means editing a modules/*.yml file and running /plainbase reload is always safe and instant — no restart required for config changes, ever.

MiniMessage formatting

Every text field you can configure (messages, item names, lore, menu titles, ban/kick screens, broadcasts) uses MiniMessage syntax, e.g. <red>, <green>, <gradient:gold:yellow>...</gradient>, <bold>. Placeholders like %player% are simple string substitutions done before MiniMessage parsing; PlaceholderAPI placeholders (%plainbase_*%, %player_name%, ...) are resolved separately if PlaceholderAPI is installed — see PlaceholderAPI.