> For the complete documentation index, see [llms.txt](https://buildsystem.eintosti.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://buildsystem.eintosti.de/v4/managing-worlds/world-backups.md).

# World Backups

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](/files/0vraWpQANBBddLr5uclI)

### 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.

{% hint style="danger" %}
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.
{% endhint %}

{% hint style="info" %}
**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.
{% endhint %}

### 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.

{% hint style="info" %}
The world is saved to disk when the backup is *queued*, not when the archive is written. If a backup is waiting behind a slow S3 or SFTP upload, the archive reflects the world as of when its own turn starts.
{% endhint %}