SnCrates changelog

Changes

• Crate icons in the editor. To tell crates apart in /crates editor, pick up any item from your own inventory and click a crate with it. The crate list draws that crate with the item from then on, instead of the chest (or whatever templates.crate.material is). The crate stores a copy of one item: the item stays on your cursor, so you can click the next crate with it or put it back.
• Shift + right-click a crate in the list to go back to the default icon.
• The icon still gets the crate template's name and lore on top. The item's own lore is not shown; a new {lore} placeholder on the crate template places it wherever you want it.
• Only admins in the editor see the icon. Every player menu draws crates exactly as before. Duplicating a crate copies its icon.
• guis/editor-main.yml now declares player-inventory: open, which is what lets you pick an item up while the editor is open. Nothing can be put INTO the menu: clicks on its cells stay cancelled. Existing installs get the new keys on the next boot; the two new lore hint lines only appear in a fresh file.
• The icon is saved in the crate's file as editor-icon:. A value that cannot be read is reported once in the console and the crate is drawn with the default icon; the value is kept until you reset the icon.
• Developer API, additions only: Crate#getEditorIconClone(), Crate#withEditorIcon(...), Crate.Builder#editorIcon(...).

Now requires SnLib 1.28.0 or later (was 1.24.0).

Changes

• A hologram above every crate block. Every block bound to a crate now shows floating text. It appears the moment the block is bound, and goes when it is unbound or its crate is deleted. It follows the crate's display name when you rename it in the editor.
• Three providers, picked in config.yml. holograms.provider is snlib by default, which is built in and needs nothing else. decentholograms and fancyholograms draw them through those plugins instead, and there every viewer sees their own value of a player placeholder such as %sncrates_keys_<crate>%. A provider that is missing, or too old or new to work, falls back to snlib with one console warning. Switching provider takes effect on /crates reload.
• Every value is configurable. holograms.enabled is the master switch. height is the distance from the block's top face to the lowest line, and means the same under every provider. update-interval-ticks sets how often placeholders refresh, and lines is the template ({crate} is the display name, {crate-id} the id).
• Per crate, in the crate's own file. A hologram: section can replace lines or height for that crate only, or hide its holograms with enabled: false. Keys you leave out follow config.yml, and an editor save keeps the section exactly as you wrote it, placeholders included.
• DecentHolograms and FancyHolograms are optional soft dependencies. Worlds that load late, and a hologram plugin stopping or starting while the server runs, are handled without a reload.
• Developer API, additions only: Crate#getHologram(), Crate#withHologram(...) and the new com.sn.crates.model.CrateHologram.

Existing installs get the new holograms: block in config.yml on the next boot, with holograms switched on. Set holograms.enabled: false to keep crate blocks bare.

Changes

• A crate key's own lore no longer shows on the menu icons drawn from it. The crate icons in /crates and the preview's info and withdraw buttons are all drawn from the crate's physical key item, and SnLib paints a template over a supplied item by appending the template's lore under the lore the item already carries. The result was every player reading the key's redeem instructions above the balance the icon exists to show, with no way for a menu file to remove or move them.
• New {lore} placeholder. Those lines are not gone: write {lore} in a template's lore: and they come back, one lore line per line the key has, exactly where you put it. Nothing shows it by default.
  • guis/key-balance.yml - the default template and any per-crate template
  • guis/preview.yml - the info and withdraw templates
  • guis/preview-compact.yml - the info template
• Reward icons in the preview are unchanged: a reward's own lore on its own icon is what the preview is for.

Existing installs get the new behaviour with no file edit; nothing in your menu files is rewritten.

Changes

• Preview titles can name the crate again. PreviewMenu now seeds {crate} (display name) and {crate-id} into the window title when it opens, the way the key balance menu seeds {player}. From 2.0.0 to 2.3.0 a title: "{crate}" in preview.yml or in a custom preview layout rendered the braces literally. No file changes are needed on an install that already wrote {crate} in a preview title; the shipped preview.yml header documents the two title placeholders.

Changes

• Mass opens are spread over ticks. access.mass-open-per-tick (shipped 10) crates settle per server tick: the first chunk in the click, the rest one tick apart, so a large balance never runs every reward command in one tick. Every crate of the batch is still a complete open (roll, one key, delivery), so a batch that stops early - the player leaves, the crate is deleted, the server stops - has spent exactly the keys of the crates it opened; the rest stay in the balance.
• The /crates menu stays open through a mass open and repaints as the batch drains. access.mass-open-cooldown-ticks (shipped 10) throttles a held Q; the refusal is silent unless messages.open.mass-cooldown says something.
• A reward-by-reward summary when the batch ends: Opened Nx <key>: then one line per distinct reward ({amount}x {reward}, {total} also available), plus a line for the fails when there were any.
• Fail chance. fail.chance in config.yml, or settings.fail-chance per crate (also from the new Fail Chance button on the crate panel): a percentage of opens that spend the key and win nothing. It is rolled in the same draw as the winner, after the check that something is winnable, so a crate with everything on limit still refuses with the key unspent. The animation lands on fail.item with effects.fail-sound and no particle burst, the strip shows that item at the fail rate, the player gets messages.open.fail, opening.log writes status.failed where the reward's name goes, the open counts and no limit burns. CrateOpenEvent fires for it; CrateRewardEvent does not. The preview's info icon says Fails N% of the time and %sncrates_failchance_<crate>% exposes the number.
• The editor's Crate Block lore now says "click a block": either mouse button lands the armed bind or unbind gesture.

