Skip to content

Warp Gates

Player-constructed, one-way FTL connections between any two sectors in the galaxy. Stored as WarpTunnel rows with type = ARTIFICIAL and created_by_player_id set — the created_by_player_id IS NOT NULL predicate distinguishes player-built gates from the generator-placed ARTIFICIAL connections that bind starter-area sectors together (see DATA_MODELS/galaxy.md → Type enum). Player gates are built, owned, taxed, and destructible; the natural tunnel network is covered in sectors.md.

Status: 🚧 Partial — the three-phase construction pipeline is shipped and gameplay-verified (2026-06-12): WarpGateBeacon/WarpGate models, warp_gate_service.py, routes/warp_gates.py, deploy-beacon/anchor-focus/cancel, scaled 48h beacon window, 1h harmonization with Ship.status = HARMONIZING, Warp Jumper consumption with destruction_cause = WARP_GATE_ANCHOR (no wreck, no insurance), destination-side escape-pod ejection, and 0-turn one-way traversal through the normal move endpoint. Quantum Jump (ADR-0030) is shipped alongside it. Still design-only: tolls, access-mode enforcement, gate transfer/sale, destruction & salvage, upgrades, the Quantum Crystal supply chain (player shard/crystal columns exist; harvesting/assembly do not), and the get-home tow ritual.

Overview

A warp gate is built from an origin beacon/focus in the source sector and a far-side gate structure in the destination sector. The Warp Jumper deploys the beacon/focus at the origin, accumulates the gate's construction materials there over multiple cargo runs, then jumps to the destination and self-destructs to raise the far-side gate — pointed back toward the origin beacon/focus, completing the one-way quantum link. Once active, traversal runs destination → beacon/focus at 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.

Placement constraints

Status: ✅ Shipped — validation lives on the deploy-beacon endpoint and re-runs at anchor AND at harmonization completion (with full Phase-3 refund on completion-time failure). no_warp/nexus_protected read from Sector.special_features (no dedicated columns exist; documented interpretation).

A beacon-deploy attempt is rejected up front if any of the following hold:

  • Same-sector loop — source == destination. A gate must connect two distinct sectors.
  • Minimum gate length — at least 50 sectors of natural-network path-distance between source and destination (or straight-line distance through the cluster graph if endpoints are unconnected). Short hops aren't worth a gate slot.
  • Anti-spam cap — the destination sector already has 5 incoming active gates. Further incoming gates are rejected to prevent hub-flooding.
  • No-warp zones — sectors flagged with the no_warp special property (story-locked sectors, sanctuary zones) are ineligible as either endpoint.
  • Nexus protected sectors — sectors with Sector.is_nexus_protected = true (Capital sector 2251, Gateway Plaza cluster, operator-tuned additions) reject deploy-beacon attempts with ERR_NEXUS_PROTECTED_SECTOR. The Nexus Sentinel Corps backstops this validation: any bypass that lets a beacon spawn anyway triggers an immediate Sentinel intercept squad (4 Sentinel Interdictors). See ../gameplay/police-forces.md.
  • Same-region constraint — both endpoints must lie in the player's current region or in Central Nexus. Cross-region gates between two non-Nexus regions are not supported.

Validation failures cost no turns and no credits and surface the specific reason. The same checks re-run at the Phase 3 self-destruct commit — a competing player filling the destination's incoming-gate cap mid-travel, a sector being flagged no_warp by an event, etc. cause the Phase 3 commit to reject. Materials already committed (Phase 1 turns, credits, Crystal; staged ORE / EQUIPMENT / LUMEN_CRYSTALS in the construction site) are retained as sunk cost; the Warp Jumper hull is not consumed because the self-destruct is the final atomic step inside a successful commit (see Phase 3 failure modes).

Construction pipeline

Status: 🚧 Partial — services/gameserver/src/services/warp_gate_service.py + services/gameserver/src/api/routes/warp_gates.py implement the beacon/focus deploy, the jump-to-destination travel window, and the destination self-destruct; gameplay-verified end-to-end 2026-06-12 (two opposing gates built live, both Jumpers consumed). The staged material-accumulation model — the gate_construction_site buffer, the stage-materials deposit endpoint, the advance-construction turn action, and the per-phase cure tick (ADR-0078) — is design-only. See ADR-0029 for the Warp-Jumper-consumption decision, ADR-0030 for the Quantum-Jump multi-step commit that surrounds the travel window, and ADR-0078 for staged construction.

