Live · concept
Placing players
The megaserver as a function — the hard filters, the score, the explanation, and the hysteresis that decides when a map grows a shard.
Edit this page on GitHubDocuments
What it is
There is no server select and no realm queue. A player asks for a map and the megaserver puts them on
the best instance of it — where "best" is a score a game authors. PlacementDirector is that score;
MapFleet is what decides the map needs another instance, or one fewer.
What it is for
Everything Guild Wars 2 is famous for at this layer falls out of one scoring function rather than being a feature beside it. "Join your friend's instance" is a party term weighted at ten thousand. "Overflow" is a shard spawned above the intended count and drained first. "No queue" is a consequence of both. Writing them as separate mechanisms is how an MMO ends up with four ways to end up somewhere, three of which disagree.
Using it
var director = new PlacementDirector(); // or PlacementWeights.Parse(yourVxplacement)var decision = director.Place(request, candidates);if (decision.Outcome == PlacementOutcome.Placed) { // decision.Shard and decision.Endpoint are everything the gate hands the client.}The hard filters come first, and each has its own name
A candidate that fails one is not scored at all:
Map, Region | a different map, or a different latency zone |
Build, Content | ADR-022's version pair. Content is the one a client that has not fetched the catalog update hits |
NotReady | starting, draining or gone. Only Ready is a placement candidate |
Full | at its hard cap |
Access | an instance's access list does not admit them |
They are separate values rather than one "excluded" because the whole use of the answer is telling somebody why they did not end up with their guild — and *"the shard your guild is on is running last week's build"* and "the shard your guild is on is full" are different conversations.
Then a score, and every term is named
party 10 000 // a party member is present — effectively a hard pullguild 400 // per member, capped at fivefriends 200 // per friend, capped at fivelocale 300 // the shard is speaking their languagefill 250 // fill is in the healthy band, 40–80 % of the soft capoverfull −40/pt // above 80 %, falling away steeplyage −100 // the shard is past its maximum ageantiflap −5 000 // they were just moved off this shard⚠ The party term outweighing everything else put together is the mechanism, not a preference. A party pull that could lose to a full guild would be a separate join feature waiting to be written.
⚠ Preferring a shard that is already half full is what makes consolidation possible. A score that spread players evenly would leave a map that is emptying with a lot of lonely shards and no way to merge them.
Examples
Why did I not end up with my guild?
Console.WriteLine(decision.Explain());// placed on 0f8fad5b-… at 10.0.0.4:7777, scoring 2450// 0f8fad5b-… scored 2450 — guild +2000, locale +300, fill +250// 7b1c9e02-… scored -5000 — antiflap -5000// 3a44f180-… excluded: ContentDoc 27 § Diagnostics is blunt about why this is not optional: *without it, placement complaints are unanswerable*. Every candidate gets a verdict whether or not it was scored.
When does a map grow?
MapFleet watches one map. It spawns when there is no shard at all, when every shard is at its soft
cap, or when the recent arrival rate projected over the lead time exceeds the free space — debounced,
because two hundred people zoning in at once must not produce twenty shards. It merges when two or
more shards have been under a quarter of their soft cap for two minutes, draining the emptiest.
fleet.Arrived(now); // every zone-in feeds the projectionvar action = fleet.Observe(now, candidates); // Spawn, Drain, or None⚠ The asymmetry is the design. Spawning at 100 % and merging below 25 %, with a dwell before any
merge, is what stops the fleet oscillating — the same lesson as InterestChain's leave-hysteresis, at
a different scale.
⚠ A cyclical map settles on its peak, not on its trough. A world boss that fills a map every three minutes keeps the shards between events, and that is correct: a fleet that collapsed every trough would spend the next peak refusing people while shards load.
Two things the traces found
The test project simulates doc 27's three traffic shapes — flash crowd, slow bleed, sawtooth — through half an hour in milliseconds, and both of these were real defects in the first version:
- A rate measured over the nominal window makes a burst read as a trickle. Ten arrivals a second read as 0.17/s until a sixty-second window fills, so the fleet spawned after saturation and refused twenty of two hundred players. The rate is now measured over the span the arrivals actually landed in, with a floor so that a party arriving in one instant is not mistaken for a rate.
- Resetting the merge dwell after each drain makes a cyclical map leak shards. Once a merge has finished, no new evidence is needed — the map has already been quiet for the dwell. What guards against draining too fast is that only one merge is in flight at a time.
Asking afterwards
PlacementDecision.Explain() has always produced the full account — the filter that excluded each
candidate and the score of each survivor — and PlaceResult.Reason carries it back to whoever asked.
But that is the only moment it exists: the gate turns it into an HTTP response and it is gone.
The complaint § Diagnostics exists to answer arrives hours later, from somebody who was not there. So every map keeps its last decision per player:
var account = await cluster.GetGrain<IMapGrain>(Keys.ForMap(key)).Explain(player);⚠ Bounded, and that is not a detail — this lives in a grain in a process meant to run for weeks,
so an unbounded record of every placement is a memory leak with a plausible excuse, worst on the
busiest map. What is kept is the last decision per player and at most Capacity of those.
⚠ Every answer is kept, not only the refusals. "Why am I on this shard rather than my guild's" is a complaint about a placement that succeeded. And "nothing is held" reads differently from "they were refused", because those send an operator to two different places next.
See also
- Shards, keys and specs — what a candidate is.
- Placing realms — what a
Spawnturns into. - docs/plan/27 § Placement.