> ## Documentation Index
> Fetch the complete documentation index at: https://docs.craftsupport.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Splitting a shard

> Give a busy region more servers without touching the rest of the map

When one region is where everybody lives, you do not have to rebuild the grid. Split that region in half — or in four — and give the new part its own server. The rest of the map, and every other shard, stays exactly as it is.

A 2x2 grid with both right-hand regions halved — `1 x 1 5` and `3 x 3 4`:

```text theme={null}
+--------+----+----+
|   0    | 1  | 5  |
+--------+----+----+
|   2    | 3  | 4  |
+--------+----+----+
```

You stand on the shard, run `/shard split`, and restart the network. The split is recorded in MongoDB, where every shard and the proxy read their grid, so **no config file is edited anywhere**. The old shard hands the new part over as files when it next starts, and you upload those files to the new server. Nobody copies region files by hand.

The same command is how an existing single server becomes a sharded network — see [Moving an existing server onto Atlas](https://docs.craftsupport.dev/deploy/migrating.md).

## Doing it

**1. See what a split would give**

On the shard you want to split:

```
/shard split
```

```
Region 1 is x[0,2048) z[-1024,1024), 2048x2048 blocks. It can be split:
  /shard split x  ->  1 (this server) x[0,1024) z[-1024,1024), 2 (new) x[1024,2048) z[-1024,1024)
  /shard split z  ->  1 (this server) x[0,2048) z[-1024,0), 2 (new) x[0,2048) z[0,1024)
  /shard split quad  ->  1 (this server) x[0,1024) z[-1024,0), 2 (new) ...
```

New parts get the lowest free numbers. Pick your own with `/shard split x 1 7`.

**2. Split it**

```
/shard split x
```

```
Working on it -- the answer follows here and in the server log.
Planned: region 1 becomes 1 x[0,1024) z[-1024,1024) and 2 x[1024,2048) z[-1024,1024).
The new grid is recorded in MongoDB, so no config file needs editing: every shard and the proxy read it when they start.
```

Recording the split is a round trip to MongoDB, so it runs in the background and the answer arrives a moment later. Over RCON only the first line comes back -- the rest is in the server log, every line prefixed `/shard split`.

**The world is not changed yet**, and every server keeps running the grid it started with. Each of them now says so, once, and `/shard topology` shows it:

```
PENDING -- MongoDB now holds the grid 2048/2x1;1 x 1 2; it takes effect when the whole network restarts.
```

Changed your mind? `/shard split cancel` on the same shard takes it back out of MongoDB, any time before the restart.

**3. Restart the network**

Restart every shard and the proxy together. Like any grid change this is a full restart, not a rolling one — do it with nobody online. A server restarted on its own before the rest picks up the new grid early, and every node will report a [grid mismatch](#if-the-grid-is-not-the-same-everywhere) until the others follow.

Before its world loads, the shard you split exports the new part and removes it from its own world:

```
split: exported region 2 to plugins/atlas/split/region-2 -- 1389 chunks of terrain (4 files whole, 6 cut), 1 of entities, 0 of points of interest
split: removed region 2 from this world -- 729 chunks of terrain, 1 of entities, 0 of points of interest
split "1 x 1 2" done in 94ms. This server now owns x[0,1024) z[-1024,1024).
```

Until the new server is up, nobody can get into the new part: anyone walking toward it is stopped at the line with *That area is not available right now*. Somebody who logged out standing there and logs back in waits in the hub, and is sent back to exactly where they were the moment the new server is up. Without a hub server they start at spawn instead, and keep that position.

**4. Bring up the new server**

Everything it needs is in `plugins/atlas/split/region-<n>/` on the old shard — download that folder from your panel.

1. A new Paper server, same Minecraft version and plugins as the others.
2. Copy the `world` folder from the export into the server folder.
3. Copy the export's `config.yml` to `plugins/atlas/config.yml` and set `SHARD_ADDRESS` in it to the address the proxy dials.
4. `server.properties` and `config/paper-global.yml` as on the other shards — same forwarding secret, `online-mode=false`.
5. Start it.

`/shard topology` on any server should now list the new region as alive.

Only one split can wait for a restart at a time. A second `/shard split`, on any shard, is refused until the network has restarted onto the first one — or it has been cancelled — so two operators cannot cut the map at once.

## How a split is written

Each split is one line, `<region> <how> <parts...>`, kept in MongoDB in the `grid` collection, one document per world:

| How | Parts, in order | Example |
| - | - | - |
| `x` | west half, east half | `"1 x 1 5"` — region 1 keeps the west half, the east half is the new region 5 |
| `z` | north half, south half | `"1 z 1 5"` |
| `quad` | north-west, north-east, south-west, south-east | `"1 quad 1 5 6 7"` |

One part keeps the region's number, which is the shard already running there; the others are new numbers for new servers. A part can be split again — run `/shard split` on its shard — and splits apply in the order they were made.

Every region is still one rectangle, so crossings, ghosts, the block mirror and border chunks work across the new line exactly as across any other. Each part must be at least 256 blocks and a whole number of chunks on each side, and the ghost band can be at most a quarter of the smallest region.

The base grid — `region-size`, `regions-x`, `regions-z` — stays in `config.yml`, where it is set once.

> [!NOTE]
>
> **Had splits in `grid.splits`?** That still works. The first shard to start copies them into MongoDB, and from then on MongoDB is the one that counts: a config that disagrees is ignored, with a warning that names both. You can delete `grid.splits` from every config once it has been copied.

## What moves, and what does not

| | |
| - | - |
| **Moves to the new server** | The part's terrain, block entities, entities and points of interest; a corridor of terrain around it, so its borders show real ground from the first second; the world's seed and generator settings; `level.dat` and the datapacks; the players' vanilla files; a `config.yml` with the old shard's settings and the new region number. |
| **Removed from the old shard** | Every entity and point of interest in the new part, and its terrain except the corridor the old shard still shows along its new border — so nothing that now belongs to the new server can also be found, killed or picked up on the old one. |
| **Does not move** | Players. Their records are in MongoDB; anyone standing in the new part is routed to the new server at their next login or crossing, once it is up. |

The players' vanilla files are there for anyone MongoDB has never seen — somebody who has not logged in since the world went onto Atlas. Whichever server they land on, they keep their things and their place. Everyone else's record is in MongoDB and the files are never read for them.

Whole region files are copied as files; only the files the new line runs through are cut, chunk by chunk, without decompressing anything.

> [!WARNING]
>
> The exported `config.yml` holds the old shard's settings, database passwords included. Keep it out of anything public.

## If the grid is not the same everywhere

Every shard publishes its grid, and every shard and proxy compares the others' with its own. A server that is running a different grid — usually one restarted before the rest after a split — is named, loudly, in every console:

```
GRID MISMATCH: shard main:world:0 runs grid 2048/2x1 but this node has 2048/2x1;1 x 1 2. ...
```

`/shard topology` shows it too. Restart the servers still on the old grid; it clears itself once they agree.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.