A gate is built as a three-phase ritual, and each phase's bulk materials are staged at the origin over multiple cargo runs rather than hauled in a single trip. The Warp Jumper carries only 200 units of cargo — far short of any one phase's material total — so the materials accumulate in a gate_construction_site at the origin sector across several deliveries before a phase can be committed (see Material staging and ADR-0078). The Warp Jumper itself is the structural keystone of the far-side gate — it survives the staging and travel phases and is consumed at the destination, where it self-destructs to raise the gate pointed back toward the origin beacon/focus. Each phase is interruptible up to the destination self-destruct; that commit is the only atomic, irreversible step.

Phase 1 — Deploy beacon/focus and open the construction site (source sector)

Field Value
Endpoint POST /api/warp-gates/deploy-beacon
Body { destinationSector }
Turn cost 50
Credit cost 10,000
Material cost 1 Quantum Crystal (consumed at this phase)
Result WarpGateBeacon row in source sector, status DEPLOYED, invulnerable_until = now() + 48h; a gate_construction_site row opened at the source sector to accumulate staged materials

The player must be piloting a Warp Jumper in the source sector. Deploying the beacon/focus also opens a gate_construction_site at that sector — the persistent buffer that the gate's bulk construction materials accumulate into over multiple runs (see Material staging). The beacon/focus is a physical object visible to all players passing through. It persists with 5,000 HP and no built-in defenses, but is flagged invulnerable for 48 real-time hours per ADR-0011 — the window covers the Warp Jumper's transit time toward the destination, since the Warp Jumper is consumed at the destination and cannot return to defend the beacon/focus itself.

The Quantum Crystal is consumed at this phase (not at the destination self-destruct), separating Crystal-risk from Warp-Jumper-risk: once Phase 1 commits, the Crystal cannot be lost in transit. The Warp Jumper hull is not consumed yet. The bulk ORE / EQUIPMENT / LUMEN_CRYSTALS are not demanded up front in a single payload — they are staged into the construction site across as many cargo runs as it takes (see below).

Material staging

Status: 📐 Design-only — the gate_construction_site model, the stage-materials deposit endpoint, the advance-construction turn action, and the per-phase cure tick are all design-stage. See ADR-0078.

The Warp Jumper carries 200 units of cargo — less than any single phase's material requirement — so the gate's bulk materials are ferried into the gate_construction_site over multiple runs rather than paid in one payload. This is what makes gate-building a construction project rather than an instant payment, and it is the resolution to the Warp-Jumper-can't-haul-a-phase's-materials constraint: no single load ever has to fit the full per-phase total.

Field Value
Endpoint POST /api/warp-gates/{siteId}/stage-materials
Body { ore?, equipment?, lumenCrystals? } (each ≤ the depositing ship's available cargo)
Per-run limit the depositing ship's cargo capacity — ≤ 200 units for a Warp Jumper
Result materials transfer from ship cargo into gate_construction_site, incrementing its staged totals

How staging works:

  • Any ship may deposit. The Warp Jumper can ferry its own ≤200-unit loads, but teammates and other haulers (Cargo Haulers carry far more per trip) can stage materials into the same site, so a team can front-load a phase's totals quickly.
  • A phase's totals accumulate across runs. Phase 1's structure draw of 1,000 ORE + 500 EQUIPMENT (1,500 units) takes at least eight Warp-Jumper runs on its own; the destination phase's 1,000 ORE + 500 EQUIPMENT + 30 LUMEN_CRYSTALS likewise stages over several trips. Materials are a real market cost staged into the site — nothing is conjured (respects ADR-0029 sink economics).
  • Commit a phase once its materials are fully staged. When the site holds a phase's full material set, the builder spends construction turns to advance it via POST /api/warp-gates/{siteId}/advance-construction (draft 5 turns/phase); the phase then cures over 24 canonical hours (lazy advance-on-read, mirroring terraforming's tick model) before the next phase opens. A 3-phase gate is a multi-session investment: ferry → commit turns → wait out the cure → repeat.

