DOCUMENTATION / 0.5 DEVELOPMENT

Crates and keys — 0.4.0 development

This page describes account keys and saved crate choices in the packaged 0.5.0-SNAPSHOT development build. See backup and recovery for current recovery boundaries.

Account keys

Account keys are stored per player UUID and crate type in keys.yml. They are enabled by default with crate-system.account-keys: true. /keys shows balances, /crates opens the crate menu and /keys open <type> opens a crate directly. Opening spends one matching key and saves seven weighted reward choices. Select one reward with a left click. Weighted draws can repeat the same reward among the seven choices.

Closing the menu or disconnecting does not discard the choices. /keys claim resumes the same draw, including after a normal server restart. Opening another crate resumes the existing choice instead of spending another key or rolling again. Item rewards require enough inventory space; a full inventory leaves the choice available. Reward definitions are snapshotted when opening, so changing the crate configuration cannot change already saved choices.

Money, shards, item stacks, custom spawners and further account keys are supported reward types. The default configuration defines Common and Prime; additional types are configurable, and the bundled donutsmp-style preset also defines Gold, Amethyst and Crimson. These are independently configured rewards; exact DonutSMP reward-table parity is not claimed.

Commands and grants

Command	Access	Behavior
`/keys`	`donsup.use`	Show account balances
`/keys open <type>`	`donsup.use`	Spend one key and display seven choices
`/keys claim`	`donsup.use`	Resume an unclaimed draw
`/keys redeem`	`donsup.use`	Convert the held stack of old tagged physical keys
`/keys give <player> <type> <amount>`	`donsup.admin`	Grant keys; account mode supports previously seen offline players
`/smp givekey <player> <type> <amount>`	`donsup.admin`	Compatibility command for the same grant
`/keyall <type> <amount>`	`donsup.admin`	Grant to every currently online player
`/keys resolve <player> refund`	`donsup.admin`	After reviewing an interrupted delivery, clear it and refund its opening key
`/keys resolve <player> complete`	`donsup.admin`	After confirming delivery, clear its interrupted status without a refund

Types use lowercase letters, numbers, underscores and hyphens, up to 48 characters. Grants accept whole amounts from 1 to 1,000,000; each account/type balance is capped at 1,000,000,000. Regular players cannot grant keys or resolve deliveries. Creator grants and shard-shop key purchases use the selected account/physical mode.

Automatic key-all

crate-system:
  account-keys: true
  keyall:
    enabled: true
    interval-seconds: 3600
    type: common
    amount: 1

The automatic grant is disabled by default. The configured interval is bounded between 60 seconds and seven days. The next run time is saved with the grants. Only online players receive keys; downtime does not accumulate multiple missed grants. Manual grants do not reset the automatic schedule. The configured type must exist under crates.

Legacy physical mode and recovery limits

Set crate-system.account-keys: false to use the previous tagged-item key and cosmetic spinner. Pending account choices remain claimable. Existing account balances remain saved. Physical admin grants reject insufficient inventory space. Hold older physical keys and run /keys redeem after enabling account mode to convert them.

Key debit and saved choices are written together in one file replacement. In development 0.4.0, new money/shard/account-key rewards automatically resume after a restart: a payment receipt prevents repeated currency credit, and account-key credit commits with claim completion. /keys claim can retry a deferred account reward. Older ambiguous claims and rewards containing physical items remain held for staff inspection of keys.yml, inventories, balances and logs. A refund command must only be used after checking whether any part of such a reward was already delivered. See the recovery protocol.

This is not a transaction spanning player world data, keys and economy files. A crash can leave delivery uncertain; physical-key conversion and shard purchases also retain cross-file crash windows. Normal restart and reconnect tests do not establish power-loss safety. Back up player/world data and all plugin data together. These recovery gaps remain commercial release blockers.

This optional classic-style module does not establish full DonutSMP parity. The separate player chest-shop module now supplies physical shop trading in the current development source.