One process owns all players, all rows and all global counters. There is little cluster infrastructure yet: the zone runs a Valkey for the API Server and the login server’s kicks, with a directory of which node holds an account, but there is no etcd and no link between two zones. Some seams already help, and a few pieces of state stand in the way.

A target shape link

graph TB
  C["Game clients"] -->|TLS| GW["<b>Gateway</b><br/>auth · rate limits · idle checks<br/>per-client batches · session epoch"]
  subgraph SIM["Simulation nodes"]
    direction LR
    A["Sim node A<br/>owns chunk cells 0…k"] <-->|"ghosts,<br/>handoff"| B["Sim node B<br/>owns chunk cells k…n"]
  end
  GW <-->|"commands,<br/>encoded batches"| SIM
  GW -->|route lookup| DIR["Directory<br/>account → node · region → node<br/>node ids · leases"]
  SIM -.->|lease| DIR
  SIM <-->|events| BUS["Message bus<br/>party · chat · trade escrow · economy"]
  SIM -.->|write-behind| DB[("Database<br/>owner column · @Version")]
  W["Companion app"] -->|"REST · WebSocket"| API["<b>API server</b><br/>REST · live push · map tiles"]
  API -->|route lookup| DIR
  API <-->|"requests,<br/>pushes"| BUS

This is a target shape, not a spec. The boxes are roles, not processes: the first version runs the gateway role inside every zone node. Clients only talk to the gateway, so an entity can move between nodes without a reconnect. Each node is the single writer for its chunk cells. Neighbours see border entities as read-only ghosts, and they replicate and hand over directly between nodes, not through a broker. Party, chat, trade and economy leave the World and talk over a bus. Spatial Cells explains the nodes, the gateway role and the handoff. The companion app does not use the gateway. A separate API Server serves its REST calls and live pushes, as a second client of the directory and the bus.

What blocks it today link

Each row is state that assumes one process. The last column says which way to grow needs it fixed. A realm is one node with its own database, so state that stays inside one node is fine there.

Seams that already help link

• Entity ids are 64-bit snowflakes (timestamp | node | sequence). The node part is 8 bits, so 256 nodes can mint ids with no coordination. A master gets its id when it is created and keeps it across sessions.
• Interest is already “who holds this chunk”. ChunkSubscriptionService keeps chunk → accounts, and ChunkEntityVisibility keeps chunk → resident entities and answers observersOf. A chunk cell is the natural unit of ownership.
• Audiences are declared, not computed. Each syncable component returns SyncTargets: PublicInRange, OwnerOnly or Accounts(ids). Two of the three name their audience by account id, so they stay correct across nodes as soon as message routing exists.
• Output has one seam. All game output goes through OutMessageProcessor to OutMessageHandler. ChannelRegistry is its one production implementation, and only socket/ knows Netty channels.
• Terrain needs no sharing. A chunk is a base plus player edits. The base is a pure function of the world seed, so every node can generate any chunk. Only the edits have to travel.
• Persister snapshots are plain data, copied out with the world to itself. They are a start for moving an entity between nodes, but they only carry mutable state such as position and HP. A handoff needs more.
• One writer per World. The tick thread owns the World, and handlers reach it through the inbox. See Threads and the Tick.
• Login and zone share no database, only a token. The login server already reaches every zone node, through the kicks stream in Valkey.

Two ways to grow link

Realm shards. Run many separate copies of the world, one node each, with one database per realm. Players connect straight to their realm, as they do today, so this path needs no gateway process. What is missing:

• The login server must know the realm list and hand out the right socket endpoint. It knows no zone at all today: its kicks go to every node through the stream.
• The login token must name its realm.
• Terrain edits must survive a restart.

The last two points are the rows marked “Both” above. This is the cheaper path.

Spatial cells. Run one large world across many nodes. You need every row above, plus ghost entities, a handoff and cross-node global services. The design is on Spatial Cells.

The single writer per World is done. Measure before you choose: a load test with simulated clients shows how many players one node holds. If one node carries the players you expect, realm shards are enough.

Order of work link

Each step can ship on its own, and each one also helps a single node.

Already in the code link

• One writer per World: the tick thread, the inbox and leases.
• Inbound messages run off the Netty event loops (AccountInbox).
• One batch per account per tick (TickOutbox).
• Audiences follow chunk subscriptions (EntityAudience, sendToObserversOf).
• Player bestias are saved when their owner leaves (PlayerBestiaEntityPersister).
• Login tokens are single use, per process.

Both paths link

1. Put a zone claim in the login token, check single use in one place, and sign with an asymmetric key.
2. Persist terrain edits in a durable store.
3. Run a load test with simulated clients, and choose.

Realm shards link

1. Give the login server a realm list with the socket endpoint of each realm.
2. Run one database per realm.

Spatial cells link

1. Make the gameplay layer toroidal (Vec3L.distance, AreaOfInterestService, SpawnerCellIndex). Do this first, on its own, with tests. It needs no cluster technology.
2. Move the last radius sender, BestiaTrapSystem, to sendToObserversOf, and delete the radius path. Then encode entity updates once per audience, as chunk data already is.
3. Make healing an intent, like damage. Heal, restorative items and regeneration still write Health directly, and a remote caster must be able to heal through a message.
4. Add World.evict beside destroy, and a negative term on Query.
5. Give ChunkStreamSystem an explicit anchor source. It finds the anchor with a local query today.
6. Write the full-entity codec for the handoff, with a boot check that covers every component type.
7. Check zone.shard-id at boot. Then lease node ids.
8. Give each global sweep and each world-wide fact an owner. Move party, chat, trade and economy onto a bus.
9. Build the gateway role, the direct node-to-node link and the directory. Then ghosts, then the handoff.