Skip to content

Special Formation — Catalog

Status: 🚧 Partial — SpecialFormation model and all 12 enum types are fully built with proper indexes and relationships; pirate_holding_id / owner capture columns are absent (depends on unbuilt PirateHolding table) … (impl audit 2026-06-16)

A Special Formation is a strategically-significant warp-graph topology — a Bubble, a Tunnel, a Dead-End, etc. — stamped into a region by the generator at chosen anchor sites. Formations are an orthogonal axis to clusters: a Bubble can sit inside a Trade Hub cluster; a Tunnel can cross a Nebula cluster's boundary. A cluster says "what biome", a formation says "what graph shape".

The catalog below derives from the canonical TradeWars 2002 community taxonomy plus the lost-formation extension in ADR-0070 (the LOST_SECTOR / LOST_CLUSTER / ARCHIPELAGO set, reachable only via Quantum Jump). Formations are stamped during galaxy generation (see ../SYSTEMS/special-formations-generation.md) and become rare landmark sites players seek out for defensive bases, hidden caches, and trap setups.

The schema below is unchanged by ADR-0069; the row source — bang vs gameserver — is what shifted. Per ADR-0069, GENERATED-origin rows are emitted by sw2102-bang and validated/persisted by the gameserver on import (see ../SYSTEMS/bang-import-pipeline.md#6-import-special-formations). EMERGENT-origin rows continue to materialize at runtime via the periodic detector pass.

Vocabulary

  • Cluster — biome / role classification (Trade Hub, Nebula, Frontier Outpost). See ./galaxy.md#cluster.
  • Sector type — per-sector biome (STANDARD, NEBULA, BLACK_HOLE as gravitational hazard, etc.). See ./galaxy.md#sector.
  • Special Formation — graph-topology pattern across one or more sectors. The subject of this document.

A sector belongs to exactly one cluster, has exactly one sector type, and may belong to zero or more formations.

The TradeWars 2002 term "Black Hole" describes a topology — a sector with inbound warps but no outbound warps (a directed sink). To avoid collision with SectorType.BLACK_HOLE (a gravitational-hazard biome), the formation is named WARP_SINK in this catalog. The two are unrelated: a sector can be either, both, or neither.

Directionality lives on the warp row, not on the type

The directed edges that compose a WARP_SINK, BACKDOOR, ESCAPE_HATCH, or a Lost World exit are ordinary one-way warps: directionality is carried by is_bidirectional = false on the underlying sector_warps or WarpTunnel row, and latency by is_latent on the same row — never by SpecialFormationType or any other enum. The column definitions live in ./galaxy.md. One-way natural warps are worldgen-only: only the formation-stamping pass produces them, and player mechanics (Genesis devices, "create natural warp tunnel") emit bidirectional natural warps only. A formation row references the sectors it spans; the one-way flags sit on the warp rows the stamper writes between them.

Catalog

BUBBLE

A connected group of two or more sectors reachable from the rest of the region only through a single gateway sector. The gateway lies outside the bubble — it is the sector whose warp leads into the bubble's interior.

Topology rule. In the local adjacency graph (sector_warps), the gateway is an articulation point whose removal separates the bubble's interior sectors from the region's main connected component.

Generation parameters. - interior_size — number of interior sectors (default range 3–8, configurable per region). - link_tunnel_depth — number of degree-2 sectors between the gateway and the bubble's first interior sector. Depth 0 means the bubble attaches directly to dense space. - branching — whether the interior is a chain (linear), tree (forks), or contains internal cycles.

In-game role. The classic defensive enclave. Players defend the gateway with mines, fighters, and hazards; the interior houses bases.

DEAD_END_BUBBLE

A BUBBLE subtype whose interior sectors have no warps leaving the bubble except back through the gateway. No cycles, no internal one-ways out.

Topology rule. Bubble plus invariant: every directed edge (u → v) where u is interior must satisfy v ∈ interior or v == gateway.

Generation parameters. Same as BUBBLE; additionally enforces the dead-end-interior invariant during stamping.

In-game role. Maximum concealment. An attacker probing the bubble's interior must walk every sector linearly — opponents cannot shortcut through internal one-ways.

GOLD_BUBBLE

A BUBBLE of operator-significant scale (≥100 interior sectors), reserved for region-scale set-pieces (a faction stronghold, a story enclave). May have multiple gateways.

Topology rule. Bubble with interior_size >= 100. Multi-gateway gold bubbles relax the single-articulation-point rule to "small set of articulation points all connected to the same interior component."

Generation parameters. - gateway_count — number of articulation-point gateways (default 1, range 1–3). - interior_size_min — default 100. - All other BUBBLE parameters.

In-game role. Operator-placed faction territory or story site. Not generated in the random budget; placed via admin tool only.

TUNNEL

A linear chain of degree-2 sectors connecting two endpoints (called mouths) of degree ≥ 3. Every interior sector of the chain has exactly two warp neighbors, both within the chain.

Topology rule. A maximal induced path in the local adjacency graph where every interior vertex has degree exactly 2.

Generation parameters. - length — number of degree-2 interior sectors (default range 3–8). - one_way_bias — probability that a tunnel sector contains a one-way warp (default 0).

In-game role. Hidden base habitat — tunnels are missed by probe-and-dead-end-finder scripts that only look for terminal nodes. Players defend the mouth.

DEAD_END

A single sector with exactly one warp out and one warp in, both connecting to the same neighbor sector — a true terminal node.

Topology rule. Vertex with undirected degree 1 in the projection of sector_warps.

Generation parameters. - parent_kind — what the dead-end attaches to (open space, tunnel, bubble interior). - is_unfigged_only — whether the dead-end sector is restricted from NPC presence at generation time.

In-game role. Hidden base placement. The first sector type adversary scripts target — counter-intuitively, frequently-trafficked dead-ends become decoys, while rare dead-ends in low-numbered sectors become prizes.

WARP_SINK

A sector with one or more inbound warps but zero outbound warps. (TradeWars 2002 calls this a "Black Hole"; renamed here to avoid collision with the BLACK_HOLE sector biome.)

Topology rule. Vertex with directed in-degree ≥ 1 and directed out-degree 0 in sector_warps.

Generation parameters. - entry_count — number of inbound warps (default 1–3). - recovery_method — designer-chosen exit mechanism (Slipdrive pad, planet portal, scheduled clear). Required for non-trap warp sinks.

In-game role. Trap or one-way migration funnel. Common in Frontier zones; rare elsewhere.

BACKDOOR

A one-way warp from outside a bubble (or defended dead-end) into its interior, bypassing the gateway. The presence of any backdoor demotes a BUBBLE to a "gapped" or "unsecure" bubble.

Topology rule. A directed edge (u → v) such that: - v is in the interior of some bubble or dead-end set B, - u is not in B and not the gateway of B, - The reverse edge (v → u) does not exist.

Generation parameters. - target_formation_id — which bubble or dead-end this backdoor pierces. - entry_distance — how deep into the interior the backdoor lands (closer to gateway means less useful for an attacker).

In-game role. Attacker's secret entry; defender's audit liability. A BACKDOOR is never generated independently — it always references a target formation that already exists.

BLISTER

A side-loop of one or more sectors where entry and exit reduce to the same sector — a detour that returns. Path-finding shortest-route algorithms (used by enemy probes) never traverse a blister because it is never on a shortest path.

Topology rule. A subgraph B with a single vertex s such that every path from B to the rest of the region passes through s, and s has additional warps that bypass B entirely with a shorter or equal cost.

Generation parameters. - interior_size — sector count in the side-loop (default 2–4). - bypass_distance — graph distance of the alternate route around the blister (smaller means more likely to be missed by probe scripts).

In-game role. Concealed base placement that probe-based discovery cannot find. Among the rarest formations.

ESCAPE_HATCH

A dead-end sector with an additional one-way inbound warp from a non-adjacent area, routing unexpected traffic into the dead-end.

Topology rule. Vertex v with undirected degree 1 (a dead-end), plus at least one directed inbound edge (u → v) where u is not the dead-end's bidirectional neighbor.

Generation parameters. - surprise_source_distance — graph hops from the surprise inbound source to the dead-end.

In-game role. Decoy or trap. Looks like a hidden-base candidate but receives traffic via the surprise inbound. Defender beware; attacker exploit.

LOST_SECTOR

A single sector with zero sector_warps and zero WarpTunnel rows linking it to the region's main connected sub-graph — reachable only by Quantum Jump (per ADR-0070).

Topology rule. A vertex v with undirected degree 0 in the union of sector_warps and WarpTunnel against the main connected component. May rarely carry a single directed one-way edge (v → u) where u is in the main component; the inbound symmetric edge (u → v) is forbidden.

Generation parameters. - exit_warp — null (default) or { destinationSectorId: int } for the optional one-way exit (nominal 5% probability).

In-game role. The atomic dark-territory landmark — a one-sector reward for Warp Jumper investment. A surfaced exit warp lets a discoverer return without re-jumping.

LOST_CLUSTER

A single internally-connected cluster of 15–40 sectors with zero external sector_warps and zero external WarpTunnel rows. The interior sectors form a real Cluster row (with a name per ADR-0044) and standard internal proximity warps — once a player reaches any interior sector via Quantum Jump, the cluster is navigable.

Topology rule. A vertex set V (size 15–40) inducing a connected sub-graph in sector_warps, with no edge in sector_warps or WarpTunnel crossing the boundary of V against the main connected component. May rarely carry a single directed one-way edge (v → u) where v ∈ V and u is in the main component.

Generation parameters. - interior_cluster_id — UUID of the Cluster row backing the formation's interior. - exit_warp — null (default) or { sourceSectorId: int, destinationSectorId: int } (nominal 15% probability — see ADR-0070 for the chosen probability profile).

In-game role. A self-contained lost world — a cluster's worth of stations, planets, and topology hiding behind the warp-graph wall. The mid-tier dark-territory reward.

ARCHIPELAGO

A spatially-proximate group of 2–6 clusters (50–200 sectors total) connected to each other by internal warps but with zero external sector_warps and zero external WarpTunnel rows. Members are real Cluster rows; cross-cluster warps inside the formation are stamped as ordinary sector_warps edges restricted to the formation's interior.

Topology rule. A set of Cluster rows whose union vertex set V (size 50–200) induces a connected sub-graph in sector_warps (internal cluster warps plus cross-cluster warps between members), with no edge in sector_warps or WarpTunnel crossing the boundary of V against the main connected component. May carry one or two directed one-way exit edges, each anchored in a different member cluster.

Generation parameters. - member_cluster_ids — UUIDs of the Cluster rows comprising the archipelago. - cross_warp_count — total number of internal cross-cluster sector_warps edges stamped between member clusters. - exit_warps — array (may be empty) of { sourceSectorId: int, destinationSectorId: int } entries, each entry's sourceSectorId belonging to a different member cluster (nominal 25% probability of at least one; ~5% probability of two).

In-game role. The high-tier dark-territory reward — a multi-cluster sub-region only Warp Jumpers ever find. Cross-warps mean the discoverer faces real navigation choices once inside, not a single corridor.

Schema

The catalog projects onto a single SQLAlchemy model: SpecialFormation in services/gameserver/src/models/special_formation.py.

SpecialFormation table

Column Type Notes
id UUID Primary key.
region_id UUID FK → regions.id. Formations are region-scoped.
type SpecialFormationType enum One of the catalog values above.
anchor_sector_id UUID FK → sectors.id. The gateway, mouth, terminal, or pivot sector — the topologically distinguished sector for the formation.
interior_sector_ids ARRAY(UUID) Sector IDs composing the interior. Empty for single-sector formations (DEAD_END, WARP_SINK, ESCAPE_HATCH, LOST_SECTOR). For LOST_CLUSTER and ARCHIPELAGO the array carries every interior sector across the formation's member clusters.
properties JSONB Type-specific parameters. Schema in ./jsonb-schema.md#special-formation-properties.
is_discovered boolean Default false; flipped when a player first observes the topology (e.g., probes the gateway).
discovery_requirement JSONB Optional gating (Warp Jumper required, faction reputation, etc.).
generation_seed String The seed used to stamp this formation, for reproducibility and audit.
created_at DateTime
last_updated DateTime
pirate_holding_id UUID FK → pirate_holdings.id, nullable. Set when this formation hosts a pirate Outpost or Stronghold (per ADR-0047). Camp-tier holdings on open Frontier sectors do not set this field — they have no formation backing.
owner_player_id UUID FK → players.id, nullable. Set on capture per ADR-0047; transfers when the holding is captured.
owner_team_id UUID FK → teams.id, nullable. Set on team capture.

Indexes. - (region_id, type) — region-scoped lookup by type. - anchor_sector_id — reverse lookup (which formation is this sector the anchor of). - GIN on interior_sector_ids — reverse lookup (which formations contain this sector). - pirate_holding_id — reverse lookup from formation to its pirate holding (if any). - owner_player_id, owner_team_id — "what formations does this player/team own" queries.

Relationships. - region ↔ Region.formations (cascade delete-orphan from region). - anchor_sector ↔ Sector.anchored_formations. - Reverse lookup of "formations whose interior contains sector X" is not a SQLAlchemy relationship — it queries the interior_sector_ids ARRAY column via the GIN index: SpecialFormation.query.filter(SpecialFormation.interior_sector_ids.contains([sector.id])).

Anchor sector by formation type

The semantic of anchor_sector_id varies by type:

Type Anchor sector
BUBBLE, DEAD_END_BUBBLE, GOLD_BUBBLE The gateway sector (outside the interior).
TUNNEL One of the two mouth sectors (lowest-numbered chosen for stability).
DEAD_END, WARP_SINK, ESCAPE_HATCH, LOST_SECTOR The sector itself.
BACKDOOR The entry sector (the source of the one-way warp).
BLISTER The pivot sector (the single sector connecting the side-loop to the main graph).
LOST_CLUSTER The lowest-numbered sector inside the interior cluster (stable choice; not a topologically distinguished vertex since the cluster has no external attachment).
ARCHIPELAGO The lowest-numbered sector inside the lowest-numbered member cluster.

SpecialFormationType enum

BUBBLE
DEAD_END_BUBBLE
GOLD_BUBBLE
TUNNEL
DEAD_END
WARP_SINK
BACKDOOR
BLISTER
ESCAPE_HATCH
LOST_SECTOR
LOST_CLUSTER
ARCHIPELAGO

Interior clusters for lost formations

LOST_CLUSTER and ARCHIPELAGO formations require their interior sectors to also belong to one or more Cluster rows. Interior clusters are real clusters — they carry a name per ADR-0044, a type, a sector-range bound, and the standard biome / faction-influence overlay — they are simply not externally warp-connected to the main connected component of the region. A LOST_CLUSTER row's properties.interiorClusterId references its backing cluster; an ARCHIPELAGO row's properties.memberClusterIds references all of its member clusters. The standard cluster-naming pipeline runs on these clusters identically; the formation is the topology wrapper around them.

Composite formations

Several catalog entries are composites — they reference or compose other formations:

  • BUBBLE with link_tunnel_depth > 0 stamps a Bubble plus a connecting Tunnel as one logical site. The tunnel's sectors are listed in interior_sector_ids of the bubble's row; no separate TUNNEL row is created. The link tunnel is a property of the bubble, not a standalone formation.
  • BACKDOOR always references a target Bubble / Dead-End-Bubble / Dead-End via properties.target_formation_id. Generating a backdoor without an existing target is invalid.
  • DEAD_END_BUBBLE is a Bubble with the dead-end-interior invariant; in storage, type = DEAD_END_BUBBLE rather than BUBBLE so the invariant can be enforced at write time.

Discovery and visibility

Formation rows are persistent metadata — the generator writes them once and they remain in the database for the region's lifetime. The is_discovered flag governs player visibility:

  • A formation is discovered when at least one of its interior sectors has been visited and scanned by a player on that region.
  • Discovered formations appear in the player's region map and admin tools.
  • Undiscovered formations exist invisibly; their sectors remain navigable, but the fact that they form a Bubble, Blister, or other shape is not surfaced to the player UI.

This separation lets gameplay (scanners, probes, scripts) emerge organically: players discover the topology by exploring, not by reading a generator manifest.

Major Space Lanes (derived, not stamped)

The "Major Space Lane" (MSL) — 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. The generator does not produce SpecialFormation rows for MSLs. Subsystems that need the MSL set (Fed-patrol routing, traffic events, extern wipe rules) compute it from sector_warps at load time and cache the result. MSL is documented here for completeness and to clarify why it is absent from SpecialFormationType.