cases

Each case is one file cases/<id>.yml. The file name, lowercased, is the case id used by /cosmeticsadmin place <id>. One example ships: cases/secret.yml. The setup walkthrough is in Creating Cases. After editing, run /cosmeticsadmin reload.

The cases/ folder is extracted only when it does not exist, so a case file you delete stays deleted.

Required sections

Settings, Animation, Place-Item, Gui and Gui.Open-Item must exist in every case file, or the plugin fails to load the case files. Everything else is optional.

Settings

Settings:
  Display-Name: "&fSecret Crate"
  Currency: "Vault"
  Price: 1000
  Show-Count: 27
  Reshuffle: true

Key	Default	Description
Display-Name	the id	Shown as {case} in messages and holograms.
Currency	Vault	The economy for this case: Vault, PlayerPoints or RivalCredits. Independent of the market’s Settings.Economy.
Price	1000	Cost per opening, charged before the animation. {price} is formatted with that provider’s currency format.
Show-Count	10	How many pool cosmetics are in the rotation (at least 1, at most the pool size).
Reshuffle	true	true re-rolls the rotation at random every day at 00:00 UTC. false keeps the first Show-Count cosmetics of the pool, in order.

Animation

Animation:
  Reward-Format-Line: "&d&l{cosmetic-name} &7({cosmetic-type})"
  Primary-Colour: "#1ff22a"
  Secondary-Colour: "#1a8a20"
  Head:
    Material: PLAYER_HEAD
    Base64: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0..."

Key	Default	Description
Reward-Format-Line	&d{cosmetic-name} &7({cosmetic-type})	The floating label shown at the reveal. Tokens: {cosmetic-name}, {cosmetic-type}, {cosmetic-rarity}.
Primary-Colour	#FF5555	Dust particle color during the spin, #RRGGBB or #AARRGGBB (the # is optional).
Secondary-Colour	#FFAA00	The second dust color; each particle burst picks one of the two.
Head	the Place-Item	Optional item that spins above the block.

A color that is not valid hex fails the load and names the case. These are particle colors, not the rarity {primary} / {secondary}.

The animation runs about 5 seconds of spinning followed by 3 seconds of the reveal label, and only the opener sees it.

Pool

What the case can put in its rotation. Entries are combined and duplicates removed; disabled cosmetics are skipped.

Pool:
  - "all"

Entry	Adds
all	Every enabled cosmetic.
type:<type>	Every enabled cosmetic of a type. <type> is a file name (type:tags, type:chat-colors) or a type key (type:TAG).
<id>	One cosmetic, by id or TYPE:id.

The reward is drawn evenly at random from today’s rotation, skipping limited cosmetics that are sold out. If nothing can be won the opening is refused with CASE-EMPTY before anything is charged.

Limited

Optional. Maps a cosmetic (id or TYPE:id) to the maximum number of players who can ever win it.

Limited:
  Dark: 3
  Lime: 1

A cosmetic with a limit is shown with Limited-Lore instead of Reward-Lore. Winners are stored in the database per cosmetic, so the count carries over restarts and is shared by every case (and every server on a shared MySQL database) that lists the same cosmetic. Entries that do not match a cosmetic, or have a limit of 0 or less, are ignored.

Reward lore

How rotation cosmetics look in the case menu.

Reward-Name: "{cosmetic}"

Reward-Lore:
  - "&7This cosmetic is available within"
  - "&7cosmetic cases all year round."
  - ""
  - "{primary}Information:"
  - "{secondary} - &7Type: &f{type}"
  - "{secondary} - &7Rarity: &f{rarity}"

Limited-Lore:
  - "&7This cosmetic is a limited edition and"
  - "&7is only available for a limited time"
  - ""
  - "{primary}Information:"
  - "{secondary} - &7Winners: &f{won}/{max}"
  - ""
  - "{primary}Winners:"
  - "{winners}"

Winner-Line:
  Won: "{secondary} - &7{position}: &f{player}"
  Unclaimed: "{secondary} - &7{position}: &fNone"

Key	Description
Reward-Name	Icon name. Default {cosmetic}.
Reward-Lore	Lore for normal cosmetics. A built-in default is used when the key is missing.
Limited-Lore	Lore for limited cosmetics. A line that is exactly {winners} expands into one Winner-Line per position.
Winner-Line.Won	A filled position. Tokens {position} (1st, 2nd, …) and {player}.
Winner-Line.Unclaimed	A position nobody has won yet. Token {position}.

Tokens in all of them: {cosmetic} (the cosmetic’s Name), {type}, {rarity}, {primary}, {secondary}. Limited-Lore also has {won} and {max}.

Place-Item

The item /cosmeticsadmin place gives. It must be a placeable block; placing it registers the block as this case. A standard item.

Place-Item:
  Material: CHEST
  Name: "&a&lSecret Case"
  Lore:
    - "&7Place this block to instantly"
    - "&7register it as a case block."
  Item-Flags: [HIDE_ATTRIBUTES]

Hologram

Optional floating lines above every block of this case. Built in, no hologram plugin needed.

Hologram:
  Enabled: true
  Height: 3.4
  Update-Interval: 20
  Lines:
    - "&a&lSecret Crate"
    - "&fYou can open this case and you"
    - "&fwill reveal 1 cosmetic per roll."
    - ""
    - "&aCost: &f{price}"
    - "&aReshuffle: &f{reshuffle}"
    - ""
    - "{item}"

Key	Default	Description
Enabled	true	false (or no Hologram section) shows no hologram.
Height	2.5	Height of the top line above the block. Lower lines stack down 0.3 blocks apart.
Update-Interval	20	Ticks between line updates (20 = one second).
Lines	[]	The lines. PlaceholderAPI placeholders resolve per viewer.

Token	Value
{case}	Display-Name.
{item}	The name of one rotation cosmetic, moving to the next every update.
{count}	Number of cosmetics in the rotation.
{price}	The price, currency formatted.
{reshuffle}	Time until the next reshuffle, or the Cosmetic-Format.Never label.

The hologram is shown to players within 48 blocks and hidden from a player while their own opening animation plays.

Gui

The case menu that opens when a player clicks the block. It is defined here, not in guis/.

Gui:
  Title: "&8Secret Case"
  Size: 36
  Cosmetic-Slots: [0-26]
  Filler-Item:
    Material: GLASS_PANE
    Name: "&r"
    Slots: [0-26]
  Open-Item:
    Material: LIME_STAINED_GLASS_PANE
    Slots: [27-35]
    Name: "&a&lOpen Case"
    Lore:
      - "&aInformation:"
      - "&2 - &7Price: &f{price}"
      - "&2 - &7Reshuffle: &f{reshuffle}"
      - ""
      - "&e➥ Click to open!"

Key	Default	Description
Title	the id	Menu title.
Size	45	Menu size, a multiple of 9.
Cosmetic-Slots	none	Slots for the rotation cosmetics, in order. Numbers or a-b ranges.
Filler-Item...	none	Any number of background items whose key starts with Filler-Item (Filler-Item, Filler-Item-2, …), each with Slots.
Open-Item	required	The open button, with Slots. Tokens {price} and {reshuffle}.

Fillers are painted first, then the rotation cosmetics on top, then the open button. Clicking any Open-Item slot opens the confirm menu from guis/case-confirm.yml, which also shows the Open-Item as its preview.