Skip to content

Definitions

Authoritative glossary for SectorWars 2102. When other docs reference a term, this is what it means.

Sections: 1. Terminology — universe structure, entities, AI, governance. 2. Game Rules — turn economy, combat, trading, colonization, balance. 3. Resource Types — commodities and strategic resources. 4. Ship Types — ship classes and stats. 5. Galaxy Components — galaxy → region → zone/cluster → sector hierarchy.

Terminology

Universe hierarchy

Galaxy
└── Region (Central Nexus | Terran Space | Player-owned)
    ├── Zone (security/policing) ── orthogonal ──┐
    └── Cluster (navigation grouping) ───────────┤
        └── Sector ──────────────────────────────┘

A sector belongs to exactly one zone (security ranges) and exactly one cluster (proximity grouping). Boundaries can cross.

Galaxy

The full game universe. Default seed = Terran Space (300 sectors) + Central Nexus (5,000 sectors); player-owned regions add 800–1,200 sectors each at Standard tier (±20% from 1,000) via subscription.

Region

Three types: - Central Nexus (central_nexus) — 5,000 sectors, single zone "The Expanse" (policing 3, danger 6). Sparse infrastructure (5% station density, 10% planet density, 0.3× warp density). Universal hub. - Terran Space (terran_space) — 300 sectors default, three zones (Federation/Border/Frontier in thirds). Standard density (15% stations, 25% planets, 1.0× warps). New-player starting region. - Player-Owned (player_owned) — 800–1,200 sectors at Standard tier (±20% from 1,000), three zones by default but customizable. $25/month ownership, $5/month citizenship. Owner sets governance, taxes, PvP rules, etc.

Code: services/gameserver/src/models/region.py, services/gameserver/src/services/galaxy_service.py.

Zone

Security/policing band defined by sector-number range within a region. Four types:

Zone Policing Danger PvP
EXPANSE 3 6 Open
FEDERATION 9 1 Restricted
BORDER 5 4 Limited
FRONTIER 2 8 Unrestricted

Terran Space and player regions split sectors as Federation 33% / Border 34% / Frontier 33% (galaxy_service._generate_zones_for_region).

Cluster

Navigation grouping of nearby sectors (typically 10–25; auto-calculated 50/cluster for Terran, 250/cluster for Central Nexus). Cluster types: Standard, Resource Rich, Population Center, Trade Hub, Military Zone, Frontier Outpost, Contested, Special Interest.

Approximately 20% of clusters carry nebula properties (defined at the cluster, not sector). Six nebula types: Crimson, Azure, Emerald, Violet, Amber, Obsidian — see Galaxy Components.

Sector

Lowest navigable unit. Each region has a Capital Sector (welcome hub) that holds a population hub planet plus a Class-0 station — fixed at sector 1 in Terran Space, randomized inside the Federation Zone in player regions, anchored in the Gateway Plaza cluster of the Central Nexus. Sector identity is the compound (Region, Cluster, sector_number); sector numbers are not globally unique. Special types: STANDARD, NEBULA, ASTEROID_FIELD, BLACK_HOLE, RADIATION_ZONE, WARP_STORM. Most generated sectors (~85%) are STANDARD.

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

Warp Tunnel / Warp Gate

  • Natural warp tunnel — pre-existing FTL connection, must be discovered. Most are bidirectional. 1 turn to use. See galaxy/sectors.md.
  • Player warp gate — artificial one-way structure. Built using a Warp Jumper (consumed at Phase 3 destination focus anchor) plus 1 Quantum Crystal (= 5 Quantum Shards, consumed at Phase 1 source beacon deploy), ~1.1M cr all-in amortising the WJ, and ~14–17 real-time days for the first gate (2–5 days subsequent if a Warp Jumper is already in production). Two gates required for round trips. 0 turns to use (vs 1 for natural). See galaxy/warp-gates.md, ADR-0029.

Code: services/gameserver/src/models/warp_tunnel.py, movement in services/movement_service.py.

Quantum Jump

Special ability of the Warp Jumper ship. Multi-phase loop: bearing/scan (player picks 3D bearing + range band Near 5–6 / Mid 7–8 / Far 9–10; scan returns a fuzzy resonance reading on the destination), commit (consumes 1 Quantum Charge + 50 turns + sets 24h cooldown), resolve (server picks the destination sector along the bearing). Sensor L3 unlocks an Extended (12–15) tier. Different from gate travel: ship-based, not infrastructure-based. See galaxy/sectors.md#quantum-jump-warp-jumper, ADR-0030.

Ship

Player vessel. Each carries cargo, drones (0–12), Genesis Devices (0–5), with shields (150–800) and hull (200–900). See Ship Types.

Escape Pod

