Skip to content

Warp Gates

Player-constructed, one-way FTL connections between any two sectors in the galaxy. Distinct from natural warp tunnels (covered in sectors.md) — gates are built, owned, taxed, and destructible.

Status: 🚧 Partial — WarpTunnel row schema (with type=ARTIFICIAL, artificial_data JSONB, created_by_player_id, is_public, access_requirements, expires_at) is shipped and supports the artificial-tunnel concept. The Warp Jumper ship advertises warp_gate_creation as a special ability. The construction pipeline (beacon → focus → quantum-link) and the gate-specific service/routes do not yet exist as code.

Overview

A warp gate is a pair of physical structures — a beacon in the source sector and a focus in the destination sector — linked by a quantum field once a Quantum Crystal is consumed to initialize the connection. Once active, traversal is 0 turns, indefinite in lifespan, and bound to its owner who controls access and tolls.

Property Natural warp tunnel Player warp gate
Origin Galaxy generation Player construction
Direction Bidirectional or one-way One-way only
Traversal cost 1–3 turns 0 turns
Discovery Must be discovered to use Visible to all in source sector
Destructible No Yes
Access control None Owner-controlled
Toll None Owner-set
Persistence Permanent Indefinite unless destroyed

The 0-turn traversal is what justifies the build cost: a single high-traffic gate replaces dozens of turns per round trip per user. Round-trip routing requires two gates.

Why a player builds one

  • Personal logistics — collapse a frequently-traveled route to 0 turns.
  • Toll income — passive credits per non-owner traversal on public gates.
  • Strategic chokepoint — control routing into/out of contested space.
  • Isolated cluster bridge — connect a discovered isolated cluster (reachable only by Warp Jumper Quantum Jump) to the main network.
  • Team / faction infrastructure — rapid fleet redeployment between owned regions.

Construction pipeline

Status: 🚧 Partial — pipeline is design-stage; target service is services/gameserver/src/services/warp_gate_service.py (does not exist), target routes at services/gameserver/src/api/routes/warp_gates.py (does not exist). The Warp Jumper prerequisite ship is shipped.

A gate is built in three phases. Each phase is interruptible and the structures are destructible until the gate finalizes.

Phase 1 — Deploy beacon (source sector)

Field Value
Endpoint POST /api/warp-gates/deploy-beacon
Body { destinationSector }
Turn cost 50
Credit cost 10,000
Material cost 1,000 ORE, 500 TECHNOLOGY
Result WarpGateBeacon row in source sector, status DEPLOYED

The player must be piloting a Warp Jumper in the source sector. The beacon is a physical object visible to all players passing through. It persists with 5,000 HP and no built-in defenses.

Phase 2 — Deploy focus (destination sector)

Field Value
Endpoint POST /api/warp-gates/deploy-focus
Body { beaconId }
Turn cost 50
Credit cost 10,000
Material cost 1,000 ORE, 500 TECHNOLOGY, 1,000 PHOTONIC_CRYSTALS
Result WarpGateFocus row in destination sector, linked to beacon

The player must travel — via natural tunnels, Warp Jumper Quantum Jump (5–10 sectors per directed jump, 24-hour cooldown), or being hauled in another player's Mega Freighter / Carrier — to the destination sector and deploy the focus structure. 5,000 HP, no built-in defenses.

Field Value
Endpoint POST /api/warp-gates/initialize
Body { beaconId, focusId }
Turn cost 100
Credit cost 50,000
Material cost 1 Quantum Crystal (consumed permanently)
Wait 1 hour real-time energy harmonization
Result WarpGate row, status flips INITIALIZING → ACTIVE

Player must be piloting a Warp Jumper at either endpoint with the Quantum Crystal in cargo. Both beacon and focus must still exist (i.e. survived the construction window). On completion the gate becomes a usable, named, owned WarpTunnel row of type ARTIFICIAL.

Phase totals

Turns Credits Real-time
Beacon 50 10,000 —
Focus 50 10,000 —
Quantum link 100 50,000 1 hr
Plus prerequisites — ~80,000 1–4 days (shard gather + crystal assembly)
Total 200 80,000+ 2–5 days

Materials at market prices add roughly 150–250k credits, putting the effective build cost around 250–350k credits for a single gate.

48-hour invulnerability window

Status: 📐 Design-only — WarpGateBeacon.invulnerable_until and WarpGateFocus.invulnerable_until columns are part of the target schema but no models or enforcement exist.

For the first 48 real-time hours after deployment, both the beacon and focus are flagged invulnerable to combat. This window:

  • Lets the builder complete travel between source and destination.
  • Lets the builder gather defenders / drones / teammates.
  • Prevents grief-destruction of a gate-in-progress before the owner is even back in the sector.