The origin-side structure phase must finish curing before the Warp Jumper jumps to the destination. The destination phase's materials stage into the same site and travel with the build state; the destination self-destruct draws against them at commit.

Phase 2 is not an endpoint — it is the travel window between the source-side beacon/focus deploy (with its phase materials staged and cured) and the destination self-destruct. Once the origin structure has cured, the player jumps the Warp Jumper from the source sector to the destination sector by any means available:

  1. Natural warp tunnels — under your own power. Slow over long distances, depending on the network coverage between the two sectors.
  2. Quantum Jump — the Warp Jumper's built-in directional FTL: 5–10 sectors per jump, 24-hour cooldown. See ADR-0030 for the multi-step commit and refund rules.
  3. Carrier hangar — dock the Warp Jumper inside a teammate's Carrier hangar (the Warp Jumper is a large ship and consumes 8 hangar units — exactly one Carrier's worth; see ../gameplay/ships.md#carrier-hangar).
  4. Teammate tractor tow — be towed by a teammate's Tractor-Beam-equipped Cargo Hauler / Defender / Carrier (the towing ship pays a +5 turns/move surcharge for the large-size tow). Tow is restricted to natural warp tunnels under the standard rule; the Warp Jumper's Quantum Jump breaks any active tow. See ../gameplay/ships.md#tractor-beam-tow-operations.

The destination-phase materials stay staged in the gate_construction_site and travel with the build state — they are not re-hauled in the Warp Jumper's hold for the jump. The Warp Jumper carries only the in-progress build link and any non-bound cargo. The Warp Jumper may itself tow up to one medium-or-smaller companion ship via its own Tractor Beam during Phase 2 (a special exception only the Warp Jumper's own Tractor enjoys; +5 turns flat surcharge applied to the Quantum Jump commit when towing). This is what enables the Get-home ritual below.

The beacon/focus's 48-hour invulnerability covers the Warp Jumper's transit window. If the Warp Jumper is destroyed in combat during Phase 2 the beacon/focus survives the remainder of the 48h window; the Crystal was already consumed at Phase 1 and is not at risk; the player can deploy a new Warp Jumper and resume from Phase 2 against the existing beacon/focus and its staged materials. If the beacon/focus expires before Phase 3 completes the gate-in-progress is abandoned.

Phase 3 — Self-destruct at destination (raise the far-side gate, Warp Jumper sacrifice)

