Give and take cosmetics
Give a player a cosmetic for good or for a time, take it back, or let a rank own it through a permission, and see what happens when it runs out.
A player owns a cosmetic through a permission or through a grant from you. A grant can be permanent or expire, and you can take it back at any time.
Before you start#
A cosmetic entry with permission: false is owned by grants only, whichever permission a player holds. For everything else, both ways work and can be mixed.
Give a cosmetic#
Run the command
/cca give <player> <type:id> [duration], for example /cca give Notch tag:heart (permanent) or /cca give Notch chat_color:aurora 30d (30 days). Durations are 30m, 2h, 14d, 1w; decimals are allowed.
Note where it came from (optional)
Add --source <name>, --ref <id> and --note <text> so you can tell a purchase from a reward later, for example --source PURCHASE --ref order-1042. An unknown source is stored as EXTERNAL.
Check
/cca check <player> <type:id> says whether they own it, and /cca list <player> lists their grants with a number each.
Or give it by permission: exyliachatcosmetics.<type>.<id> unlocks one, and the wildcards below unlock more. Use your permissions plugin, for example LuckPerms, and see Permissions.
| Node | Grants |
|---|---|
exyliachatcosmetics.tag.heart | one cosmetic |
exyliachatcosmetics.tag.category.premium | every cosmetic in one tab of a type |
exyliachatcosmetics.tag.* | every cosmetic of a type |
exyliachatcosmetics.* | everything |
Check that it works#
The player runs /cc tags (or the menu of that type). The cosmetic is no longer locked and they can click it to wear it.
Going further#
Take it back#
/cca remove <player> <type:id> [source] confirmrevokes every active grant of that cosmetic, or only those of one source./cca revoke <id>revokes exactly one, by the number/cca listprints./cca unequip <player> <type>and/cca equip <player> <type:id>change what they wear./cca clear <player> confirmtakes everything off an online player.
A player may hold several grants for one cosmetic (a permanent one from a rank, a 30-day purchase). Removing one never touches the others.
When a grant expires#
The cosmetic stops being drawn, the player gets an expired message, and an online sweep runs every 30 seconds. With expiry.notify-on-join on (default), a player is told on join about temporary grants running low and about worn ones that ran out while they were away. Expired and revoked rows stay for expiry.retention-days (default 30) so /cca list still shows what was given, then are deleted.
Grants on a network#
Each grant remembers the server scope it was given under, set by ownership.scope in config.yml (see Configuration). With a scope other than global, a grant counts only on servers of that scope. A cosmetic bought with one of the ownership.global-currencies, and every grant made before 1.4.0, counts on every server. New in v1.4.0
Why a cosmetic stays "on" after losing the rank#
What a player wears is stored on their row, and ownership is asked again whenever a line is drawn. A cosmetic they no longer own is simply not drawn, and it comes back the day it is theirs again, still where they left it. Nothing is removed because a permission said no: a permission plugin still loading on join must never take someone's cosmetics away for good. The only removal that is written down is a custom cosmetic that was deleted.
Technical details
Three separate questions: available (exists, not hidden), owned (a valid permission or grant) and equipped (worn). Ownership sources:
| Source | Stored | Comes from |
|---|---|---|
PERMISSION | no, asked live | exyliachatcosmetics.<type>.<id> and the wildcards; ignored for permission: false |
ADMIN | yes | /cca give without --source |
PURCHASE, REWARD, EVENT, ACHIEVEMENT, EXTERNAL | yes | /cca give --source <name>, or the API |
| the maker of a custom cosmetic | implicit | their row, permanent |
| a group named by a rank colour | implicit | the groups list in rank-colors.yml |
A grant row carries expires_at (0 is permanent) and revoked_at; an inactive row is simply not a grant, so an offline player's grant stops counting without anything running.
Tables (H2 by default, others as in Database): chatcosmetics_profiles, chatcosmetics_entitlements, chatcosmetics_custom, chatcosmetics_loadouts, chatcosmetics_tokens. A profile is read once on join and held in memory, so chat adds no queries. Writes are batched and flushed every 5 seconds, on quit and on shutdown.
Something missing on this page? Tell us on Discord