crates

Every crate is one file in crates/. The file name (without .yml) is the crate’s id, used in commands and placeholders, and its capitalized form is the {crate} name shown in messages (vote.yml → Vote). After editing, run /cratesadmin reload.

One example ships, vote.yml. A walkthrough is in Creating Crates; this page is the full field reference.

File layout

Settings: { … }
Display-Item: { … }
No-Keys-Item: { … }
Place-Item: { … }
Particles: { … }
Hologram: { … }
Rewards: { … }

Section	Required	Description
Settings	yes	Mode, animation, preview and open options.
Display-Item	yes	The crate’s icon in /crates, plus its Slot.
No-Keys-Item	no	Icon flashed in the clicked slot when a player without keys tries to open the crate. Without it, only the message and sound play.
Place-Item	yes	The block given by /cratesadmin place.
Particles	no	Particles around placed crate blocks.
Hologram	no	Hologram above placed crate blocks.
Rewards	yes	At least one reward.

Settings

Settings:
  Mode: "ROLL"
  Spin-Animation: "csgo"
  Preview-Enabled: true
  Preview-Menu: "default"
  Mass-Open-Enabled: true
  Display-Amount: -1

Key	Default	Description
Mode	ROLL	ROLL rolls a weighted random reward. PICK lets the player choose the reward from the preview, one key per pick.
Spin-Animation	none	A file name from animations/ without .yml, or "none" / "" for no animation. Ignored by PICK crates.
Preview-Enabled	true	Lets players preview the rewards (right click in /crates, left click on a block, /crates preview). Must be true for a PICK crate.
Preview-Menu	""	A file name from previews/ without .yml. Required whenever Preview-Enabled is true.
Mass-Open-Enabled	true	false caps every open to one key: the Open All Keys button is hidden and /crates open <crate> 50 opens just one. Ignored by PICK crates.
Display-Amount	-1	Stack size of the icon in /crates. -1 shows the player’s key balance (at least 1, at most a full stack). Any other number is a fixed size.

A crate that names a missing file does not load

If Preview-Menu names a preview that does not exist, or Spin-Animation names an animation that does not exist or failed to load, the whole crate fails to load and the console names the crate file and the missing file. It never opens without its animation or preview.

Display-Item

Display-Item:
  Material: LIME_SHULKER_BOX
  Slot: 11
  Name: "&a&lVote Crate"
  Lore:
    - "&7Earned by voting for the server,"
    - "&7every key opens one reward."
    - ""
    - "&aInformation:"
    - "&2 - &7Keys: &f{keys}"
    - "&2 - &7Rewards: &f{rewards}"
    - ""
    - "&e➥ Left click to open!"
    - "&e➥ Right click to preview!"

Slot is the raw slot in the /crates menu, from 0. A slot outside the menu Size hides the crate from the menu (it still works on blocks and with /crates open). Give each crate its own slot.

Tokens: {crate}, {keys} (the viewer’s keys), {rewards}, {player}. The stack size comes from Settings.Display-Amount, not Amount.

No-Keys-Item and Place-Item

No-Keys-Item:
  Material: BARRIER
  Name: "&c&lError!"
  Lore:
    - "&7You don't have any &f{crate} &7keys to open!"

Place-Item:
  Material: LIME_SHULKER_BOX
  Name: "&a&lVote Crate"
  Lore:
    - "&7Place this block to instantly"
    - "&7register it as a crate block."

No-Keys-Item flashes for about two seconds in the clicked slot of the crates menu or a PICK picker. It takes the same tokens as Display-Item.

Place-Item must be a placeable block. See Crate Blocks.

Item fields

Display-Item, No-Keys-Item, Place-Item and every reward Display-Item are standard items:

Field	Description
Material	Any material name. Required.
Name	Display name.
Lore	Lore lines.
Amount	Stack size.
Base64	Head texture value, for PLAYER_HEAD only. "{player}" shows the viewer’s own head.
Custom-Model-Data	Custom model data for resource packs.
Item-Model	Item model key for resource packs.
Glow	true adds an enchant glint.
Enchantments	A section of enchantment: level.
Unbreakable	true makes the item unbreakable.
Item-Flags	A list of item flags, such as HIDE_ATTRIBUTES.

Names and lore support colors, MiniMessage and PlaceholderAPI.

Particles

Particles:
  Enabled: true
  Interval: 2
  Particle: "Dust"
  Color: "#00FF00"

