Skip to content

Bang Import Pipeline

Status: 🚧 Partial — The bang import pipeline is the REAL live generation path (BangImportService invokes the bang Docker sidecar, parses Universe JSON … (impl audit 2026-06-16)

Launch-target architecture. This pipeline is the launch design: galaxy generation will be owned by a separate sw2102-bang service that emits Universe JSON, and the gameserver will import that JSON via the pipeline below. Today's bridge is single-process: the admin-ui's "Bang a New Galaxy!" button posts directly to POST /admin/galaxy/generate, which calls GalaxyGenerator.generate_galaxy in the gameserver — there is no separate generator service yet, no Universe JSON crossing the boundary, and the translator code paths cited below (bang_schema.py, bootstrap_from_bang.py, commodity_catalog.py, etc.) describe where that code should live once the extraction is complete. See ./galaxy-generation.md for the live in-process generator.

Purpose

The bang import pipeline translates a sw2102-bang Universe JSON (or its equivalent rows in the bang PostgreSQL schema) into a fully-scaffolded gameserver multi-region galaxy. It is the canonical bridge between the world generator and the live game: every path that materializes generator output into the gameserver — admin-triggered import, first-time bootstrap, Alembic data fixture — invokes this pipeline. The pipeline is deterministic for a given input and target-region context, idempotent on re-run, and writes its output in a single transaction so a partial failure never leaves the gameserver schema in a half-imported state.

Worldgen-content allow-list (runtime content rejected)

Per ADR-0053 WR5 and ADR-0069, the import pipeline accepts only worldgen-content tables. Runtime-content tables in the payload are rejected.

Worldgen-importable (allow-list):

  • Region (top-level metadata for the region being imported)
  • Sector
  • Cluster (named, sector-range-bounded; faction-influence values seeded gameserver-side)
  • Zone
  • Station (the structure plus initial inventory; not its market-transaction state)
  • Planet (including initial inventory and citadel content)
  • WarpTunnel
  • sector_warps
  • SpecialFormation
  • NPCRoster (count + host-sector entries; NPCCharacter rows materialize at runtime)

Runtime-rejected (deny-list — presence triggers ERR_BANG_IMPORT_INCLUDES_RUNTIME_CONTENT listing the offending tables):

  • MessageBeacon
  • NPCCharacter, NPCDeathLog
  • MarketTransaction (enhanced_market_transactions), MarketPrice, PriceHistory
  • CombatLog, CombatStats
  • BountyClaim, BountyHunterMembership
  • ARIAObservationLog, ARIAPersonalMemory, ARIAMarketIntelligence, ARIAExplorationMap, ARIAQuantumCache
  • PirateKillLog, PirateHolding
  • OutlawBase (lodging structure is runtime-only; worldgen-time pre-seeding in Phase 12.6 creates these via the gameserver, not via bang import)
  • Player, User, PlayerCentralBankAccount, Reputation, TeamMembership
  • All other audit-trail tables

The pipeline validates both presence (every worldgen table is complete and consistent — already covered by Phase 13 invariants per the canonicality contract below) and absence (no runtime-table rows in the payload). Rejection lists every offending table so the bang-side debugger can identify which tables were inadvertently included.

Canonicality contract

Per SK20 in ADR-0050 and ADR-0069, the gameserver is canonical for runtime behavior. Bang produces fully-formed region snapshots but cannot ship output the gameserver wouldn't accept. The contract:

  1. Bang produces a Universe JSON dataset — clusters, special formations, station/planet inventories, citadel content, and NPC rosters all included.
  2. Bang internally enforces the same invariants Phase 13 enforces (notably ADR-0046's "no WARP_SINK inside a BUBBLE") so output is correct-by-construction.
  3. Import endpoint runs the gameserver Phase 13 validation gate against the imported content. Validation logic is factored into services/gameserver/src/services/galaxy_validation.py and imported by both sides.
  4. Rule violation → reject the import with ERR_BANG_VALIDATION_FAILED listing the failing invariants.
  5. Successful import → content commits as if Phase 13 had passed natively in the gameserver.

This closes the equivalence-drift question: there is one validation surface, factored to be reusable, and bang submits to it. Bang's own internal validation is allowed to be stricter (catch issues at generation time before producing JSON) but never looser than the gameserver's.

The contract is load-bearing on Universe.version — bang and gameserver release in lockstep on contract bumps. Adding a field to the bang payload, changing a field's shape, or relocating an invariant from one side of the boundary to the other is a contract change and bumps the version.

Inputs

The pipeline accepts one of two equivalent input shapes:

  • Universe JSON as emitted by sw2102-bang/src/serialize.ts:universeToJSON. The sectors map is rehydrated from the keyed object on read.
  • bang schema rows — a bang.universes row plus its dependent bang.sectors, bang.warps, bang.clusters, bang.special_formations, bang.ports, bang.planets, bang.nebulae, bang.nav_hazards, bang.npc_rosters, bang.special_locations rows. Used by Path B (bootstrap script) when the generator has run in service mode.

Per ADR-0069, commodity-pricing and quantity constants are passed into bang as part of its generation request — the gameserver owns balance tuning, but bang's deterministic seeding pass executes inside bang. Initial inventory values therefore arrive in the payload from bang already populated; the import pipeline does not re-seed them.

In addition to the bang payload, the caller supplies:

  • Target region context. Which gameserver Region is being created from this Universe. One of:
  • central_nexus — bootstrap of the universal hub. Forces 5,000 sectors, single EXPANSE zone, 20-cluster overlay.
  • terran_space — bootstrap of the starter region. Forces 300 sectors, three zones (Fed/Border/Frontier), governance autocracy at 2% tax.
  • player_owned — region purchased by a player. Sector count and tier come from the subscription; the owner's User.id must be supplied.
  • Optional admin overrides. A small dict of overrides applied after the per-region defaults: custom faction_influence weights, custom governance_type, custom tax_rate, custom special_features. Overrides go through the same validation as the defaults.
  • Idempotency key. A stable identifier for this import attempt. Default: Universe.seed combined with Universe.config hash. Used to detect re-runs of the same import.

The pipeline does not read live game state (no players, no transactions, no live presence); it only reads the bang payload, the Region row, and the optional overrides.

Process

The pipeline runs as a single database transaction with the numbered steps below. Each step's preconditions are validated before the next step begins. Per ADR-0069, the pipeline is narrower than a content-derivation pipeline: bang emits clusters, formations, station/planet inventories, citadel content, and NPC rosters as part of the payload, and the translator's job is to validate, scaffold, glue, and translate, not to derive.

1. Validate input

Before any write, the validator (services/gameserver/src/services/bang_schema.py — target) checks:

  • Universe.version is in the supported version allowlist. Unknown versions abort with a structured error; no rows are written. The allowlist is a constant in the validator module and is bumped in lockstep with bang releases.
  • Universe.totalSectors === Object.keys(Universe.sectors).length — the declared count matches the actual sector map size. Drift aborts the import.
  • Every Warp.from and Warp.to exists in Universe.sectors. Orphaned warps are logged and dropped (non-fatal).
  • Universe.fedspaceSectors is a sorted contiguous range starting at sector 1. Length equals config.fedspaceSize.
  • Universe.specialLocations references only sector IDs present in Universe.sectors.
  • Universe.clusters partitions [1, totalSectors] exactly with no gaps and no overlaps. For Nexus imports, the cluster list matches the canonical 20-name overlay in ./central-nexus-clusters.md.
  • Universe.specialFormations references only sector IDs present in Universe.sectors. The 9-type catalog is enforced; no WARP_SINK interior intersects any BUBBLE / DEAD_END_BUBBLE / GOLD_BUBBLE interior (cross-check of the invariant bang itself enforced at generation time).
  • Universe.npcRosters references only sector IDs present in Universe.sectors. Roster shapes (kind, factionCode, targetCount, hostSectorId, namePool) match the schema in ../FEATURES/gameplay/police-forces.md.

Validation failures that abort the import never produce partial writes; the transaction is never opened.

2. Create or upsert the Galaxy row

The Galaxy is a singleton; the pipeline reads-or-creates by name. The row stores the bang Universe.seed and Universe.config in Galaxy.density.resource_distribution and a translator-specific bang_universe_id extension on Galaxy.statistics for idempotency tracking.

  • name from caller; default "Sectorwars 2102" for the singleton.
  • max_sectors set to the sum of all regions the operator plans to import (caller hint; default 10,000).
  • expansion_enabled = true, resources_regenerate = true, warp_shifts_enabled = true, default_turns_per_day = 1000.
  • statistics, density, state, events, combat_penalties, economic_modifiers JSONBs initialized from services/gameserver/src/core/galaxy_defaults.py (target).
  • statistics.bang_universe_id set to the import's idempotency key. If a Galaxy row already exists with the same key and identical config, the pipeline returns early as a no-op.

3. Create the Region row

Exactly one Region is created per pipeline invocation. The region_type, governance defaults, and starter ship come from the target region context:

Context region_type governance_type tax_rate total_sectors subscription_tier
central_nexus central_nexus autocracy 0.00 5000 n/a (no owner)
terran_space terran_space autocracy 0.02 300 n/a (no owner)
player_owned player_owned from override or autocracy from override or 0.10 from subscription tier from subscription tier

The Region's language_pack, aesthetic_theme, traditions, social_hierarchy, trade_bonuses JSONBs default to empty objects and are populated post-import by the regional governance flow.

For initial bootstrap, the operator runs the pipeline twice: once with central_nexus against a 5,000-sector bang Universe, then again with terran_space against a 300-sector bang Universe. The two imports produce distinct Region rows under the same Galaxy.

4. Partition zones

Zone partitioning is driven entirely by the target region context, not by anything in the bang payload (bang has no zone concept):

  • central_nexus — one Zone row: zone_type = EXPANSE, name = "The Expanse", start_sector = 1, end_sector = 5000, policing_level = 3, danger_rating = 6.
  • terran_space and player_owned — three Zone rows split by sector number:
  • FEDERATION — first 33% of sectors — policing_level = 9, danger_rating = 1.
  • BORDER — middle 34% — policing_level = 5, danger_rating = 4.
  • FRONTIER — last 33% — policing_level = 2, danger_rating = 8.

The split-percentage rounding favours FEDERATION on the low end and FRONTIER on the high end so that start_sector/end_sector ranges are contiguous and cover the full sector range with no gaps.

5. Import cluster rows

Per ADR-0069, clusters arrive in the bang payload as named, sector-range-bounded entities; the translator imports them as-is rather than deriving them from sector totals. For each Universe.clusters[i]:

  • name ← bang.cluster.name (AI-generated per ADR-0044).
  • type ← bang.cluster.type (one of STANDARD, RESOURCE_RICH, POPULATION_CENTER, TRADE_HUB, MILITARY_ZONE, FRONTIER_OUTPOST, CONTESTED, SPECIAL_INTEREST).
  • Sector-range membership is stored on Sector.cluster_id (set in step 7); the cluster's own range bounds are kept in Cluster.special_features for diagnostic queries.
  • stats JSONB initialized with zeros; recomputed in step 16.
  • warp_stability, economic_value, is_discovered, is_hidden, (x_coord, y_coord, z_coord) ← bang-emitted values where present, otherwise default per cluster type.
  • faction_influence ← not set here; seeded gameserver-side in step 15 from the per-zone profile (faction enum is gameserver-side state).

For Nexus imports, bang emits the canonical 20-cluster overlay specified in ./central-nexus-clusters.md: 20 named clusters in declaration order, 250 sectors per cluster, fixed types (8 TRADE_HUB / 4 POPULATION_CENTER / 8 STANDARD), 5×4 grid layout. The translator validates the overlay matches the canonical list (count, names, sector-range partition) and rejects mismatches.

6. Import special formations

Per ADR-0069, SpecialFormation rows are stamped by bang during generation, between proximity-warp placement and long-distance-tunnel placement, and arrive in the payload ready to import. For each Universe.specialFormations[i]:

  • type ← bang formation.type (one of the 12-type catalog: BUBBLE, DEAD_END_BUBBLE, GOLD_BUBBLE, TUNNEL, DEAD_END, WARP_SINK, BACKDOOR, BLISTER, ESCAPE_HATCH, plus the lost-formation set LOST_SECTOR / LOST_CLUSTER / ARCHIPELAGO added in ADR-0070). The import logic is unchanged for the new types — still a row-copy from payload to gameserver table; the enum grew, the algorithm did not.
  • anchor_sector_id ← UUID of the gameserver Sector at bang formation.anchorSectorId.
  • interior_sector_ids ← ARRAY of UUIDs from the imported sector rows.
  • properties JSONB ← bang formation.properties (1:1 copy; type-specific keys per ../DATA_MODELS/special-formations.md).
  • region_id ← the Region created in step 3.
  • is_discovered = false, discovery_requirement ← default per formation type.
  • generation_seed ← Universe.seed (audit trail).

The translator does not stamp formations or rerun the stamping algorithm — bang emits the rows correct-by-construction, including the ADR-0046 invariant ("no WARP_SINK inside a BUBBLE"). Phase 13 cross-checks the invariant on import.

7. Assign sectors to cluster + zone

Each bang Sector becomes a gameserver Sector row. The translator iterates sectors in numeric order and assigns:

  • sector_id (integer) ← bang Sector.id.
  • sector_number (nullable integer) ← Sector.id for Nexus sectors so admin queries can use it; null elsewhere.
  • name ← bang Sector.beacon if non-null, else generated as "Sector {id}".
  • cluster_id ← the cluster created in step 5 that owns the sector's number range.
  • zone_id ← the zone created in step 4 that contains the sector's number, or null if no zone covers it.
  • region_id ← the Region created in step 3.
  • security_level, development_level, traffic_level ← drawn uniformly from the cluster type's profile (Nexus, biased by TRADE_HUB / POPULATION_CENTER / STANDARD) or the zone profile (Terran/player-owned). Zone defaults: FEDERATION (8/7/7), BORDER (5/5/5), FRONTIER (2/3/3).
  • is_discovered ← bang Sector.explored (the bang generator marks fedspace and special-location sectors as discovered).
  • (x_coord, y_coord, z_coord) — version-dependent:
  • Universe.version parses as >= 1.1.0 (including pre-release suffixes like 1.1.0-pre.0): consume bang Sector.position.{x, y, z} directly. Bang emits these as integers scaled by 10000 to match the gameserver's Integer not null schema (DATA_MODELS/galaxy.md); translator copies as-is, no rescale or rounding.
  • Universe.version is 1.0.0: bang did not emit positions. Interpolate from the Hilbert packing used in step 5 (legacy synthesis path). The translator must NOT mix the two paths within a single import.
  • radiation_level = 0.0, hazard_level = 0 unless overridden by step 8.
  • resources ← default JSONB from DATA_MODELS/jsonb-schema.md#sectorresources. Asteroid yields stay zero unless the cluster type is RESOURCE_RICH, in which case the translator rolls non-zero ore / precious_metals / radioactives from the cluster's resource_distribution.
  • defenses, players_present, ships_present, active_events, nav_beacons, nav_hazards ← defaults from DATA_MODELS/jsonb-schema.md.
  • controlling_faction = null.

8. Mark sector special types

Sector types are assigned in two passes:

  1. Nebula pass. Every bang Sector.nebula != null becomes a gameserver Sector with type = NEBULA. The bang nebula's type and density are translated through the table in the appendix and written into the owning Cluster.nebula_properties JSONB (the gameserver carries nebula classification at the cluster level for atmospheric/colour metadata; the per-sector Sector.type = NEBULA flag is what gates sensor/combat effects).
  2. Special-type pass. From the remaining sectors, 15% are flagged as special types. Per-cluster regional profile drives the distribution:
  3. RESOURCE_RICH clusters → 60% ASTEROID_FIELD, 40% STANDARD.
  4. MILITARY_ZONE clusters → 80% STANDARD, 10% RADIATION_ZONE, 10% WARP_STORM.
  5. FRONTIER_OUTPOST clusters → 70% STANDARD, 15% BLACK_HOLE, 15% RADIATION_ZONE.
  6. All others → 85% STANDARD, 15% split evenly across ASTEROID_FIELD, RADIATION_ZONE, WARP_STORM, BLACK_HOLE.

The special-type roll is seeded from Universe.seed and the sector number so re-imports produce identical assignments.

9. Identify isolated clusters

After all sectors are written but before warps are translated, the pipeline runs a graph traversal over the bang warp list to compute connected components. A cluster is is_isolated = true when none of its sectors is reachable from a fedspace sector via natural warps.

Target: 10–20% of clusters are isolated. If the natural traversal yields fewer isolated clusters, the translator does not synthesize isolation; the bang seed determines reachability and the gameserver inherits it. If the natural traversal yields more than 25%, a warning is logged but the import proceeds — the operator should re-roll the bang seed if isolation is undesirable.

Sectors in isolated clusters require a Warp Jumper Quantum Jump to reach (see ../FEATURES/galaxy/sectors.md#quantum-jump-warp-jumper); the movement service reads Cluster.is_isolated to gate movement. (is_isolated is stored in Cluster.special_features as the string "isolated" since Cluster does not carry a dedicated boolean column.)

10. Translate warps

Each bang Warp{from, to, oneWay} becomes one row in the sector_warps association table:

  • source_sector_id ← UUID of from.
  • destination_sector_id ← UUID of to.
  • is_bidirectional = !oneWay.
  • turn_cost = 1 (default; bang has no turn-cost concept).
  • warp_stability = 1.0 (default; degraded stability is a runtime concern).

When a bang warp connects sectors more than N numbers apart (heuristic threshold: max(50, totalSectors / 20)), the pipeline additionally creates a WarpTunnel row:

  • type = NATURAL, status = ACTIVE, is_bidirectional = !oneWay. (type = ARTIFICIAL with created_by_player_id = NULL is reserved for engineered low-sector bridges; bang's procedural warps map to NATURAL.)
  • stability = 1.0, stability_enum = STABLE.
  • properties JSONB initialized from DATA_MODELS/jsonb-schema.md#warptunnelproperties with traversal_cost = 1, discovered = true, affected_by_storms = false.
  • source_endpoint / destination_endpoint JSONBs populated with the source and destination sector/cluster/region IDs and coordinates.

The sector_warps row is the lightweight association used by routing; the WarpTunnel row carries the heavier metadata (lifecycle, decay, discovery). Both reference the same sector pair.

11. Translate ports → stations

Each bang Port becomes a gameserver Station with a co-created Market and per-commodity MarketPrice rows. Mapping:

  • name ← bang Port.name.
  • sector_uuid ← UUID of the bang sector hosting the port.
  • sector_id ← integer bang sector ID (denormalized for read paths).
  • station_class ← StationClass.CLASS_<n> for n = 0..8. Bang class 0 (Stardock-only) maps to gameserver CLASS_0; bang classes 1–8 map directly. Gameserver classes 9–11 are reserved for higher-tier stations created post-import (Nova / Luxury / Advanced Tech Hub).
  • type (enum StationType) ← derived from class via services/gameserver/src/core/station_class_map.py (target): bang class 1 → MINING, class 2 → INDUSTRIAL (agricultural), class 3 → INDUSTRIAL, class 4–7 → TRADING, class 8 → TRADING with is_quest_hub = true, class 0 → DIPLOMATIC.
  • status = OPERATIONAL, size = 5, faction_affiliation from the cluster's controlling_faction.
  • commodities JSONB ← see commodity expansion below.
  • trader_personality JSONB ← sampled from the default-distribution pool. Pool: 40% BORDER, 25% FEDERATION, 20% FRONTIER, 10% LUXURY, 5% BLACK_MARKET. Stations in FEDERATION zones bias toward FEDERATION; in FRONTIER zones bias toward FRONTIER.
  • services, defenses, acquisition_requirements JSONBs ← class-appropriate defaults from services/gameserver/src/core/station_defaults.py (target).

Commodity expansion (3 → 8). Bang carries the three classic commodities (fuel_ore, organics, equipment) under each port's commodities block, where each commodity's quantity field is the initial seeded value (per ADR-0069, seeded by bang's deterministic pass using gameserver-supplied pricing constants). The translator maps the 3 classic commodities to the 8-commodity catalog:

  • ore ← bang fuel_ore (rename: bang's fuel_ore is the "raw mineral" classic commodity, mapped to gameserver ore per Station.commodities). quantity, capacity, regenRate all from bang's commodities.fuel_ore.
  • organics ← bang organics (direct). quantity, capacity, regenRate from bang's commodities.organics.
  • equipment ← bang equipment (direct). quantity, capacity, regenRate from bang's commodities.equipment.
  • fuel, luxury_goods, gourmet_food, exotic_technology, colonists ← seeded from services/gameserver/src/core/commodity_catalog.py (target) using the class-specific defaults already documented in Station.commodities. The bang generator does not produce stocks for these five today; they default to the catalog's class-appropriate quantity/capacity/base_price values. (Per ADR-0062 E-D2 the design target is for bang to cover the full set; until that contract bump lands, these five are translator-synthesized.)

After the JSONB is written, the pipeline calls Station.update_commodity_trading_flags() and Station.update_commodity_stock_levels() to apply the buys/sells and stock pattern from get_trading_pattern() for the assigned StationClass.

A Market row is created per station with the standard volatility defaults; one MarketPrice row is inserted per commodity-station pair.

12. Translate planets

Each bang Planet becomes a gameserver Planet row in the same sector:

  • name ← bang Planet.name.
  • sector_uuid / sector_id ← bang sector hosting the planet.
  • type ← gameserver PlanetType per the appendix table.
  • status = UNINHABITABLE unless the planet is at a special location (Terra → DEVELOPED with population hub).
  • owner_id = null, population = 0, colonists = bang.colonists, fuel_ore/organics/equipment from bang's flat planet fields (bang.fuelOre, bang.organics, bang.equipment — per ADR-0069, these are the initial seeded values).
  • resources JSONB initialized from the gameserver default; bang's planetary stockpiles seed the integer columns directly.
  • production JSONB ← {"fuel": 0, "organics": 0, "equipment": 0, "research": 0}.
  • Citadel: if bang Planet.citadel is non-null, write citadel_level = bang.citadel.level, citadel_drone_capacity = bang.citadel.droneCapacity, and citadel_safe_contents = bang.citadel.safeContents (per ADR-0069 bang emits the citadel state including drone capacity and safe contents). Otherwise leave defaults at 0.

13. Special locations

Each bang SpecialLocation is materialized into the gameserver via location-specific rules:

  • Terra — placed at the target region's Capital Sector (Region.capital_sector_number). For Terran Space the Capital is fixed at sector 1; for the Nexus the Capital is anchored in the Gateway Plaza cluster; for player regions the Capital was randomized within the Federation Zone before the import reaches this step. The host Sector gets special_features = ["terra", "homeworld"]. A Planet row of type TERRA with status = DEVELOPED, large population, max citadel level, and ownership defaulting to the Terran Federation faction is created.
  • Stardock — Class-0 Station named "Stardock" with is_quest_hub = true, is_player_ownable = false, all services enabled. Hosting sector gets special_features = ["stardock"].
  • Rylan / Alpha Centauri / Fringe homeworld — host Sector gets special_features containing the location slug; if the location is canonically a homeworld, an associated Planet of the appropriate PlanetType is created with faction ownership.
  • SpaceDock anchor — for Nexus imports, the pipeline ensures the Capital Sector (Gateway Plaza cluster) carries the SpaceDock special feature regardless of bang output. If bang did not place SpaceDock at the Capital, the translator upserts the SpaceDock station and demotes any conflicting bang-placed station to a normal port.

All special-location upserts are idempotent on (region_id, special_features contains <slug>).

13.5. Import NPC rosters

Per ADR-0069 and ../FEATURES/gameplay/police-forces.md, bang emits NPCRoster rows for both the Federation Marshal squads (Phase 12.5a — region rosters, non-Nexus only) and the Nexus Sentinel Corps (Phase 12.5b — Nexus rosters), plus pirate-tier rosters for Phase 12.6 holdings. The translator imports them as-is:

  • kind ← bang roster.kind (e.g., federation_marshal, nexus_sentinel, pirate_lord, pirate_captain, pirate_enforcer).
  • faction_code ← bang roster.factionCode.
  • target_count ← bang roster.targetCount.
  • host_sector_id ← UUID of the gameserver Sector at bang roster.hostSectorId.
  • name_pool ← bang roster.namePool (JSONB).
  • region_id ← the Region created in step 3.

For Nexus imports, the translator additionally sets Sector.is_nexus_protected = true on the Capital sector and the Gateway Plaza cluster's sectors (per ../FEATURES/gameplay/police-forces.md Phase 12.5b).

The translator does not materialize NPCCharacter rows. Phase 12.5c (npc_scheduler.bootstrap_region(region_id)) runs as a post-commit hook (see step 17 below) outside the worldgen transaction so a roster-spawn failure doesn't block region creation.

14. Fedspace zone mapping

Bang's fedspaceSectors array (sector IDs 1 through config.fedspaceSize) drives Federation security in the gameserver:

  • Each fedspace sector's Sector.security_level = 10 (overrides whatever was rolled in step 7).
  • Each fedspace sector is assigned to the FEDERATION zone for Terran/player-owned regions, or to the EXPANSE zone for Nexus.
  • The sector's controlling_faction is set to "terran_federation".

For the Nexus (which has only one zone), fedspace sectors retain EXPANSE zone but receive maximum security level — the EXPANSE zone's policing/danger ratings are unchanged.

15. Faction influence seeding

Galaxy.faction_influence and per-Cluster.faction_influence JSONBs are seeded from a per-zone-type default profile in services/gameserver/src/core/faction_profiles.py (target):

Zone type terran_federation mercantile_guild frontier_coalition astral_mining_consortium nova_scientific_institute fringe_alliance
FEDERATION 80 15 0 2 2 1
BORDER 30 30 20 10 5 5
FRONTIER 5 10 60 10 5 10
EXPANSE 25 25 15 15 10 10

Each row sums to 100. dominant_faction is computed as argmax. Admin overrides applied at step 3 are merged into the cluster-level influence post-seed (with renormalization to keep the sum at 100).

The Galaxy.faction_influence row is the area-weighted average of all clusters in the galaxy.

16. Recompute Galaxy aggregates

The final step calls Galaxy.update_statistics() (or its equivalent target service method) to recompute:

  • Galaxy.statistics.total_sectors, discovered_sectors, station_count, planet_count, warp_tunnel_count, genesis_count (last is 0).
  • Galaxy.density.station_density, planet_density, one_way_warp_percentage, resource_distribution.
  • Galaxy.state.exploration_percentage (≈ count of is_discovered sectors / total_sectors).
  • Per-Cluster.stats JSONB values (total_sectors, populated_sectors, resource_value, etc.).

The transaction is committed at the end of step 16. If any earlier step raised, the entire transaction is rolled back and the gameserver schema returns to its pre-import state.

17. Post-commit NPC bootstrap (out-of-transaction hook)

After the worldgen transaction commits, the pipeline fires a one-time npc_scheduler.bootstrap_region(region_id) call (Phase 12.5c per ../FEATURES/gameplay/police-forces.md) that materializes the initial roster of named NPCCharacter rows from each NPCRoster.name_pool. This step happens outside the worldgen transaction so a roster-spawn failure does not block region creation; if it fails, NPC scheduler Loop B picks up the slack on its next 10-minute tick.

bootstrap_region is idempotent on (region_id, roster_id) — a second invocation finds the already-spawned characters and returns without re-spawning.

Outputs / state changes

A successful import inserts (or upserts):

  • 1 Galaxy row (upserted by name; statistics recomputed).
  • 1 Region row (always inserted; the same Universe imported into a different region context produces a different Region row).
  • 1 to ~3 Zone rows depending on region context (1 for Nexus, 3 for Terran/player-owned). The Nexus's 20-cluster overlay lives in the Cluster rows, not as additional zones.
  • C Cluster rows where C = Universe.clusters.length (Nexus = 20, Terran ≈ 6, player-owned scaled per bang's emitted overlay).
  • F SpecialFormation rows where F = Universe.specialFormations.length.
  • N Sector rows where N = Universe.totalSectors.
  • M sector_warps rows where M = Universe.warps.length.
  • 0 to M' WarpTunnel rows where M' is the count of long-distance warps (typically 5–15% of warp count).
  • K Station rows where K = number of bang sectors with a non-null port.
  • K Market rows (one per Station).
  • K × 8 MarketPrice rows (one per Station per commodity).
  • J Planet rows where J = sum of bang.Sector.planets.length across all sectors.
  • R NPCRoster rows where R = Universe.npcRosters.length.
  • S Sector.special_features updates for each bang SpecialLocation.

Out-of-transaction (step 17, post-commit):

  • 0 to ΣR.target_count NPCCharacter rows materialized by npc_scheduler.bootstrap_region.

Side effects:

  • Galaxy.statistics, Galaxy.density, and per-Cluster.stats JSONBs are recomputed.
  • No realtime-bus events are emitted during import. The import is a bulk operation; the bus is signalled once at completion (galaxy.imported event) so dashboards can refresh, but no per-row events fire.
  • No player/team/ship rows are touched.
  • No reputation, market-transaction, or audit-log rows are written.

The transaction commits or aborts atomically.

Invariants

  • Sector count match. Total sectors written equals Universe.totalSectors. If the count drifts during step 7 (a sector failed to insert), the transaction aborts.
  • Cluster membership. Every Sector belongs to exactly one Cluster. Sector.cluster_id is non-null and references a Cluster within the same Region.
  • Region membership. Every Sector belongs to exactly one Region. Sector.region_id matches the Region created in step 3 for every Sector inserted by this run.
  • Zone membership. Every Sector either belongs to one Zone whose sector range contains the sector's number, or Sector.zone_id is null only when no zone covers the sector's range (which only happens if the operator passes a region-context that omits zones — not a default).
  • Nexus cluster sum. For Nexus imports, the 20 clusters cover exactly 5,000 sectors with no gaps and no overlap. Bang's emitted cluster list must match the canonical 20-name overlay; mismatches abort at step 1.
  • Formation invariant. No WARP_SINK formation interior intersects any BUBBLE / DEAD_END_BUBBLE / GOLD_BUBBLE interior (per ADR-0046). Bang enforces this internally; the translator cross-checks at step 1 and Phase 13 cross-checks again.
  • Roster shape. Every NPCRoster.host_sector_id resolves to a sector in the same region; target_count >= 1; name_pool is non-empty.
  • Warp referential integrity. Every sector_warps row references two existing sectors; orphaned warps are dropped at validation time, never written.
  • Schema version. Universe.version is in the supported allowlist; no row is written for an unknown version.
  • Idempotency. Re-running the pipeline on the same Universe.seed + config against the same Region context is a no-op. Detection is via Galaxy.statistics.bang_universe_id (or an equivalent translator-private extension).
  • Faction influence sums. Per-Cluster faction_influence numeric values sum to 100; dominant_faction matches argmax.
  • Determinism. Two runs with the same Universe.seed, config, and target region context produce identical row contents. No random.random() calls outside seeded RNG.
  • Single transaction. All writes occur in one transaction; partial failure leaves zero rows.

Failure modes

  • Version mismatch. Universe.version not in the allowlist → abort at step 1; structured error includes the supplied version and the allowlist. No partial writes.
  • Sector count drift. Universe.totalSectors !== Object.keys(sectors).length → abort at step 1.
  • Orphaned warps. Warp references a missing sector → log + skip the warp; import continues. The skipped warp is reported in the import summary.
  • Faction profile missing. Zone type has no entry in faction_profiles.py → fall back to the neutral profile (each faction at 16-17, sum to 100, dominant_faction = "contested").
  • Cluster generation oversampling. Standard distribution rolls produce too few STANDARD clusters to satisfy invariants → fall back to STANDARD for any cluster that would have been a special type.
  • Idempotency mismatch. A Galaxy.statistics.bang_universe_id already exists with a different config hash → abort with explicit "use --force-reimport to override" hint. The --force-reimport flag deletes the prior Galaxy / Region / Cluster / Sector cascade and re-runs.
  • Cluster sum mismatch. Bang's emitted cluster list does not partition [1, totalSectors] exactly (gap, overlap, or — for Nexus — name/count drift from the canonical 20-cluster overlay) → abort at step 1.
  • Formation invariant violation. Bang emitted a formation set that violates ADR-0046 ("no WARP_SINK inside a BUBBLE") → abort at step 1 with the offending (sink_id, bubble_id) pair listed.
  • Roster validation failure. A roster references a missing host sector or carries an empty name_pool → abort at step 1.
  • Special location collision. Two different special locations claim the same sector → abort with the conflicting location list.
  • Database transaction failure. Any underlying constraint violation → entire transaction rolls back; the operator sees the underlying SQL error in the structured response.
  • Long-running import. Imports of full 5,000-sector Nexus universes can take 60–120 seconds; the operator must run the pipeline outside the realtime request path (see the operations doc for CLI / async-job invocation modes).

Source map

Concern Path
Translator entry point services/gameserver/scripts/bootstrap_from_bang.py (target)
Admin trigger services/gameserver/src/api/routes/admin/galaxy.py:POST /admin/galaxy/import-bang (target)
Region/Zone/Cluster scaffolding services/gameserver/src/services/galaxy_bootstrap_service.py (target)
Cluster overlay validator (Nexus) services/gameserver/src/services/nexus_generation_service.py:_validate_nexus_cluster_overlay (target — bang emits the overlay; gameserver validates it matches the canonical 20-name list)
NPC scheduler bootstrap hook services/gameserver/src/services/npc_scheduler.py:bootstrap_region (target)
Commodity catalog defaults services/gameserver/src/core/commodity_catalog.py (target)
Station class → type map services/gameserver/src/core/station_class_map.py (target)
Station defaults (services, defenses, acquisition) services/gameserver/src/core/station_defaults.py (target)
Faction influence profiles services/gameserver/src/core/faction_profiles.py (target)
Galaxy / Region / Cluster JSONB defaults services/gameserver/src/core/galaxy_defaults.py (target)
Bang JSON schema validator services/gameserver/src/services/bang_schema.py (target)
Bang DB reader (Path B) services/gameserver/src/services/bang_db_reader.py (target)
Idempotency tracker services/gameserver/src/services/galaxy_bootstrap_service.py:_already_imported() (target)

Generator-side reference paths (not written by this pipeline; cited for context):

  • sw2102-bang/src/types.ts — Universe, Sector, Warp, Port, Planet, Nebula, NavHazard, SpecialLocation interfaces.
  • sw2102-bang/src/config.ts — BigBangConfig, DEFAULT_CONFIG, resolveConfig() clamps.
  • sw2102-bang/src/bigbang.ts — generator orchestrator.
  • sw2102-bang/src/serialize.ts — universeToJSON / universeFromJSON.
  • sw2102-bang/db/init.sql — bang-side DB schema (used by Path B).

Appendix A — Bang Commodity → gameserver commodity

Bang carries three commodities in Port.commodities. The gameserver Station.commodities JSONB has eight keys. The 3 → 8 expansion is:

Bang commodity Gameserver key Translation
fuel_ore ore Direct rename. Bang's "fuel ore" is the classic raw mineral; the gameserver's ore JSONB key carries the same role. Quantity, capacity, regen rate copied.
organics organics Direct. Quantity, capacity, regen rate copied.
equipment equipment Direct. Quantity, capacity, regen rate copied.
(synthesized) fuel Defaulted from commodity_catalog.py: quantity = 1500, capacity = 4000, base_price = 12, production_rate = 120, price_variance = 15.
(synthesized) luxury_goods Defaulted: quantity = 200, capacity = 800, base_price = 100, production_rate = 20, price_variance = 40.
(synthesized) gourmet_food Defaulted: quantity = 150, capacity = 600, base_price = 80, production_rate = 15, price_variance = 35.
(synthesized) exotic_technology Defaulted: quantity = 50, capacity = 200, base_price = 250, production_rate = 5, price_variance = 50.
(synthesized) colonists Defaulted: quantity = 100, capacity = 500, base_price = 50, production_rate = 10, price_variance = 10.

The bang PortCommodityState.action (B/S) maps to buys/sells flags on the corresponding gameserver commodity. After the JSONB is written, Station.update_commodity_trading_flags() sets the per-class trading pattern (overriding the per-commodity flags for the five synthesized commodities so the station class drives the pattern, not the bang JSON).

The synthesized commodities' buys/sells flags are set entirely by get_trading_pattern() for the station's class. Stations carry stock for commodities they neither buy nor sell when the catalog defaults reflect typical free-market presence — the per-class trading pattern decides whether that stock is offered at the trade UI.

Appendix B — Bang NebulaeType → gameserver nebula classification

Bang emits two nebula types (normal and magnetic) with a per-nebula density value (1–100). The gameserver carries six named nebula classifications. The mapping is monotonic: high bang density / magnetic type maps to high quantum-field gameserver classifications (Crimson end); low density / normal type maps to low quantum-field classifications (Obsidian end). magnetic is uniformly higher-field than normal.

Bang NebulaeType Density range Gameserver classification Field strength Secondary effect
normal 1 – 33 obsidian 0–20 Sensor masking; severe warp disruption
normal 34 – 66 amber 20–40 Hull damage hazard while traversing
normal 67 – 100 violet 40–60 Rare-spawn bias (exotic encounters)
magnetic 1 – 33 emerald 50–70 Production bonus on adjacent planets
magnetic 34 – 66 azure 60–80 Stable warp formation in-cluster
magnetic 67 – 100 crimson 80–100 Mild combat advantage; highest shard yield

Selection is deterministic on (type, density) — zone bias on the gameserver side comes from the _populate_sectors_with_nebulae weighting in galaxy_service.py (see ../FEATURES/galaxy/generation.md) and is independent of bang's mapping. A bang magnetic nebula with density 90 becomes crimson regardless of which zone its host sector lands in.

The chosen classification is written into the owning Cluster.nebula_properties JSONB:

{
  "primary_nebula": "<classification>",
  "density": <bang_density>,
  "sectors": [<sector_numbers>],
  "effects": {
    "sensor_penalty": <derived>,
    "combat_modifier": <derived>,
    "warp_stability_penalty": <derived>
  }
}

The per-Sector flag is the binary Sector.type = NEBULA (carried in the existing sector_type enum). The classification colour does not appear on the Sector row; it is read from the owning Cluster's JSONB by the UI and combat resolver.

Appendix C — Bang PlanetType → gameserver PlanetType

Bang PlanetType Gameserver PlanetType
barren BARREN
earth TERRA
mountainous MOUNTAINOUS
oceanic OCEANIC
glacial ICE
volcanic VOLCANIC

Gameserver-only PlanetType values (DESERT, GAS_GIANT, JUNGLE, ARCTIC, TROPICAL, ARTIFICIAL) are not produced by the bang generator. They reach the universe through gameserver-side sources rather than the bang import: DESERT is a Genesis-rollable terraforming target; JUNGLE, ARCTIC, and TROPICAL are colonizable worlds the gameserver generates (and arrive via special encounters or operator-seeded sectors); GAS_GIANT is a real body that cannot be landed on or claimed. ARTIFICIAL is a reserved enum value with no generation path.

Translation defaults set status = UNINHABITABLE and habitability_score = 0 for all imported planets. The Terra special location is the one exception: its planet is upgraded to status = DEVELOPED, habitability_score = 100, population = 10_000_000_000, and full citadel during step 13.

Appendix D — Bang SpecialLocationType → gameserver Sector flags

Bang SpecialLocationType Sector special_features Additional state
terra ["terra", "homeworld"] Planet of type TERRA, status = DEVELOPED; faction owner terran_federation; placed at the region's Capital Sector
stardock ["stardock"] Station of class CLASS_0 named "Stardock"; is_quest_hub = true, is_player_ownable = false; all services enabled
rylan ["rylan", "homeworld", "alien"] Planet of type OCEANIC; faction owner nova_scientific_institute
alpha_centauri ["alpha_centauri", "stellar_landmark"] Planet of type TERRA with reduced habitability; no fixed faction
fringe_homeworld ["fringe_homeworld", "homeworld", "hostile"] Planet of type BARREN; faction owner fringe_alliance; sector controlling_faction = "fringe_alliance"

Special features are appended to the Sector's existing special_features ARRAY rather than replaced, so a sector that is both a Stardock host and inside the Fringe Alliance homeworld system would carry both slugs. (In practice, bang places these locations at distinct sectors.)

The SpaceDock anchor — described in step 13 — is not a bang SpecialLocationType. It is a gameserver-only convention for the Nexus Region, idempotently upserted into the Capital Sector (Gateway Plaza cluster).

Appendix E — Bang Port class → gameserver StationClass

Bang Port class Gameserver StationClass Gameserver StationType Trading pattern
0 CLASS_0 DIPLOMATIC special: buys/sells special_goods, sells colonists
1 CLASS_1 MINING buys ore; sells organics, equipment
2 CLASS_2 INDUSTRIAL buys organics; sells ore, equipment
3 CLASS_3 INDUSTRIAL buys equipment; sells ore, organics
4 CLASS_4 TRADING buys exotic_technology; sells ore, organics, equipment, fuel
5 CLASS_5 TRADING buys all four basics; sells luxury_goods
6 CLASS_6 TRADING buys ore, organics; sells equipment, fuel
7 CLASS_7 TRADING buys equipment, fuel; sells ore, organics
8 CLASS_8 TRADING (is_quest_hub = true) premium buyer: buys all four basics

Gameserver classes 9–11 (CLASS_9 Nova premium seller, CLASS_10 Luxury Market, CLASS_11 Advanced Tech Hub) are reserved for higher-tier stations created post-import by the economy or quest systems; the bang generator does not produce them.

The bang Port.class === 0 case appears only at the Stardock special location; the translator treats Stardock as the single canonical CLASS_0 station per Region and rejects any additional CLASS_0 ports the bang payload contains.

Appendix F — Bang Cluster → gameserver Cluster

Bang field Gameserver column Translation
cluster.name Cluster.name Direct copy. AI-generated per ADR-0044.
cluster.type Cluster.type Direct copy. One of STANDARD, RESOURCE_RICH, POPULATION_CENTER, TRADE_HUB, MILITARY_ZONE, FRONTIER_OUTPOST, CONTESTED, SPECIAL_INTEREST.
cluster.sectorRangeStart / sectorRangeEnd Cluster.special_features ("sector_range_start", "sector_range_end" keys) Stored on the cluster for diagnostic queries; sector membership is materialized via per-sector Sector.cluster_id in step 7.
cluster.warpStability, economicValue, isDiscovered, isHidden Cluster.warp_stability, etc. Direct copy where bang emits; otherwise default per cluster type.
cluster.coords (x, y, z) Cluster.x_coord, y_coord, z_coord Direct copy. Bang lays Nexus clusters out on a 5×4 grid; standard regions use a Hilbert-packing on cluster sector-range.
(gameserver-only) Cluster.faction_influence Not from bang. Seeded gameserver-side at step 15 from the per-zone profile in faction_profiles.py.

Bang clusters arrive named, sector-range-bounded, and laid out spatially. The gameserver overlays faction-influence percentages because those depend on the gameserver's faction enum and per-customer admin overrides.

Appendix G — Bang SpecialFormation → gameserver SpecialFormation

The translation is a 1:1 import. Bang owns formation stamping (anchor selection, template application, validation) and emits ready-to-insert rows; the gameserver validates and persists.

Bang field Gameserver column Translation
formation.type SpecialFormation.type Direct copy. One of the 12-type catalog: BUBBLE, DEAD_END_BUBBLE, GOLD_BUBBLE, TUNNEL, DEAD_END, WARP_SINK, BACKDOOR, BLISTER, ESCAPE_HATCH, LOST_SECTOR, LOST_CLUSTER, ARCHIPELAGO (the last three added in ADR-0070).
formation.anchorSectorId SpecialFormation.anchor_sector_id UUID of the imported sector at this bang ID.
formation.interiorSectorIds SpecialFormation.interior_sector_ids ARRAY of UUIDs from imported sectors.
formation.properties SpecialFormation.properties (JSONB) 1:1 copy. Type-specific keys per ../DATA_MODELS/special-formations.md.
(gameserver-only) SpecialFormation.region_id Set to the Region created in step 3.
(gameserver-only) SpecialFormation.is_discovered Default false; per-player discovery handled at runtime per ADR-0045.
(gameserver-only) SpecialFormation.generation_seed Set to Universe.seed for audit trail.

Phase 13 cross-checks the ADR-0046 invariant ("no WARP_SINK inside a BUBBLE") on the imported set; bang enforces the same invariant at generation time so the cross-check is belt-and-suspenders.

Appendix H — Bang NPCRoster → gameserver NPCRoster

Bang field Gameserver column Translation
roster.kind NPCRoster.kind Direct copy. One of federation_marshal, nexus_sentinel, pirate_lord, pirate_captain, pirate_enforcer, etc. (see ../FEATURES/gameplay/police-forces.md and ADR-0047).
roster.factionCode NPCRoster.faction_code Direct copy.
roster.targetCount NPCRoster.target_count Direct copy.
roster.hostSectorId NPCRoster.host_sector_id UUID of the imported sector.
roster.namePool NPCRoster.name_pool JSONB array of candidate names; consumed by npc_scheduler.bootstrap_region at step 17.
roster.defaultLodgingId NPCRoster.default_lodging_id Optional FK to an OutlawBase (pirate-tier rosters) or NPCBarracks (Marshal/Sentinel rosters).
(gameserver-only) NPCRoster.region_id Set to the Region created in step 3.

NPCCharacter rows are not imported — they are runtime-managed and materialized post-commit by npc_scheduler.bootstrap_region(region_id) (step 17). The data-model rule: NPCRoster is worldgen-stamped (now bang-stamped); NPCCharacter is runtime-managed.