Galaxy Generation¶

Status: 🚧 Partial — bang sidecar + BangImportService pipeline shipped for core topology seeding; several runtime cluster effects and yield multipliers remain design-only. (re-verified 2026-08-21 vs Sectorwars2102 HEAD 46bce720.)

How the universe is built, from a metadata record down to populated sectors with stations, planets, and warp tunnels.

Pipeline¶

Galaxy (metadata)
  └── Region (Central Nexus | Terran Space | Player-owned)
        ├── Zones (security: Federation/Border/Frontier or Expanse)
        ├── Clusters (proximity grouping)
        │     └── Sectors (lowest navigable unit)
        │           ├── Stations (5–15% of sectors)
        │           ├── Planets (10–25% of sectors)
        │           ├── Warps (adjacency)
        │           └── Warp Tunnels (long-distance)
        └── Capital Sector (per-region; population hub + Class-0 station)

Region generation runs in the external sw2102-bang sidecar; the gameserver's services/gameserver/src/services/bang_import_service.py:BangImportService validates the produced snapshot and persists it. The steps below are the canonical generation design owned by sw2102-bang — the gameserver is a validating loader, not the in-process orchestrator. See ../../OPERATIONS/bang-integration.md.

Step 1 — Galaxy metadata¶

generate_galaxy(name, config) creates a single Galaxy row holding statistics and density defaults:

max_sectors — capacity across all regions (default 10,000).
density.station_density — default 15.
density.planet_density — default 25.
density.one_way_warp_percentage — default 10.

Regions (and thus actual sectors) are created separately.

Step 2 — Regions¶

Three region types (models/region.py:RegionType):

Type	Sectors	Zones	Density modifiers
Central Nexus	5,000	1 (Expanse)	Stations 5%, planets 10%, warps ×0.3
Terran Space	300 (configurable)	3 (Fed/Border/Frontier)	Stations 15%, planets 25%, warps ×1.0
Player-Owned	800–1,200 (Standard tier; ±20% from 1,000)	3 by default, customizable	Same as Terran

Player-owned regions are created on PayPal subscription activation.

Step 3 — Zones¶

_generate_zones_for_region creates security boundaries:

Central Nexus → single EXPANSE zone covering all 5,000 sectors. Policing 3, danger 6.
All others → three zones split by sector number:
FEDERATION — first 33% — policing 9, danger 1.
BORDER — middle 34% — policing 5, danger 4.
FRONTIER — last 33% — policing 2, danger 8.

For Terran Space (300 sectors): Federation = 1–100, Border = 101–200, Frontier = 201–300 (clean 100/100/100 split).

Step 4 — Clusters¶

_create_clusters_for_region partitions the region's sector budget across clusters:

