The crate and the shop

A pattern or colour is a player's if a permission grants it, if a crate landed on it, or if they bought it. The last two are written to their account rather than granted as a node, so they outlive a rank running out. All three count the same in the editor, the colour picker and the API.

Rarities

Every pattern and colour in shields.yml names a tier, and crate.tiers in config.yml declares what the tiers are:

shield_patterns:
  stripe_bottom:
    name: "Base Stripe"
    tier: common

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 }

chance is a weight, not a percentage. Add, rename or delete any rarity; an entry that names none, or one that no longer exists, falls in the first. The shipped file sorts the 43 patterns and 16 colours as 35 common, 14 rare, 7 epic and 3 legendary.

The crate

One key opens one crate, and the crate can land on any pattern or colour. Keys live on the player's account, where nothing can drop, dupe or be lost to a full inventory.

Landing on something already owned — by permission, by an earlier crate or by a purchase — hands back crate.duplicate-refund keys instead.

Keys that can be held

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

A key item opens the crate when a bound crate block is right clicked while holding it. It can be traded and dropped. Its material is crate.key-item in config.yml, its name and lore key_item in messages.yml.

Settings

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

on-spin, on-win and on-duplicate are full ExyliaLib effect blocks, played as the reels turn and once per reel as it lands.

The 3D opening

With opening: SPATIAL a crate stands in the world in front of the player, a reel of shields slows onto the prize, and the reveal shows the shield it unlocks turning where the crate stood. Sneaking skips to the end and hands the prize over at once. The prize is drawn and the key spent before anything is shown, so the odds are the same either way. Its look is spatial/crate.yml, written the first time it is used.

Crate blocks

/shieldsadmin crate block add      # the block you are looking at
/shieldsadmin crate block remove
/shieldsadmin crate block list
/shieldsadmin crate block clear

They are written to config.yml, not into the world. While a block is bound it cannot be broken, blown up or pushed away, and clicking it no longer does what its material does.

Keys and unlocks by command

Unlock ids are the entry's key with what it is in front: pattern:stripe_bottom, color:red. See Commands and permissions for every subcommand; keys and unlocks work on a player who is offline too. To take every unlock and key back, reset the player with ExyliaLib's /exylialib resetplayer <player> ExyliaShields.

Keys and unlocks are stored in ExyliaLib's exylia_crate_players table, in this plugin's own database.

The shop

A locked pattern or colour can be bought from the editor or the colour picker. The row draws its price and a click asks the player to confirm before anything is charged; the menu then comes back with the row unlocked.

shop:
  enabled: true
  tier-prices:
    common: 250
    rare: 750
    epic: 2000
    legendary: 5000

A price is a number (500, 2.5k) or a block naming a currency: {amount: 50, currency: gems}. An entry in shields.yml can set its own price, which wins over its rarity's. The money is taken by ExyliaEconomy or Vault; with neither installed, or with the shop off, locked entries look exactly as they always have.

A bought entry is unlocked on the account, the same as one won from the crate. A purchase that could not be handed over gives the money back. The confirmation and every answer it sends are ExyliaLib's own lines, under purchase in ExyliaLib's messages.yml, shared by every cosmetic plugin.

In the menus, purchasable_template stands in for no_permission_template on a row that is for sale, with %price% for what it costs and the shield:buy action.