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 100–1,000 sectors each 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) — 100–1,000 sectors, 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. Sector 1 of every region holds a population hub planet plus a Class-0 station. Special types: NORMAL, NEBULA, ASTEROID_FIELD, BLACK_HOLE, RADIATION_ZONE, WARP_STORM. Most generated sectors (~85%) are NORMAL.

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 by sacrificing a Warp Jumper plus 5 Quantum Crystals (= 25 Quantum Shards), 100k–500k credits, and 7–14 real-time days. Two gates required for round trips. 0 turns to use (vs 1 for natural). See galaxy/warp-gates.md.

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

Quantum Jump

Special ability of the Warp Jumper ship — directional jump of 5–10 sectors with a 24-hour cooldown. Different from gate travel: ship-based, not infrastructure-based.

Ship

Player vessel. Each carries cargo, drones (0–12), Genesis Devices (0–5), with shields (150–900) 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. Eight types (Terra, M/L/O/K/H/D/C-class) 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. 1,000 credits each at military stations. Types: combat, defense, mining, scout, research. 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. Six designed factions (Terran Federation, Mercantile Guild, Frontier Coalition, Astral Mining Consortium, Nova Scientific Institute, Fringe Alliance) plus hostile-only Pirates. Reputation scale per-faction is −1000 to +1000. Rivalries: Federation↔Fringe (combined cap 800), Mercantile↔Shadow Syndicate (cap 600). 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: Founder, Officer, Veteran, Member, Recruit. Shared treasury holds 12 resource types. 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 Sector 1 (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 — population units, 30–80 cr/unit. Sold only at each region's Sector 1 hub. 1 cargo each.
  • combat_drones — 1,000 cr each at military outposts.
  • quantum_shards — found in nebulae (mostly Crimson). Five → one Quantum Crystal at a Class 7+ assembler.
  • quantum_crystals — required for player warp gates (5 per gate).

Rare materials

  • prismatic_ore — superior hull reinforcement; ~1 in 10,000 asteroids.
  • photonic_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_SHIP, COLONY_SHIP, DEFENDER, CARRIER, WARP_JUMPER.

Ship Cost (cr) Cargo Drones Genesis Speed (sec/turn) Shields Hull
Escape Pod — (issued) 0 0 0 very low (high turn cost) 150 200
Light Freighter 10,000 500 2 0 1.0 300 400
Fast Courier 30,000 200 0 0 2.0 200 300
Scout Ship 25,000 100 1 0 2.5 150 200
Cargo Hauler 50,000 1,000 2 2 0.5 400 600
Defender 70,000 400 6 3 1.0 700 800
Colony Ship 100,000 1,000 2 5 0.4 400 600
Carrier 150,000 800 12 5 0.75 800 900
Warp Jumper 500,000 (built only) 200 0 1 jump-only 500 600

Numbers above match core/ship_specifications_seeder.py:ShipType definitions. Per-ship Genesis capacity: Cargo Hauler 2, Colony Ship 5, Defender 3, Carrier 5, Warp Jumper 1. The Advanced Genesis tier sacrifices the Colony Ship and only consumes 1 advanced device.

🐛 Bug — Escape Pod hull / shield divergence. The seeder ships Escape Pod with hull_points: 150 and max_shields: 100. The design target above is hull 200 / shields 150 per legacy spec. Bring the seeder values up to match.

Special abilities: - Light Freighter — Versatile Configuration (no mechanical bonus). - Cargo Hauler — Cargo Compression (+15% storage). - Fast Courier — Stealth Systems (25% pirate-encounter avoidance). - Defender — Shield Projection. - Carrier — Fleet Coordination (+20% to nearby allies). - Colony Ship — Terraforming Modules (−30% Genesis sequence time). - Scout Ship — Advanced Sensors. - Warp Jumper — Quantum Jump (5–10 sector directional, 24h cooldown). Craft-only.

Insurance: BASIC (50% / 5% deductible), STANDARD (75% / 10%), PREMIUM (90% / 15%) — models/ship.py:InsuranceType.

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)

Type Color Quantum field Primary resource Notable effect
Crimson Red 80–100 Quantum Shards Highest shard yield
Azure Blue 60–80 Photonic Crystals Stable warp formation
Emerald Green 40–60 Organics Production bonus
Violet Purple 70–90 Exotic Materials Rare-spawn bias
Amber Orange 20–40 Radioactives Hull damage hazard
Obsidian Dark 50–70 Stealth tech Sensor masking

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