Indestructible failsafe craft. Every player has one. On ship destruction the player is ejected to it, retains all credits (credits are virtual), loses all cargo. Can dock with a teammate's ship for free transport. Pod movement consumes substantially more turns than a normal ship.

Planet

Colonizable celestial body. Seven active types (Terra, Mountainous, Oceanic, Desert, Volcanic, Barren, Ice) with different habitability, growth rate, and resource multipliers. See planets/colonization.md.

Port (Station)

Trading station. Class 0–11 determines what it buys/sells. The codebase calls these stations; the term port is synonymous in user-facing docs. See economy/trading.md.

Drone

Autonomous combat or utility unit. Combat-class drones split into Attack drones (1,000 cr) and Defense drones (1,200 cr) at military stations. Other types: mining, scout, repair. Ships have type-specific drone capacity; sectors and planets can host deployed drones. See gameplay/combat.md and galaxy/sectors.md.

Code: services/gameserver/src/models/drone.py, services/drone_service.py.

Genesis Device

Planet-creation tool. Three tiers (basic/enhanced/advanced); advanced sacrifices a Colony Ship for an instant Settlement-phase colony. See galaxy/genesis-devices.md.

Credits

Universal currency. Stored on the player record, never on the ship — never lost on destruction.

ARIA (Adaptive Reactive Intelligence Assistant)

Per-player AI companion. Tracks consciousness levels (1–5) and bonus multipliers (1.0×–1.5×) that affect turn regeneration and trading. Used heavily in first login (as the security guard) and in trading/haggling. Stored on Player.aria_* columns. See gameplay/aria-companion.md and gameplay/first-login.md.

Faction

NPC organization. Seven allyable factions (Terran Federation, Mercantile Guild, Frontier Coalition, Astral Mining Consortium, Nova Scientific Institute, Fringe Alliance, Shadow Syndicate) plus two hostile-only adversary factions (Pirates, Cabal). Reputation scale per-faction is −1000 to +1000. Rivalries: Federation↔Fringe (combined cap 800), Mercantile↔Shadow Syndicate (cap 600). The Cabal is a 📐 Design-only Terran-Space singleton — endgame antagonist with one fixed HQ in a random Border-zone sector (101–200) and no broader territorial presence. See services/faction_service.py and gameplay/faction-lore.md.

Personal Reputation

Player alignment, separate from faction standing. Range −1000 to +1000, eight tiers from Villain (−1000) to Legendary (+1000). Updated by combat actions (e.g. attack innocent: −100, kill escape pod: −500, defeat bounty target: +100). See services/personal_reputation_service.py and gameplay/ranking.md.

Military Rank

Achievement-based progression, 18 ranks across five tiers (Enlisted/NCO/Warrant/Officer/Flag). Earned by accruing rank points; ranks are never lost. Trading bonus ranges 0%→+50% from Recruit to Fleet Admiral. See gameplay/ranking.md.

Team

Cooperative alliance. Default cap 4 players (configurable per-team via max_members). Team creation costs 10,000 credits. Roles: LEADER / OFFICER / MEMBER / RECRUIT (canonical 4-role TeamRole enum). Shared treasury holds resource commodities. See gameplay/factions-and-teams.md.

Fleet

Multi-ship combat formation owned by a team. Five formations (Standard / Wedge / Defensive / Offensive / Scatter) with per-formation modifiers. Code: services/fleet_service.py.

Game Rules

Turn economy

  • Daily allocation: 1,000 turns, regenerated continuously (not as a daily reset). Base rate ≈ 1000 / 86,400 s ≈ 0.0116 turns/s, modified by aria_bonus_multiplier (1.0×–1.5×).
  • No carryover: pool capped at Player.max_turns (default 1,000).
  • Costs (canonical):
  • Travel between sectors: 1 turn (modified by ship speed; escape pod is much higher).
  • Dock / undock: 1 turn each.
  • Trading while docked: 0 turns.
  • Ship upgrades, defending: 0 turns.
  • Combat initiation: variable (read from ShipSpecification.attack_turn_cost of the defender's ship type — minimum 2; an escape pod's cost is intentionally enormous to discourage pod-killing).
  • Sector-drone attack: 2 turns.
  • Planet/port attack: 3 turns.

Code: services/movement_service.py, services/combat_service.py.

See gameplay/turns.md for full action cost matrix.

Combat

  • Defending costs zero turns; attackers pay turns.
  • Resolution mixes drone counts, ship-type matchup multipliers (e.g. DEFENDER vs CARGO_HAULER = 1.5×; CARRIER vs SCOUT = 1.8×), weapon types (laser/plasma/missile/emp with shield/hull effectiveness ratios), shields, hull, RNG.
  • Ship destruction → escape pod, all credits retained, all cargo lost.
  • Combat hooks award rank points, update ARIA consciousness, run bounty/reputation logic, and trigger medal checks.

