SnCrates changelog

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.