Skip to content

Central Nexus Clusters

Status: 🚧 Partial — nexus_generation_service implements the canonical 20-named-cluster 5×4 table with the 4/2/6/5/3 cluster-type mix (names, ranges, warp_stability 0.95, economic_value 8), plus TradeDock 1A+2B seed and per-station MarketPrice sweep. (gap-list re-verified 2026-08-21 against origin/feat 46bce720 — items 1+3+5 shipped; Outputs prose synced for TradeDock + MarketPrice)

Gap list (Partial → Full), verified against nexus_generation_service.py 2026-08-21 (tip 46bce720; PR #578/#579/#584): 1. ✅ Nexus Capital station at Gateway Plaza — Shipped (PR #579, 2d40fcc6). _seed_nexus_capital_station seeds Central Nexus Starport Prime at the computed Gateway Plaza first sector after TradeDock/cluster seeding; idempotent, dead sector-1 branch extracted into a reusable _build_starport_prime_station_row helper. 2. Starport Prime / Terra Nova Prime civic-safe starter is dead code. Special-case sector_num == 1 never fires because live generation starts at current_sector_num = 301 (:170-171, self-flagged dead at :621-625). Superseded by item 1's shipped fix — the dead branch's station-row logic now also serves the live Gateway Plaza seed path; the sector_num == 1 special-case itself remains unreachable. 3. ✅ Region.capital_sector_number set — Shipped (PR #578 ac4f083b, corrected by PR #579 2d40fcc6). _create_nexus_region now sets it via _gateway_plaza_capital_sector_number() (computed 2551 under live 301-based numbering — PR #578's initial hardcoded 2251 came from this doc's own stale sector-range table, since corrected below). 4. Capital welcome planet / Pioneer Office hub missing — only the dead sector_num == 1 Terra Nova Prime branch exists (:688-705). 5. ✅ Expanse Zone live range — Shipped (PR #584). _create_nexus_zone stamps The Expanse via nexus_expanse_sector_range (301–5300 at default total_sectors=5000), matching live cluster numbering (verified vs origin/feat 46bce720). Dual-numbering remains intentional: ADR-0005 / cluster-table Nexus-local 1–5000 vs live 301-offset globals — see Dual numbering guardrail below; do not collapse them. 6. Partial-seed recovery unimplemented end-to-end. Failure modes ask for is_populated=False on crash; Region has no such column and this service never sets one. 7. force_regenerate is a no-op. Route accepts the flag; generate_central_nexus only early-returns "exists" (:145-148) with no CASCADE delete/re-seed. 8. TRADE_HUB / POPULATION_CENTER seeding biases not applied — only RESOURCE_RICH / FRONTIER_OUTPOST / MILITARY_ZONE are special-cased (:448-531); those two types behave like STANDARD for ports/planets. 9. ✅ Doc-only Outputs lag — synced (2026-08-17). Outputs / state changes now lists shipped TradeDock 1A+2B seed (_seed_nexus_tradedocks) and per-station MarketPrice sweep (_create_market_prices_for_nexus_stations).

Not Full blockers: MILITARY_ZONE / CONTESTED branches are intentionally 0-slot scaffolding (canon mix). subscription_tier="nexus" vs doc galactic_citizenship needs a separate consistency ruling, not a silent flip.

Purpose

The Central Nexus is a sparse 5,000-sector hub region that every player can reach. Internally it is partitioned into 20 named clusters of 250 sectors each, organized in a 5×4 grid. Cluster names give the Nexus its sense of place — "Diplomatic Quarter", "Free Trade Zone", "Frontier Gateway" — and feed the UI's location strings, ARIA dialogue context, and the cluster-type bias that drives port and planet seeding.

This doc defines the 20-cluster table, their cluster-type assignments, and the seeding behavior that flows from them.

Inputs

The clustering reads: - Region.id for the central-nexus region row. - Region.total_sectors (5,000 by design; clamp 5,000 ≤ N). - nexus_generation_service.NEXUS_CONFIG: per-Nexus density overrides (port_density = 0.05, planet_density = 0.10, warp_density = 0.3). - The fixed cluster_names and cluster_types_distribution arrays in nexus_generation_service._create_nexus_clusters — see the table below.

The system fires when: - POST /api/v1/admin/nexus/generate is called and the Nexus does not already exist. - force=true is currently a no-op — the route accepts the flag but generate_central_nexus early-returns {"status": "exists"} when the region is already seeded, with no drop/re-seed (target behavior once built: see the gap-list entry below).

Cluster table

The 20-cluster table below is the Nexus mix per GX1 (audit/design-briefs/gx1-cluster-bias/): the Nexus is a "central hub in the middle of nowhere" — a compact commercial core set in remote, sparse space rather than a civic megacity. The proportions are 4 TRADE_HUB · 2 POPULATION_CENTER · 6 STANDARD · 5 FRONTIER_OUTPOST · 3 RESOURCE_RICH · 0 MILITARY_ZONE · 0 CONTESTED · 0 SPECIAL_INTEREST. nexus_generation_service._create_nexus_clusters implements this table directly; the galaxy-map named-cluster join and the locked tests track it.

Authoritative source: services/gameserver/src/services/nexus_generation_service.py:_create_nexus_clusters.

All sector ranges below are Nexus-local (sector_number within the Nexus region, 1–5000) per the region-scoped identity model (ADR-0005). The compound canonical identifier remains (Region.id, Cluster.id, sector_number).

Dual numbering guardrail: bang-import stamps Gateway Plaza with bang-local 2251–2500; this table's 2551–2800 is the 301-offset global/narrative view used by nexus_generation_service. Both are intentional — see ../DATA_MODELS/galaxy.md#nexus-gateway-plaza--dual-numbering-intentional. Do not collapse them into one literal.

# Cluster name Cluster type Sector range Grid (x, y)
1 Commerce Central Hub TRADE_HUB 301–550 (0, 0)
2 Diplomatic Quarter POPULATION_CENTER 551–800 (1, 0)
3 Industrial Complex TRADE_HUB 801–1050 (2, 0)
4 Prospect Belt RESOURCE_RICH 1051–1300 (3, 0)
5 Drift Reaches FRONTIER_OUTPOST 1301–1550 (4, 0)
6 Outer Survey Station FRONTIER_OUTPOST 1551–1800 (0, 1)
7 Free Trade Zone TRADE_HUB 1801–2050 (1, 1)
8 Lodestar Reach RESOURCE_RICH 2051–2300 (2, 1)
9 Quiet Quarter STANDARD 2301–2550 (3, 1)
10 Gateway Plaza STANDARD 2551–2800 (4, 1)
11 Settlers' Rest POPULATION_CENTER 2801–3050 (0, 2)
12 Transit Junction STANDARD 3051–3300 (1, 2)
13 Slag Fields RESOURCE_RICH 3301–3550 (2, 2)
14 Starport Complex TRADE_HUB 3551–3800 (3, 2)
15 Marker's Edge FRONTIER_OUTPOST 3801–4050 (4, 2)
16 The Bazaar STANDARD 4051–4300 (0, 3)
17 Lonesome Span FRONTIER_OUTPOST 4301–4550 (1, 3)
18 Wayfarer Hollow STANDARD 4551–4800 (2, 3)
19 Merchant's Row STANDARD 4801–5050 (3, 3)
20 Frontier Gateway FRONTIER_OUTPOST 5051–5300 (4, 3)

Counts: 4 × TRADE_HUB, 2 × POPULATION_CENTER, 6 × STANDARD, 5 × FRONTIER_OUTPOST, 3 × RESOURCE_RICH, 0 × MILITARY_ZONE / CONTESTED / SPECIAL_INTEREST (= 20).

The mix reads as a compact commercial crossroads — a 4-cluster TRADE_HUB core (Commerce Central Hub, Industrial Complex, Free Trade Zone, Starport Complex) plus the safe STANDARD transit anchor at Gateway Plaza — surrounded by sparse FRONTIER_OUTPOST rim clusters and a few RESOURCE_RICH mining belts out from the core.

Civic-safe anchors (invariant). Two slots never carry a bias type: - Slot 1 — Commerce Central Hub (TRADE_HUB) holds the first-generated sector and is the starter cluster; it stays a civic-safe commerce type. - Slot 10 — Gateway Plaza (STANDARD) is the Capital cluster where cross-region travelers land (see Nexus Capital); it stays STANDARD/TRADE_HUB, never FRONTIER_OUTPOST or RESOURCE_RICH.

Per-cluster fixed properties (set at seed time): - is_discovered = True — the Central Nexus is always pre-discovered for every player. - is_hidden = False. - warp_stability = 0.95 — slightly more stable than the standard 1.0 baseline; reflects the Nexus's engineered warp infrastructure. - economic_value = 8 — high (all Nexus clusters drive heavy trade traffic). - recommended_ship_class = "any".

Sector numbering

Sectors are identified by the compound tuple (Region.id, Cluster.id, sector_number) — sector numbers are scoped to the Nexus region, not globally unique. Within the Nexus, sectors are numbered sequentially 1..5000. Cluster N spans [(N − 1) × 250 + 1, N × 250] (with the last cluster, Frontier Gateway, absorbing any remainder). There is no universe-global sector numbering; cross-region distinctness is provided by Region.id, not by disjoint sector-number ranges.

The Nexus's single zone "The Expanse" covers the full live sector span (nexus_expanse_sector_range → 301–5300 at default size). The cluster table's Nexus-local 1–5000 identities remain the ADR-0005 region-scoped view — not a second Zone stamp.

Nexus Capital

The Nexus's Capital Sector — its welcome hub, equivalent in role to a player region's Capital — is anchored in the Gateway Plaza cluster (Nexus-local sectors 2551–2800). This is by design: Gateway Plaza is the cluster where players arrive when traveling into the Nexus from a connected region (the "petal connection point"), so the Capital sits where traffic naturally lands.

The Capital hosts the Central Nexus Starport Prime station — the canonical landing spot for cross-region travelers — and a population-hub planet whose Pioneer Office issues migration contracts for any frontier world in the universe. Region.capital_sector_number for the Nexus row is set to a deterministic Nexus-local sector inside the Gateway Plaza range (default: the first sector of the cluster, sector_number = 2551).

Unlike player regions, the Nexus's Capital location is not random — players arriving at the Nexus repeatedly need a predictable destination. Gateway Plaza's role as "where the petals connect" makes its Capital placement canonical lore rather than discovery mystique.

Cluster-type behavior

The cluster type drives downstream seeding decisions when sectors, ports, and planets are populated inside the cluster. The five types used in the remixed Nexus are:

Type Bias
TRADE_HUB Boosts port density toward higher classes (Class 4–8 distribution); reduces hazard rolls; feeds station traffic stats. Used for the commercial core.
POPULATION_CENTER Boosts colonist-port and residential-flavor planet types (TERRA, OCEANIC); higher base population on generated planets. Used for the Nexus's two civic/settlement clusters.
STANDARD Mixed-use; no specific bias. Default when no theme dominates; the safe filler (and the Capital anchor).
RESOURCE_RICH Raises asteroid-field probability and applies a +50% asteroid-yield ratio per the GX1 bias (generation.md); the Nexus mining belts out from the core.
FRONTIER_OUTPOST Halves effective station/port density (~50% per GX1) and scatters nebula sectors; the sparse, remote rim that gives the Nexus its "middle of nowhere" character.

MILITARY_ZONE, CONTESTED, and SPECIAL_INTEREST are not seeded in the Nexus (0 slots): the Nexus hard-codes security_level = 5 for every sector — so CONTESTED would be a no-op — and MILITARY_ZONE / SPECIAL_INTEREST are reserved for player-region generation and hand-placed lore respectively.

Cluster-type bias is applied during the per-cluster sector generation pass (_generate_cluster_sectors in nexus_generation_service.py).

Process

generate_central_nexus(total_sectors=5000)
  │
  ▼
ensure region row exists
  (name="central-nexus", region_type=CENTRAL_NEXUS,
   subscription_tier="galactic_citizenship")
  │
  ▼
create one zone "The Expanse" via nexus_expanse_sector_range
  (default 301..5300 at total_sectors=5000; not 1..N)
  │
  ▼
for i in 0..19:
    create Cluster(
      name=cluster_names[i],
      type=cluster_types_distribution[i],
      sector_count=250,
      x_coord=i % 5, y_coord=i // 5, z_coord=0,
      warp_stability=0.95, economic_value=8,
      is_discovered=True
    )
  │
  ▼
for each cluster (in declaration order):
    # Live stamps use NEXUS_FIRST_SECTOR_NUM=301 offset;
    # Nexus-local 1..5000 remains the ADR-0005 compound-identity view.
    start_sector = 301 + cluster_index × 250
    end_sector   = start_sector + 249  (last cluster absorbs remainder → 5300)
    generate 250 Sector rows in [start_sector, end_sector]
    populate ports at port_density (5%)
    populate planets at planet_density (10%)
    create warp tunnels at warp_density (0.3 multiplier)
  │
  ▼
update region statistics; commit

Outputs / state changes

After successful generation: - 1 Region row with name="central-nexus". - 1 Zone row "The Expanse" stamped via nexus_expanse_sector_range (default 301–5300). - 20 Cluster rows with the names and types above. - 5,000 Sector rows on the live 301-offset span (default 301–5300; ADR-0005 Nexus-local 1–5000 remains the compound-identity view), each with cluster_id referencing one of the 20 clusters. - ~250 Station rows (5% × 5,000) distributed across clusters, plus the canon TradeDock quota (1 Tier-A + 2 Tier-B) from _seed_nexus_tradedocks. - Per-station MarketPrice rows from _create_market_prices_for_nexus_stations (trading endpoint reads this table). - ~500 Planet rows (10% × 5,000) distributed across clusters. - Warp tunnel network built at 0.3× standard density.

Invariants

  1. The Nexus has exactly 20 clusters; the count is hard-coded and not configurable per generation.
  2. Sector numbers in the Nexus run 1–5000 within the Nexus region. Cross-region distinctness is provided by Region.id per the compound canonical identifier (Region.id, Cluster.id, sector_number) (ADR-0005); sector-number ranges are intentionally not globally disjoint.
  3. Every Nexus sector belongs to exactly one cluster; no orphans.
  4. Region.name = "central-nexus" is unique; only one Central Nexus exists per deployment.
  5. Cluster names and order are fixed across regenerations — re-running with force=true reproduces the same names in the same positions.
  6. The Expanse zone is the only zone in the Nexus region; cluster-level bias supplies all the within-region thematic variation.

Failure modes

Mode Target handling
Region already exists, no force flag Service returns {"status": "exists"} without re-seeding.
Force regenerate Drop the region row (CASCADE through clusters, sectors, ports, planets, warp tunnels) and re-seed from scratch.
Partial seed crash mid-generation The service runs sector population per cluster; if a cluster fails, the partial data sits behind a region row with is_populated=False (target). Operators re-run with force=true to recover.
Cluster name collision with another region Cluster names are scoped by region_id; collisions are not possible across regions.

By design, not a failure mode: Region.subscription_tier is hard-coded to galactic_citizenship for the Nexus row. The Nexus is the galaxy's one singleton region and is always max-tier by design — there is no code path where it could seed at a lower tier, so this is not a mismatch to fix.

Source map

Concern Path
Generation service services/gameserver/src/services/nexus_generation_service.py
Cluster name / type arrays nexus_generation_service.NexusGenerationService._create_nexus_clusters
Sector generation per cluster nexus_generation_service.NexusGenerationService._generate_cluster_sectors
Cluster model services/gameserver/src/models/cluster.py
Cluster type enum services/gameserver/src/models/cluster.py:ClusterType
Region model services/gameserver/src/models/region.py
Admin generate endpoint services/gameserver/src/api/routes/nexus.py:generate_nexus
Cluster info endpoint GET /api/v1/nexus/clusters (list), GET /api/v1/nexus/clusters/{cluster_id} (detail)