Getting started

Introduction

What ExyliaChatCosmetics is, the two halves it ships as, and how this documentation is organised.

ExyliaChatCosmetics is two things in one jar, and you can run either half on its own.

The cosmetics are what a player wears in chat: a tag in front of their name, a colour on the name, a colour on their rank's prefix, a colour on what they type, a shadow under it, a font, a decoration or two. They pick them from a menu, they own them through a permission or a grant that can expire, and they save the combinations they liked as loadouts.

The chat module is off by default, and turning it on makes this plugin the server's chat: channels, formats, private messages, a filter that reads English and Spanish, mentions, emojis, [item] renders and an announcer. With it on the cosmetics land inside the line directly, with no placeholder round-trip.

The catalogue you get

Nothing here is a placeholder for content you have to write. The shipped files are the content.

File	Holds
`tags.yml`	180 tags in seven tabs — symbols, animated sprites, particles, item and block icons, interface icons, flags as head skins, premium
`nick-colors.yml`	90 nick colours in six tabs
`chat-colors.yml`	96 chat colours in six tabs
`shadow-colors.yml`	90 shadow colours in six tabs, answering the chat colour tabs
`rank-colors.yml`	77 rank colours in six tabs, including animated ones and a staff tab
`fonts.yml`	18 fonts in four tabs
`modifiers.yml`	bold, italic, underlined, strikethrough and obfuscated
`animations.yml`	18 animations across six kinds of movement

They are ordinary YAML. Delete what you do not want, write your own, and /cca reload picks it up.

A tag is not a second rank

Every tag the plugin ships is a single glyph — a symbol, a sprite, a particle, an item icon, a flag drawn as a head. No brackets, no words, nothing that reads as a rank somebody bought.

Ranks stay where they are

Rank colours repaint the prefix and suffix your permission plugin already writes; they never invent one and never touch the name. A player wearing a rank colour is the same rank they were, in a colour they chose. See Colours.

What is included

The catalogue

The files under cosmetics/, the fields every entry shares, and the colour grammar that runs through all of them.

Requirements

Requirement	Detail
Server	Paper 1.21 or newer. Spigot runs the cosmetics through the legacy hook; the chat module needs Paper. Folia supported.
Java	21
Required	`ExyliaLib`, `packetevents`
Optional	`PlaceholderAPI`, `LuckPerms` (rank colours need it), Redis for several servers

1.21.9 for sprites and heads

Tags built from sprites, particles and head skins are object components, which arrived in Minecraft 1.21.9. An older client shows those tags as the text they are written in rather than failing — but the SYMBOLS tab, and everything about colours, fonts and the chat, works on 1.21 the same as on the newest release.

How to read this documentation

Getting started

Installation, and a player wearing something within a couple of minutes.

The catalogue

What ships, what each file can say, and how to write your own entries.

Wearing them

The menus, how ownership is decided, and the tokens that pay for what players make.

Chat module

Only if you want this plugin to run your chat. Skip it entirely otherwise.

Reference

Commands, permissions, placeholders, every configuration key, the integrations and the API.

Conventions

A cosmetic is named type:id everywhere — tag:mvp, chat_color:aurora, customtag:42.
Keys are normalised to a-z 0-9 _ - in lower case, so MVP and mvp are the same id.
Colours use ExyliaLib palette tokens ({primary}, {highlight}, {muted}), which follow your server's colors.yml rather than fixed hex values.
Durations are ExyliaLib's: 30m, 2h, 14d, 1w, decimals allowed.
Values marked default are what the plugin writes on the first start. An existing file is kept.

Something missing on this page? Tell us on Discord