Field Value
Endpoint POST /api/warp-gates/anchor-focus
Body { beaconId }
Turn cost 100
Credit cost 10,000
Material cost 1,000 ORE, 500 EQUIPMENT, 30 LUMEN_CRYSTALS (drawn from the staged construction site, not the Warp Jumper's hold)
Sacrifice Warp Jumper hull is consumed — it self-destructs to raise the far-side gate, pointed back toward the origin beacon/focus
Wait 1 hour real-time energy harmonization
Result WarpGateFocus row in destination, WarpGate row links beacon/focus + far-side gate, WarpTunnel flips INITIALIZING → ACTIVE

Player must be piloting the same Warp Jumper at the destination sector. Both the origin beacon/focus (still alive at source) and the player's Warp Jumper must be present at their respective endpoints, and the destination phase's materials must be fully staged and cured in the construction site; the server verifies all three before commit.

Phase 3 splits into two atomic steps with a 1-hour harmonization window between them. The Warp Jumper hull is not consumed at the call to anchor-focus — it self-destructs only at the harmonization-completion commit at the end of the 1-hour timer.

Step A — Self-destruct commit (call-time, atomic). - Phase 3 turns / credits are deducted, and the staged ORE / EQUIPMENT / LUMEN_CRYSTALS are drawn from the construction site and materialized into the far-side gate. - The Warp Jumper enters Ship.status = HARMONIZING (a new ship-status value distinct from IN_SPACE/DOCKED/IN_COMBAT/DESTROYED). The hull stays intact and visible to other players in the sector but is flagged invulnerable for the harmonization hour — the same invulnerability mechanism the beacon/focus uses during the 48h window. Hostile attack during harmonization is a no-op. - The far-side gate structure spawns at 5,000 HP with no built-in defenses, inheriting the beacon/focus's invulnerable_until flag until harmonization completes. - The WarpTunnel row exists in INITIALIZING state; not yet open for traffic.

Step B — Harmonization completion (timer-fired, atomic, 1 hour later). - The Warp Jumper's Ship.status flips from HARMONIZING to DESTROYED with destruction_cause = WARP_GATE_ANCHOR (a new value on the destruction-cause enum). No CargoWreck is generated — this is a planned self-destruct that raises the gate, not an explosion that scatters salvage. - Non-bound cargo on the Warp Jumper transfers to the pilot's escape pod inventory. - The pilot ejects to an escape pod in the destination sector (not the source sector — there is no automatic relocation back). The Get-home ritual is the standard pattern for returning home. - No insurance payout. Warp Jumpers are non-insurable per ../gameplay/ship-insurance.md#non-insurable-ships — the 1,000,000 cr ship value is the gate-builder's actual risk capital, written off in full at this step. Combat-destruction in transit pays out nothing either. - The beacon/focus's invulnerable_until clears, the gate's WarpTunnel row flips to ACTIVE, and the gate is open for traffic — players traverse it destination → beacon/focus at 0 turns.

Splitting the self-destruct off the call-time commit lets cancel and external-failure paths refund the Warp Jumper hull plus all Phase 3 materials cleanly — the hull self-destructs only on the successful harmonization completion.

Failure modes at Phase 3:

  • Player cancels mid-harmonization, destination becomes no_warp mid-harmonization, or destination's incoming-gate cap fills before harmonization completes: the Warp Jumper exits HARMONIZING back to IN_SPACE at the destination, intact. All Phase 3 materials (turns, credits, ORE, EQUIPMENT, LUMEN_CRYSTALS) refund to the construction site / player; the far-side gate structure deletes; the WarpTunnel row is removed. The Crystal from Phase 1 stays gone (already fused at Phase 1 commit per existing rules) and is not refunded.
  • Beacon/focus destroyed during Phase 2 (only possible if Phase 2 exceeds 48h): the anchor-focus endpoint rejects with ERR_BEACON_LOST before any Phase 3 deduction fires. Phase 3 materials are not deducted (the precondition check fails up front), but Phase 1 materials (including the Crystal) are gone.
  • Hostile attack on the Warp Jumper during harmonization: rejected, no-op. The harmonization-window invulnerability is non-negotiable.

Phase totals

Turns Credits Real-time Notes
Phase 1 — beacon/focus 50 10,000 — + 1 Crystal at deploy; 1,000 ORE + 500 EQUIPMENT staged into the site over multiple runs
Material staging + 5/phase varies + 24 hr cure/phase ferry runs (≤200/run for a WJ) + advance-construction turns + per-phase cure
Phase 2 — travel varies varies hours to ~48h depends on travel mode + Quantum Jump cooldowns
Phase 3 — self-destruct 100 10,000 1 hr + 1,000 ORE, 500 EQUIPMENT, 30 LUMEN_CRYSTALS (staged into the site over multiple runs), Warp Jumper hull
Plus prerequisites — ~1,080,000 14 days + shard/crystal gather Warp Jumper build (1M) + Crystal supply chain
Total 150 + staging + travel ~1,100,000 ~14–17 days first gate, 2–5 days subsequent hull is the dominant cost

Materials at market prices and the consumed Warp Jumper put the effective build cost around 1.1–1.25M credits per gate (most of which is the sacrificed hull). The bulk ORE / EQUIPMENT / LUMEN_CRYSTALS are ferried into the construction site across multiple cargo runs — the Warp Jumper's 200-unit hold never has to fit a phase's total in one trip, and teammates with larger haulers can front-load the staging. Players who keep a "gate-builder" Warp Jumper in production can amortize the 14-day build by overlapping the next hull with the current expedition.

48-hour invulnerability window

Status: 🚧 Partial — WarpGateBeacon.invulnerable_until is shipped and drives beacon expiry; the HARMONIZING hull's combat invulnerability is enforced in combat_service. Structure-vs-structure attack paths (and therefore post-window destructibility) remain design-only.

For the first 48 real-time hours after Phase 1 deployment, the beacon is flagged invulnerable to combat. The focus inherits the same invulnerability flag for the remainder of that 48h window plus the Phase 3 harmonization hour. This window:

  • Covers the Warp Jumper's transit from source to destination during Phase 2. The Warp Jumper is consumed at Phase 3 and cannot return to defend the beacon, so the beacon must rely on the invulnerability flag rather than its builder's hull.
  • Lets the builder gather defenders, drones, or teammates at the destination sector before the gate goes live.
  • Prevents grief-destruction of a gate-in-progress before the harmonization completes.

After the 48-hour window expires the structures become destructible at their listed HP. After Phase 3 harmonization 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 Any Class 3+ station or SpaceDock (per ADR-0009) 5 shards + 10,000 cr + 24 hr → 1 Quantum Crystal
3. Use in gate Phase 1 beacon deploy at the source sector 1 Crystal consumed (locked at Phase 1, safe from Phase 2 combat loss)

Alternative shard sources: anomaly investigation (1% jackpot per ./quantum-resources.md#2-anomaly-investigation-secondary — narrow odds; smaller yields more common), 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 the beacon/focus, jump to the destination, or self-destruct to raise the far-side gate. The hull is consumed at the destination self-destruct.

Property Value
Credit cost 1,000,000 all-in
Build time 14 days at TradeDock (slip rental — see ../economy/tradedock-shipyard.md)
Ownership limit 1 per player (can't stockpile)
Materials 3,000 ORE + 3,500 EQUIPMENT + 2,000 EXOTIC_TECHNOLOGY + 1,000 QUANTUM_SHARDS + 20 LUMEN_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 (30k) + 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 (subject to 24h tenure rule below), allied factions (configurable)
Collection Atomic on traversal; deposited to owner's account
Reporting total_revenue, usage_count, last_used updated per use

Team-tenure rule (per ADR-0049): toll exemption for owner's team-mates requires 24 hours of continuous team membership at the moment of traversal. The toll endpoint validates that the traversing player's TeamMembership row has joined_at <= now() - 24h and left_at IS NULL. A player who joined the gate-owner's team less than 24 hours ago pays the standard toll. Repeat join/leave cycles restart the clock — the rule reads joined_at from the most recent membership row. Closes the alt-account toll-bypass loophole (alts joining → traversing → leaving → repeating) without affecting legitimate teams whose members traverse during normal play.

A high-traffic public gate (50 uses/day at 500 cr) yields ~25k cr/day, ~750k cr/month — i.e. break-even on the ~1.1M all-in build cost in ~44 days, then passive income indefinitely.

Region-termination cascade

Per ADR-0052 SK38 and the broader cascade in ADR-0050, if a region containing either endpoint of a player-built warp gate enters cleanup:

  1. The gate's both endpoints are destroyed atomically — the entire WarpGate row deletes in one transaction. No half-gates orphaned in the surviving region.
  2. The gate owner is notified via realtime broadcast + ARIA narration ("Your warp gate {name} has been destroyed — the {opposite_region_name} side terminated").
  3. The owner receives 50% of the gate's construction cost (snapshot at build time on WarpGate.construction_cost) credited to their Player.credits if online, or PlayerCentralBankAccount (per ADR-0050) if offline.

The 50% refund covers about half of the consumed Warp Jumper hull (~1M cr), 50 Lumen Crystals, and the Phase 1–3 build materials. Compensates the owner for the involuntary loss without making cascade-destruction profitable. If the owner's own region is the one terminating, the gate compensation is independent of their personal asset cascade (planets/stations/etc.) — gates are separate infrastructure.

Cross-regional double-cascade edge case: if both endpoints' regions terminate in overlapping windows, whichever cleanup orchestrator fires first deletes the gate and pays the 50% refund. The second region's pass finds no gate. Owner is paid once.

Credit-poor travelers

When Player.credits < toll_fee, the gateserver rejects the traversal at the gate with ERR_INSUFFICIENT_CREDITS_FOR_TOLL and the toll amount in the error payload. No partial pay, no negative balance, no owner-side waiver — toll enforcement is atomic. The player must find an alternate route (natural warp tunnels, Quantum Jump, a different gate) or earn credits before retrying. Whitelisted travelers, owner team-mates, and allied-faction players bypass the check entirely; the rejection only applies to non-free traversers whose credits fall short.

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.

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

Transfer & sale

Status: 📐 Design-only.

An owner can transfer a finalized active gate to another player atomically.

Field Value
Endpoint POST /api/warp-gates/{gateId}/transfer
Body { newOwnerId, salePrice? }
Effect Gate ownership flips; toll, access mode, defense settings, and accumulated total_revenue carry over
Slot accounting Frees a slot for the seller; consumes a slot for the buyer
Buyer-cap check Rejected if the buyer's current owned gates + 1 exceeds their max_gates
Failure mode Sale-price holds are reversed; ownership unchanged; both parties notified

Optional salePrice is settled atomically — credits debit from buyer, credit to seller, gate row updates owner — all in a single transaction. salePrice = 0 is a free transfer (typical for team reorganization, alliance gifts, departing-player bequest). The transfer does not retroactively change historical revenue attribution; only future tolls accrue to the new owner.

Use cases this is meant to cover: a builder selling a profitable toll gate to a player better positioned to defend it; a team consolidating gate ownership under a single member; a quitting player converting their gates to credits; alliance gifting strategic infrastructure during diplomacy.

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
EQUIPMENT 250
LUMEN_CRYSTALS 10
Quantum Crystal Not recoverable (consumed at Phase 1 beacon deploy)
Warp Jumper hull Not recoverable (consumed structurally at Phase 3 anchor; no CargoWreck is ever generated)

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 EQUIPMENT + 500 EXOTIC_TECHNOLOGY

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 EQUIPMENT + 1,000 EXOTIC_TECHNOLOGY

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.

Get-home ritual

Status: 📐 Design-only — companion-tow pattern that returns the pilot to the source after the Warp Jumper sacrifice. See ADR-0029.

Because the Warp Jumper is consumed at Phase 3 in the destination sector and the pilot ejects to an escape pod at the destination, a builder who wants to return to the source after the gate goes live brings a companion ship along. The standard pattern:

  1. Approach together. The Warp Jumper and a companion ship (medium-or-smaller, equipped with a Tractor Beam) approach the destination via Quantum Jump. The Warp Jumper's own Tractor tows the companion through Quantum Jumps — a special exception only the Warp Jumper's Tractor enjoys, costing +5 turns flat surcharge on the Quantum Jump commit. Cap: one companion ship, medium-size or smaller.
  2. Phase 3 sacrifice. The Warp Jumper executes Phase 3 anchor at the destination. The Warp Jumper hull is consumed; the pilot ejects to an escape pod in the destination sector with non-bound cargo intact.
  3. Companion tows the pod. The companion ship's Tractor Beam tows the escape pod (+1 turn surcharge for tiny-size tow). See ../gameplay/ships.md#tractor-beam-tow-operations.
  4. Traverse the new gate. Both the companion ship and the towed escape pod traverse the now-ACTIVE warp gate from destination back to source at 0 turns.
  5. Tow through player warp gates is permitted at +2 turns surcharge. Player gates are stable two-way bridges (unlike Quantum Jump), so a Tractor tow may traverse a gate together with its tow target for a +2 turn surcharge on the gate traversal. This rule preserves the get-home ritual end-to-end.

The +2-turn through-gate surcharge applies to any Tractor tow traversing a player gate — not only the get-home ritual, though the ritual is its primary motivating use case. Natural warp tunnels remain the standard tow medium; Quantum Jumps still break tows except for the Warp Jumper's own Tractor exception above.

If the builder skips the companion, the pilot in the escape pod is stranded in the destination sector and must arrange transport home by other means (teammate pickup, paying a passing player, traversing the gate back if it leads somewhere else useful, or scrapping the pod for a return shuttle at a station).

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_site staging model (ADR-0078) services/gameserver/src/models/warp_gate.py (target)
Gate construction service services/gameserver/src/services/warp_gate_service.py (does not exist)
Material staging / advance-construction / cure tick (ADR-0078) warp_gate_service.py:stage_materials / advance_construction / cure tick (target)
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