# Crates

> A key for every day on the server, opened with /crate, and what is inside is up to the server.

Source: https://stygion.eu/docs/keystone/crates
Updated: 2026-10-09

The `crates` module, `crates.toml`. **It is off after an install**: a module that hands things out is not something an update should switch on by itself. You turn it on with `enabled = true`; its settings are visible in the editor (the Crates screen) even while it is off.

## A key for every day

Everybody gets one key on each day they are on the server — on their first join of the day, or at midnight if they are online when it passes. The day is counted in the server's time zone (`crates.time-zone`). `keys-per-day` (default 1) and `max-keys` (default 30) say how many keys a day and how many can be held in stock.

Keys live in Keystone's database, not in an inventory, so they **cannot be traded, dropped or duplicated**. They are earned, never sold.

## The player

```
/crate          how many keys you hold and your odds
/crate open     spends one key and opens a crate
/crate odds     every group's odds and what each rarity holds
```

Whatever does not fit in an inventory is dropped at the player's feet, where only they can pick it up (the way `/give` does it). A crate opened in the tick before somebody left is handed over on their next join. A legendary is announced to the server (`crates.announce`).

## Odds and rewards

`crates.odds` is one line per group, worst first: `default: 70, 22, 7, 1` is the chance (in percent) of common, uncommon, rare and legendary. A player rolls with the last line whose group they are in. A server that wants everybody to have the same odds keeps the single `default` line.

`crates.loot.common` to `.legendary` say what each rarity holds, the same for everybody, in the same shapes as a vote reward: a command, `perk`, `rank` — plus `item <id> <n>`, a weight in front (`3: …`) and a label after `|`. A rarity with nothing in it cannot come up, and the odds shown say so.

## Items with a look of their own

`crates.items` names them: `<id> <item> [model=<n>] [look=<ns:path>] [colour=#rrggbb] [glint] <name> | <lore>`. `model=` is the number a resource pack matches on Minecraft 1.21.1, `look=` the model it names from 1.21.4; with a look the name and lore are also read from the pack in the player's language. Such an item stacks to 64 and does not glint unless asked (`glint`).

**An item with a look is protected.** It carries Keystone's mark, which no survival action can write. An anvil offers no result and lets nothing be taken while either slot holds one; a creative player below operator level 2 cannot write one into a slot; and one that enters an inventory loses a name an anvil gave it elsewhere. So a server can treat it as genuine.

## Running it

```
/keystone crate give <player> <n>       gives keys (works for somebody offline; from a vote: keystone crate give {player} 1)
/keystone crate history <player>
/keystone crate test <group> [rolls]    rolls up to a million crates, gives nothing, and prints what came out beside what was expected
```

Only the owner may change what is in the crates (`crates.loot`) from in game.
