Shards, keys and specs

A shard is a map being simulated: one process, one scene, a population. ShardId names it, ShardKey says which map, region and version it is for, ShardCapacity says how full it may get, and RealmSpec is everything a process needs in order to be one — encoded as a single string that crosses the process boundary as one argument or one environment variable.

These types exist so that several processes can agree about a shard without any of them being able to disagree quietly. Three separations are load-bearing and each of them is a bug the design refuses to be able to express:

• ShardId is not RealmInstanceId. One shard may be carried by several processes over its life — a crash and a replacement, a version rollout — and one process never carries two shards. A lost shard is replaced by a placement, not a resurrection.
• PlayerKey is not Vixen.Net.Sessions.PlayerId. PlayerId numbers a player within one session; it survives a dropped connection and not the session. PlayerKey is who the database thinks they are, on every realm they ever visit. It is an account and a character, because two characters on one account are two sets of inventory.
• RealmVersion is a build and a content hash, and both filter placement. A client whose catalog hash does not match a shard's is never placed on it — it is placed on one that matches. That is what turns a hard rejection into a routing decision, and it is the whole of the incremental-upgrade story.

An orchestrator decides a shard should exist and writes a spec. The endpoint may be left unbound — with no port, or with nothing at all — which says the backend chooses, and tells me.

On the other side of the boundary, a process asks whether it is a realm at all:

TryRead prefers the argument over VIXEN_REALM_SPEC, because a launcher that set both meant the argument: the environment is what a pod template inherits, and inheriting a stale one is the accident that order prevents.

Ready is the only state that is a placement candidate. That single rule is what makes both elastic scaling and rolling upgrades work with no further mechanism: a shard stops taking arrivals the instant it starts draining, and one that has not finished loading its map never takes any.

ShardKind distinguishes a public map from a dungeon, a match and a player's house. They differ in who is admitted and when the shard may stop, and in nothing else — which is what makes instanced content a placement decision rather than a second server.

Capacity is two numbers because it answers two questions. HardCap is a filter — a shard at it is not scored at all — and SoftCap is where placement's fill term turns negative. The gap between them is what a party arriving together fits into.

A map address is an addressable address, and its leaf is the scene's name — which is what NetworkSceneId hashes:

So a client that has loaded the map already agrees with the realm about what the props are before a packet arrives.

• Writing a realm — the process a spec boots.
• Placing realms — what writes one.
• Transfer tickets — how a player gets in.
• docs/plan/27 § Placement, § Shard kinds.