See gameplay/combat.md.

Trading

  • Each station has a class (0–11) determining the commodity buy/sell pattern.
  • Prices computed dynamically from supply ratio: midpoint = base_price × (1.5 − supply_ratio), with a 15% spread (SELL_SPREAD = 1.15, BUY_SPREAD = 0.85). Result clamped to spec ranges.
  • Trading while docked is instant (0 turns); dock/undock cost 1 each.

See economy/trading.md.

Colonization

  • 10,000 colonists + 10,000 credits to establish a basic outpost.
  • Population purchased from each region's Capital Sector (price clamped 30–80 cr/unit). 1 cargo space per population unit.
  • Genesis Device alternative: see galaxy/genesis-devices.md.

Player progression

Tracked via credits, planets owned, citadel levels, ports owned, ships, faction reputations, personal reputation, military rank. See gameplay/ranking.md.

Resource Types

Codebase uses lowercase_underscore commodity names consistently.

Core trading commodities (7)

Commodity Price range (cr) Role
ore 15–45 Construction baseline
organics 8–25 Survival, colonization
gourmet_food 30–70 Premium colony enhancement
fuel 20–60 Ship & station propulsion
equipment 50–120 Manufactured goods
exotic_technology 150–300 Advanced tech components
luxury_goods 75–200 High-margin volatile market

Ranges enforced in services/trading_service.py:COMMODITY_PRICE_RANGES.

Strategic resources

  • colonists — pioneer migration contracts; 30–80 cr per pioneer, contracts secured only at each region's Capital Sector Pioneer Office. 1 cargo space per pioneer (cryosleep transit pod). Contracts fulfilled on landing — pioneers settle as colonists at the destination world.
  • combat_drones — Attack drones 1,000 cr / Defense drones 1,200 cr at military outposts. See gameplay/combat.md#drones.
  • quantum_shards — found in nebulae (mostly Crimson). Five → one Quantum Crystal at any Class 3+ station or SpaceDock (per ADR-0009).
  • quantum_crystals — required for player warp gates (1 per gate, consumed at Phase 1 source beacon deploy per ADR-0029).

Rare materials

  • prismatic_ore — superior hull reinforcement; ~1 in 10,000 asteroids.
  • lumen_crystals — sensor/weapon enhancement; only in specific nebula types.

Genesis Devices

Tracked separately, not as cargo. See galaxy/genesis-devices.md.

Ship Types

Nine types in code (models/ship.py:ShipType): ESCAPE_POD, LIGHT_FREIGHTER, CARGO_HAULER, FAST_COURIER, SCOUT, COLONY, DEFENDER, CARRIER, WARP_JUMPER. The full per-ship catalog — cost, capacity, combat rating, scanner range, special abilities, faction gates, insurance tiers — lives in ./gameplay/ship-roster.md. Lifecycle (acquisition, ownership, maintenance, upgrades, destruction) lives in ./gameplay/ships.md. Schema lives in ../DATA_MODELS/ships.md.

Galaxy Components

(Compact reference; see galaxy/generation.md for the generation procedure.)

Galaxy

Universe-level container. ~5,300 starting sectors; expandable via player-owned regions purchased through PayPal subscriptions. Density defaults: 15% station / 25% planet / 10% one-way warps.

Region

See Terminology > Region.

Zone

Security boundary; assigned by sector-number range within a region. Determines policing, danger, PvP rules, NPC patrol density.

Cluster

Proximity-based grouping of 10–25 sectors. Carries nebula properties when applicable.

Nebula (cluster property)

All nebulae yield Quantum Shards as their primary resource; the six types differentiate via field-strength band, shard yield rate, and a secondary gameplay effect.

Type Color Quantum field Shard yield / harvest Secondary effect
Crimson Red 80–100 2–3 Mild combat advantage (heat-glow concealment)
Azure Blue 60–80 1–3 Stable warp formation in-cluster
Emerald Green 50–70 1–2 Production bonus on adjacent planets
Violet Purple 40–60 1–2 Rare-spawn bias (exotic encounters)
Amber Orange 20–40 0–1 Hull damage hazard while traversing
Obsidian Dark 0–20 0–1 (rare ×5 crit) Sensor masking; severe warp disruption

Coverage: 30–70% of cluster typical; 100% rare. Cluster entry points are never placed in core nebula sectors.

Sector

Special types and effects: - NEBULA — sensor interference (30–80% reduction by density), +1–5 turn movement penalty in cores, hosts quantum gathering. - ASTEROID_FIELD — mineable; movement hazards. - BLACK_HOLE — high danger, possible unique travel. - RADIATION_ZONE — hull damage if unshielded. - WARP_STORM — temporary; disables nearby tunnels.

Warp Tunnel

See Terminology > Warp Tunnel.

Cross-references