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. Nothing spawns or changes there and nothing is mirrored, so they are scenery that will not match the owner’s edits.
There is no player object there to check. A mesh-wide claims system has to hook the Atlas API rather than the Bukkit event.

​
Correctness edges

An entity crossing is retried three times against a dedup key on the target. If the target spawned it and every acknowledgement was lost, the source restores its own copy and logs a warning naming the uid. That is the one path that can leave two of something.
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.One Minecraft version. Roughly two dozen net.minecraft classes are used directly, and those are renamed and reshaped between versions, so a 26.2 build does not run on 26.3. 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.