Minimal Backup

Key Features

• Delta Storage (Space-First): Tracks individual chunks and .dat files in append-only .zpack archives. The first block is a full copy; subsequent blocks are Zstd dictionary deltas. Untouched chunks take zero space.
• Fast, Copy-Free Restores: Restoring does not unzip files beforehand. It intercepts game reads to serve snapshot data directly, falling through to disk for untouched data.
• In-Process Server Swap: On dedicated servers, restoring boots a fresh server instance in the same JVM while holding player connections open with a heartbeat. Modded clients reconnect automatically. Integrated (single-player) servers use the same connection hold while the old server stops, then the client quietly reloads the world, so the vanilla "connection lost" screen never appears.
• Server-Side & Optional UI: Vanilla clients can join freely. Modded clients can press F9 (or /backup ui in single-player) for the visual Time Tree; it needs UILib + Architectury (0.3.6 + 9.2.14 on 1.20.1, 9.0.0 + 13.0.6 on 1.21.1). Without them the client shows a chat hint and /backup commands still work. Players below permission level 2 get a read-only tree: list and status are available, while create/restore/rename/delete/verify are disabled and the server rejects those requests. A second key binding, unbound by default, creates a snapshot immediately using the default timestamp title; bind it in the vanilla controls screen if you want one-key backups.

Commands (Requires OP Level 2)

/backup create [name]            # Create a manual snapshot
/backup list                     # List snapshots
/backup status                   # Show runtime & vault status
/backup restore <slot> [confirm] # Checkpoint current state & restore to <slot>
/backup disarm                   # Cancel a pending restore
/backup delete <slot>            # Soft-delete (tombstone) a snapshot
/backup rename <slot> <name>     # Rename a snapshot
/backup verify <slot>            # Verify block hashes for a snapshot
/backup gc [confirm]             # Preview or run garbage collection (compaction)
/backup baseline [confirm]       # Import all existing chunks/data into the vault
/backup reload                   # Reload server config
/backup ui                       # Open client GUI

Storage & Configuration

• Vault Path: <gameDir>/mbackups/<worldFolderName>/ (Stored outside saves/).
  • Note: Deleting a world keeps its backups. Renaming a world folder starts a fresh backup vault.
• Configs: config/minimalbackup-server.toml and config/minimalbackup-client.toml.
  • Triggers: Auto-backup on world unload (triggerOnUnload=true) or timer (triggerOnInterval + intervalMinutes).
  • Retention & Compression: Configure retentionKeep, retentionMaxBytes, and zstdLevel.
  • Scope: Enable fullBaseline to import untouched worlds, or copyJson to include advancements/ and stats/.

Limitations (Non-Goals)

• NBT Pipeline Only: datapacks/, serverconfig/, and custom non-NBT mod databases are ignored. (advancements/*.json and stats/*.json require backup.copyJson=true).
• Local & Version-Locked: Backups are local only (<gameDir>/mbackups) and cannot be restored across different Minecraft versions.
• Vanilla Client Reconnect: Vanilla clients can play normally, but must manually click "Reconnect" after a dedicated server restore.

Offline CLI Tool

The mod jar can be run directly with Java (while the world is stopped) for offline maintenance:

java -cp <mod.jar> engine.cli.Main list     <gameDir> <worldKey>              # List snapshots & sizes
java -cp <mod.jar> engine.cli.Main rollback <gameDir> <worldKey> <slot> <dir> # Rebuild world into <dir>
java -cp <mod.jar> engine.cli.Main compact  <gameDir> <worldKey>              # Run garbage collection
java -cp <mod.jar> engine.cli.Main heal     <gameDir> <worldKey>              # Clean up interrupted writes

License

GNU Lesser General Public License v3.0 only