Galaxy / Region / Cluster / Zone / Sector / WarpTunnel

The spatial hierarchy. Region is the unified ownership unit. Regions contain Clusters (thematic groupings) and Zones (security/policing slices). A Sector belongs to exactly one Cluster and at most one Zone.

Galaxy (singleton metadata)
  └─ Region (Central Nexus | Terran Space | Player-owned)
       ├─ Cluster (navigation/thematic)
       │    └─ Sector
       └─ Zone (security: EXPANSE/FEDERATION/BORDER/FRONTIER)
            └─ Sector (also belongs to a Cluster)

---

Galaxy

Source: services/gameserver/src/models/galaxy.py

Purpose: Singleton metadata + global statistics container. Subdivision happens at the Region level.

Fields:

name	type	constraints	notes
id	UUID	PK
name	String(100)	not null
statistics	JSONB	not null	counts: total_sectors, discovered_sectors, station_count, planet_count, player_count, team_count, warp_tunnel_count, genesis_count
density	JSONB	not null	station_density %, planet_density %, one_way_warp_percentage, resource_distribution map
faction_influence	JSONB	not null	per-faction influence numbers
state	JSONB	not null	age_in_days, resource_depletion, economic_health, exploration_percentage, player_wealth_distribution
events	JSONB	not null	active_events / scheduled_events arrays
expansion_enabled	Boolean	default true
max_sectors	Integer	default 500
resources_regenerate	Boolean	default true
warp_shifts_enabled	Boolean	default true
default_turns_per_day	Integer	default 1000
combat_penalties	JSONB	not null	per-zone-type penalty levels (federation/border/frontier)
economic_modifiers	JSONB	not null
hidden_sectors	Integer	default 5
special_features	ARRAY(String)	default []

Relationships: none directly modeled on Galaxy; aggregates are populated from related entities via update_statistics(). Region is the ownership/cascade root for sectors.

---

Region

Source: services/gameserver/src/models/region.py

Purpose: Owned territory unit. Three kinds: Central Nexus (5000 sectors), Terran Space (300 sectors, starter), and player-owned (100–1000 sectors).

Fields:

name	type	constraints	notes
id	UUID	PK
name	String(255)	unique	machine name
display_name	String(255)	not null
region_type	String(50)	default player_owned	enum-like: central_nexus / terran_space / player_owned
owner_id	UUID FK users.id	nullable	null for special regions
subscription_tier	String(50)	default standard
paypal_subscription_id, subscription_status, subscription_started_at, subscription_expires_at, last_payment_at, next_billing_at	mixed	nullable	PayPal billing trail
status	String(50)	default active	active/suspended/terminated/pending
governance_type	String(50)	default autocracy	autocracy/democracy/council
voting_threshold	DECIMAL(3,2)	default 0.51, 0.1–0.9	check constraint
election_frequency_days	Integer	default 90, 30–365	check constraint
constitutional_text	Text	nullable
tax_rate	DECIMAL(5,4)	default 0.10, 0.05–0.25	check constraint
trade_bonuses	JSONB	default {}	per-resource multipliers
economic_specialization	String(50)	nullable
starting_credits	Integer	default 1000, ≥100
starting_ship	String(50)	default scout
language_pack, aesthetic_theme, traditions, social_hierarchy	JSONB	default {}	cultural identity
nexus_warp_gate_sector	Integer	nullable	sector hosting the gate
total_sectors	Integer	default 500	type-conditioned check constraint
active_players_30d, total_trade_volume	counts	default 0

Relationships: - owner → User (FK owner_id). - memberships → RegionalMembership (1:many, cascade delete). - zones / clusters / sectors / planets / stations (1:many). - elections, policies, treaties_as_a, treaties_as_b for governance/diplomacy.

---

Cluster

Source: services/gameserver/src/models/cluster.py

Purpose: Thematic grouping of sectors inside a Region (resource-rich, trade hub, frontier outpost, etc.).

Fields:

name	type	constraints	notes
id	UUID	PK
name	String(100)	not null
region_id	UUID FK regions.id	not null, CASCADE
type	Enum cluster_type	not null	STANDARD, RESOURCE_RICH, POPULATION_CENTER, TRADE_HUB, MILITARY_ZONE, FRONTIER_OUTPOST, CONTESTED, SPECIAL_INTEREST
sector_count	Integer	default 0
is_discovered	Boolean	default true
discovery_requirement	JSONB	nullable	gates discovery
stats	JSONB	not null	total_sectors, populated_sectors, resource_value, danger_level, development_index, exploration_percentage
resource_modifiers	JSONB	default {}
economic_focus	ARRAY(String)	default []
resources	JSONB	not null	primary_resources, resource_distribution, special_resources
economic_value	Integer	default 50	0-100
controlling_faction	String	nullable	null = contested
faction_influence	JSONB	not null	per-faction numbers + dominant_faction
nav_hazards	ARRAY(String)	default []
recommended_ship_class	String	default light_freighter
x_coord, y_coord, z_coord	Integer	default 0
special_features	ARRAY(String)	default []
is_hidden	Boolean	default false
warp_stability	Float	default 1.0

