Galaxy Generation¶

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. Three of these are fully spec'd for the Central Nexus generator (see SYSTEMS/central-nexus-clusters.md#cluster-type-behavior). The other five are 📐 Design-only — biases below are launch-target intent applied during the per-cluster generation pass:

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.
`POPULATION_CENTER`	Boosts colonist-port and residential-flavor planet types (TERRA, OCEANIC); higher base population on generated planets. ✅ Shipped.
`RESOURCE_RICH`	Higher asteroid-field and rare-resource sector probability; +50% asteroid yield; bias toward resource-extraction port classes (Class 1–3). 📐 Design-only.
`MILITARY_ZONE`	Increased policing presence (NPC patrols), hostile-encounter spawn rate (faction patrols + Pirates); biased toward Defender/Carrier-class faction-owned stations. 📐 Design-only.
`FRONTIER_OUTPOST`	Sparse station density (~50% of standard); higher quantum-shard nebula probability; lower starting-discovery rate (rewards exploration). 📐 Design-only.
`CONTESTED`	Multi-faction territorial overlay (no single faction dominant); elevated PvP encounter rate; faction-rep swings amplified for activity in these clusters. 📐 Design-only.
`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. 📐 Design-only.

Nebulae (cluster-level)¶

~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 available (SectorType): STANDARD, NEBULA, ASTEROID_FIELD, BLACK_HOLE, RADIATION_ZONE, WARP_STORM, ANOMALY (📐 Design-only — spatial oddity with investigation-driven loot drops; ~1–2% of generated sectors).

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 is admin-triggered, not player-facing for the base universe.
Players observe the result via the galaxy map UI and 3D visualization.
Player-owned regions are generated when subscriptions activate, using the same pipeline.

Source map¶

Topic	Path
Generator	`services/gameserver/src/services/galaxy_service.py`
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	`services/gameserver/src/services/galaxy_service.py:_populate_sectors_*`
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