New keys merge in on boot: access.mass-open-per-tick, access.mass-open-cooldown-ticks, fail.chance, fail.item, effects.fail-sound, and the lang keys under messages.open.*, messages.preview.fail-tag, messages.editor.* and status.failed. The editor-crate.yml layout gained the fail-chance cell h on its fourth row (fffhfrfff); an existing install keeps its own layout, so add the letter there to see the button.

Changes

New: /crates key wipe [crate] [confirm]

Deletes the virtual key balances of every player on the server, offline players included. Without a crate id it clears every crate; with one it clears only that crate. Physical key items are untouched - they live in inventories and no balance command reaches them.

It cannot be undone, so it runs in two halves. Without the confirmation word the command only counts: it reports how many balances and how many keys are at stake and quotes back the exact line that would destroy them. Only a second invocation carrying that word deletes anything.

/crates key wipe
> WARNING This deletes 4,120 virtual key(s) across 1,284 balance(s), for EVERY player
> and EVERY crate. It cannot be undone. Run /crates key wipe confirm to go through with it.

/crates key wipe confirm
> Wiped 1,284 virtual key balance(s), for every player and every crate.

• The confirmation word lives in the language file (messages.keys.wipe-confirm-word, default confirm), so it translates with the rest of the plugin. It is never tab-completed - having to type it is the safety.
• Online players' cached balances are cleared too, so nobody keeps spending keys that no longer exist anywhere.
• A mistyped crate id is refused rather than silently widening into a server-wide wipe.
• Works on a crate that no longer accepts virtual keys: those leftover rows are exactly what this is for.

New permission

sncrates.admin.wipekeys (default op, child of sncrates.admin). Required on top of sncrates.admin.keys, so the ordinary key commands can be delegated to a junior admin without handing them the one that empties the key economy.

New language keys

messages.keys.wipe-confirm-word, wipe-warning, wipe-warning-crate, wiped, wiped-crate, wipe-nothing, wipe-nothing-crate, wipe-failed. They merge into an existing lang/messages_en.yml on boot; your edits are kept.

Changes

The editor tells you how to get out of a chat prompt. Every prompt now sends the cancel word and the seconds left underneath it. One language key (messages.editor.cancel-hint), so it covers every prompt including new ones.

Preview Layout is a click, not a chat prompt. It cycles the layouts listed under the new editor.preview-layouts in config.yml, skipping any id that no file in guis/ backs, so a crate can never end up pointing at a preview that will not open.

Accepted Keys offers physical, virtual and both. PERMISSION is off the button. It still parses out of a crate file and still opens crates - clicking the button on such a crate restarts the cycle at physical.

A reward's win commands are listed on its icon, numbered, so you can see which ones are there. A line is marked in red when it will not run as written: it is empty, it uses a placeholder that does not exist (only {player}, {amount} and {crate} are filled in), or it uses a %papi% token on a server with no PlaceholderAPI.

Fixed: opening a crate panel logged Invalid value in config.yml -> 'effects.complete-particle-count': received '40', using default '40' once per render. Nothing was wrong with the value - the panel was reading a number as text. It is read as a number now.

Tidier defaults. The five three-state controls no longer share two dyes between them; each state of each control has its own item. Every "Back" is the same door and the arrows are only ever page arrows. The menu and message text says what to write - FLAME, BLOCK_CHEST_OPEN 1 1.2 - instead of naming types like "a Bukkit particle" or "DateTimeFormatter syntax".

CHAIN was avoided on purpose: it is IRON_CHAIN on 1.21.9 and newer. Every material shipped here resolves on 1.20.2, 1.21.1 and 1.21.11.

SnCrates v2.0.0

A complete rewrite. SnCrates 2.0.0 was written from zero on SnLib and does everything 1.16.2 did, with the same crates, the same commands and the same key items already in your players' inventories.

Read the "Before you update" section. This is a major version and it is a clean break, not an in-place upgrade: some stored data is deliberately not carried over.

Before you update

Your database tables start empty

Every table now carries the sncrate_ prefix, so 2.0.0 does not read the rows 1.16.2 wrote. On the first boot you get empty key balances, statistics, opening history, physical block bindings and reward filters.

