Skip to content

Special Formations

🚧 Partial. The SpecialFormation model and the generator's stamping pass are in place, and discovered formations surface on the galaxy map — name and type withheld until discovered, listing a neighbour's formation does not count as visiting it (no map info leak; WO-A7 61f7f65). ✅ The investigate reward ships: POST /formations/{id}/investigate (services/gameserver/src/api/routes/player.py:538) calls special_formation_service.investigate_formation to pay a one-time, rarity-scaled credit reward — 404 before the formation is discovered, 409 if it has already been investigated. The Lost-World (Quantum-Jump-only) access this page describes is the target spec. The full catalog and topology rules live in ../../DATA_MODELS/special-formations.md; the generator's stamping pipeline is in ../../SYSTEMS/special-formations-generation.md.

A Special Formation is a rare, distinctive shape that the universe takes on at certain places — a sealed pocket of sectors with one way in (a Bubble), a long narrow chain of empty sectors (a Tunnel), a sector you can warp into but never out of (a Warp Sink), a hidden side-loop that probes never find (a Blister), and others. Formations are stamped into a region's warp graph at galaxy generation and stay there for the life of the universe. They're an orthogonal axis to clusters: a Bubble can sit inside a Trade Hub cluster; a Tunnel can cross a Nebula cluster's boundary. Cluster says "what biome"; formation says "what graph shape."

Formations are how the galaxy gets texture. Without them, a region is a uniformly-distributed warp graph with stations and planets sprinkled on top. With them, every region has memorable landmark sites — defensive enclaves, hidden bases, traps, and refuges that players seek out, defend, exploit, or fear.

Formations are persistent metadata, written by the generator once and stored in SpecialFormation rows. Players don't see "this is a Bubble" labels in their sector view by default — formations are discovered through play. Visit the gateway, scan it with a Warp Jumper, observe the topology, and the formation flips to is_discovered = true for that player (per ADR-0045). ARIA surfaces the discovery once the topology is known.

Each formation gets a unique evocative name within its region, generated at bang time per ADR-0044 — "the Quiet Sector," "Shrouded Veil," "Bubble of the Lost Star," "Mercurion's Approach." The name is what players remember; the topology is what makes it worth remembering.

The catalog

Twelve formation types — the original nine plus a lost-formation trio added in ADR-0070 for content reachable only via Quantum Jump. Each has a distinct topology, a distinct generation pattern, and a distinct player-facing role.

Formation What it looks like Player role
Bubble A pocket of sectors reachable only through one gateway sector The defensive enclave. Players defend the gateway with mines + drones; the interior houses bases.
Dead-End Bubble A Bubble whose interior has no internal cycles — every interior sector is a linear dead-end off the gateway Maximum concealment. Probes can't shortcut; attackers must walk every sector linearly.
Gold Bubble An operator-placed mega-Bubble with ≥ 100 interior sectors and possibly multiple gateways Faction stronghold or story-driven enclave. Not in the random generation budget; placed by hand.
Tunnel A chain of degree-2 sectors connecting two outside endpoints — every interior sector has exactly two warps Hidden base habitat. Probe-and-dead-end-finder scripts miss tunnels because they're not terminal.
Dead-End A single sector with one warp in and one warp out, both to the same neighbor Hidden base placement. Heavily contested; common dead-ends become decoys, rare ones become prizes.
Warp Sink A sector you can warp into but never out of (zero outbound warps) Trap or one-way migration funnel. Recovery requires Slipdrive, planet portal, or scheduled clear. Common in Frontier.
Backdoor A one-way warp from outside a Bubble or Dead-End directly into its interior, bypassing the gateway Attacker's secret entry; defender's audit liability. Demotes a "secure" Bubble to "gapped."
Blister A side-loop where entry and exit reduce to the same sector — the alternate route around it is shorter Concealed base placement. Path-finding shortest-route algorithms never traverse a Blister. Among the rarest.
Escape Hatch A Dead-End plus a one-way inbound warp from a far-away sector Decoy or trap. Looks like a hidden-base candidate but receives surprise traffic via the inbound.
Lost Sector A single sector with no warps connecting it to the rest of the galaxy at all A pinprick of dark territory — reachable only by Quantum Jump. Rarely carries a one-way exit warp back to the connected galaxy.
Lost Cluster A whole cluster (15–40 sectors, internally connected) sitting off the warp graph with no link back to civilisation A self-contained lost world — stations, planets, and topology hiding behind the warp-graph wall. Sometimes carries a one-way exit.
Archipelago A group of 2–6 lost clusters (50–200 sectors) interconnected only to each other, not to the main galaxy The biggest dark-territory reward. Cross-warps between member clusters give the discoverer real navigation choices once inside; may carry one or two one-way exits anchored in different member clusters.