After the 48-hour window expires the structures become destructible at their listed HP. After Phase 3 completes the merged gate has its own HP pool (10,000) and can be attacked using normal infrastructure-attack mechanics.

Resource costs

Quantum Crystal supply chain

Status: 📐 Design-only — Quantum Shard inventory column, harvester equipment, and the assembly endpoint are all design-stage. See quantum-resources.md for the full chain.

Step Mechanism Cost
1. Gather Quantum Shards Run a Quantum Field Harvester in a nebula (Crimson best — quantum field 80–100) 1,000 cr + 15 turns + 2 hr per attempt → 1–3 shards
2. Assemble Crystal Class 7+ Technology Port fusion 5 shards + 10,000 cr + 24 hr → 1 Quantum Crystal
3. Use in gate Phase 3 initialization 1 Crystal consumed

Alternative shard sources: anomaly investigation (5% jackpot of 5 shards / 35% small yields / 60% nothing), combat salvage from Quantum Smugglers (5%) and Rogue Scientists (15%) and destroyed Warp Jumpers (100% of cargo), black-market ports (50–100k cr/shard, requires Federation-hostile reputation), team treasury pooling.

Prerequisite ship — Warp Jumper

Status: ✅ Shipped — Warp Jumper specification is in services/gameserver/src/core/ship_specifications_seeder.py with special_abilities: ["quantum_jump", "warp_gate_creation"].

Only Warp Jumpers can deploy beacons, foci, or initialize quantum links.

