# Player snapshots and inventory restore

> What a player carried at death, on leaving, on changing dimension and every so often - inventory, armour, ender chest, Curios, experience - and putting it back from the editor or a command without handing anything over twice. New in 0.4, on by default.

Source: https://stygion.eu/docs/keystone/snapshots
Updated: 2026-11-16

"I died and lost everything", a mod that ate an item, a dupe you have to undo: Keystone keeps what every player carries, and the team puts it back.

## What a snapshot holds

- the whole inventory: hotbar, backpack, armour and off hand
- the ender chest
- **Curios** slots, normal and cosmetic, when Curios is installed (Trinkets is a Fabric mod; Keystone runs on NeoForge)
- experience: level, progress and total
- where they stood: dimension and position

Each stack is kept as the game itself saves it, with every component - a modded backpack, an enchanted tool, a renamed sword or a shulker box full of things comes back exactly as it was. Keystone does not need to know a mod to keep its items.

## When one is taken

| Moment | Setting | Default |
|---|---|---|
| A player dies - **before** anything drops, before a grave or corpse mod moves a thing | `take.death` | on |
| A player leaves | `take.leave` | on |
| A player changes dimension | `take.dimension` | on |
| Every so often, for everybody online | `take.every` | `15m` (`off` turns it off) |
| A player joins | `take.join` | off |
| By hand | `/keystone snapshots take <player>` or **Take now** in the editor | - |

A periodic, leave, join or dimension snapshot is skipped when it would be the same as the player's newest one, so somebody standing still does not fill the database. A death is always kept. The periodic ones are taken one player a tick, so forty players cost no lag spike.

## How long they are kept

- `keep.for` (`14d`): older snapshots are deleted, checked every hour
- `keep.routine` (`30`): ordinary snapshots (leave, join, dimension, periodic) kept per player
- `keep.important` (`20`): deaths, manual and before-restore snapshots kept per player, counted apart - a day of play does not push out yesterday's death

A snapshot a waiting restore needs is kept until the restore is done.

## Putting one back

**In the editor:** *Snapshots & restore* (in People). Find the player, open a snapshot, see every stack by slot, pick what to restore and press **Preview**: it says what would go back, what would be left out and why, against what the player carries right now. Then **Restore**.

**In game:** `/keystone snapshots list <player>`, click one, then **Fill empty slots** or **Replace**.

Two ways to restore:

- **Fill** puts a stack back only into its own slot, only when that slot is empty, and leaves out what the player already carries again (the same item with the same components, anywhere on them) - so the sword they picked up from where they died is not handed over a second time. Nothing they carry is touched.
- **Replace** empties the parts you restore and writes the snapshot over them. It asks first, and what it replaced is kept as a *before a restore* snapshot - so a replace can be undone with that one.

You choose the parts: inventory, ender chest, Curios, experience, and optionally **move them** to where they stood. Fill never takes experience away.

> [!IMPORTANT]
> **Nothing is handed over twice.** A snapshot that was restored once, or one taken before the player's last restore, needs `again`. A player has one restore at a time. Everything is written into the player in one tick, so nothing they do lands in between.

**Somebody offline** gets the restore at their next join, exactly once - even if they join twice, or the server stops in the middle (then the restore is shown as *interrupted* and never applied again by itself; look at their inventory and cancel it). Waiting restores are listed under *Waiting for a join* and in `/keystone snapshots pending`, and can be cancelled.

An item whose mod has been removed cannot be put back: it is reported as unreadable, stays in the snapshot, and everything else still comes back.

> [!WARNING]
> After a death, what dropped - or a grave or corpse - may still lie in the world. Restoring and picking it up as well is two of everything. Fill leaves out what they carry again; replace does not look.

## Who restored what

Every restore is written down: who, which snapshot into whom, fill or replace, when, and the result (how many stacks came back and which did not, and why). The editor lists them under *Restores*; in game `/keystone snapshots history [player]`.

## Tickets

When the player has an open ticket, the restore says so in it as the person who restored it: *"Your inventory from 30 Oct 2026 21:14 (death) is restored: 31 stacks are back."* The line goes wherever the ticket's lines go - the player's chat, the ticket's Discord channel, your own forward.

- `tickets.reply`: `newest` tells their newest open ticket by itself; `off` only the one you name
- in the editor pick *newest*, a number, or none; in game add `ticket=12` or `no-ticket`
- `tickets.text` and `tickets.text-partly` are the words, with `{when}`, `{reason}`, `{placed}`, `{not-done}` and `{by}`

## Commands

| Command | What it does | Permission |
|---|---|---|
| `/keystone snapshots` | the newest snapshots | `keystone.snapshots` |
| `/keystone snapshots list <player>` | a player's snapshots | `keystone.snapshots` |
| `/keystone snapshots view <id>` | what one holds, with the restore buttons | `keystone.snapshots` |
| `/keystone snapshots items <id>` | every stack, slot by slot | `keystone.snapshots` |
| `/keystone snapshots take <player>` | take one now, online or from their saved file | `keystone.snapshots.take` |
| `/keystone snapshots restore <id> fill\|replace [options]` | put it back | `keystone.snapshots.restore` |
| `/keystone snapshots pending` | restores waiting for a join | `keystone.snapshots` |
| `/keystone snapshots cancel <restore>` | cancel a waiting or interrupted restore | `keystone.snapshots.restore` |
| `/keystone snapshots history [player]` | who restored what | `keystone.snapshots` |

Options after `fill` or `replace`: `confirm` (replace), `again`, `position` (move them there), `ignore-carried` (fill puts back even what they carry - can duplicate), `only=inventory,ender,curios,xp`, `ticket=<number>`, `no-ticket`.

`restore.self` (off): nobody but the owner restores into their own inventory - a restore creates items, and doing it for yourself is the one restore nobody else checks.

## The API

`GET /v1/snapshots`, `/v1/snapshots/one`, `/v1/snapshots/preview`, `/v1/snapshots/restores`, `POST /v1/snapshots/take`, `/v1/snapshots/restore`, `/v1/snapshots/cancel`. They need the scopes `snapshots.read` and `snapshots.write`, which only the owner's keys carry: snapshots say where every player stood, and a restore creates items. A moderator restores in game with the permission. Details in [The interface - every route](/docs/keystone/api-reference).

## Privacy

Snapshots live in the server's own `keystone.db` and nowhere else. Keystone sends nothing about them anywhere; the one line that can leave is the "restored" reply in a ticket, and only where that ticket's lines already go. Turn the module off in *Settings* and nothing is taken.
