Spyglass v1.0.2

Spyglass is a block, action, and event logging plugin (CoreProtect alternative) that records block, container, chat, command, combat, and movement events, lets you query them with a key:value language, and rolls back any of it - by player, region, cause, or in bulk, all while the server holds a consistent 20 TPS.



Three storage backends: embedded SQLite (zero setup, default), MySQL, MongoDB, and ClickHouse. SQLite makes it as easy to drop in as CoreProtect; the larger backends are there when you outgrow it.

Performance
2,000,376-block rollback - Paper 1.21.8, 6 GB heap, Aikar flags:

• Rollback time: SG SQLite ~3s / SG MongoDB ~7s / SG ClickHouse ~5s / CP SQLite ~11s / CP MySQL ~12s
• Undo time: SG SQLite ~3s / SG MongoDB ~6s / SG ClickHouse ~4s / CP SQLite ~9s / CP MySQL ~210s
• TPS during op: Spyglass 20.0/20.0 flat on all backends / CoreProtect dips to 13-14
• Worst single tick: SG SQLite ~37ms / SG MongoDB ~100ms / SG ClickHouse ~50ms / CP SQLite ~670ms / CP MySQL ~270ms
• On-disk footprint: SG ClickHouse ~11 MiB / SG MongoDB ~145 MiB / SG SQLite ~156 MiB / CP SQLite ~160 MiB / CP MySQL ~180 MiB

Rollback runs entirely off the main thread. No backend dips below 20 TPS.



Features
Spyglass only

• Combat logging - hits and projectile shots
• Movement and teleport logging
• Password redaction in command logs
• Item search by display name, lore, or enchantment
• Cross-server search via an optional Velocity companion
• Extension API - custom events, query params, display renderers, rollback effects
• Container salvage - items inside a rollback-destroyed container are recoverable via /sg inventory
• One-command undo, any size, walks back through your history
• Crash-resume - an interrupted rollback is resumable from a saved cursor on restart
• Rollback emits no new log rows
• Automatic data pruning / configurable TTL
• Rollback runs fully off the main thread

Shared with CoreProtect

• Block, container, and entity logging
• Chat, command, session, and IP logging
• Explosions, fire, liquids, and growth
• WorldEdit capture - all operations, not just //set
• Inspector wand and block history lookup
• Rollback and restore by player, time, or region

CoreProtect only

• Preview a rollback before applying

Requirements

• Paper 1.21.8 or newer 1.21.x (not Spigot or Folia)
• Java 21
• One of: SQLite (default, zero setup), MongoDB, or ClickHouse
• Optional: WorldEdit 7.3+ or FastAsyncWorldEdit 2.15+ for edit capture and -we region queries

Commands
Root: /spyglass or /sg. All permissions default to op.

• /sg search [query] (s, lookup) - spyglass.search
• /sg rollback [query] (rb, roll) - spyglass.rollback
• /sg restore [query] (rs) - spyglass.rollback
• /sg undo - reverse your last rollback or restore - spyglass.rollback
• /sg rbqueue (list / stop / cancel id / resume id) - spyglass.rollback
• /sg tool - inspection wand toggle - spyglass.tool
• /sg inventory - browse items salvaged from rollback-destroyed containers - spyglass.rollback
• /sg events - list enabled event types
• /sg page [n] - page through results
• /sg help
• spyglass.search.ip - reveals join IPs and unlocks the ip: query key
• spyglass.worldedit - allows the -we flag to use a WorldEdit selection as the search region

Query language
Search, rollback, and restore share one key:value syntax. Combine any number of keys; prefix a value with ! to exclude it.
Example: /sg search p:Steve b:diamond_ore t:1d r:50
Example: /sg rollback p:griefer a:break,!place t:6h r:100
Keys

• p: player(s) - comma-separated for OR, p:!Steve to exclude
• a: event type - see /sg events; a:!place to exclude
• b: block material - b:!chest to exclude
• i: item material
• iname: item display name (substring)
• ilore: item lore line (substring)
• ench: enchantment - e.g. ench:sharpness=5
• e: entity type
• c: cause - e.g. c:tnt,!creeper
• m: chat, sign, or book text (substring)
• r: radius in blocks
• t: time window - t:1d, t:30m, t:1d12h (default: 4h)
• w: world name
• srv: server name (multi-server)
• ip: source IP - requires spyglass.search.ip

Flags

• -g - global, skip the default radius
• -we - use your active WorldEdit selection as the region
• -ord:asc / -ord:desc - sort order
• -ng - don't merge duplicate adjacent results
• -nc - suppress the chat summary line
• -ex - show extra detail columns
• -nod:r,t - drop defaults (e.g. run with no radius or time bound)

Examples

• Who broke this block? /sg search b:* t:1d r:5
• Roll back a griefer: /sg rollback p:Bob alace,break t:2h -g
• TNT crater (player-lit TNT is attributed to the igniter): /sg rollback p:griefer t:1h r:30
• Skip containers: /sg rollback p:griefer t:6h r:100 b:!chest
• Find who took a named item: /sg search aickup iname:Excalibur t:1w -g
• Track an enchanted item: /sg search ench:sharpness=5 t:1d -g
• Commands from a suspicious IP: /sg search ip:1.2.3.4 a:command t:1d -g
• Restore a WorldEdit selection: /sg restore a:break t:1h -we

License
Please refer to our Github for our license agreement.

GitHub