Content generated with AI — it may contain mistakes.

ExyliaChatCosmetics/Wearing themUpdated in v1.4.0

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.

Page 11 of 304 min read

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.

NodeGrants
exyliachatcosmetics.tag.heartone cosmetic
exyliachatcosmetics.tag.category.premiumevery 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] confirm revokes every active grant of that cosmetic, or only those of one source.
  • /cca revoke <id> revokes exactly one, by the number /cca list prints.
  • /cca unequip <player> <type> and /cca equip <player> <type:id> change what they wear. /cca clear <player> confirm takes 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:

SourceStoredComes from
PERMISSIONno, asked liveexyliachatcosmetics.<type>.<id> and the wildcards; ignored for permission: false
ADMINyes/cca give without --source
PURCHASE, REWARD, EVENT, ACHIEVEMENT, EXTERNALyes/cca give --source <name>, or the API
the maker of a custom cosmeticimplicittheir row, permanent
a group named by a rank colourimplicitthe 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