The prefix is not cosmetic. CREATE TABLE IF NOT EXISTS never compares columns, so a table name this plugin does not exclusively own can bind the schema to another plugin's table and fail every query for the life of the install.

The one you will notice on the server: every placed crate block loses its binding and becomes an ordinary breakable block. Re-bind them from the editor.

If you ran a pre-release 2.0.0 build on a staging server, this empties those tables too, not only 1.16.2's.

Back up your database and your plugins/SnCrates/ folder before updating. Virtual key balances are the thing worth restoring by hand if you have a busy server.

Your configuration is kept, and merges from now on

config-version is gone and nothing is ever regenerated. New keys merge into your files on boot and your values, your comments and any extra keys you added survive. You can freeze a section you do not want touched with a # sn:extensible marker.

Old files are simply not read. There is no importer and no migration path - that is deliberate.

SnLib is required

SnCrates 2.0.0 needs SnLib 1.24.0 or later installed. It will not enable without it.

Changed behaviour

The editor captures the item in your hand

The screen that sets a reward's item, adds a reward or sets a crate's key item no longer has a slot you drag into. Hold the item in your main hand and click the capture cell.

• You keep what you are holding - the crate gets a copy. The old screen consumed the stack.
• Closing the window now changes nothing. There is a Back button.
• The captured amount is whatever you were holding; the reward's own Amount control is the easier way to change it afterwards.

This replaced a hand-built inventory that could not use the library's click protection and leaked real reward items in five separate ways.

Mass open ships with a limit

mass-open-max now ships as 64 instead of unlimited. -1 and 0 still mean genuinely unlimited, and the config comment says what that costs you: the open loop runs on the main thread, so an unbounded mass open is a server freeze proportional to the number of keys.

Opens are refused while a player's data is still loading

Rather than running with per-player limits unenforced, an open is refused with a new messages.open.data-loading line and a reload of the slice is attempted.

Deleting things cleans up after itself

• Deleting a crate unbinds every physical block bound to it, clears its global limits, per-player limits and reward filters, and force-closes (and settles) any open still running on it. Key balances, stats and history are deliberately kept - those are entitlement and record.
• Deleting a reward clears that reward's limits and filters and settles any spin running on it. Reward ids are reused by the editor, so leaving them behind gave the next reward the old one's limits.

Key commands

• /crates key take and /crates key set now refuse on a crate that accepts no virtual keys, instead of reporting success and doing nothing. New line: messages.keys.no-virtual-balance.
• Both work again on a permission-only crate, matching give.
• [amount] stays optional for give, giveall and take, and required for set.

Key protection

• A key in your off hand is now protected on a live crate block too. The open exemption stays main-hand only, matching the hand the open listener acts on.
• An orphaned crate block no longer exempts a key from protection.
• Protections remain unconditional and apply to operators. There is no bypass permission.

Smaller changes

• animations.csgo.strip-size and animations.wheel.strip-size are capped at 256.
• A mass open no longer aborts when one reward fails to settle; the failure is logged and the remaining keys still open and report.
• A chat prompt that times out now reopens the editor screen, as typing cancel already did.
• blocks.bind-armed / blocks.unbind-armed now say "click ... either button", because either button really does consume the armed gesture.
• The public CrateOpenEvent fires immediately after the session is registered rather than just before. Still after the key is consumed and before the reward is delivered, so the documented contract is unchanged.
• New config keys: api-events.enabled, defaults.reward-weight.
• Removed two language keys that nothing read: messages.general.reload-summary and reload-failed.

What did not change

These are the things a rewrite is most likely to break, so they were held constant on purpose.

• Your key items still work. They carry the same sncrates:crate_id tag, so keys already in players' inventories are recognised.
• Placeholders: %sncrates_total_opens%, %sncrates_keys_<crateId>%, %sncrates_opens_<crateId>%, %sncrates_chance_<crateId>_<rewardId>%.
• Commands: /crates, aliases crate and snc. A bare /crates still opens your own key balance.
• The public API: CrateOpenEvent and CrateRewardEvent keep their signatures.
• Reward delivery is still exactly once. The winner is drawn before the first animation frame renders and delivery fires only at settle, so closing the menu, disconnecting or reloading the plugin mid-spin each deliver exactly one reward and consume exactly one key. The key is consumed after the winner is picked, so a crate with nothing winnable refuses the open and you keep your key.

Under the hood

Rebuilt as a SnLib consumer: configuration, language, colour, menus, item building, database access, the command tree and PlaceholderAPI all run on the library instead of on hand-rolled code. The plugin no longer bundles a menu library or a YAML library, which removes an entire class of "another plugin shipped a different version" crashes.

Supports Paper 1.20.x and 1.21.x on Java 21.