Relationships: - region → Region (FK). - sectors → Sector (1:many, cascade delete).

---

Zone

Source: services/gameserver/src/models/zone.py

Purpose: Security/policing slice of a Region defined by a sector-number range. Independent of cluster organization; orthogonal dimension.

Fields:

name	type	constraints	notes
id	UUID	PK
region_id	UUID FK regions.id	not null, CASCADE, indexed
name	String(200)	not null	e.g., "The Expanse", "Federation Space"
zone_type	Enum zone_type	not null	EXPANSE, FEDERATION, BORDER, FRONTIER
start_sector	Integer	not null, ≥1	check constraint
end_sector	Integer	not null, ≥ start_sector	check constraint
policing_level	Integer	default 5, 0–10	check constraint
danger_rating	Integer	default 5, 0–10	check constraint

Relationships: - region → Region. - sectors → Sector (1:many, cascade delete).

---

Sector

Source: services/gameserver/src/models/sector.py

Purpose: A discrete navigable space; the basic location unit for ships, planets, stations, drones, and combat.

Fields:

name	type	constraints	notes
id	UUID	PK
sector_id	Integer	unique, not null	human-readable sector number
sector_number	Integer	nullable	alternative numeric ID (Central Nexus)
name	String(100)	not null
region_id	UUID FK regions.id	nullable
cluster_id	UUID FK clusters.id	not null, CASCADE
zone_id	UUID FK zones.id	nullable, SET NULL, indexed
type	Enum sector_type	default STANDARD	STANDARD/NEBULA/ASTEROID_FIELD/BLACK_HOLE/STAR_CLUSTER/VOID/INDUSTRIAL/AGRICULTURAL/FORBIDDEN/WORMHOLE
security_level, development_level, traffic_level	Integer	default 5/1/1	1-10
is_discovered	Boolean	default true
discovered_by_id	UUID FK players.id	nullable
discovery_date	DateTime	nullable
x_coord, y_coord, z_coord	Integer	not null
radiation_level	Float	default 0.0
hazard_level	Integer	default 0	0-10
resources	JSONB	not null	has_asteroids, asteroid_yield (ore/precious_metals/radioactives), gas_clouds, has_scanned
resource_regeneration	Float	default 1.0
players_present	JSONB	default []	live presence list
ships_present	JSONB	default []
defenses	JSONB	not null	defense_drones, owner_id, owner_name, team_id, mines, mine_owner_id, patrol_ships
controlling_faction	String	nullable
controlling_team_id	UUID FK teams.id	nullable
last_combat	DateTime	nullable
active_events, special_features, nav_hazards, nav_beacons	JSONB / ARRAY	defaults
description	String	nullable

Relationships: - cluster (FK), zone (FK), region (FK). - planets, stations (1:many, cascade delete). - ships via Ship.sector_id (note: integer FK by sector_id, not UUID). - discovered_by → Player, controlling_team → Team. - deployed_drones → Drone, drone_deployments → DroneDeployment, fleets → Fleet. - outgoing_warps / incoming_warps (many-to-many via sector_warps). - warp_tunnels_origin, warp_tunnels_destination → WarpTunnel (1:many each direction).

sector_warps (association table)

Columns: source_sector_id, destination_sector_id (both UUID FK sectors.id, PK), is_bidirectional (default true), turn_cost (default 1), warp_stability (default 1.0), created_at. Cheap point-to-point warp links — the heavier WarpTunnel is a separate concept with its own metadata.

---

WarpTunnel

Source: services/gameserver/src/models/warp_tunnel.py

Purpose: Named, often artificial, sector-to-sector connection with lifecycle, traversal cost, and discovery state — distinct from the lightweight sector_warps table.

Fields:

