Design
Interactions do not cross a border
Interactions do not cross a border
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.
One grid per deployment
One grid per deployment
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.
Player ghosts are mannequins
Player ghosts are mannequins
They are not player entities. They do not appear in the tab list and plugins cannot treat them as players.
Chunks past the ghost band are a snapshot
Chunks past the ghost band are a snapshot
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.
Per-server claims need a bridge to stop edits from across a border
Per-server claims need a bridge to stop edits from across a border
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 can be lost, but not doubled, when a crossing goes wrong
An entity can be lost, but not doubled, when a crossing goes wrong
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.
Kicks are the recovery of last resort
Kicks are the recovery of last resort
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.
Kill credit across a border is best effort
Kill credit across a border is best effort
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.
A drained player can lose the last minute
A drained player can lose the last minute
Autosaves are once a minute per player. An unclean stop — killing the process rather than draining — loses whatever happened since.
Operational
Paper or a fork of it, and one Minecraft version
Paper or a fork of it, and one Minecraft version
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.One Redis per network
One Redis per network
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.
A cross-geo crossing may not be seamless
A cross-geo crossing may not be seamless
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.
Two servers for one region would diverge
Two servers for one region would diverge
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.