Prison Crates

PrisonCrates adds crates to your prison server. Players hold keys as a balance rather than as items, so they can open one key or a million in one go, and rewards can pay out PinnaPrison currencies, boosters, enchant levels, items, keys or commands. You can also place animated crates in the world and hand out lootboxes that open on the spot.

The short version

Upload the jar to plugins/ next to PinnaPrison and start the server once so it creates its files. It ships with six crates: test, rusty, iron, golden, mythical and the treasure lootbox. In game, run:

/prisoncrates give <you> test 100
/crates
/prisoncrates item test

1. /prisoncrates give puts 100 Test Crate keys on your balance. Use your own name for <you>.
2. /crates opens the crate selector. Left-click the Test Crate to open one key with the roulette reel, right-click it to see every reward and its chance, or hover over it and press Q to open every key at once. You get a chat summary of what you won.
3. /prisoncrates item test gives you the placeable Test Crate. Right-click a block to place it: it spins, bobs and shows a hologram with your own key count. Left-click it to open a key.

The Test Crate demonstrates every option, so plugins/PrisonCrates/crates/test.yml is the file to copy when you make your own. It also has an icon in the live selector, so take that icon out (see Adding a crate for where the icons live) if you don't want players to see it.

What you need

Keys and bulk opening

Keys are a number stored with each player's data, not items. You can give keys to players who are offline, as long as they've joined the server before.

In the /crates selector, left-clicking a crate icon opens one key, right-clicking opens the reward preview, Q opens every key the player has and shift + left-click opens 10. You can change these under gui.crate-click in config.yml.

Opening 1,000 keys or more at once asks the player to confirm first. Players can turn that off with the Bulk Confirmation button in the selector, and you can change the number with gui.confirm-bulk.threshold. To cap how many keys one open can spend, set limits.max-keys-per-open (0 means no cap).

However many keys are opened, each reward is handed out once with the total: 1,000 wins of currency:tokens 3,500,000 pay 3.5 billion tokens in one payment.

In the preview, players can click a reward to filter it. A filtered reward still rolls, so the odds don't change, but it's thrown away instead of given and shows as "(filtered)" in the summary. Set toggleable: false on a reward to stop players filtering it.

Reward items go into the player's inventory, and whatever doesn't fit waits in /crates claim. Nothing is dropped on the ground. Set claim.mode: always in config.yml to send every item reward from a crate straight to /crates claim instead.

Crate files and rewards

Every file in plugins/PrisonCrates/crates/ is one crate, and the file name is its id: test.yml is the crate test. Here's a trimmed copy of test.yml:

display-name: '<gradient:#F1C226:#FD6141>&lTest Crate</gradient>'
tier: '&7[Tier #0]'
# crate: virtual keys + placeable | lootbox: a physical item only (see treasure.yml)
type: crate
# A preset from animations.yml, or none
animation: 'roulette'
# Seconds between opens per player
cooldown: 0

pools:
  main:
    rolls: 1                  # draws from this pool per key
    rewards:
      tokens-small:
        weight: 1800          # relative weight, not a percentage (chance = weight / pool total)
        rarity: common
        announce: false       # broadcast when won
        actions:
          - 'currency:tokens 3,500,000'
        display:
          material: MAGMA_CREAM
          name: '&f&l3,500,000 &r&4┃ &r&c&lTokens'
          lore:
            - '{rarity}'

A crate has one or more pools, and each pool draws rolls rewards per key. The bundled crates use the weights 1800 (common), 500 (rare), 120 (legendary), 20 (mythical) and 5 (final). Run /prisoncrates simulate <crate> 1000000 to check your odds before players see them. rarity: names an entry in the rarities: list in config.yml, which sets the coloured text shown for {rarity}.

