Skip to main content

Design

Breaking, placing and hitting are forwarded to the region’s owner and work. Containers, doors, anvils and anything with a screen or a state machine stay refused. Opening a container on another server is not a block edit with extra steps: it is a live inventory session against a block this server cannot hold a reference to, and half-implementing it is how you get duplicated items.
Every world in a deployment shares the configured grid. There is no per-world grid and no dynamic resizing, and changing the grid is a full restart of the network.
They are not player entities. They do not appear in the tab list and plugins cannot treat them as players.
Under the player’s view distance, past the ghost band, nothing is mirrored live. With border chunks on, the neighbour shows the owner’s ground as of its last publish; without them, it shows its own generated terrain. Either way it is scenery that will not track edits in real time.
There is no player object on the owning shard to raise BlockBreakEvent or BlockPlaceEvent for, so Atlas raises ShardRemoteEditEvent there instead. Claims stored where every shard can read them are checked on the player’s own shard and need nothing; claims kept per server need a small bridge plugin listening for the event. See Claims and protection.

Correctness edges

An entity crossing is retried three times against a dedup key on the target. If no acknowledgement ever arrives, the source tries to take that same key for itself: if it wins, the target never spawned the entity and never will, and the source restores its copy; if it loses, the target has it, and the source drops its own. The remaining edge is a target that took the key and then failed to spawn the entity at the moment the source gave up — that entity is lost rather than duplicated.
A stale lease, a handoff that cannot be reverted, or a lost lease renewal kicks the player asking them to reconnect. Reconnecting lands them on the correct shard with the correct state. It is ugly and it is always correct.
A projectile carries its owner, and a death within ten seconds of the last off-shard hit is credited. Outside that window, or if the killer has gone offline, the kill is simply not awarded.
Autosaves are once a minute per player. An unclean stop — killing the process rather than draining — loses whatever happened since.

Operational

Two separate constraints, often confused.Paper, or anything downstream of it. Purpur, Pufferfish, Leaf, Gale and the like all work, because they inherit Paper’s API and internals. Spigot and CraftBukkit do not: the plugin uses Paper’s Brigadier commands, its configuration-phase connection event, its Netty channel listener, and its rewritten chunk system. Folia does not work either — the plugin uses the Bukkit scheduler and assumes one main thread throughout.Specific Minecraft versions. Roughly two dozen net.minecraft classes are used directly, and those can be renamed and reshaped between versions, so each release is built and tested for the versions it names — currently 26.2 and 26.3, both end to end. A new Minecraft version needs a release that has been checked against it. This is the constraint that bites.A different build of the same version is not a problem, and the build pinned in gradle.properties is pinned so the build is reproducible, not because the plugin refuses others. The one caveat: the chunk system classes are server internals with no compatibility promise, so a build that reorganises them could break it — which is exactly why the pin exists for building.
Keys are under a common prefix but are not namespaced per network. Two networks on one Redis overwrite each other’s routing, and the symptom is misrouted players rather than an error. Use separate instances or separate database numbers.
Inside a geo the client keeps its world and there is no loading screen. Across geos the proxy bridges when it can, which is also seamless, and otherwise falls back to a client transfer, which is a full reconnect.
The fence keeps player state safe, but both would write blocks and both would mirror, and the world itself would diverge with nothing to reconcile it. Whatever starts your shards must guarantee one process per region.

Testing

The unit suite covers the lease against a real MongoDB, the grid, mesh routing and the configuration layout. There is no automated coverage of the Paper or Velocity plugins, and no automated test walks a player across a border — no headless client speaks the pinned protocol version yet. The container network covers startup, configuration, self-registration and recovery, and a crossing still needs a person.