> 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/managing-worlds/downloading-a-world.md).

# Downloading Worlds

Hand players a world as a single-player save over an expiring download link.

`/worlds download <world>` packs a world into a save a player can drop into their client's `saves` folder, and sends them a clickable link to fetch it. The feature is **off by default** — enabling it hands out world data.

Archives are served one of two ways. The built-in server (`storage: local`) opens a port on the machine and streams the file itself. Pre-signed links (`storage: s3`) upload the archive to the bucket set in the root `storage.s3` section and send the player a signed, expiring URL — no port, no size limit, and the download never touches the game server.

***

## Why an export is needed

Since Paper 26.1 a server world is no longer its own folder. Every world is a *dimension* of the main level:

```
worlds/<level-name>/
├── level.dat
└── dimensions/minecraft/
    ├── overworld/
    ├── the_nether/
    ├── the_end/
    └── <your-world>/        <- a BuildSystem world lives here
        ├── region/
        └── data/minecraft/world_gen_settings.dat
```

A world in another [namespace](https://buildsystem.eintosti.de/getting-started/creating-a-world.md#world-namespaces), such as `maps:lobby`, sits in `dimensions/maps/lobby` instead. It is exported the same way.

Copying that folder out by hand gives you something the client cannot open. It has no `level.dat`, its chunks sit under the wrong dimension, and its saved data is in the wrong place: Paper keeps a per-world copy of the level-scoped files (`world_gen_settings.dat`, `game_rules.dat`, `weather.dat`, …) inside each dimension folder, while a single-player save keeps one set at the root. A client that finds no generator settings there refuses the world outright.

The export rebuilds all of that. The world becomes the save's overworld, gets a `level.dat` named after it, and its data is split by scope:

```
<world>/
├── level.dat                                       from the main level, renamed and scrubbed
├── data/minecraft/                                 level-scoped: world_gen_settings, game_rules, weather, …
└── dimensions/minecraft/overworld/
    ├── region/  entities/  poi/
    └── data/minecraft/                             dimension-scoped: raids, world_border, chunk_tickets
```

A world still stored in the pre-26.1 flat layout already is a save, so only its `level.dat` is rewritten - it keeps its own nether and end, and dimensions belonging to other worlds are left behind.

***

## Enabling downloads

```yaml
world:
  download:
    enabled: false
    storage: local
    port: 8080
    url: "http://localhost:8080"
    behind-proxy: false
    expiration-minutes: 30
    max-size-mb: 2048
    max-storage-mb: 8192
    max-concurrent-downloads: 3
```

| Key                        | Default                   | Description                                                                                 |
| -------------------------- | ------------------------- | ------------------------------------------------------------------------------------------- |
| `enabled`                  | `false`                   | Turns downloads on.                                                                         |
| `storage`                  | `local`                   | `local` for the built-in server, `s3` for pre-signed links.                                 |
| `port`                     | `8080`                    | Port the built-in server listens on. Must be reachable by players. Ignored on `s3`.         |
| `url`                      | `"http://localhost:8080"` | Base address players are linked to. Ignored on `s3`.                                        |
| `behind-proxy`             | `false`                   | Identify clients by `X-Forwarded-For`. Enable only behind a reverse proxy. Ignored on `s3`. |
| `expiration-minutes`       | `30`                      | How long a link stays valid. The archive is deleted when it expires.                        |
| `max-size-mb`              | `2048`                    | Largest single export. `local` only.                                                        |
| `max-storage-mb`           | `8192`                    | Budget shared by all live downloads. `local` only.                                          |
| `max-concurrent-downloads` | `3`                       | Transfers served at once. `local` only.                                                     |

Set `url` to whatever players actually reach — a domain, or the address of a reverse proxy. The server speaks plain HTTP, so put it behind a proxy and point `url` at the HTTPS address if links leave your network. When you do, also set `behind-proxy: true`, or every request looks like it came from the proxy and link pinning and rate limiting stop telling players apart.

Toggling `enabled` or `storage` takes effect on `/config reload`; no restart needed.

### Serving from S3

```yaml
world:
  download:
    enabled: true
    storage: s3

storage:
  s3:
    access-key: YOUR_ACCESS_KEY
    secret-key: YOUR_SECRET_KEY
    region: eu-central-1
    bucket: my-bucket
```

`storage: s3` reads the credentials, bucket and endpoint from the root `storage.s3` section — there is nothing to configure twice, and any S3-compatible service works. Backups do not have to be on S3; the two features pick their backend independently. If `storage.s3` is incomplete, downloads stay off and the console says which key is missing.

What changes:

* **No port.** Nothing has to be reachable from outside, so this works behind NAT or on a host that will not open one.
* **No size limit.** Archives upload in parts, so `max-size-mb` and `max-storage-mb` do not apply and a world of any size can be downloaded.
* **Your uplink carries the world once**, on upload, instead of once per player fetching it.
* **The link is https**, signed by S3 and valid for `expiration-minutes`.

Uploads live under the prefix set by `storage.s3.path` (`downloads/` by default) and are deleted when their link expires. Anything left by a crash is cleared at the next startup, so the bucket does not accumulate archives. That cleanup removes everything under the prefix, so do not point it at backups or other data in the bucket.

{% hint style="warning" %}
A pre-signed link is a pure bearer token. Unlike a local link it cannot be pinned to one client or rate limited, so anyone it is forwarded to can use it until it expires. Keep `expiration-minutes` short.
{% endhint %}

{% hint style="info" %}
You pay S3 for the storage and for egress on every download. A 2 GB world fetched ten times is 20 GB of transfer.
{% endhint %}

***

## Downloading a world

* **Command**: `/worlds download <world>`
* **Permission**: `buildsystem.download` (`OP`, supports `.self` / `.other`)

The world is saved first - waiting for its chunks to reach disk, and with its autosave paused until the archive is ready, so the archive never catches a region file mid-write - then zipped in the background. An animated progress bar runs in the action bar while it packs, showing real progress - bytes packed against the world's total size - with a sweeping highlight and spinner so a pause on one large region file still reads as working. On `s3` the bar then switches to the upload and tracks that the same way, so it never sits full while work is still running. When it is ready the player gets a clickable message; the link opens in their browser. Only one export per player runs at a time.

While a world is being packed, deleting, renaming, restoring or backing it up is refused with `worlds_world_busy`. A download of a world that is busy with one of those is refused the same way.

Restyle the bar through `worlds_download_progress` and `worlds_download_uploading` in `messages.yml`, which take `%world%`, `%bar%`, `%percent%` and `%spinner%`. The finished message is `worlds_download_finished`; its `%button%` placeholder marks where the clickable link goes, and only that segment carries the click and hover - its text is `worlds_download_button`.

Extract the archive into `.minecraft/saves/` and the world appears in the single-player list.

{% hint style="info" %}
A dimension world has no `level.dat` of its own, so its export borrows the main level's - gamemode and difficulty start out matching the server's main level rather than the exported world. A flat-layout world keeps its own settings.
{% endhint %}

***

## What is exposed

Treat a link as private. Everything else is closed off.

With `storage: s3`, the link is signed by S3 and dies with its expiry; the pinning, rate limiting and transfer caps below are properties of the built-in server and do not apply. Everything about what an export *contains* applies either way.

* Each export is reachable only through a random 256-bit token that forms the entire URL path. Requests cannot name a file, so nothing outside `plugins/BuildSystem/downloads` is reachable.
* Archives and their links are deleted together: on expiry, on reload, and on shutdown. Anything left behind by a crash is wiped at startup, since its link did not survive the restart.
* An unknown or expired link returns a bare `404`.
* A link is pinned to the first client that uses it. Forwarding it to someone else does not work, while the player who asked for it can still retry or resume.
* Requests are rate limited to 30 per minute per address, and concurrent transfers are capped, so one host cannot saturate the endpoint. A request over the transfer cap gets `503` with `Retry-After`.
* Exports never include player data (`players/`, `playerdata/`, `stats/`, `advancements/`), so downloading the main world does not hand out the whole server's inventories. The exported `level.dat` also drops the server's brand, version and server-side datapacks.

{% hint style="warning" %}
`buildsystem.download` hands out the full contents of a world. Grant it with the same care as `buildsystem.backup`.
{% endhint %}
