World Backups

Schedule backups to disk, S3, or SFTP, and restore them.

BuildSystem includes a database-linked backup subsystem. Backups copy region files and world configurations, sending them to local or remote storage drivers.

---

Backup Scheduling

Automatic Backups

If configured in config.yml (world.backup.auto-backup.enabled), backups run on a recurring schedule.

• Interval: Set in seconds via interval (e.g., 900 for 15 minutes).

• Active World Filtering: If only-active-worlds is set to true, background timer counts increment only when a registered builder is present in the world.

Manual Backups

Administrators or builders can force an immediate backup of their current world:

• Command: /worlds backup create

• Permission: buildsystem.backup.create

---

Viewing & Restoring Backups

To view the history of backups for the current world:

• Command: /worlds backup

• Permission: buildsystem.backup (requires being the world creator or having the buildsystem.admin bypass permission).

World Backups List

Restoration

1. Open the backups list (/worlds backup).

2. Click on the target backup item (named with the timestamp of creation).

3. Confirm the restoration prompt.

Restoring a backup wipes the current world directory before extracting the archive, and there is no undo. Take a manual backup first if the current state matters at all.

The server's primary world cannot be restored in place, and BuildSystem refuses to try. Since Paper 26.1 every other world lives inside the primary world's folder, under dimensions/minecraft, so wiping that folder would delete every world on the server. Bukkit also refuses to unload the primary world, so the unload that is supposed to precede the wipe would silently do nothing.

To roll the primary world back, stop the server and extract its archive by hand.

Creating a Backup Manually

• Command: /worlds backup create

• Permission: buildsystem.backup.create

Backups of one world run one at a time. Asking for a second while the first is still uploading queues it rather than running both, so the retention limit set by world.backup.max-backups-per-world cannot be overshot by two backups racing each other.

The world is saved to disk when the backup is queued, not when the archive is written. On Paper the save also waits for the chunk writer to finish, so the archive never contains half-written region files. If a backup is waiting behind a slow S3 or SFTP upload, the archive reflects the world as of when its own turn starts.