Key	Default	Description
Enabled	false	false (or no section) means no particles.
Interval	2	Ticks between particle frames. Minimum 1.
Particle	DUST	Dust (or redstone) draws two counter-rotating dust rings around the block. Any other Bukkit particle name is spawned as a burst above the block, written as NAME;ox;oy;oz;speed;count. Everything after the name is optional and defaults to 0.4;0.5;0.4;0;6.
Color	#FF5555	Dust only. One hex color, or several separated by commas ("#FF0000,#00FF00,#0000FF") for a smooth cycle through them.

The rings make one full turn every 50 ticks. Particles are only sent to players within about 34 blocks who can see the block. An unknown particle name or a bad color fails the crate load.

Hologram

Hologram:
  Enabled: true
  Height: 2.9
  Update-Interval: 50
  Lines:
    - "&a&lVote Crate"
    - "&7You have &f{keys}x &7crate keys."
    - "&e➥ Left click to preview!"
    - "&e➥ Right click to open!"
    - ""
    - "{item-display}"

Key	Default	Description
Enabled	false	false (or no section) means no hologram.
Height	2.0	Height above the bottom of the block, in blocks.
Update-Interval	30	Ticks between updates. Each update moves on to the next reward. Minimum 1.
Lines	required	The hologram lines, top to bottom. An enabled hologram with no lines fails the crate load.

Hologram tokens

Token	Value
{crate}	The crate’s name.
{rewards}	Number of rewards.
{item-display}, {reward}	The current reward’s display name. Cycles through every reward.
{chance}	The current reward’s chance.
{keys}	The viewer’s own key balance.

{keys} and %...% placeholders are filled in per viewer. Holograms are shown to players within 48 blocks.

Rewards

Every key under Rewards is one reward, and the key is its id. Order matters: it is the order of the preview, the summary message and dispatch.

Rewards:
  "1x T1 Souls Pouch":
    Display-Item:
      Material: EMERALD
      Name: "&a&lT1 Souls Pouch &2&l(1x)"
      Lore:
        - "&8Common Reward"
        - ""
        - "&aInformation:"
        - "&2 - &7Chance: &f{chance}%"
    Actions:
      - "[console] vouchers give {player} soulspoucht1 $1"
    Chance: 25.0

Key	Required	Description
Display-Item	yes	The icon in previews, pickers and animations. Its Name is the reward’s name in the summary and holograms (the reward id is used if it has none). Tokens: {crate}, {reward}, {chance}, {rewards}.
Chance	yes	The weight. Must be above 0. The roll is bounded by the sum of all chances, so any scale works.
Actions	one of	[type] argument lines run when the reward is won.
Items	one of	Real items given when the reward is won. Written by the editor; editing them by hand is not recommended.

A reward needs Items, Actions, or both. A reward with neither, or with a chance of 0 or lower, fails the crate load.

Reward actions

Action	Does
[console] <command>	Runs the command from console.
[player] <command> / [command] <command>	Runs the command as the player.
[message] <text>	Sends the player a chat message. Supports [center].
[broadcast] <text>	Sends a message to everyone online.
[actionbar] <text>	Shows an action bar message.
[title] <title>;<subtitle>;<in>;<stay>;<out>	Shows a title. Times are in ticks.
[sound] <NAME;volume;pitch>	Plays a sound to the player.

{player}, {uuid} and PlaceholderAPI placeholders are resolved in every action. Stick to the types above: a line with any other type throws an error when the reward is handed out.

Scaling with $n

When several keys are opened at once, a reward can be won several times.

• An action containing $n runs once, with every $n multiplied by the number of wins. With three wins, [console] give {player} diamond $16 runs once as give Steve diamond 48.
• An action without $n runs once per win.
• Items are multiplied by the number of wins and given in full stacks. Whatever does not fit is dropped at the player’s feet.

Validation

Each crate file is validated on load and on /cratesadmin reload. A broken file is skipped, logged to console with its file name and the reason, and every other crate keeps loading. These fail a crate:

• Missing Settings, Display-Item, Place-Item or Rewards section
• No rewards, a reward with Chance of 0 or lower, or a reward that gives nothing
• An unknown Mode
• Preview-Enabled: true without a Preview-Menu, or a Preview-Menu that does not exist
• A PICK crate with Preview-Enabled: false
• A Spin-Animation that is not a loaded animation
• An enabled hologram without lines, an unknown particle or a bad color
• An invalid material anywhere