Property Value
Credit cost 500,000
Build time 3–5 days at TradeDock or Research Station
Ownership limit 1 per player (can't stockpile)
Materials 3,000 ORE + 2,000 TECH + 1,500 EQUIP + 2,000 EXOTIC_TECH + 1,000 QUANTUM_SHARDS + 500 PHOTONIC_CRYSTALS
Quantum Jump 5–10 sectors directed, 24 hr cooldown
Genesis capacity 1 (see genesis-devices.md)

Prerequisite equipment — Quantum Field Harvester

Status: 📐 Design-only — quantum_harvester_slot flag and the equip/operate endpoints are design-stage.

Property Value
Purchase 50,000 cr
Install 24 hr at Class 7+ Technology Port
Operating cost 1,000 cr per harvest attempt
Compatible ships Scout, Fast Courier, Defender, Warp Jumper

A Scout (25k) + Harvester (50k) is the cheapest viable shard-gathering rig.

Gate properties

A finalized warp gate is represented by a WarpTunnel row of type = ARTIFICIAL. See DATA_MODELS/galaxy.md → WarpTunnel for the full column list. Gate-relevant fields:

Field Use for gates
type ARTIFICIAL
is_bidirectional false (gates are always one-way)
stability 1.0 baseline; degraded by storms or damage
properties.traversal_cost 0 (the speed advantage)
properties.cool_down typically 0; design slot for high-traffic throttling
tunnel_status.traffic_level 0–100 usage saturation
tunnel_status.last_traversal Drives recent-activity sorting / discovery
created_by_player_id Owner
is_public Coarse flag; full access modes live in access_requirements
access_requirements JSONB: access mode, whitelist, faction-rep gates
artificial_data JSONB: build-phase metadata, beacon/focus IDs, defense/upgrade state
expires_at null for persistent gates

The active-gate target schema also tracks gate HP (10,000 default), shield level, turret level, defense drone count, toll fee, total revenue, usage count — these can live as additional columns on a dedicated WarpGate table or be folded into artificial_data JSONB. See Source map.

Toll system

Status: 📐 Design-only — no toll-collection code path exists.

Owners may charge a per-traversal toll on non-owners.

Setting Range
toll_fee 0 – 10,000 credits per use
Free passage Owner, owner's team, allied factions (configurable)
Collection Atomic on traversal; deposited to owner's account
Reporting total_revenue, usage_count, last_used updated per use

A high-traffic public gate (50 uses/day at 500 cr) yields ~25k cr/day, ~750k cr/month — i.e. break-even in ~14 days, then passive income indefinitely.

Access control

Status: 📐 Design-only — access_requirements JSONB exists on WarpTunnel but the access-mode enforcement layer does not.

Owners pick an access mode and optionally layer additional gates on top.

Mode Allowed users
PUBLIC Anyone (default)
TEAM_ONLY Owner + members of owner's team
PRIVATE Owner only
WHITELIST Specific player UUIDs from access_requirements.whitelist
ALLIANCE Owner's team + allied teams/factions

Optional layered gates (any combination):

  • Faction reputation minimum — e.g. Federation rep ≥ 5 to use.
  • Faction reputation maximum — e.g. block players with positive Federation rep on a smuggler route.
  • Team membership — restrict to a named team.
  • Toll bypass list — players who pay 0.

POST /api/warp-gates/{gateId}/permissions updates the access mode, whitelist, allied teams, and toll fee atomically.

Gate limits per player

Status: 📐 Design-only.

Hard cap on simultaneous owned active gates per player, computed as:

max_gates = 1
          + floor(active_team_size / 4)
          + (3 if player_is_region_owner else 0)

A solo player has 1 gate. A captain of an 8-member team has 3. A region owner with the same team has 6. The cap counts only ACTIVE gates — destroyed or in-construction structures don't consume a slot. Transferring or selling a gate frees a slot for the seller and consumes one for the buyer.

Rationale: prevents gate spam, preserves the strategic value of routes, ties expansion to social/economic progress.

Destruction & salvage

Status: 📐 Design-only — combat-against-infrastructure paths exist for sector drones and planet defenses but no warp-gate target.

Anyone can attack a beacon, focus, or active gate after the 48-hour invulnerability window.

Target HP Built-in defenses
Beacon 5,000 None until upgraded
Focus 5,000 None until upgraded
Active gate 10,000 None until upgraded

POST /api/combat/attack-warp-gate with { gateId }. Attack costs 75 turns plus reputation loss with the owner's faction/team. Resolution uses the standard combat resolver (see SYSTEMS/combat-resolver.md) against the target's effective HP, accounting for shields and turret return-fire.

When a gate (or one of its still-vulnerable structures) is destroyed:

  • The WarpTunnel row flips to status = COLLAPSED.
  • The structure rows (beacon/focus) are deleted.
  • Any cargo / drones assigned to the gate's defense are lost.
  • The destroyed-gate event is published on the realtime bus (see SYSTEMS/realtime-bus.md) so subscribed players see the route disappear.
  • The attacker receives partial salvage:
Salvaged on destruction Approximate yield
ORE 500
TECHNOLOGY 250
PHOTONIC_CRYSTALS 200
Quantum Crystal Not recoverable (consumed in initialization)

Attacker reputation loss with the owner's affiliations is the main social deterrent.

Upgrades

Status: 📐 Design-only.

The owner can install upgrades at any time via POST /api/warp-gates/{gateId}/upgrade. Upgrades stack within their type; only the highest level applies.

Shield generator

Level Adds Cost
1 +5,000 shields 10,000 cr + 500 TECH
2 +10,000 shields 25,000 cr + 1,000 TECH
3 +20,000 shields 50,000 cr + 2,000 TECH + 500 EXOTIC_TECH

Shields regenerate (design); shield value is tracked separately from HP and absorbed first.

Turret arrays

Level Turrets Cost
1 10 15,000 cr + 1,000 ORE + 500 EQUIP
2 25 35,000 cr + 2,000 ORE + 1,000 EQUIP
3 50 75,000 cr + 4,000 ORE + 2,000 EQUIP

Turrets return fire on attackers using the standard combat-resolver damage table.

Auto-repair

Tier Rate Cost
Standard 100 HP/hr 25,000 cr + 1,000 TECH
Fast 500 HP/hr 100,000 cr + 3,000 TECH + 1,000 EXOTIC_TECH

Repair runs continuously up to max_health. Damaged shields regenerate on a separate (design) curve.

Drone squadron

The owner deploys combat drones from a Warp Jumper / Defender / Carrier into gate defense. Drones patrol the gate sector and auto-engage attackers using the deployed-drone combat path (see sectors.md → Combat against deployed drones). Drones are consumed if the gate is destroyed; survive and return to inventory if the gate stands.

Source map

Concern Target path
WarpTunnel model (gates use type=ARTIFICIAL) services/gameserver/src/models/warp_tunnel.py
WarpGate / WarpGateBeacon / WarpGateFocus models services/gameserver/src/models/warp_gate.py (does not exist)
Gate construction service services/gameserver/src/services/warp_gate_service.py (does not exist)
Gate construction REST routes services/gameserver/src/api/routes/warp_gates.py (does not exist)
Movement using gates services/gameserver/src/services/movement_service.py:MovementService.move_player_to_sector
Quantum-shard / crystal inventory services/gameserver/src/models/player.py (target columns: quantum_shards, quantum_crystals)
Quantum harvester equipment services/gameserver/src/services/equipment_service.py (target)
Crystal assembly endpoint services/gameserver/src/api/routes/quantum.py (target)
Combat against gates services/gameserver/src/services/combat_service.py (extend with attack_warp_gate)
Warp Jumper specification services/gameserver/src/core/ship_specifications_seeder.py (warp_gate_creation ability flag)
Toll collection warp_gate_service.py:apply_toll (target)
Realtime gate-status events services/gameserver/src/services/realtime_service.py