cosmetics

Cosmetics live in cosmetics/, one file per type, each holding many cosmetics:

cosmetics/
├─ chat-colors.yml    ├─ glow.yml         ├─ join-messages.yml
├─ tags.yml           ├─ tab-icons.yml    └─ leave-messages.yml
└─ name-paints.yml

Inside a file, each top-level section is one cosmetic, and its key is the cosmetic id (the id you pass to /cosmeticsadmin give, givevoucher, and case pools). Add a cosmetic by adding a section; after editing, run /cosmeticsadmin reload. See Creating Cosmetics for a walkthrough.

cosmetics/chat-colors.yml

"Rose Quartz":
  Enabled: true
  Order: 1
  Rarity: "Exotic"
  Material: "PLAYER_HEAD"
  Base64: "eyJ0ZXh0dXJlcyI6..."
  Name: "{primary}<b>Chat Color:</b> <GRADIENT:fa8cb2,d14977,a82255,8a0c43>Rose Quartz</GRADIENT>"
  Value: "<GRADIENT:fa8cb2,d14977,a82255,8a0c43>{context}</GRADIENT>"

Lime:
  Enabled: true
  Order: 2
  Rarity: "Legendary"
  Material: "PLAYER_HEAD"
  Base64: "eyJ0ZXh0dXJlcyI6..."
  Name: "{primary}<b>Chat Color:</b> <#00FF00>Lime</#00FF00>"
  Value: "<#00FF00>{context}</#00FF00>"

Fields

Key	Default	Description
Enabled	true	false hides this cosmetic from the menu, the market and every count (it can’t be equipped or won).
Order	0	Sort key for the “Item” sort, ascending. Ties break by id.
Rarity	Common	A rarity name from Rarity-Colors; fills {primary} / {secondary} and drives the “Rarity” sort.
Material	type default	The menu icon material (XMaterial name). Missing or unknown falls back to the type’s default (heads for most, GLOWSTONE for glow).
Base64	-	Head texture, applied only when Material is PLAYER_HEAD.
Custom-Model-Data	0	Applied to the icon when non-zero.
Name	id	The cosmetic’s display name in menus.
Lore	-	Extra menu lines, shown above the state lore from Lore-Addons.
Value	-	The effect payload. Its meaning depends on the type - see below.
Voucher	-	Optional item definition that makes this cosmetic giveable as a redeemable voucher. See Vouchers.

Name, Lore and Value all support the full formatting set, and have {primary} / {secondary} filled from the cosmetic’s rarity when it loads.

Value per type

Value is what the cosmetic actually does. Each type reads it differently:

Type	Value is	Example
Chat Color	A template containing {context}. {context} is replaced with the chat message (and split into a prefix/suffix for the placeholder).	<#00FF00>{context}</#00FF00>
Name Paint	A template containing {context}. {context} is replaced with the player’s name.	<GRADIENT:c6d7b9,ee6f68>{context}</GRADIENT>
Tag	The tag text itself (no {context}).	&8[<#ed6de5><b>Suzuka</b></#ed6de5>&8]
Glow	A comma-separated list of color names. The glow placeholder cycles through them every 2 seconds; only valid color names are kept.	BLACK,WHITE or RED,GOLD,YELLOW
Tab Icon	A symbol or short text.	⛏
Join / Leave Message	The message, with {player} for the player’s name. Wrap in [center]...[/center] to center it.	[center]&e{player} joined the server![/center]

Colors and glow need a renderer

For chat color, tag, name paint and tab icon, Value is exposed through PlaceholderAPI for your chat/nametag/tab plugin to display - the plugin doesn’t print them itself (except chat color when Paint-Chat-Message is on). Glow Value colors only come through the %optimalcosmetics_glow% placeholder; on its own the plugin just makes the player glow with the default white outline. Join/leave messages are the exception - the plugin sets those directly. See Placeholders.

Item fields

Material, Base64 and Custom-Model-Data above are part of the shared item definition used across the plugin (voucher templates, menu items, case items, temporary icons). The full field set:

Key	Description
Material	Required. XMaterial name. An invalid material is a loud error.
Name	Display name.
Lore	List of lore lines.
Amount	Stack size (default 1, minimum 1).
Base64	Head texture, used when Material is PLAYER_HEAD.
Custom-Model-Data	Applied when non-zero.
Item-Flags	List of Bukkit item flags, e.g. HIDE_ATTRIBUTES.

The Voucher block

Add a Voucher block to a cosmetic to make it giveable with /cosmeticsadmin givevoucher and to let cases hand out a voucher when a player wins a cosmetic they already own. It’s an item definition with these extra tokens: {cosmetic}, {rarity}, {type}, {count}, {date}, {primary}, {secondary}.

Galaxy:
  Enabled: true
  Order: 2
  Rarity: "Epic"
  Material: "PLAYER_HEAD"
  Base64: "eyJ0ZXh0dXJlcyI6..."
  Name: "{primary}<b>Name Paint:</b> <#ed6de5>Galaxy</#ed6de5>"
  Value: "<#ed6de5>{context}</#ed6de5>"
  Voucher:
    Material: PAPER
    Name: "&f{cosmetic} Voucher"
    Lore:
      - "{secondary} - &7Type: &f{type}"
      - "{secondary} - &7Rarity: &f{rarity}"
      - ""
      - "&e➥ Click to redeem!"
    Item-Flags:
      - HIDE_ATTRIBUTES

Without a Voucher block, a cosmetic uses the global Voucher template in config.yml if one is set; with neither, the cosmetic can’t be given as a voucher.