Skip to content

Special Formations Generation

Status: 🚧 Partial — Per ADR-0069 the stamping algorithm legitimately lives in sw2102-bang (out of this repo, unverifiable here) … (impl audit 2026-06-16)

Purpose

This document describes how the galaxy generator stamps Special Formations — Bubbles, Tunnels, Dead-Ends, Blisters, and the rest of the catalog — into a region's warp graph as rare strategic landmarks. Formation taxonomy and schema live in ../DATA_MODELS/special-formations.md; this document covers the generation pipeline, rarity controls, and stamping algorithms.

Per ADR-0069, GENERATED-origin formation stamping runs inside sw2102-bang, between bang's proximity-warp placement and long-distance-tunnel placement. Bang emits SpecialFormation rows in the Universe payload; the gameserver validates and persists them on import (see ./bang-import-pipeline.md#6-import-special-formations) and runs the Phase 13 cross-checks. The algorithm is unchanged; only the execution location is bang-side.

Formations are stamped during the warp-graph phase of generation (see ./galaxy-generator-design.md Phase 9 for the gameserver's view) and produce SpecialFormation rows alongside the sector_warps adjacency entries.

Pipeline placement

Formation stamping inserts as Step 6.5 in the existing galaxy-generation pipeline:

# Step Output
4 Clusters Cluster rows with biome types
5 Sectors Sector rows with 3D coords, biome types
6 Local warp adjacency sector_warps (proximity-based)
6.5a Lost-formation stamping (LOST_SECTOR, LOST_CLUSTER, ARCHIPELAGO) SpecialFormation rows with their backing Cluster rows; reserved sector set excluded from later passes
6.5b Standard special-formation stamping (all other types) SpecialFormation rows; adjusted sector_warps
7 Long-distance warp tunnels WarpTunnel rows (skips lost-formation sectors)
8 Stations & planets Station, Planet rows

The order matters:

  • Step 6 (proximity adjacency) runs first to give Step 6.5 a baseline graph to mutate.
  • Step 6.5a (lost-formation stamping) runs before Step 6.5b and Step 7. Per ADR-0070, lost formations carve out their sector set as reserved — subsequent passes (standard formation stamping, long-distance tunnels) must skip any anchor or interior sector of a lost formation. The one-way exit warps for lost formations are stamped as part of this pass, not as ambient sector_warps rows.
  • Step 6.5b stamps the rest of the catalog by adding, removing, and reorienting edges in sector_warps to satisfy each formation's topology rule.
  • Step 7 (long-distance tunnels) runs last so tunnel placement can avoid breaking formation invariants — a long-distance tunnel into a Bubble's interior would defeat the gateway, and a long-distance tunnel into a lost formation would defeat the Quantum-Jump-only contract.

Phase decomposition

Formation stamping itself runs in three sub-phases.

Phase A — Anchor selection

For each formation type the region's budget calls for, pick an anchor sector that:

  • Lives in an appropriate cluster (Bubbles favor Frontier Outpost and Standard clusters; Backdoors favor Border and Frontier zones).
  • Has the right baseline degree — Bubbles need an articulation-point candidate; Tunnels need a chain seed.
  • Is sufficiently far from other formations' anchor sectors (configurable minimum distance, default 5 hops).

Anchor selection runs deterministically from the generation seed; chosen anchors are recorded so a re-stamp produces the same layout.

Phase B — Template stamping

For each anchor + formation type, apply the type's template to the local graph:

Formation Stamping operation
BUBBLE Reserve interior_size sectors adjacent (or near-adjacent) to anchor. Remove all warps from interior to the rest of the region except those passing through anchor. Optionally insert a degree-2 link tunnel between anchor and first interior sector.
DEAD_END_BUBBLE Stamp BUBBLE, then strip any interior-to-interior cycles, leaving each interior sector as a dead-end off the anchor's bubble-internal warps.
GOLD_BUBBLE BUBBLE with interior_size >= 100, optional multi-anchor (each anchor independently isolates a slice of the same interior component).
TUNNEL Pick length sectors in a chain. For each interior chain sector, ensure exactly two warps — both within the chain. Excise any other warps.
DEAD_END Reduce the anchor sector to undirected degree 1 by stripping all but one bidirectional neighbor warp.
WARP_SINK Strip all outbound warps from the anchor; ensure at least one inbound warp survives (or add one from a nearby sector if pruning made it isolated).
BACKDOOR Pick a target Bubble / Dead-End and a non-gateway sector outside it. Add a one-way warp from outside-sector to an interior sector of the target.
BLISTER Pick a single anchor sector with degree ≥ 3. Carve a short side-loop (2–4 sectors) whose entry and exit both terminate at the anchor; ensure the alternate path around the blister is shorter, so probe shortest-paths bypass it.
ESCAPE_HATCH Stamp DEAD_END, then add a single one-way inbound warp from a far-away sector (graph distance ≥ 4).
LOST_SECTOR Pick a single Frontier-biased sector ≥ N hops from the Capital and not already inside another formation. Strip any existing warps that would link it externally. Roll the 5% exit-warp probability; if positive, stamp a single one-way (v → u) to a connected-sub-graph destination chosen per the rules below.
LOST_CLUSTER Reserve a contiguous group of 15–40 sectors as a new Cluster row (name per ADR-0044). Run the standard local-adjacency pass restricted to this sector set so the cluster is internally connected. No external warps. Roll the 15% exit-warp probability; if positive, pick an interior source sector and stamp a single one-way exit to the main connected sub-graph.
ARCHIPELAGO Reserve 2–6 spatially-proximate cluster-sized groups (per Sector.position distance) as new Cluster rows. Generate internal warps within each cluster via the standard local-adjacency pass restricted to the cluster's sector set; then stamp cross-cluster warps between member clusters at a tunable density (1–3 cross-warps per pair, totalling crossWarpCount). No external warps. Roll the 25% exit-warp probability for one exit and a further ~5% for a second; each exit's source must live in a different member cluster.

After stamping, write the SpecialFormation row with the chosen anchor, interior sectors, and computed properties.

Lost-formation specifics

Per ADR-0070, the three lost-formation types share an anchor-selection and exit-warp protocol.

Anchor selection.

  • LOST_SECTOR: pick any single sector in a Frontier-heavy zone that is at least N hops from the Capital (default N = 12, configurable per region tier) and not already inside another formation. Reserve it; remove any warps that would link it externally.
  • LOST_CLUSTER: pick a spatially-contiguous group of 15–40 sectors that will form an internally-connected cluster (per Sector.position proximity). Reserve them as a new Cluster row. No external warps; internal warps come from the standard local-adjacency pass restricted to the cluster's sector set.
  • ARCHIPELAGO: pick 2–6 cluster-sized groups (each 15–40 sectors) in spatial proximity, reserve them as new Cluster rows, generate internal warps within each cluster, then stamp cross-cluster warps between member clusters at the tunable cross-warp density.

All lost-formation anchor selections honour the standard exclusion rules (no Capital, SpaceDock, Class-0 station, special location, or fedspace sectors in the reserved set) and the standard minimum-spacing rule against other formations.

One-way exit stamping.

For each stamped lost formation, roll the per-type exit probability (nominal 5% / 15% / 25% for LOST_SECTOR / LOST_CLUSTER / ARCHIPELAGO; ARCHIPELAGO additionally rolls a ~5% second-exit probability). On a positive roll:

  1. Pick an exit source sector inside the formation (for ARCHIPELAGO, choose a different member cluster for each exit).
  2. Pick an exit destination sector in the connected sub-graph, constrained to avoid Federation Zone destinations and to be ≥ N hops from the Capital (same N as anchor selection).
  3. Write a single one-way warp row from source to destination: is_bidirectional = false, is_latent = false (marked, not latent — the discoverer can rely on it for return per ADR-0070), origin GENERATED. From the destination's local view this appears as an ordinary outbound warp with no inbound — analogous to ESCAPE_HATCH's inverse, except the formation hides the source rather than the inbound.
  4. Record the exit on the formation's properties.exitWarp (or properties.exitWarps[]) so the import-time validator can correlate the warp row with its formation.

Exit warps are stamped as part of the lost-formation pass, not as ambient sector_warps rows produced by Step 6 or by the ambient one-way pass — anchoring the warp to the formation row keeps the validator's connectivity rules tractable and lets the per-player discovery surface know which warp belongs to which formation.

Phase C — Validation

Each stamped formation must satisfy its topology rule (see catalog). The validator runs:

  1. For each formation, recompute its topology from sector_warps and assert it matches the type's invariant.
  2. Cross-check no two formations share an anchor (except BACKDOOR, which intentionally references another formation's interior).
  3. Confirm overall region connectivity — no formation has stranded a non-formation sector from the main graph. Lost-formation interiors are intentionally disconnected; the validator excludes lost-formation sector sets from the "main-graph" definition before running the strand check.
  4. Confirm the Capital Sector and both SpaceDocks are not inside any restrictive formation (Bubble interior, Warp Sink, etc.).
  5. For each lost formation: confirm the interior is internally connected (LOST_CLUSTER, ARCHIPELAGO); confirm no external sector_warps or WarpTunnel rows cross the interior boundary (except the optional one-way exits recorded on the formation's properties); confirm the formation contains no Capital, SpaceDock, Class-0 station, special location, or fedspace sector.

Validation failures abort the generation transaction; the region rolls back to its pre-stamping state.

Rarity controls

Formations are configured per region via a formation budget:

Region type Budget profile
Central Nexus (5,000 sectors) 8–12 BUBBLE, 4–6 TUNNEL, 2–3 BLISTER, 0 GOLD_BUBBLE (operator-placed only), 1–2 BACKDOOR per Bubble
Terran Space (300 sectors) 1–2 BUBBLE, 1 TUNNEL, 0 BLISTER, 0 GOLD_BUBBLE, 0 BACKDOOR
Player-owned (Standard tier 800–1,200 sectors) Per region tier (see below)

Player-owned region tiers (Standard tier covers the launch range; smaller / larger ranges are reserved for operator-managed special regions and 📐 Design-only higher subscription tiers):

Sectors Bubble Tunnel Dead-End Blister Escape Hatch Warp Sink Backdoor (per Bubble) Lost Sector Lost Cluster Archipelago
100–300 0–1 0–1 1–2 0 0 0–1 0 0–1 0 0
301–600 1–2 1 2–3 0–1 0–1 0–1 0–1 0–2 0–1 0
601–800 2–3 1–2 3–4 1 1 1 1 1–2 0–1 0
801–1,200 3–4 2–3 4–5 1–2 1 1–2 1 1–3 0–1 0–1
1,201–1,500 (📐 future tiers) 4–5 3–4 5–6 2–3 1–2 2–3 1–2 2–4 1–2 0–1

Counts are upper bounds; the generator may stamp fewer if anchor selection fails (graph too sparse, no qualifying sectors, conflict with already-stamped formations).

Tiny-region spacing relaxation (per ADR-0051 SK34): for regions ≤ 300 sectors, the standard 5-hop minimum spacing between formations is relaxed to 3-hop. Without the relaxation, tiny regions often fail to stamp any formation; the relaxation lets a single notable formation surface where one would otherwise be excluded by spacing. The 0–1 budget for tiny regions still caps the count; spacing simply allows the count to actually land.

GOLD_BUBBLE is operator-only; it never appears in the random budget. Operators stamp gold bubbles via an admin endpoint (see Source map below).

Region-zone biases

Anchor selection respects the region's zone layout (Federation / Border / Frontier; see ./galaxy-generation.md#step-3--zones):

Formation Federation Border Frontier
BUBBLE rare common common
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-zone candidates for that formation type. Federation is high-policing and player-friendly; trap formations break the safe-zone contract. Lost formations bias hard to Frontier — the dark-territory reward only makes sense in zones the warp-graph wall can credibly hide.

Determinism

Formation stamping is fully deterministic given:

  • The Region.generation_seed.
  • The completed Step-5 sector layout.
  • The Step-6 baseline sector_warps adjacency.
  • The region-scoped formation budget.

Re-running stamping on the same inputs produces the same SpecialFormation rows in the same order. Formation IDs are stable across re-runs (UUIDs derived from seed plus ordinal index).

Invariants

  1. Every SpecialFormation row's anchor_sector_id and interior_sector_ids reference sectors that exist and belong to the same region_id.
  2. The topology rule for each formation type holds in sector_warps after Step 6.5 completes — validated in Phase C.
  3. No formation isolates the Capital Sector, either SpaceDock, or any sector with a Class-0 station from the region's main connected component.
  4. BACKDOOR formations always reference a target formation that exists in the same region.
  5. Formation stamping never modifies sectors in the first 10 (fedspace anchor); fedspace stays a dense, formation-free starter area.
  6. No WARP_SINK may anchor in a BUBBLE / DEAD_END_BUBBLE / GOLD_BUBBLE interior (per ADR-0046). Bubble-family formations stamp first; Warp Sink anchor selection skips Bubble-claimed sectors. Phase 13 cross-checks this with a SQL existence query.
  7. No LOST_SECTOR / LOST_CLUSTER / ARCHIPELAGO sector carries any sector_warps row or WarpTunnel row crossing into the main connected sub-graph, except the optional one-way exit warps recorded on the formation's properties (per ADR-0070). Lost formations stamp first (Step 6.5a); standard formation stamping and long-distance tunnel placement (Step 7) skip lost-formation sector sets.

Failure modes

Mode Target handling
Anchor selection exhausts candidates Stamp fewer formations than the budget upper bound; log under-budget event with reason.
Stamping would isolate a Capital Sector or SpaceDock Reject this candidate; retry with the next candidate.
Validation (Phase C) fails Abort generation transaction; surface validation error to admin.
Backdoor target formation does not exist Generate target formation first; if budget already allocated, drop the backdoor.
Operator-only formation requested in random budget Reject configuration at pre-flight.

EMERGENT formation detector pass

📐 Design-only. Per ADR-0053 WR7. Runtime service that materializes new EMERGENT-origin formations as the warp graph evolves (player gates anchored, player gates destroyed in cascade, etc.).

Cadence: every 6 hours.

Scan target: the warp graph at the region level. The detector runs the same topology rules as the worldgen stamping templates against the live sector_warps graph and identifies any topology that matches a formation template but has no corresponding SpecialFormation row.

Action: insert new SpecialFormation rows with origin = EMERGENT and is_discovered = false. Per-player discovery applies via ADR-0045 — players discover the formation via Warp Jumper scan or sector visit, same as GENERATED-origin formations.

Idempotency: a second pass on an already-detected emergent formation finds the existing row and skips. Matching uses topology hash (sector ID set + edge set), not just sector ID, so minor warp drift doesn't double-create.

Why 6 hours: emergent formations are infrequent. Player gate construction and cascade destruction are rare events; 4 detector passes per day catches them with bounded latency. A faster cadence would burn cycles re-scanning unchanged graphs.

Failure modes: missed pass extends emergence-detection by 6 hours. Acceptable.

Source: services/gameserver/src/services/formation_detector_service.py:run_emergent_pass (target).

Source map

Concern Path (target)
Stamping orchestrator (bang-side) sw2102-bang/src/formations.ts:stampFormations
Per-type templates (bang-side) sw2102-bang/src/formation-templates.ts
Anchor selection (bang-side) sw2102-bang/src/formation-templates.ts:selectAnchor
Internal stamping-time validation (bang-side, including ADR-0046) sw2102-bang/src/formation-templates.ts:validateFormation
Import-time validation + persistence (gameserver) services/gameserver/src/services/special_formation_service.py:validate_and_persist_imported_formations
SpecialFormation model services/gameserver/src/models/special_formation.py
Admin gold-bubble endpoint services/gameserver/src/api/routes/admin.py:place_gold_bubble