The crate

The crate is how skins are won rather than given. A key is spent, a reel falls, and what it lands on is unlocked on the player's account: the whole skin, every piece it fits, owned for good whatever happens to their rank afterwards. The crate itself is ExyliaLib's; this plugin hands it the skins in skins.yml and reads its settings from config.yml and its lines from messages.yml.

It works in every behaviour.mode. On an item server there is no wardrobe to wear an unlock in, so set crate.reward to ITEM or BOTH there and the crate hands over the skin item.

Rarities

Every skin declares a tier in skins.yml, and crate.tiers in config.yml declares what the tiers are:

crate:
  tiers:
    common:
      name: "Common"
      color: "{muted}"
      chance: 60.0
      priority: 1
    rare:
      name: "Rare"
      color: "{info}"
      chance: 25.0
      priority: 2
    epic:
      name: "Epic"
      color: "{accent}"
      chance: 12.0
      priority: 3
    legendary:
      name: "Legendary"
      color: "{highlight}"
      chance: 3.0
      priority: 4

The forty shipped skins are 14 common, 12 rare, 9 epic and 5 legendary: one colour and a trim stay common, and the more a skin moves the rarer it is. The full list is on Skins.

Nothing here is hard-coded. Delete legendary, invent mythic, rename all four: the key is the id skins.yml writes as tier, and a skin naming a rarity that no longer exists counts as the first one. A skin with no tier is common.

Keys

Two kinds, and the crate takes both.

On the account

A number on the player's crate row. Nothing can be dropped, duped, or lost to a full inventory:

/armorskinsadmin keys give <player> <amount>
/armorskinsadmin keys take <player> <amount>
/armorskinsadmin keys set <player> <amount>
/armorskinsadmin keys check <player>

Safe to run from console and for players who are offline — a shop, a vote listener or a reward plugin hands keys over the same way:

[console] armorskinsadmin keys give %player% 1

Every player is given crate.start-keys keys — none by default — the first time they are seen.

In the hand

An item, so it can be sold, put in a kit, dropped and given to a friend:

/armorskinsadmin item key <player> [1-64]

Right click a bound crate block holding one and it opens on the spot: one key, one reel, no question screen. Left clicking never spends one — that is how a player asks what a block is. How the key is drawn is crate.key-item in config.yml (material and glow) and key-item in messages.yml (name and lore); it is recognised by what it carries in its data, not by its name or material. Keys that do not fit in the inventory wait and are handed over on the player's next join, with rewards-claimed.

Opening

/wardrobe crate, the SKIN CRATE button in the corner of the wardrobe, or a bound block clicked without a key in hand. The first screen asks only one thing: how many at once.

The 3D opening

crate:
  opening: SPATIAL   # INVENTORY (default): the reels in menus/crate_open.yml

With SPATIAL the question screen stays the same, but the choice opens the crate in the world instead of in menus/crate_open.yml: a crate stands in front of the player, a reel of skins slows onto the prize, the lid opens, the prize grows into the middle with its name, rarity and whether it was new or a duplicate, and the player's own body appears wearing it on every piece it fits. After the last crate, OPEN ANOTHER (while they can pay for one) and DONE.

The prize is drawn and the keys spent exactly as with the reels; only what is shown changes. Sneaking skips to the end and hands every prize over at once, and so does dying, changing world or quitting. While it plays the player is held still and sees nobody. Its look is spatial/crate.yml, written by ExyliaLib the first time.

A client older than 1.21.4 always gets the inventory reels, whatever opening says.

What comes out

crate.reward decides:

crate.won names what came out (%reward%) and its rarity (%tier%).

Duplicates

Landing on a skin the player has already unlocked hands keys back, as many as crate.duplicate-refund says, with crate.duplicate (%refund% is how many). At the default of 1 a duplicate is a free re-roll rather than a loss.

A skin the player only owns through a permission is not a duplicate: it is unlocked for good, so it outlives the rank that granted it.

Buying with currency

A skin the player does not own can also be bought from the wardrobe. While shop.enabled is on and the skin has a price, its locked row is drawn by purchasable_template instead of no_permissions_template, with the price in its lore; clicking it asks to confirm, charges the price and unlocks the skin exactly as a crate would — the whole skin, for good.

shop:
  enabled: true
  tier-prices:
    common: 500
    rare: 1500
    epic: 4000
    legendary: 10000

A skin's own price in skins.yml wins over its rarity's:

skins:
  galaxy:
    tier: epic
    price: 2500                              # the default currency
  eclipse:
    tier: legendary
    price: {amount: 50, currency: gems}      # a named currency

The money goes through ExyliaLib's economy, so it is whichever of ExyliaEconomy or Vault the server runs; with neither, every price is unavailable and nothing is offered. One purchase per player at a time, and an unlock that fails after the charge gives the money back. What the player is told — the confirmation, success, not enough money, already owned — is ExyliaLib's own wording, under purchase in ExyliaLib's messages.yml.

A skin is offered wherever the player may not wear it on the piece being dressed, so a player who owns one piece through a per-piece node can still buy the rest: the purchase is only refused as already owned once they may wear every piece it fits.

Settings

crate:
  enabled: true
  start-keys: 0
  duplicate-refund: 1
  reward: UNLOCK
  blocks: []
  max-at-once: 4
  spin-frames: 34
  stagger-seconds: 2.0
  opening: INVENTORY
  key-item:
    material: TRIPWIRE_HOOK
    glow: true

on-spin, on-win and on-duplicate are full ExyliaLib effect blocks — title, action bar, boss bar, sound, particle and firework — played on every falling tick, and then once per reel as it lands. They ship as a hi-hat, a level-up and a bass note.

Crate blocks

A physical block, anywhere in the world, that opens the crate when it is clicked:

/armorskinsadmin crate block add      # the block you are looking at, up to six blocks away
/armorskinsadmin crate block remove
/armorskinsadmin crate block list
/armorskinsadmin crate block clear

They are written to config.yml, not into the world, so a bound block survives a schematic paste, a world edit and a rollback. While it is bound it cannot be broken, blown up or pushed away, and clicking it no longer does what its material does — a crate drawn on a barrel must not open a barrel.

Handing skins over without a crate

/armorskinsadmin unlocks grant <player> <skin>
/armorskinsadmin unlocks revoke <player> <skin>

The same unlock a crate writes, for a reward plugin or a support ticket. It outlives a rank running out and needs no permissions plugin. Taking back everything a player unlocked, or starting a new season, is ExyliaLib's job: /exylialib resetplayer <player> ExyliaArmorSkin or /exylialib wipe. See ExyliaLib commands.