STYGION Documentation Search the docs

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.

Keystone 0.5.0 Updated 5 min read
On this page 9 parts
  1. What a snapshot holds
  2. When one is taken
  3. How long they are kept
  4. Putting one back
  5. Who restored what
  6. Tickets
  7. Commands
  8. The API
  9. Privacy

"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.

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.

Did this page help?

Opens the feedback panel with this page attached. It lands in the same queue as everything else.