name	type	constraints	notes
id	UUID	PK
name	String(100)	not null
origin_sector_id	UUID FK sectors.id	not null, CASCADE
destination_sector_id	UUID FK sectors.id	not null, CASCADE
type	Enum warp_tunnel_type	not null	see Type enum below
status	Enum warp_tunnel_status	default ACTIVE	see Status enum below
is_bidirectional	Boolean	default true
stability	Float	default 1.0	continuous score 0.0–1.0
stability_enum	Enum warp_tunnel_stability_enum	default STABLE	discrete classification: STABLE / UNSTABLE
properties	JSONB	not null	length, stability_rating, expected_lifetime, age, traversal_cost, cool_down, discovered, discoverer_id, discovery_date, affected_by_storms
tunnel_status	JSONB	not null	is_active, disruption, traffic_level, last_traversal, maintenance_status
source_endpoint, destination_endpoint	JSONB	not null	sector/cluster/region/coordinates/controlling_faction/is_secured/access_requirements
artificial_data	JSONB	nullable	management data for player-built tunnels
total_traversals	Integer	default 0
traversal_history	JSONB	default []
turn_cost	Integer	default 1	mirrors properties.traversal_cost
energy_cost	Integer	default 0
is_public	Boolean	default true
access_requirements	JSONB	nullable
created_by_player_id	UUID FK players.id	nullable
created_by_faction	String	nullable
max_uses, current_uses	Integer	nullable / default 0
expires_at	DateTime	nullable
special_effects	JSONB	default {}

Type enum (warp_tunnel_type)

• NATURAL — formed by spacetime fold; no maintenance.
• ARTIFICIAL — player-constructed via warp-gate beacon/focus.
• STANDARD — generic alias used at galaxy generation when no other type fits.
• QUANTUM — exotic-matter tunnel; may degrade rapidly.
• ANCIENT — pre-Federation tunnel; sometimes unstable, sometimes stable for centuries.
• UNSTABLE — tunnel with stochastic stability; may collapse without warning.
• ONE_WAY — tunnel that traverses in one direction only.

Status enum (warp_tunnel_status)

• ACTIVE — in normal use.
• UNSTABLE — random failure rate elevated; usable.
• DEGRADING — stability is dropping over time; collapse imminent.
• COLLAPSED — no longer traversable; row kept for archaeology.
• MAINTENANCE — owner has paused traffic for repairs/upgrades.
• FORMING — under construction (player gate beacon/focus phase).

Stability: continuous vs. discrete

stability (Float, 0.0–1.0) is the live continuous score consumed by traversal-risk calculations and decay ticks. stability_enum is the discrete bucket (STABLE / UNSTABLE) used for indexing, list filters, and UI badging. The two are kept consistent: when stability crosses the unstable threshold, stability_enum flips and status may advance to UNSTABLE or DEGRADING.

Disruption & maintenance

The tunnel_status JSONB blob carries the live operational signals:

• disruption — active anomaly events (warp storms, gravitational shear, faction interdiction) that prevent traversal while present. Disruption events are randomly seeded by the world tick (e.g., warp storms sweeping a cluster) and clear after a defined duration; the tunnel returns to its prior status when the disruption expires.
• last_traversal — timestamp of the most recent successful transit; feeds cool-down and traffic analytics.
• maintenance_status — owner-initiated state for player-built gates only. While maintenance is in progress, traffic is paused and status is set to MAINTENANCE; the tunnel returns to ACTIVE on completion.
• traffic_level — rolling counter feeding congestion modifiers and economic telemetry.

Natural and ancient tunnels never enter MAINTENANCE; only artificial (player-gated) tunnels expose maintenance controls.

State transitions

FORMING ──► ACTIVE ◄──► UNSTABLE ──► DEGRADING ──► COLLAPSED
              │
              ▼
         MAINTENANCE ──► ACTIVE

FORMING is the construction phase for artificial tunnels. ACTIVE is the steady state. UNSTABLE is reversible — stability can recover and the tunnel returns to ACTIVE. Once a tunnel enters DEGRADING, collapse is the only terminal: it advances to COLLAPSED and the row is retained for archaeology and discovery history. MAINTENANCE is reachable only from ACTIVE on player-owned tunnels and always returns to ACTIVE.

Relationships: - origin_sector, destination_sector → Sector. - created_by → Player.

Note: Per-traversal cost and stability are authoritative inside the properties JSONB (traversal_cost, stability_rating); the column-level turn_cost and stability fields are denormalized mirrors used for indexing and quick filters.

See also: - FEATURES/galaxy/warp-gates.md — player gate construction, beacon/focus phases, and maintenance flows for ARTIFICIAL tunnels. - FEATURES/galaxy/sectors.md — natural-tunnel seeding, the lightweight sector_warps association table, and how sectors expose adjacency.