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). (impl audit 2026-06-16)

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 triggers a regenerate that drops and re-seeds the entire Nexus region.

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).

# Cluster name Cluster type Sector range Grid (x, y)
1 Commerce Central Hub TRADE_HUB 1–250 (0, 0)
2 Diplomatic Quarter POPULATION_CENTER 251–500 (1, 0)
3 Industrial Complex TRADE_HUB 501–750 (2, 0)
4 Prospect Belt RESOURCE_RICH 751–1000 (3, 0)
5 Drift Reaches FRONTIER_OUTPOST 1001–1250 (4, 0)
6 Outer Survey Station FRONTIER_OUTPOST 1251–1500 (0, 1)
7 Free Trade Zone TRADE_HUB 1501–1750 (1, 1)
8 Lodestar Reach RESOURCE_RICH 1751–2000 (2, 1)
9 Quiet Quarter STANDARD 2001–2250 (3, 1)
10 Gateway Plaza STANDARD 2251–2500 (4, 1)
11 Settlers' Rest POPULATION_CENTER 2501–2750 (0, 2)
12 Transit Junction STANDARD 2751–3000 (1, 2)
13 Slag Fields RESOURCE_RICH 3001–3250 (2, 2)
14 Starport Complex TRADE_HUB 3251–3500 (3, 2)
15 Marker's Edge FRONTIER_OUTPOST 3501–3750 (4, 2)
16 The Bazaar STANDARD 3751–4000 (0, 3)
17 Lonesome Span FRONTIER_OUTPOST 4001–4250 (1, 3)
18 Wayfarer Hollow STANDARD 4251–4500 (2, 3)
19 Merchant's Row STANDARD 4501–4750 (3, 3)
20 Frontier Gateway FRONTIER_OUTPOST 4751–5000 (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 range.

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 2251–2500). 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 = 2251).

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" covering sectors 1..total_sectors
  (zone-internal numbering — see below)
  │
  ▼
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):
    start_sector = 1 + cluster_index × 250    # Nexus-local numbering
    end_sector   = start_sector + 249  (last cluster absorbs remainder)
    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". - 20 Cluster rows with the names and types above. - 5,000 Sector rows (Nexus-local sectors 1–5000), each with cluster_id referencing one of the 20 clusters. - ~250 Station rows (5% × 5,000) distributed across clusters. - ~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.
Subscription tier mismatch Region.subscription_tier is hard-coded to galactic_citizenship for the Nexus row.

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)