Skip to content

Sectors: Defense, Warp, Navigation

What players actually do within and between sectors. Generation is in generation.md; this doc covers runtime mechanics.

Movement basics

services/gameserver/src/services/movement_service.py:MovementService.move_player_to_sector:

  1. Lock the player row (with_for_update) — prevents double-spending turns from concurrent requests.
  2. Reject if docked or landed.
  3. Reject if the player has no active ship.
  4. Resolve the movement type:
  5. Direct warp (adjacent sector) → cost is Ship.turn_cost (≈1, ship-modified).
  6. Warp tunnel → cost from WarpTunnel.turn_cost (1–3).
  7. Neither → "no path available."
  8. Verify player.turns >= cost.
  9. Execute: deduct turns, update current_sector_id, set home_region_id if crossing into a new region.
  10. Run encounter checks (_check_for_encounters) — pirates, sector drones, etc.
  11. Commit and return.

Movement on the same sector returns success with 0 turn cost.

Warp tunnels

Two flavors (covered in definitions.md):

Natural warp tunnels

  • Pre-existing during galaxy generation.
  • 60–80% of sectors connect to the main network via natural tunnels.
  • Mostly bidirectional; some one-way.
  • Must be discovered before use — undiscovered tunnels don't appear on the player's map.
  • Cost: 1 turn to use (some longer-range tunnels cost up to 3).
  • Cannot be destroyed.

Player-created warp gates

  • One-way only — round-trip requires two gates.
  • 0 turns to use (the speed advantage that justifies the build cost).
  • Permanent unless destroyed by attack.
  • Owner controls access permissions and toll fees.
  • Built only by sacrificing a Warp Jumper ship + 5 Quantum Crystals (= 25 Quantum Shards) + 100k–500k credits + 7–14 real-time days.

🚧 Partial — full gate construction pipeline (beacon/focus placement, multi-day build state, toll collection) is design-stage; the Warp Jumper ship itself is implemented.

Quantum Crystal gathering

Tunnel construction needs Quantum Crystals (full chain in quantum-resources.md; player-built gates detailed in warp-gates.md). To make one:

  1. Equip a Quantum Field Harvester (50,000 cr) on a Scout / Fast Courier / Defender / Warp Jumper.
  2. Travel to a nebula cluster — Crimson is best (quantum field 80–100 → highest yield).
  3. Run a harvest: 1,000 cr + 15 turns + 2 hours real-time per attempt; yields 1–3 shards.
  4. Once you have 5 shards, dock at a Class 7+ Technology Port: 10,000 cr + 24 hours = 1 Quantum Crystal.

Other shard sources: anomalies (low yield), combat salvage from rare NPCs, black market (50–100k cr/shard, requires Federation-hostile reputation), team pooling.

Quantum Jump (Warp Jumper)

Distinct from gate travel. The Warp Jumper ship has built-in directional FTL: - Range: 5–10 sectors per jump. - Direction-based, not target-based — you set a bearing, not a destination. - 24-hour cooldown. - Burns significant fuel. - The only way to reach isolated clusters that have no natural tunnel to the main network.

Sector contents

A sector can contain (any combination): - Stations (5–15% of sectors carry one). - Planets (10–25%). - Player ships (transient). - Deployed drones (sector-defense). - Genesis devices in formation. - Mines.

Player count and last_combat timestamp are tracked on the Sector row.

Sector defense system

SectorDefense lets a player claim and protect a sector by deploying drones, mines, or NPC defenders.

Drone deployment

  • Player ship's drones can be transferred to a sector.
  • Restrictions:
  • Cannot deploy in Stardock sectors (sectors 1–7 reserved as safe).
  • Can only deploy in the player's current sector.
  • Only one player can hold deployed drones in a sector at a time (others must defeat them first).
  • Visibility: any player entering the sector sees the drone count and owner.
  • Deployed drones get +5% effectiveness over ship-mounted drones.

Drone retrieval

  • Player must be in the sector.
  • Ship must have spare drone capacity.
  • Instantaneous, 0 turns.
  • Partial retrieval allowed.

Combat against deployed drones

When an enemy attacks deployed drones: 1. Sector owner is notified. 2. Combat resolves via combat_service.attack_sector_drones (2-turn cost, defender pays 0). 3. Drone exchanges roll probabilistically (50% base hit) until one side hits zero. 4. Owner notified of result.

Other sector-defense options

  • Mines — 2,000 cr each (design); damage hostile entrants.
  • Owned port defenses — port classes 1–5 carry built-in drones.
  • Owned planet defenses — see planets/defense.md for layered defenses.
  • NPC defenders — design only, not implemented.
  • Automated drone recall — design only.
  • Galaxy map UI — discovered sectors shown with warp connections.
  • A* pathfinding (design) — optimal route calculation between sectors.
  • Route optimization service (services/route_optimizer.py) — fuel-vs-time-vs-danger tradeoffs.
  • ARIA — personalized recommendations based on visited sectors and player trade history.

Player-facing affordances

  • Click destination sector on the galaxy map → preview turn cost → confirm to spend turns.
  • Sector view shows other ships present (with name colors driven by personal reputation).
  • Drone deploy/retrieve UI when standing in your sector.
  • Notifications when someone enters a sector you've defended.
  • Discovery state per-player — you only see what you've visited (or what's pre-discovered for Terran/Nexus).

Source map

Topic Path
Movement services/gameserver/src/services/movement_service.py
Sector model services/gameserver/src/models/sector.py
Warp tunnel model services/gameserver/src/models/warp_tunnel.py
Sector REST routes services/gameserver/src/api/routes/sectors.py
Combat against sector drones services/gameserver/src/services/combat_service.py:attack_sector_drones
Drone deployment services/gameserver/src/services/drone_service.py
Route optimization services/gameserver/src/services/route_optimizer.py
Encounter generation services/gameserver/src/services/movement_service.py:_check_for_encounters