14. Configuration Files

All configuration is YAML, read and written with ConfigLib 4.8.1. Each platform has its own set of files in its data directory.

Every file is written back on every start: the plugin reads it, fills in what is missing with the default of the key and writes the canonical version back. A file that is edited by hand keeps its values; a key that is added by a newer version of the plugin appears with its default.

14.1 Paper Files (plugins/AppelToolsPaper/)

File	Purpose	Written by
config.yml	Main config (economy, modules, server, database, two-factor, updater)	the plugin, on every start
messages.yml	Player-facing messages (MiniMessage)	the plugin, on every start
data.yml	Per-server persistent data (the uuid of the server)	the plugin, on every start

data.yml is managed by the plugin: the uuid of the server is written into it and must not be changed by hand.

14.2 Velocity Files (plugins/AppelTools/)

File	Purpose	Written by
config.yml	Main config (discord, chat filter, announcements, modules, server, database, two-factor, updater)	the plugin, on every start
messages.yml	Player-facing messages (MiniMessage)	the plugin, on every start

14.3 config.yml (Paper)

# Economy
economy:
  start-balance: 0.0
  # How long the log of the balance changes is kept, in days. Zero keeps
  # it for ever: nothing is removed.
  transaction-history-days: 0

# Modules
modules:
  root:
    enabled: true
  economy:
    enabled: true
  staff:
    enabled: true
  gamemode:
    enabled: true
  speed:
    enabled: true
  chat-modifier:
    enabled: true
  teleport:
    enabled: true
  home:
    enabled: true

# Required plugins (the server fails to start if any of them is missing)
required-plugins: []

# Teleport
teleport:
  cooldown-seconds: 3
  request-timeout-seconds: 60

# Server
server:
  name: "Example"
  ip: "play.example.com"
  locale: "nl"                 # en or nl
  record-player-ips: true
  record-private-ips: false
  ipinfo-token: ""

# Database
database:
  host: "0.0.0.0"
  port: 3306
  name: "database"
  username: "username"
  password: "password"
  ssl: false
  debug: false

# Two-factor authentication
two-factor:
  enabled: true
  trusted-ip-days: 3

# The plugin updater
plugins: {}

14.4 config.yml (Velocity)

# Discord
discord:
  token: ""
  activity: "play.example.com"
  staff-roles: []             # the roles that are mentioned in a message
  admin-roles: []             # the roles that may run a slash command
  channels:
    staff-notifications: ""   # the joins, the leaves, the switches, the vanishments
    reports: ""               # the reports, the notes, the filtered chat
    punishments: ""           # the punishments
    log: ""                   # the missing plugins, the maintenance, the restarts, the crashes

# Chat filter
chat-filter:
  enabled: true
  curse-words: []
  block-advertising: true

# Announcements
announcements:
  enabled: true
  interval: "120s"

# Modules
modules:
  appeltools:
    enabled: true
    chat-modifier: true
  broadcast:
    enabled: true
  maintenance:
    enabled: true
    icon: true
    motd: true
    player-list-hover: true
    version: true
  message-system:
    enabled: true
    ignore: true
    spy: true
  punishment-system:
    enabled: true
    ip-ban: true
    ban: true
    ip-kick: true
    kick: true
    ip-mute: true
    mute: true
    ip-unban: true
    unban: true
    ip-unmute: true
    unmute: true
  report:
    enabled: true
  restart-server:
    enabled: true
  rules:
    enabled: true
  server-info:
    enabled: true
    icon: true
    motd: true
    player-list-hover: true
    version: true
  staff:
    enabled: true
    chat: true
    list: true
    version-list: true
    mode: true
    notifications: true
  party:
    enabled: true
  friends:
    enabled: true
  plugin-updater:
    enabled: false
  servers:
    enabled: true

# Required plugins (the proxy fails to start if any of them is missing)
required-plugins: []

# Server
server:
  name: "Example"
  ip: "play.example.com"
  locale: "nl"
  join-message: ""
  record-player-ips: true
  record-private-ips: false

# Database
database:
  host: "0.0.0.0"
  port: 3306
  name: "database"
  username: "username"
  password: "password"
  ssl: false
  debug: false

# Two-factor authentication
two-factor:
  enabled: true
  server-key: ""              # the proxy writes a random key when it is empty
  trusted-ip-days: 3

# The plugin updater
plugins: {}

14.5 The plugin updater (plugins)

Both plugins read the same section. Every entry is a plugin, and the key is the name of the plugin:

plugins:
  luckperms:
    provider: "jenkins"        # jenkins | spigotmc | modrinth | hangar | github | geyser
    api-url: "https://ci.lucko.me/job/LuckPerms"
    artifact-prefix: "LuckPerms-Bukkit-"

The providers and their keys are described in the updater page.

14.6 messages.yml

The messages are MiniMessage. The file is generated on the first start with the defaults of the plugin, and every message can be changed. The keys are grouped in the same sections as the commands that use them.

prefix:
  normal: "<gray>[<white>AppelTools<gray>] <reset>"
  staff: "<dark_gray>[<white>Staff<dark_gray>] <reset>"

errors:
  no-permission: "<red>You don't have permission."
  player-only: "<red>Only players can run this command."
  invalid-args: "<red>Invalid arguments."

restart:
  broadcast:
    - ""
    - "<red>{SERVER_NAME} is restarting in {TIME_LEFT}!"
    - "<red>Please reconnect to {SERVER_IP}"
    - ""
  kick-message:
    - ""
    - "<red>{SERVER_NAME} is restarting!"
    - "<red>Please reconnect to {SERVER_IP}"
    - ""
  cancelled:
    - "<red>The restart has been cancelled!"

The placeholders {SERVER_NAME} and {SERVER_IP} are filled in by the plugin; a value that a player typed is escaped, so a name can never be read as a tag.

14.7 Loading sequence

1. Config.java registers every ConfigKey in the key registry; Messages.java does the same for the MessageKeys.
2. The file is read by the YAML store of ConfigLib into the record of the plugin (ConfigConfig, MessagesConfig).
3. The values of the record are written into the keys, so that the rest of the plugin reads them from one place.
4. The file is written back: the missing keys appear with their default, and the file gets the canonical order and the comments.
5. Every module that is enabled is initialised.

14.8 Runtime mutation

/atp reload and /atv reload read the files again and write the values into the keys. The modules pick the new values up — the curse words of the chat filter, for example.

Some settings cannot be reloaded: the database and the two-factor key need a full restart.

14.9 Validation

Every ConfigKey has a default. A value that cannot be read — a number where a text belongs, for instance — falls back to that default and is logged as a warning.