Skip to content
BattleStudio

cosmetics

The cosmetics/ folder - one file per type, every cosmetic's fields, values and voucher block.

Cosmetics live in cosmetics/, one file per type. Every top-level key in a file is one cosmetic, and the key is its id. After editing, run /cosmeticsadmin reload. A walkthrough is in Creating Cosmetics; this page is the field reference.

File Type Type key (for TYPE:id)
chat-colors.yml Chat Color CHAT_COLOR
tags.yml Tag TAG
name-paints.yml Name Paint NAME_PAINT
rank-colors.yml Rank Color RANK_COLOR
glow.yml Glow GLOW
tab-icons.yml Tab Icon TAB_ICON
join-messages.yml Join Message JOIN_MESSAGE
leave-messages.yml Leave Message LEAVE_MESSAGE

The folder is extracted only when it does not exist. A type file that is missing simply means that type has no cosmetics. Delete the whole folder to get the shipped examples back.

Cosmetic fields

Section titled “Cosmetic fields”
"Rose Quartz":
  Enabled: true
  Rarity: "Exotic"
  Material: "PLAYER_HEAD"
  Base64: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0..."
  Custom-Model-Data: 0
  Name: "{primary}<b>Chat Color:</b> <GRADIENT:fa8cb2,d14977,a82255,8a0c43>Rose Quartz</GRADIENT>"
  Lore:
    - "&7Soft pink, for soft words."
    - ""
  Value: "<GRADIENT:fa8cb2,d14977,a82255,8a0c43>{context}</GRADIENT>"
Key Default Description
Enabled true false hides it from the menu, the market and case pools. Owners keep it.
Rarity Common A name from Rarity-Colors. Sets {primary} / {secondary} and the rarity sort.
Material type default Icon material. Registry names and XSeries names both work. An unknown name fails the load naming the cosmetic and file. Defaults: NAME_TAG for chat colors, tags, name paints and rank colors, GLOWSTONE for glow, PAPER for tab icons and join/leave messages.
Base64 "" Head texture, used only when Material is PLAYER_HEAD.
Custom-Model-Data 0 0 leaves it unset.
Name the id Icon name, and the {cosmetic} shown in messages, vouchers and case menus.
Lore [] Extra lore shown above the Lore-Addons state lore.
Value "" What the cosmetic does. See Values per type.
Voucher none Optional voucher item for this cosmetic. See Voucher block.

{primary} and {secondary} are replaced with the rarity’s colors in Name, Lore and Value. Lore lines also take {type}, {rarity} and {count} (enabled cosmetics of that type).

Ids are case-sensitive in the file but matched case-insensitively in commands. Quote ids with spaces ("Rose Quartz"); in commands, use the type prefix if two types share an id (CHAT_COLOR:Lime).

Values per type

Section titled “Values per type”
Type Value Example
Chat Color Format around {context} (the message). "<#00FF00>{context}</#00FF00>"
Tag The tag. "&8[<#ed6de5><b>Suzuka</b></#ed6de5>&8]"
Name Paint Format around {context} (the name). "<GRADIENT:c6d7b9,ee6f68,5e8d5a>{context}</GRADIENT>"
Rank Color Format around {context} (the rank, colors stripped). "<GRADIENT:ffd479,ff8c42,e8402a>{context}</GRADIENT>"
Glow Comma-separated chat color names. "BLACK,WHITE"
Tab Icon The symbol. "⛏"
Join Message The join line, {player} for the name, optional [center]...[/center]. "[center]&e{player} joined the server![/center]"
Leave Message The quit line, same rules. "[center]&e{player} left the server![/center]"
  • A chat color, name paint or rank color without {context} has no effect: chat is not painted, the name and rank come back unchanged.
  • Glow colors must be among BLACK, DARK_BLUE, DARK_GREEN, DARK_AQUA, DARK_RED, DARK_PURPLE, GOLD, GRAY, DARK_GRAY, BLUE, GREEN, AQUA, RED, LIGHT_PURPLE, YELLOW, WHITE. Any other name fails the load. %optimalcosmetics_glow% steps through them every 2 seconds.
  • An empty join or leave Value leaves the vanilla message in place.

Voucher block

Section titled “Voucher block”

A Voucher section on a cosmetic overrides the global Voucher template for that cosmetic only.

Lime:
  Rarity: "Legendary"
  Material: "PLAYER_HEAD"
  Name: "{primary}<b>Chat Color:</b> <#00FF00>Lime</#00FF00>"
  Value: "<#00FF00>{context}</#00FF00>"
  Voucher:
    Material: LIME_DYE
    Name: "&a{cosmetic} &7Voucher"
    Lore:
      - "&7Right-click to unlock this"
      - "&7{type} &7({rarity}&7)."
    Glow: true

It is a standard item and takes the tokens {cosmetic}, {type}, {rarity}, {count}, {date} (MM/dd/yyyy), {primary} and {secondary}.

The voucher stores the cosmetic’s type and id, not its look. Editing the template changes new vouchers only; renaming or deleting the cosmetic makes existing vouchers invalid.

Validation

Section titled “Validation”

These fail loudly on load and on /cosmeticsadmin reload, naming the cosmetic and file:

  • An unknown Material
  • A glow Value naming something that is not a chat color

Check the console after every reload.