World Backup

Simple, reliable world backups at the press of a key — or the tip of a command.

Ever had your world corrupted by a rogue mod, a power outage, or just a bad decision with WorldEdit? World Backup lets you create instant, compressed zip backups of your entire world folder with a single command. Backups run asynchronously so your server never freezes, and automatic rotation keeps your disk from filling up.

---

✨ Features

• Instant backups — Create a full .zip backup of your world with /backup <name>
• Non-blocking — Backups run on a separate thread; your server stays responsive
• Automatic rotation — Old backups are pruned automatically based on a configurable limit
• Configurable — Set your backup limit via command or JSON config file
• Safe by default — Name validation prevents path traversal attacks
• Conflict-friendly — Copies your world to a temp directory first, then zips from the clean copy. Files locked by other mods (Sable, etc.) are retried automatically with increasing backoff.
• Server-wide broadcast — All players see backup progress and completion messages

---

📋 Commands

Command	Description
/backup <name>	Creates a timestamped zip backup with the given name
/backuplimit <number>	Sets the maximum number of backups to keep (1–1000)

Examples:

/backup before-portal          →  before-portal_2025-06-03_21-30-00.zip
/backup vanilla-test           →  vanilla-test_2025-06-03_21-31-15.zip
/backuplimit 25                →  Sets the rotation limit to 25 backups

All players can use these commands by default — no operator permissions required.

---

⚙️ Configuration

The backup limit is stored in backup/backup_config.json inside your server directory. It is created automatically on first use and can be edited directly:

{
  "backupLimit": 10
}

The limit can also be changed in-game with /backuplimit <number>.

---

📁 Where are backups stored?

Backups are saved to the backup/ folder inside your server directory (next to your world folders). Each backup is a compressed .zip file named in the format:

<name>_<YYYY-MM-DD_HH-mm-ss>.zip

---

🔄 Compatibility

World Backup is designed to coexist peacefully with other mods:

• Sable — Fully compatible. World files are copied to a temporary directory before zipping, so Sable's file locks don't interfere. Retried up to 5 times with increasing backoff.
• Ice and Fire, Dread Land, and other dimension mods — All sub-levels and custom dimensions are backed up.
• Any file-locking mod — The copy-first strategy combined with retry logic handles files locked by other mods without skipping data.
• Any world type — Works with vanilla, modded, and custom world formats.

---

🛠 Technical Details

• Copy-first strategy — World folder is copied to a temp directory using Files.copy (path-to-path), which on Windows uses the CopyFileEx API to handle locked files
• Backups flush all chunks to disk before copying (saveAllChunks)
• Asynchronous execution via CompletableFuture — no server tick lag
• Automatic retry with backoff (up to 5 attempts) for temporarily locked files
• Temp directory is cleaned up automatically after backup completes (even on failure)
• Backup rotation deletes the oldest files first by modification time
• Safe filename validation: only letters, numbers, hyphens, and underscores allowed

---

📦 Installation

1. Install NeoForge for Minecraft 1.21.1+
2. Drop worldbackup-1.0.0.jar into your mods/ folder
3. Start the server — backups are ready to go

No configuration needed to get started. Just /backup my-backup and you're set.