Skip to content

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)
        └── Sector 1 (region-specific population hub + Class-0 station)

The orchestrator is services/gameserver/src/services/galaxy_service.py:GalaxyGenerator (~1,882 lines).

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 100–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–99, Border = 100–201, Frontier = 202–300.

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.

Nebulae (cluster-level)

~20% of clusters carry nebula properties — defined at the cluster, inherited by member sectors of special_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): NORMAL, NEBULA, ASTEROID_FIELD, BLACK_HOLE, RADIATION_ZONE, WARP_STORM.

Step 6 — Warps & warp tunnels

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

_create_warp_tunnels_enhanced adds long-distance warp tunnels: - 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 — Region starter sector

_ensure_region_starter_sector guarantees Sector 1 of every region has: - A population hub planet (Planet.is_population_hub = True). - A Class-0 trading station (the unique commodity is colonists). - Public, well-policed, never destroyed.

This is the only place to buy population in a region.

Step 9 — SpaceDock

_create_spacedock_for_region places a special station at sector 10 (or nearby) for genesis-device sales and special equipment. Counterpart to TradeDock for late-game logistics.

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