Skip to main content

The count

A four-region network is not four servers. Start with a 2 by 2 grid. Every extra region is another server to pay for, and the interesting behaviour is all there with four.
The hub is not strictly required — without one a drain logs an error and leaves players where they are — but you cannot cleanly restart a shard without it.

Versions

Atlas reaches into the server for things Bukkit does not expose, which fixes two things: it needs Paper or a fork of it, and it is built for specific Minecraft versions — currently 26.2 and 26.3, each tested end to end with real clients. Paper forks are fine — Purpur, Pufferfish, Leaf, Gale and anything else downstream inherit what it uses. Spigot and CraftBukkit are not, and neither is Folia, which has a different threading model entirely. What it will not survive is a Minecraft version it was not built for; a different Paper build of a supported version is fine. Every shard and the hub must run the same Minecraft version. The versions pinned in gradle.properties are pinned so the build is reproducible.
Check the Java and Minecraft versions your host actually offers before committing. A Minecraft version mismatch is a startup crash, not a degradation, and on shared hosting you often cannot pick. Which Paper fork it is does not matter.

The proxy

A crossing is seamless because the client never rebuilds its world: the proxy withholds the destination server’s join-game and respawn, and the shard turns its login teleport into a no-op. Plain Velocity cannot do the first half — every server switch sends the client through the configuration screen and a terrain reload. atlas-proxy is Velocity 4 with that switch added, and it is what Atlas ships with. Use its jar as the proxy server’s jar (any Velocity egg runs it) and turn both settings on in velocity.toml:
velocity.toml
The proxy says which it is when the Atlas plugin starts:
Anything else is logged as a warning naming the setting to change. Each proxy also reports it to the shards, and a shard only neutralises the login teleport when every proxy in its geo keeps the client’s world — so plain Velocity, or one proxy with a setting off, still works, with a loading screen at each border instead of a player stranded at the origin.
remove-reconfig assumes every backend runs the same Minecraft version, because the client keeps the registries it received from the first server it joined. On an Atlas network that is already a requirement.

MongoDB: a standalone is fine

A plain mongod works. Ownership is a fenced lease, which is a single-document update, and single-document atomicity is something every deployment provides. What differs is the read concern, and Atlas asks the server what it is on startup and adapts. On a replica set it reads with majority, which guards against a failover rolling back an acknowledged write and resurrecting a lease another shard has taken. A standalone has no second node and therefore no failover, so it reads with local, which is the same guarantee rather than a lesser one. The one thing you lose is the multi-document transaction helper offered to other plugins. Nothing in the crossing path uses it, and plugins that need it fail loudly rather than half-applying. If you want it, a single-member replica set is one flag and one command on the same mongod:
then name it in the URI with ?replicaSet=rs0. Any managed MongoDB is already a replica set.

Redis: one per network

Keys are not namespaced by tenant. Two networks pointed at one Redis overwrite each other’s routing and transfer tickets, and the symptom is players being sent to the wrong network’s servers rather than an error. Use a separate instance, or at minimum a separate database number:

The world

This is the requirement with no error message, and the one that looks like a bug in Atlas when it bites. Every shard uses the same level-seed and the same level-name, and turns on tuning.border-chunks. Each shard then generates only its own region, and the ground either side of each border is shared through MongoDB. That sharing is what the seed alone cannot give you. Chunk decoration is not a pure function of the seed, so servers generating “the same” world disagree about where the trees are, and without it every border shows a seam. How it works, and what it costs, is in Same seed, no world copy.
Border chunks are off by default while they are new. The alternative is the original approach: generate the world once, pre-generate it to the edge of the grid, and copy the folder to every shard, so each holds the whole map.
What players build on region 0 lives only on region 0’s server either way. That is the point.