STYGION Documentation Search the docs

Block and container audit with rollback

Who broke, placed, blew up, took and put what, where and when - looked up with a click or a filter, undone with a rollback a few blocks each tick, CoreProtect's history imported. New in 0.4, on by default.

Keystone 0.5.0 Updated 6 min read
On this page 10 parts
  1. What is recorded
  2. Not drowned by machines
  3. Looking it up
  4. Rolling back
  5. CoreProtect
  6. How it costs nothing
  7. The editor
  8. Commands
  9. The API and events
  10. Privacy

Somebody's base is griefed overnight, a chest is emptied, a creeper took the roof: Keystone keeps every change to blocks and containers, tells you who did it, and puts it back.

What is recorded

#
What Under whom Setting
Blocks broken, with what a chest or a sign held the player, or a machine as # and its name record.break
Blocks placed (players, endermen, snow golems) the player or the mob record.place
Blocks an explosion destroyed the player who lit the TNT when the game knows, otherwise #tnt, #creeper … record.explode
Items taken out of and put into any block with an inventory (chests, barrels, shulkers, any mod's storage) the player record.containers
What machines do: mods' fake players such as Create deployers and drills, quarries # and the machine's name record.machines
What a mod reports through the AuditNoted event the mod's own words record.notes

Nothing is recorded in the worlds in worlds.skip (by default Keystone's own benchmark world).

Left out on purpose: water and lava spreading, fire, leaves decaying and crops growing are the world's own and would be most of the rows. Blocks that Create contraptions and Sable ships lift out of the world are not breaks - they still exist, inside the contraption or the ship, so putting them back would make two. Entity kills are not recorded in this version.

Not drowned by machines

#

A drill in a cobblestone generator breaks the same block forever; a chain of TNT breaks thousands a second.

  • limits.repeat (10m): a cause that is not a player changing the same block the same way again within this time is kept once.
  • limits.cause-per-second (5000): past this many rows a second from one such cause, the rest of that second becomes one summary row ("4211 more changes by #tnt in one second were not kept one by one").

Players are never limited.

Looking it up

#

Inspect: /keystone audit inspect, then left-click a block to see its history, right-click a container to see who took and put what. The same command again stops it.

A filter, written the way CoreProtect writes it:

Word Means Example
u: who - players, or causes u:Ada,#tnt
t: how far back t:30m, t:2h, t:3d, t:1w
r: blocks around you (or xyz:); #world the whole world, #global every world r:20
a: actions: break, place, explode, take (-container), put (+container), note a:break,-container
b: / e: only these blocks or items / all but these b:diamond_ore e:dirt
w: the world w:the_nether
xyz: the centre, from the console xyz:100,64,-20
#preview count, change nothing
#force put blocks back even where something else stands now

A word that does not read is refused, never ignored: a rollback that quietly dropped a mistyped u: would undo everybody's work.

/keystone audit lookup u:Ada t:6h r:30 lists the newest first, /keystone audit page 2 the next page, /keystone audit near is r:5 t:3d around you.

Rolling back

#

/keystone audit rollback u:Grief3r t:6h r:40 undoes what the filter matches; /keystone audit restore with the same filter does it all again. Add #preview first to see how many changes and whose.

  • Newest first: a block placed, broken and placed again ends as it began. A restore goes oldest first.
  • Nothing is overwritten. A block goes back only where the block there now is the one the change left; anything built since is left alone and counted. #force overrides it.
  • No lag. It runs a few blocks each tick: at most rollback.budget-ms (5 ms) and rollback.per-tick (2000) changes. Chunks that are not loaded are loaded for it and let go when it ends; it carries on with the loaded ones meanwhile. Blocks go back without neighbour updates, so sand does not fall and water does not flow while it works.
  • Containers: a take is put back into the container, a put taken out again - all or nothing, only items exactly like those (with their enchantments and components).
  • Guards: a rollback needs t: (rollback.needs-time) and u:, r: or w:; at most rollback.max (250 000) changes; one at a time. /keystone audit cancel stops it.

When it ends, Keystone says how many changes went back, how many were left alone, how long it took and over how many ticks, and tells mods through AuditRolledBack.

CoreProtect

#

/keystone import coreprotect (see Importers) reads CoreProtect's database.db and takes its history into the audit: breaks and places (clicks and kills are left out) and container changes. Bukkit's world names become the game's (world_nether is minecraft:the_nether), causes keep CoreProtect's words. Running it again takes only what CoreProtect wrote since. Imported block changes can be rolled back like Keystone's own; imported container changes are for looking up only (CoreProtect keeps the items in a form only Bukkit reads). A MySQL CoreProtect cannot be read.

How it costs nothing

#

The game only notices: each change asks whether it is kept, reads the block state (and a block entity's data only when there is one) and puts a row in a queue. A container is copied when it opens and compared when it closes. A thread of its own writes the queue to disk in batches. A full queue (store.queue) drops new rows and says so - the server never waits for the disk.

The rows live in keystone/audit/audit.db, a file of its own beside keystone.db, so a backup of the server's settings does not grow with the history. A change takes about 77 bytes (strings are kept once and referred to by number; a chest's contents are deflated, store.compress). Older rows go after keep.for (30 days), the oldest first when the file passes keep.max-size (4096 MB). /keystone audit purge 60d deletes now.

The editor

#

Block audit & rollback (in People): the filter as fields or typed, the changes newest first, Preview, Roll back and Restore with a confirmation, the rollback under way with a Stop button, and what is recorded, how much is kept and what it costs a tick.

Commands

#
Command What it does Permission
/keystone audit status and help keystone.audit
/keystone audit inspect click blocks to see their history keystone.audit
/keystone audit lookup <filter> / page <n> / near look up keystone.audit
/keystone audit rollback <filter> / restore <filter> undo / do again keystone.audit.rollback
/keystone audit cancel stop the rollback under way keystone.audit.rollback
/keystone audit purge <time> delete rows older than a time keystone.audit.purge

The API and events

#

GET /v1/block-audit (status), /v1/block-audit/lookup, /v1/block-audit/preview, POST /v1/block-audit/rollback (confirm=true), /v1/block-audit/cancel, /v1/block-audit/purge. The scopes block-audit.read, block-audit.write and block-audit.purge are carried only by the owner's keys: every block somebody placed is where they live, and a rollback rewrites the world. Details in The interface - every route.

For mods: emit AuditNoted (who, a word of your own, where, what, how many, a note) and the row sits beside Keystone's own, looked up but never rolled back; listen to AuditRolledBack to redraw a map or tell a claim after a rollback.

Privacy

#

Everything stays in the server's own audit.db. Keystone sends nothing about it anywhere. Turn the module off in Settings and nothing is recorded.

Did this page help?

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