Configuration
Every key of config.yml with its default, and what lives in messages.yml instead.
Three places hold the plugin's files: plugins/ExyliaChatCosmetics/config.yml (the settings on this
page), lang/<language>/cosmetics/*.yml (the catalogue) and
lang/<language>/messages.yml, menus/ and chat/ (text and screens, see
messages and languages and
editing menus). Run /cca reload after editing any of them. The
settings owners change most are modules, defaults, chat and
shop; full key tables follow for each file section.
config.yml is generated from the plugin's own settings and re-read by /cca reload. That is worth
knowing for three reasons:
- A key the plugin does not recognise is removed on load, and every removal is reported once in the console. A typo does not sit there quietly doing nothing.
- A value the plugin cannot read is reported and the default used. The server starts either way; it never refuses to load over a bad line.
- The file carries a version and is migrated in place. A file written by an older release has its
renamed and moved keys carried over on the first start:
chat.module.enabledbecamemodules.chat,rank-colors.repaintbecamerank-colors.keep,chat.default-colorgave way to thedefaultssection, and themenusection moved intolang/<language>/messages.yml.
The cosmetics themselves are not here. They live in lang/<language>/cosmetics/*.yml and are described in
the catalogue.
config.yml, every catalogue, lang/<language>/cosmetics/animations.yml and, while the chat module is on, its settings and filter can also be edited from the browser with
ExyliaLib's web editor (/exylialib editor ExyliaChatCosmetics). Each file
needs exyliachatcosmetics.admin, catalogues show a preview of every entry as the game paints it, and an
applied change is checked by the same reader that loads the file, then reloaded.
language#
| Key | Default | Meaning |
|---|---|---|
language | default | The language of the menus and messages. default follows the language set in ExyliaLib's config.yml; en, es, pt, fr, ru or tr set this plugin alone. Each one is a folder under lang/ you can edit; custom holds the files the server had before languages existed. |
modules#
What this server uses at all. A module that is off registers nothing — no cosmetic kind, no command,
no button, no placeholder answer — and what players already wear of it stays on their profile, so
turning it back on gives everybody their things back. Every switch ships true.
| Key | What it switches |
|---|---|
chat | The built-in chat module: channels, formats, private messages, the filter, moderation. Off, the plugin is cosmetics only and your chat plugin keeps delivering through the hook. Applies on /cca reload. |
tags | Tags in front of the name |
nick-colors | Colours for the player's name |
rank-colors | Colours for the rank's prefix and suffix |
chat-colors | Colours for the message |
shadows | Shadows under the name, the rank and the message; each needs its colour module |
custom | Tags and colours players make with tokens; each needs its tag or colour module |
fonts | Fonts for the message |
modifiers | Bold, italic and the other message modifiers |
presets | Whole looks the server puts together (lang/<language>/cosmetics/presets.yml) |
loadouts | Looks players save and put back on |
A command can only be added while the server is starting, so /cca reload applies chat and nothing
else. When any other switch changed, the reload says so in the console — The modules in config.yml changed; restart the server to apply them. — and the running set stays as it started.
defaults#
What a player wears of a kind they have picked nothing of, by rank. One list per kind, each line a
permission and the id of an entry in that kind's catalogue as its cosmetic. The same lists are
editable in game from the settings screen.
defaults:
tag:
- permission: group.owner # first, so it wins over vip
cosmetic: staff
- permission: group.staff
cosmetic: none # staff get no default tag
- permission: group.vip
cosmetic: heart
chat-color:
- permission: '' # everyone else
cosmetic: snow| Key | Names an entry of |
|---|---|
tag | lang/<language>/cosmetics/tags.yml |
nick-color | lang/<language>/cosmetics/nick-colors.yml |
rank-color | lang/<language>/cosmetics/rank-colors.yml |
chat-color | lang/<language>/cosmetics/chat-colors.yml |
shadow-color, nick-shadow, rank-shadow | lang/<language>/cosmetics/shadow-colors.yml — the three shadows are one catalogue worn in three places |
font | lang/<language>/cosmetics/fonts.yml |
modifier | lang/<language>/cosmetics/modifiers.yml |
- First match wins. Lines are read top to bottom and the first one whose permission the player holds
is theirs, so put the highest rank first. A group is the node
group.<name>that LuckPerms sets. - An empty permission is everyone;
nonegives that group nothing and stops the search. - Empty (what every list ships as) leaves the player wearing nothing of that kind, so a fresh server looks as it did before.
- A default is the server's to give, not the player's to own. It needs no grant, it is not saved to the player's row, and the moment the player picks something of that kind theirs is drawn instead. A pick they no longer own falls back to the default.
- Taking it off keeps it off. A player who takes a kind off (the menu or
/cc unequip) gets no default for it until they pick something again. Staffunequipandclear, the Take it all off button and loadouts put the default back. - Menus show a default with
menu.default-markerafter its name, and the_idand_nameplaceholders report it like anything worn. - An id that names no entry is reported in the console on load and on reload, and that line is skipped.
No catalogue may name an entry
none. - A file written with the older
group: idblocks is converted on start: each group becomes agroup.<name>line in the order written, anddefaultthe last line, with an empty permission.
chat#
| Key | Default | Meaning |
|---|---|---|
hook | decorate | How the message body is styled. The four modes are below. |
priority | NORMAL | Event priority for chat_event and legacy_event: LOWEST, LOW, NORMAL, HIGH, HIGHEST, MONITOR. Anything else falls back to NORMAL with a warning. |
sanitize | true | Formatting a player types — &c, <red>, {primary} — is shown as the text they typed. exyliachatcosmetics.chat.format lets colours, gradients and decorations through. Clicks, hovers, fonts, heads and line breaks stay text even with sanitize: false. § is always neutralised, permission or not. |
The hook only runs while modules.chat is off. With the chat module
on, the hook is uninstalled and the module styles the body itself.
The four hook modes#
| Mode | What happens | Pick it when |
|---|---|---|
decorate | AsyncChatDecorateEvent: the styled body replaces the decorated message before any chat plugin sees it. Nothing is cancelled. | Paper, with a chat plugin that renders through the event — Paper's own chat, and every renderer-based plugin. Recommended. |
chat_event | AsyncChatEvent.message(...), at priority. | The chat plugin ignores decoration but reads message(). |
legacy_event | AsyncPlayerChatEvent.setMessage(...), written as § codes with hex. | The chat plugin still uses the string event. |
off | Chat is never touched. | You compose the line yourself through the API, or you only want the identity placeholders. |
Whatever the mode, the message is rendered from cached state only. A render that fails leaves the message exactly as it was typed and is reported at most once a minute, so a broken cosmetic cannot turn into a wall of console.
tags#
| Key | Default | Meaning |
|---|---|---|
format | "%tag% " | How a tag sits around the name; %tag% is the tag itself. The trailing space is why %exyliachatcosmetics_tag%%exyliachatcosmetics_nick% needs nothing between them. A tag entry may override this with its own format. |
rank-colors#
| Key | Default | Meaning |
|---|---|---|
keep | []()<>{}| | The characters a rank colour never repaints: the frame a rank writes around its name, so &8[&eVIP&8] keeps its grey brackets while VIP takes the new colour. Everything else is repainted — letters, glyphs from a resource pack, the star in a suffix. A character the rank wrote with no colour of its own is always repainted. Empty repaints everything. |
custom-tags#
The rules a tag a player writes for themselves has to pass. They apply to /cc customtag create, to
the Make one button, and to /cca customtag set — an admin skips the token, not the rules.
| Key | Default | Meaning |
|---|---|---|
min-length | 2 | |
max-length | 16 | A rank raises it with exyliachatcosmetics.customtag.length.<n>; the highest wins |
pattern | [A-Za-z0-9_\-]+ | A regular expression the whole text must match. <>{}&§%\ are rejected whatever the pattern says. |
blacklist | [admin, staff, owner] | Words a tag may not contain, case-insensitively |
unique | true | Two players may not hold the same text |
custom-colors#
| Key | Default | Meaning |
|---|---|---|
max-stops | 4 | How many colours a custom gradient may run through. A rank raises it with exyliachatcosmetics.customcolor.stops.<n>; the highest wins |
loadouts#
| Key | Default | Meaning |
|---|---|---|
limit | 3 | How many looks one player may keep saved. A rank raises it with exyliachatcosmetics.loadouts.<n>; the highest wins |
There is no custom-tags.limit and there never will be. How many custom tags and colours a player
may write is a balance, held per player and per type and handed out with /cca tokens give.
Making one spends a create token, changing one spends an edit token, and deleting one gives
nothing back. A quota in config.yml would be the same number for everybody; a balance is something
you can sell, award or take away one player at a time. See
Tokens.
animations#
| Key | Default | Meaning |
|---|---|---|
tick | 2 | Ticks between animation frames. Lower is smoother and costs more. |
preview#
| Key | Default | Meaning |
|---|---|---|
format | %tag%%prefix% %name%%suffix%{letters_black}: %message% | The line /cc preview and the menu previews draw. %tag% already carries its trailing space from tags.format; %prefix% and %suffix% are the rank's, in whichever rank colour is being looked at. |
What the menus call things#
The menu section that used to sit here — the name of each kind, the status lines, the star, none,
the sample message and prefix, the custom-row hints — is player-facing text, so it lives in
lang/<language>/messages.yml under menu now, where it is translated. A config.yml from an older
release has its menu section moved there on the first start. See messages.yml.
expiry#
| Key | Default | Meaning |
|---|---|---|
notify-on-join | true | On join: one line per worn temporary grant with the time left, plus a count of worn grants that ran out while they were away |
retention-days | 30 | How long an expired or revoked grant stays in the table for auditing before the daily sweep deletes it |
placeholders#
| Key | Default | Meaning |
|---|---|---|
none | "" | What a placeholder with no value returns |
unknown | ? | What a placeholder naming something that does not exist returns |
shop#
Buying a locked cosmetic with currency, from the menu. Needs ExyliaEconomy or Vault; with neither, nothing shows a price.
| Key | Default | Meaning |
|---|---|---|
enabled | true | Whether a locked cosmetic with a price can be bought from the menu |
tier-prices | common: 500, rare: 1500, epic: 4000, legendary: 10000 | The price of each tier, in the default currency or as {amount, currency} |
An entry in lang/<language>/cosmetics/*.yml joins a tier with tier: rare, or sets its own price, which wins over
its tier's. An entry with neither is not for sale:
tags:
crown:
price: {amount: 50, currency: gems}A price is a number above zero — 500, or 2.5k — or a block with amount and currency. Anything
else, zero and negatives included, reads as no price, so a typo makes a cosmetic unpurchasable rather
than free. A price whose currency no economy takes is not shown either. /cca reload re-reads the
tiers.
ownership#
Where what a player unlocks counts. Restart to apply. New in v1.4.0
| Key | Default | Meaning |
|---|---|---|
ownership.scope | global | global (an unlock counts on every server), server, default (this server's network group) or the name of a group. What was unlocked globally always counts. |
ownership.global-currencies | [] | Currencies whose purchases count on every server, whatever the scope |
messages.yml#
Every player-facing line lives in plugins/ExyliaChatCosmetics/lang/<language>/messages.yml, generated from the
plugin's CosmeticMessages record and reloaded with the rest. prefix — {primary}&lE-CHAT {letters_black}•<reset>
by default — is what %prefix% expands to in this file.
Lines are written with ExyliaLib palette tokens ({primary}, {success}, {error}, …) rather than
hex, so recolouring the whole server from colors.yml recolours these too. The placeholders each
line accepts are named in the comment above it.
| Section | What is in it |
|---|---|
general | reloaded, player-only, no-permission, unknown cosmetic / type / player, invalid key, invalid duration |
entitlements | granted and its two target lines, revoked, the list lines, the check lines, expired, expired-on-join, expiring-soon |
equip | equipped, unequipped, unequipped-type, not-owned, nothing-equipped, cleared |
favorites | added, removed |
loadouts | saved, applied, deleted, limit, unknown, empty, invalid, the list lines |
custom | created and its target line, edited, deleted, none, not-yours, too-short, too-long, pattern, blacklisted, taken, invalid-color, too-many-stops |
tokens | no-create, no-edit, spent, given, taken and set with their target lines, the balance lines, unknown-kind, not-custom |
presets | applied, applied-partial, not-owned, unknown, the list lines |
prompts | the titles and hints of the text inputs: custom tag, colour, editing either, loadout name |
menu | types (what each kind is called in titles and lore), status (selected, available, locked, expiring), favorite-on, favorite-off, none, sample-message, sample-prefix, custom-hints |
admin | the samples /cca preview, render and chat line draw, permanent, and the ON/OFF switches of the chat admin screens |
confirm | the questions asked before anything is deleted, in menus and on the command line |
The chat module keeps its own lang/<language>/chat/messages.yml, with its own prefix. A chat plugin talks as the
chat, not as the cosmetics plugin, so %prefix% there never expands to this one. See
the chat module.
Something missing on this page? Tell us on Discord