A reward can also have hidden: true (it can be won but isn't shown in the preview), permission: (only players with that node roll it), sound: and slot: (its position in the preview). test.yml shows each one with a comment.

Each line under actions: gives something. Amounts accept 3,500,000, 1_000_000 or 2.5M.

The boosted-gems reward in test.yml shows the long form of an action, with type, value, amount and chance. chance: is rolled once per open, not once per win, so in a bulk open the action either runs with the full total or not at all.

Adding a crate

1. Copy crates/test.yml (or one of the simpler tier crates, such as rusty.yml) to crates/<id>.yml and change its name, animation and rewards.

2. Run /prisoncrates reload, then /prisoncrates list to check it loaded.

3. Add an icon to the selector in plugins/PinnaPrison/guis/prisoncrates/prisoncrates-crates.yml. Copy an existing crate icon and change crate: and slot:, like this one from the file:

   yamlCopy

   rusty:
     custom-item:
       type: 'prisoncrates-crate'
       crate: 'rusty'
     material: CHEST
     slot: 11
     name: '&6&lRusty &r&e&lKey &r&7[Tier #1]'

   The filler item covers every unused slot, so take your new slot out of its slot: list. Then run /pinna reload.

4. Give yourself keys with /prisoncrates give <you> <id> 10 and try it.

Physical crates and lootboxes

A physical crate is a crate shown in the world: a spinning block with a hologram above it. It's client-side only, so nothing is placed in or saved to the world, and players see it within 32 blocks (physical.hologram-range). Its look comes from the placeable: section of the crate file, and its positions are saved in plugins/PrisonCrates/data/placed.yml.

To place one, either run /prisoncrates item <crate> and right-click a block with the item, or stand on the spot and run /prisoncrates place <crate>. Crates can't be placed in PinnaPrison's mines world. To remove one, run /prisoncrates remove near it, or sneak and left-click it. Sneak-left-clicking hands the crate item back to you.

By default, left-clicking a placed crate opens one key, right-clicking opens the preview, sneak + right-click opens every key and sneak + left-click removes it. Change these under physical: in config.yml (left-click, right-click, sneak-left-click and sneak-right-click) to preview, selector, open-one, open-all, remove or none. remove only works for players with prisoncrates.place; for everyone else it opens the preview.

A lootbox is a crate with type: lootbox. It has no keys and can't be placed. Players get it as an item, right-click it to use one up, and it opens on the spot with the crate's animation. The bundled treasure.yml is one. Give lootboxes with /prisoncrates givelootbox <player> treasure 1, or from another crate's reward with a command: action, as golden.yml and mythical.yml do. In the selector, a lootbox icon only opens its preview.

Animations

A crate picks its animation with animation: <preset>, from the presets in plugins/PrisonCrates/animations.yml. Use none to give rewards instantly.

The rewards are rolled before the animation starts, so animations never change the odds. Rewards are given at the animation's grant point, or straight away if the player closes the menu or leaves. In-world animations are client-side only.

animate-bulk: false on a crate skips the animation when more than one key is opened. Players can turn animations off with /crates animations or the button in the selector, and force-animation: true on a crate plays them anyway. Sounds and particles in the in-world animations follow each player's PinnaPrison sound and particle settings.

Commands

Player commands. /crates has the aliases /crate, /keys and /lootbox.

Admin commands. /prisoncrates has the alias /edcrates.

Permissions

You can lock a whole crate, or a single reward, behind a permission of your own with permission: in the crate file.

Files

The menus are PinnaPrison GUI files. PrisonCrates writes them once and never overwrites them, so your edits are safe across updates. Delete one and restart to get the default back. The six bundled crate files are only written when the crates/ folder doesn't exist yet.

storage.type can be yaml, sqlite or mysql. Use mysql if you run several servers, so keys follow players between them.

Placeholders

These need PlaceholderAPI. Replace <crate> with a crate id, such as rusty. Player values only show for players who are online.

Troubleshooting

A new crate works with commands but isn't in /crates. The selector is a menu file, so it only lists the crates you add to it. Add an icon to plugins/PinnaPrison/guis/prisoncrates/prisoncrates-crates.yml (see Adding a crate) and run /pinna reload. If /prisoncrates list shows the crate with 0 rewards, or the console says crates/<id>.yml has no rewards when you reload, the file most likely has a YAML mistake. The console error above that line says where.

Menu changes don't show after /prisoncrates reload. That command doesn't reload menus. Run /pinna reload instead. If the console says GUI '...' does not exist, the menu file is missing or the id under gui: in config.yml doesn't match a file name.

A reward gives nothing. Check the console after opening. Unknown reward action type means a typo in the action, and no hooked economy knows means the currency id doesn't exist in PinnaPrison. token-blocks, gem-blocks and greed-blocks pay nothing to players who don't have that greed enchant, and permission: rewards need LuckPerms. If the summary shows the reward as "(filtered)", the player filtered it in the preview: they can click it again there to undo that.

Players keep seeing "Your crate data is still loading". Their data couldn't be loaded. Look for Could not load crate data in the console. With sqlite or mysql, check the storage: settings in config.yml and that the server could download the database drivers on its first start, then restart.

A placed crate disappeared when I sneak-clicked it. By default, sneak + left-click removes a placed crate for anyone with prisoncrates.place, which ops have, and gives the crate item back. Right-click a block with the item to put it back. To stop it happening, set physical.sneak-left-click to preview or none and run /prisoncrates reload.

"Player not found!" when giving keys. give, take, set and balance only work for offline players who've joined this server before, or by their UUID. givelootbox, item and open need the player to be online.