Installation

Before you start

The server needs Paper 1.21 or newer and Java 21. Two plugins have to be in plugins/ beside the jar; two more are optional and each buys something specific.

# Soft on purpose: a hard depend stops this plugin from loading when
# ExyliaLib is absent, and the loader that would install ExyliaLib is
# exactly what has to load for the install to happen.
softdepend: [ExyliaLib, PlaceholderAPI, LuckPerms]

What each optional plugin buys

PlaceholderAPI. ExyliaLib registers every placeholder under %exyliachatcosmetics_<name>% and bridges them into PAPI automatically. Inside ExyliaLib's own text they work regardless; PAPI is what makes them resolve in someone else's chat format, scoreboard or tab list. If the built-in chat module is doing the delivering, nothing needs the round trip and PAPI buys you nothing.

LuckPerms. A rank colour repaints the prefix and suffix your permission plugin already writes, and it reads them from LuckPerms' cached data. Without LuckPerms {prefix} and {suffix} draw nothing and the whole rank-colour screen is empty. LuckPerms also carries the groups an entry's groups list names, and its UserDataRecalculateEvent drops the memoised permissions and the render cache, so a rank that ran out takes its cosmetics off without a relog. Ownership by permission still works through Bukkit without it — the memo simply refreshes on join, on reload and on the 30-second sweep instead.

Installing

What the first boot writes

Everything lives under plugins/ExyliaChatCosmetics/. Each file is copied out once and never overwritten, so your edits survive an update.

cosmetics/

The catalogue. These are not schema-managed on purpose — a catalogue is curated by hand and a schema writer keeps none of its comments — so what ships is a commented file you can read top to bottom.

menus/

Six ExyliaLib menu files, compiled on load and recompiled by /cca reload.

The chat/ tree

None of it is written on the first boot. The chat module builds its files the first time it starts, which is the first load or reload after chat.module.enabled: true.

Database

By default the plugin uses H2: a file inside the plugin folder, with no server, no installation and no maintenance. Tables are created on first use and widened automatically when a column needs more room.

A sixth table, chatcosmetics_chat_players, belongs to the chat module and is created only once that module runs. It carries a player's channel, their ignore list and their moderation state.

To share cosmetics across several servers, point them at the same engine:

database:
  type: mysql
  settings:
    max-pool-size: 0
  mysql:
    host: 127.0.0.1
    port: 3306
    database: minecraft
    username: root
    password: ""

Supported engines: h2, mysql, mariadb, postgresql and mongodb. Only the block matching type is read, and an unrecognised value falls back to h2 and says so. The file is ExyliaLib's; its full reference is in the library's database page.

A profile is read once on join — the row, the grants, what the player made and their loadouts — and held in memory while they are online. Menu clicks mark the row dirty and a flush runs every five seconds, on quit and on shutdown. Drawing a chat line never touches the database.

Folia

plugin.yml declares folia-supported: true, and everything thread-bound goes through ExyliaLib's Tasks: profile writes and event firing land on the player's own region, the animation clock and the expiry sweep are asynchronous, and rendering a line or answering a placeholder reads memory only. Nothing extra to configure.

Updating

Replace the jar and restart. Your catalogue files, menus and chat files are kept untouched, and everything a player owns lives in the database.

config.yml and messages.yml are generated from records, so they are handled differently from the files that are merely copied: a key a new release adds appears with its default and its comment, and a key no record declares any more is removed on load and reported once as UNKNOWN_KEY. That is one-way — a typo in a key name is deleted rather than warned about for ever, so read the console after an update if you have been editing by hand.

Reloading

/cca reload

Permission exyliachatcosmetics.admin. It runs five steps in order, and a step that fails is reported while the rest still run:

/exylialib reload is separate: it reloads the palette, and this plugin drops its render cache in response, so recolouring the server recolours tags and names without touching anything here.

Where to go next