The crate

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

It works in every mode: keys, the crate screens and crate blocks are there even with mode: item. Opening it needs exyliaarmortrims.crate, which everybody holds by default.

What it can land on

Two kinds of prize, every one of them in trims.yml:

A combination is never a prize; its two halves are. A trim is worn once the player owns both halves, by node or by unlock.

Rarities

Every pattern and material declares a tier in trims.yml, and config.yml declares what the tiers are, under crate.tiers:

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 shipped catalogue has 29 prizes:

Nothing here is hard-coded. Delete legendary, invent mythic, rename all four: the key is the id trims.yml writes as tier, and an entry naming a rarity that no longer exists falls back to the first one. An entry 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:

/armortrimsadmin keys give <player> <amount>
/armortrimsadmin keys take <player> <amount>
/armortrimsadmin keys set <player> <amount>
/armortrimsadmin 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] armortrimsadmin 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:

/armortrimsadmin 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

/armortrim crate, the TRIM CRATE button in the corner of the trim menu, the crate icon of the 3D wardrobe, or a bound block clicked without a key in hand. The first screen asks only one thing: how many at once.

With crate.opening: SPATIAL the reels are replaced by the opening in the world — see The 3D opening.

What comes out

crate.reward decides:

A pattern or a material has no item of its own, so with every prize being a half ITEM and BOTH behave as UNLOCK: a key never buys nothing. crate.won names what came out (%reward%) and its rarity (%tier%).

Duplicates

Landing on something the player already owns 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.

Buying with currency

Anything still locked can be bought instead of won. A locked pattern or material with a price is drawn by the menu's *_purchasable_template, with its price; clicking it asks the player to confirm, charges them and unlocks it exactly as a crate would. The 3D wardrobe sells the same halves through its BUY & SAVE button. Buying needs exyliaarmortrims.buy, which everybody holds by default.

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

An entry in trims.yml can set its own price, which wins over its rarity's:

patterns:
  silence:
    tier: legendary
    price: 25000                          # the default currency
materials:
  netherite:
    tier: epic
    price: {amount: 50, currency: gems}   # a named currency

The confirmation and every outcome — bought, already owned, not enough money — are ExyliaLib's own lines, under purchase in its messages.yml. After the purchase the menu reopens.

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 as the reels turn, and then once per reel as it lands. They ship as one sound each: BLOCK_NOTE_BLOCK_HAT, ENTITY_PLAYER_LEVELUP and BLOCK_NOTE_BLOCK_BASS.

The 3D opening

crate.opening: SPATIAL plays an opening in front of the player instead of the reels: a crate in the world, a reel slowing onto the prize, the reveal and a preview of it — a pattern is tried on the player as a full set in the first material of the catalogue, a material shows its icon. Sneaking skips to the end and hands the prize over at once.

The prize is drawn the same way either way: keys, odds, duplicates and payouts do not change. Its look is spatial/crate.yml, which is ExyliaLib's crate scene. A client older than 1.21.4 gets the reels.

Crate blocks

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

/armortrimsadmin crate block add      # the block you are looking at, up to six blocks away
/armortrimsadmin crate block remove
/armortrimsadmin crate block list
/armortrimsadmin 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 trims over without a crate

/armortrimsadmin unlocks grant <player> <prize>
/armortrimsadmin unlocks revoke <player> <prize>

<prize> is pattern:<id> or material:<id>. 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. To take back everything a player unlocked, use ExyliaLib's player reset with @account.