Content generated with AI — it may contain mistakes.

ExyliaChatCosmetics/ReferenceUpdated in v1.4.0

Configuration

Every key of config.yml with its default, and what lives in messages.yml instead.

Page 21 of 3013 min read

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.enabled became modules.chat, rank-colors.repaint became rank-colors.keep, chat.default-color gave way to the defaults section, and the menu section moved into lang/<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#

KeyDefaultMeaning
languagedefaultThe 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.

KeyWhat it switches
chatThe 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.
tagsTags in front of the name
nick-colorsColours for the player's name
rank-colorsColours for the rank's prefix and suffix
chat-colorsColours for the message
shadowsShadows under the name, the rank and the message; each needs its colour module
customTags and colours players make with tokens; each needs its tag or colour module
fontsFonts for the message
modifiersBold, italic and the other message modifiers
presetsWhole looks the server puts together (lang/<language>/cosmetics/presets.yml)
loadoutsLooks players save and put back on
Every switch but chat waits for a restart

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.

plugins/ExyliaChatCosmetics/config.yml
yaml
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
KeyNames an entry of
taglang/<language>/cosmetics/tags.yml
nick-colorlang/<language>/cosmetics/nick-colors.yml
rank-colorlang/<language>/cosmetics/rank-colors.yml
chat-colorlang/<language>/cosmetics/chat-colors.yml
shadow-color, nick-shadow, rank-shadowlang/<language>/cosmetics/shadow-colors.yml — the three shadows are one catalogue worn in three places
fontlang/<language>/cosmetics/fonts.yml
modifierlang/<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; none gives 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. Staff unequip and clear, the Take it all off button and loadouts put the default back.
  • Menus show a default with menu.default-marker after its name, and the _id and _name placeholders 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: id blocks is converted on start: each group becomes a group.<name> line in the order written, and default the last line, with an empty permission.

chat#

KeyDefaultMeaning
hookdecorateHow the message body is styled. The four modes are below.
priorityNORMALEvent priority for chat_event and legacy_event: LOWEST, LOW, NORMAL, HIGH, HIGHEST, MONITOR. Anything else falls back to NORMAL with a warning.
sanitizetrueFormatting 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#

ModeWhat happensPick it when
decorateAsyncChatDecorateEvent: 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_eventAsyncChatEvent.message(...), at priority.The chat plugin ignores decoration but reads message().
legacy_eventAsyncPlayerChatEvent.setMessage(...), written as § codes with hex.The chat plugin still uses the string event.
offChat 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#

KeyDefaultMeaning
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#

KeyDefaultMeaning
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.

KeyDefaultMeaning
min-length2
max-length16A 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
uniquetrueTwo players may not hold the same text

custom-colors#

KeyDefaultMeaning
max-stops4How many colours a custom gradient may run through. A rank raises it with exyliachatcosmetics.customcolor.stops.<n>; the highest wins

loadouts#

KeyDefaultMeaning
limit3How many looks one player may keep saved. A rank raises it with exyliachatcosmetics.loadouts.<n>; the highest wins
How many customs a player may make is not a key

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#

KeyDefaultMeaning
tick2Ticks between animation frames. Lower is smoother and costs more.

preview#

KeyDefaultMeaning
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#

KeyDefaultMeaning
notify-on-jointrueOn 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-days30How long an expired or revoked grant stays in the table for auditing before the daily sweep deletes it

placeholders#

KeyDefaultMeaning
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.

KeyDefaultMeaning
enabledtrueWhether a locked cosmetic with a price can be bought from the menu
tier-pricescommon: 500, rare: 1500, epic: 4000, legendary: 10000The 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:

plugins/ExyliaChatCosmetics/cosmetics/tags.yml
yaml
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

KeyDefaultMeaning
ownership.scopeglobalglobal (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.

SectionWhat is in it
generalreloaded, player-only, no-permission, unknown cosmetic / type / player, invalid key, invalid duration
entitlementsgranted and its two target lines, revoked, the list lines, the check lines, expired, expired-on-join, expiring-soon
equipequipped, unequipped, unequipped-type, not-owned, nothing-equipped, cleared
favoritesadded, removed
loadoutssaved, applied, deleted, limit, unknown, empty, invalid, the list lines
customcreated and its target line, edited, deleted, none, not-yours, too-short, too-long, pattern, blacklisted, taken, invalid-color, too-many-stops
tokensno-create, no-edit, spent, given, taken and set with their target lines, the balance lines, unknown-kind, not-custom
presetsapplied, applied-partial, not-owned, unknown, the list lines
promptsthe titles and hints of the text inputs: custom tag, colour, editing either, loadout name
menutypes (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
adminthe samples /cca preview, render and chat line draw, permanent, and the ON/OFF switches of the chat admin screens
confirmthe 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