Cluster count auto-calculated unless overridden: - Central Nexus → 20 clusters (~250 sectors each). - Terran Space → 6 clusters (~50 sectors each). - Player regions → max(2, total_sectors // 50).

Each cluster gets: - A region-appropriate type (Standard, Resource Rich, Population Center, Trade Hub, Military Zone, Frontier Outpost, Contested, Special Interest). - A name like "Terran Space Cluster A". - Variable size (±33% from average). - is_discovered = True for Terran/Nexus, False for player regions.

Zone resource asymmetry¶

Within a region, resource availability scales asymmetrically across zones — Frontier yields more for the same activity (mining, harvesting, anomaly investigation), Federation yields less. The danger/policing curve provides the inverse: Federation is safe but resource-poor; Frontier is hazardous but lucrative. Exact yield multipliers are 📐 Design-only:

Zone	Yield multiplier (vs standard)	Rationale
Federation	×0.7	Safety tax — over-mined inner sectors, regulated access
Border	×1.0	Baseline
Frontier	×1.4	Lawless extraction — no oversight, contested but rich

Cluster-type biases (above) compose with zone yield multipliers — a RESOURCE_RICH cluster in Frontier yields more than the same cluster in Federation.

Cluster-type biases¶

The cluster type drives downstream seeding decisions when sectors, ports, and planets are populated inside the cluster. Central Nexus behavior is spec'd in SYSTEMS/central-nexus-clusters.md#cluster-type-behavior. Bang (sw2102-bang content.ts / clusters.ts / bigbang.ts, LEG-12) implements generation-time biases below; runtime-only effects (hazard rolls, NPC patrol density, PvP, rep swings) stay Design-only unless noted.

Cluster type	Bias
`STANDARD`	Mixed-use; no specific bias. Default when no theme dominates. ✅ Shipped.
`TRADE_HUB`	Boosts port density toward higher classes (Class 4–8 distribution); reduces hazard rolls; feeds station traffic stats. ✅ Shipped (port-class skew in bang; hazard-roll / station-traffic effects remain runtime — out of bang scope).
`POPULATION_CENTER`	Boosts colonist-port and residential-flavor planet types with an oceanic-heavy draw plus a habitability baseline boost (higher `maxPopulation`). Does not roll random TERRA — TERRA stays reserved for the Capital welcome planet and Alpha Centauri SpecialLocation (B-101 / Phase 13 #8). ✅ Shipped.
`RESOURCE_RICH`	Higher asteroid-field probability; +50% asteroid yield; bias toward resource-extraction port classes (Class 1–3). ✅ Shipped in bang `content.ts` (`RESOURCE_RICH_ASTEROID_CHANCE`, `makeResourceRichAsteroids`, `PORT_CLASS_WEIGHTS_RESOURCE_RICH`).
`MILITARY_ZONE`	🚧 Partial — bang ships Class 4–8 port skew + `recommendedShipClass = fighter` (`PORT_CLASS_WEIGHTS_MILITARY`, `clusters.ts`). 📐 Design-only residuals: Defender/Carrier faction-owned station types (bang has no such port types / `Port.factionAffiliation`), increased NPC policing presence, hostile-encounter spawn rate.
`FRONTIER_OUTPOST`	✅ Shipped — ~50% station density and ×2 nebula probability (`FRONTIER_OUTPOST_PORT_FACTOR` / `FRONTIER_OUTPOST_NEBULA_FACTOR`); qualitative lower starting-discovery via LEG-148 Bang `clusters.ts` (`isDiscovered: false` for `FRONTIER_OUTPOST`; Nexus path keeps `isDiscovered: true`). No ratified numeric discovery rate.
`CONTESTED`	🚧 Partial — type is assigned in bang topology (`clusters.ts` weights / `maxWarps`). 📐 Design-only residuals: multi-faction territorial overlay, elevated PvP encounter rate, amplified faction-rep swings (no content-pass bias in `content.ts`).
`SPECIAL_INTEREST`	Reserved for unique lore content — Cabal HQ in Terran Space Border Zone (a single sector randomized in 101–200 per `../gameplay/faction-lore.md#the-cabal`), other story-driven sectors. Generation seeds a single themed station + planet. ✅ Shipped (LEG-12 `specialInterestRanges` + Cabal hub placement in `content.ts`).

Nebulae (cluster-level)¶

📐 Design-only / conflict-open — cluster-tier nebula coverage in this subsection is not silently ratified. Sibling OPERATIONS/bang-integration.md --nebula-percent is a per-sector Bernoulli. Which model is authoritative is human decision LEG-DEC-99 (raised; unanswered). Do not read these coverage/weighting tables as shipped cluster-tier generation. Do not pick a model here.

~20% of clusters carry nebula properties — defined at the cluster, inherited by member sectors of type = NEBULA. See definitions.md for the six nebula types and their effects.

Nebula coverage distribution (design): - 30% coverage clusters: 50% probability. - 50% coverage: 30%. - 70% coverage: 15%. - 100% coverage: 5%.

Nebula type weighting by zone type: - Federation — Azure 50%, Emerald 30%, Obsidian 20% (safer types). - Border — Crimson 30%, Violet 30%, Azure 20%, Amber 20%. - Frontier — Crimson 40%, Violet 30%, Amber 20%, Obsidian 10% (dangerous types).

Step 5 — Sectors¶

_create_sectors_for_cluster creates rows incrementally:

Sector numbers are sequential within the region (starting from 1).
85% generated as STANDARD; 15% chosen from the cluster's allowed special types.
Each sector gets 3D coordinates from _generate_cluster_coordinates.
Both zone_id (by sector-number range) and cluster_id (by creation grouping) are set — these are orthogonal; nothing prevents a cluster from spanning multiple zones.

Special types live today in the SectorType enum (models/sector.py:36-47): STANDARD, NEBULA, ASTEROID_FIELD, BLACK_HOLE, STAR_CLUSTER, VOID, INDUSTRIAL, AGRICULTURAL, FORBIDDEN, WORMHOLE, RADIATION_ZONE, WARP_STORM (damage-over-time / warp-tunnel-disrupting hazards — ✅ shipped, wired to the live Sector.type column). One more is ✅ shipped: ANOMALY (spatial oddity with investigation-driven loot drops; ~1–2% of generated sectors — shipped audit cycle 27, 2026-08-09, via POST /player/sectors/{id}/investigate-anomaly, see ./quantum-resources.md § 2).

Step 6 — Warps & warp tunnels¶

_create_warps_between_sectors connects adjacent sectors with standard warps (1-turn cost).

Step 6.5 — Special Formations¶

Between local-warp adjacency and long-distance tunnel placement, the generator stamps Special Formations — Bubbles, Tunnels, Dead-Ends, Warp Sinks, Blisters, and the rest of the catalog. Each formation is a rare graph-shape landmark (a sealed pocket reached through one gateway, a chain of empty sectors, a one-way trap) that gives the region texture beyond a uniformly-distributed warp graph. Formations are an orthogonal axis to clusters — a Bubble can sit inside any cluster type. Every formation gets a unique evocative name within its region, AI-generated at bang time.

Player-facing reference: ./special-formations.md. Stamping pipeline: ../../SYSTEMS/special-formations-generation.md. Catalog and schema: ../../DATA_MODELS/special-formations.md.

Step 6.75 — Long-distance warp tunnels¶

_create_warp_tunnels_enhanced adds long-distance warp tunnels (after formations have stamped, so tunnel placement avoids breaking formation invariants): - Density multiplier 0.3 for Central Nexus (sparse). - Density multiplier 1.0 for Terran/player regions. - Mix of one-way and two-way (mostly two-way).

Warp tunnels intentionally include isolated clusters (10–20% of sectors) with no natural warp tunnels to the main network — these can only be reached via Warp Jumper quantum jumps.

Step 7 — Stations & planets¶

_populate_sectors_with_ports and _populate_sectors_with_planets: - Central Nexus — 5% station density, 10% planet density. - Other regions — 15% station density, 25% planet density.

Station class is assigned probabilistically per the region/zone profile.

Step 8 — Capital Sector¶

Every region has one Capital Sector — the welcome hub stored as Region.capital_sector_number. It's where new arrivals dock first, where the population-hub planet sits, and the only place pioneer migration contracts can be secured.

Terran Space: Capital fixed at sector 1.
Player regions: Capital randomly placed inside the Federation Zone (random(1, floor(0.33 × total_sectors))). Players arriving from another region cannot guess the Capital's number — they have to explore the Federation Zone to find it.
Central Nexus: Capital anchored in the Gateway Plaza cluster (the cluster where players arrive from connected regions).

_ensure_region_capital_sector populates the Capital with: - A population hub planet (Planet.is_population_hub = True). - A Class-0 trading station (the unique commodity is colonists). - Public, well-policed, never destroyed.

The sector immediately following the Capital (capital_sector_number + 1, if available) gets a Class-1 mining-pattern station — the basic-trading counterpart inside fedspace, one warp from the Capital.

Sector identity is the compound (Region, Cluster, sector_number) tuple — sector numbers are region-scoped, so what's "sector 47" in your home region isn't related to "sector 47" in someone else's region.

Step 9 — SpaceDocks (two per region)¶

_create_spacedocks_for_region places two SpaceDock stations per region. SpaceDocks live outside the Class 0–11 trading-pattern enumeration (the Class enum's slot 11 is "Premium Tech Specialist", a trading station — see ../economy/trading.md#class-11-premium-tech-specialist). Both SpaceDocks have identical service portfolios (genesis devices, mining drones, refining, luxury amenities, faction-headquarters services):

SpaceDock #1 — fedspace anchor. capital_sector_number + 9 (or nearest available, still inside fedspace) — keeps high-end services within reach of the Capital.
SpaceDock #2 — frontier anchor. total_sectors − 5 (or nearest available, in the Frontier zone) — rewards traversal into dangerous territory, anchors the far end of the region economically.

Both SpaceDocks are non-destructible and offer the same services; differentiation is by location, not content.

Determinism / seeding¶

The galaxy uses Python's random directly (no explicit seed parameter in generate_galaxy). Tests and admin tools should set the seed externally. The bang/world generator (sw2102-bang repo) handles richer seeded generation for development previews.

Player-facing affordances¶

Galaxy generation of the base universe is admin-triggered, not a player control (no player-fired generator on tip 46bce720).
Players observe the result via 3D visualization: ✅ services/player-client/src/components/galaxy/Galaxy3DRenderer.tsx (+ ConnectionPath3D / SectorNode3D / StarField) on tip 46bce720. There is no GalaxyMap.tsx page — do not conclude a standalone map page is live.
Player-owned region generation on subscription is payments/ops, not a player-facing control — honesty-mark only; do not mint a GS/PC product WO.

Source map¶

Topic	Path
Generator	`sw2102-bang` repo (`bigbang.ts`, topology) + `services/gameserver/src/services/bang_import_service.py` (`BangImportService` translate/apply import)
Galaxy/region/zone/cluster/sector models	`services/gameserver/src/models/galaxy.py`, `region.py`, `zone.py`, `cluster.py`, `sector.py`
Warp tunnel model	`services/gameserver/src/models/warp_tunnel.py`
Station/planet seed logic	`sw2102-bang` repo (topology) + `services/gameserver/src/services/bang_import_service.py` (post-import seeding, e.g. `_apply_tradedock_seeding`)
Admin generation API	`services/gameserver/src/api/routes/admin.py`, `admin_comprehensive.py`
Nexus generation (alternative)	`services/gameserver/src/services/nexus_generation_service.py`, `api/routes/nexus.py`
External world generator	`sw2102-bang` repo