(TradeWars 2002's "Black Hole" formation is renamed Warp Sink here to avoid colliding with SectorType.BLACK_HOLE, the gravitational-hazard biome — the two are unrelated. A sector can be either, both, or neither.)

One-way directionality is a primitive, not a type

Several formations carry directed warps: a Warp Sink has inbound warps and no outbound; a Backdoor is a one-way edge into a Bubble or Dead-End; an Escape Hatch has a one-way inbound from far away; and a Lost World may carry a one-way exit. In every case the direction lives on the warp row itself — is_bidirectional = false on the sector_warps or WarpTunnel row — never on the formation type or any other enum. Latency (whether the warp looks bidirectional until a Warp Jumper's scan reveals it) lives on is_latent on the same row. A formation type names the graph shape; the directed edges that compose it are ordinary warp rows flagged one-way.

One-way natural warps are a worldgen-only primitive: only BACKDOOR, WARP_SINK, ESCAPE_HATCH, and Lost World exit warps produce them. No player mechanic creates a one-way natural warp — Genesis devices and any "create natural warp tunnel" mechanic produce bidirectional natural warps only. Player-built warp gates are intrinsically directional but are a separate mechanism governed by their own access model (see ./warp-gates.md), not part of this natural-warp rule. The player-facing discovery, marked/latent split, and one-way stranding recovery are detailed in ./sectors.md#one-way-warps.

Rarity

Formations are budgeted per region by sector count and zone:

Region size Bubble Tunnel Dead-End Blister Escape Hatch Warp Sink Lost Sector Lost Cluster Archipelago
100–300 sectors 0–1 0–1 1–2 0 0 0–1 0–1 0 0
301–600 sectors 1–2 1 2–3 0–1 0–1 0–1 0–2 0–1 0
601–800 sectors 2–3 1–2 3–4 1 1 1 1–2 0–1 0
801–1,200 sectors (Standard tier) 3–4 2–3 4–5 1–2 1 1–2 1–3 0–1 0–1

Backdoors are stamped only against an existing Bubble or Dead-End (one Backdoor per target, max). Gold Bubbles are operator-only (no random budget). Archipelagos appear only in Standard-tier and larger regions — a 200-sector formation isn't a credible landmark in a 300-sector region.

Zone biases shape which formations a region gets where:

Formation Federation Border Frontier
Bubble / Dead-End Bubble rare common common
Tunnel uncommon common common
Dead-End common common common
Warp Sink never rare uncommon
Backdoor never rare uncommon
Blister rare rare uncommon
Escape Hatch never uncommon uncommon
Lost Sector never rare common
Lost Cluster never rare uncommon
Archipelago never never rare

"Never" means the generator skips Federation candidates for that type — Federation Zone is high-policing and player-friendly; trap formations break the safe-zone contract. Lost formations bias hard to Frontier — dark territory only reads as dark when the surrounding region is already wild.

Lost Worlds — Quantum-Jump-only content

📐 Design-only. Per ADR-0070. Lost Sectors, Lost Clusters, and Archipelagos sit off the warp graph — zero sector_warps and zero WarpTunnel rows connect any interior sector of the formation to the Capital's strongly-connected component. They are graph-disconnected sub-graphs: routine warp traversal cannot reach them. The only way in is Quantum Jump — the Warp Jumper's multi-phase directional FTL primitive (see ./sectors.md#quantum-jump-warp-jumper). Because Quantum Jump resolves against a sector's 3D position rather than the warp graph, a Lost World is reachable from any sector within Quantum Jump's range-and-accuracy envelope even though no warp leads to it. Worldgen enforces a reachability floor: every Lost World anchor lies within Quantum Jump's maximum committed range of at least one sector in the Capital's strongly-connected component, so the formation is hidden-but-discoverable rather than truly unreachable. The strict graph-only reachability that applies elsewhere is deliberately relaxed for Lost Worlds — their existence outside the Capital's strongly-connected component is canonical, bounded by the 75% floor in Worldgen invariants.

This is the dark-territory reward for committing to the Warp Jumper investment. Lost Worlds carry the same biome variety, station and planet inventories, and citadel content that any other region cluster does — they are just hidden behind the warp-graph wall. A discoverer who lands inside a Lost Cluster or Archipelago finds a fully-furnished sub-region they can prospect, defend, and use as a hidden base in ways the rest of the player population cannot reach by routine play.

A minority of lost formations carry a one-way exit warp out to the connected galaxy — the discoverer can rely on the exit for return without re-jumping. The exit is strictly outbound: its source sector is interior to the formation, its destination is in the Capital's strongly-connected component, and it is flagged is_bidirectional = false like any other one-way warp. A player already inside the formation can take the exit and leave conventionally; a player in the connected graph cannot enter through it, because the direction does not go that way. Exit warps are marked (is_latent = false, visible to anyone inside the formation), so finding the island once means knowing how to leave it. From the destination side, the exit looks like an ordinary outbound warp with no inbound — non-discoverers see a "where does this go?" curiosity, not a return path. Lost formations without an exit warp require a fresh Quantum Jump for every return trip.

Exit-warp probabilities by type:

Type Probability of an exit warp
Lost Sector ~5%
Lost Cluster ~15%
Archipelago ~25% (with a small chance of two exits, each anchored in a different member cluster)

The asymmetry rewards investment: a Lost Sector is almost always a strand-and-jump-back proposition; an Archipelago is plausibly a settle-in-and-claim proposition.

Discovery

A formation's is_discovered flag flips to true for a player when:

  • They visit any of the formation's interior sectors (or the anchor for single-sector formations like Dead-End or Warp Sink), AND
  • They run a Warp Jumper scan (or other scan equipment per ADR-0045) that observes the local topology.

Once discovered, the formation appears in the player's regional map by name, ARIA references it conversationally ("you've been to the Quiet Sector four times this week"), and the formation's topology is annotated in the sector view (gateway glyph for Bubble, "no exit" warning for Warp Sink, etc.).

Per-player discovery state is governed by ADR-0045 — one player's discovery does not leak to another player by default. Corp-mates can share discoveries via the existing realtime-bus event.

Naming

Formation names are AI-generated at bang time per ADR-0044, themed by formation type and region tone. Federation regions get sober names ("Mercurion's Approach"); Frontier regions get rugged ones ("Ashpit," "Rendezvous of the Damned"); the Central Nexus gets civic names ("Concordat Quarter"). Names are unique within a region — (region_id, name) is UNIQUE-constrained on the schema.

Operators can override an LLM-generated name post-generation; the uniqueness constraint still applies.

Pirate-occupied formations

Some formations come pre-populated with pirates at galaxy generation. A Bubble in the Frontier zone is exactly the topology pirates want — one defensible chokepoint, an internal cache — and the worldgen pre-seeding pass (Phase 12.6) lays an OutlawBase and a PirateHolding row inside qualifying formations. The result is a pirate-occupied formation — the topology layer (Bubble, Dead-End Bubble, Tunnel) plus a population layer (named pirate Lord/captains, sector defenses, planets with citadels, pirate-owned stations).

For the full design — tier model (Camp / Outpost / Stronghold), composition spectrum (open-sector hideouts, lone trading posts, fortified planets, multi-component complexes), capture mechanics, ownership transfer, and organic recovery — see ./pirate-holdings.md and ADR-0047.

A formation hosting a pirate holding is referenced via SpecialFormation.pirate_holding_id. Camps without formation backing don't set the field (they live on open Frontier sectors with no topological anchor); Outposts and Strongholds typically do.

Worldgen invariants

A handful of rules hold across all generated regions, validated at galaxy generation Phase 13:

  • The Capital Sector's strongly-connected component contains at least ⌊0.75 × total_sectors⌋ sectors. No formation may reduce it below that floor. The remaining sectors may form graph-disconnected Lost Worlds (see Lost Worlds below).
  • No formation isolates the Capital Sector, either SpaceDock, or any Class-0 station from the Capital's strongly-connected component. Federation Zone sectors stay inside that component under every stamping outcome.
  • Formations never touch the starter cluster (sectors 1..fedspaceSize, default 10) — fedspace stays a dense, formation-free starter area.
  • A Backdoor always references a target Bubble / Dead-End that exists in the same region.
  • A Warp Sink is never stamped inside a Bubble interior (per ADR-0046 / SK6) — the combination produced an undefined topology.

Major Space Lanes (not formations)

A "Major Space Lane" (the union of shortest paths between hub sectors — sector 1, the Capital, both SpaceDocks, plus any Class-0 stations) is a derived structure, not a stamped formation. Subsystems that need MSL data (Federation patrol routing, traffic events, extern-wipe rules) compute it from sector_warps at load time. MSL is documented here only to clarify why it isn't in the formation catalog.