Jump Gates

Overview

Jump gates are static orbital objects that serve as landmarks and spawn points. They follow the same passive orbital mechanics as stations (gravity-only integration, fixed attitude) but have a distinct octagonal frame mesh with an energy portal effect.

Data Model

JumpGate

Stored as a Redis hash at jumpgate:{jumpgate_id}.

Field	Type	Description
jumpgate_id	string (UUID)	Unique identifier
name	string	Human-readable name
position_x/y/z	float	Barycenter coordinates (meters)
velocity_x/y/z	float	Velocity (m/s)
attitude_w/x/y/z	float	Quaternion (fixed, identity)
mass	float	kg (default: 500,000)
radius	float	meters (proximity envelope, default: 150)
parent_body	string	Reference body name

Physics Dataclass

@dataclass
class JumpGate:
    jumpgate_id: str
    name: str
    position: Vec3
    velocity: Vec3
    attitude: Quaternion    # Fixed (identity)
    mass: float             # 500,000 kg
    radius: float           # 150m (larger than stations)
    parent_body: str

Event Stream

Stream: galaxy:jumpgates

Event	Fields
jumpgate.spawned	event, jumpgate_id, name, parent_body
jumpgate.removed	event, jumpgate_id

gRPC API

Messages

• JumpGateState — mirrors StationState fields with jumpgate_id
• SpawnJumpGateRequest — name, primary_body, secondary_body, lagrange_point
• SpawnJumpGateResponse — success, jumpgate_id, jumpgate, error
• RemoveJumpGateRequest — jumpgate_id
• RemoveJumpGateResponse — success, error
• GetAllJumpGatesRequest — empty
• GetAllJumpGatesResponse — repeated JumpGateState
• ClearAllJumpGatesRequest — empty
• ClearAllJumpGatesResponse — success, jumpgates_removed, error

RPCs

• SpawnJumpGate — spawn at Lagrange point (L4/L5 only)
• RemoveJumpGate — delete by ID
• GetAllJumpGates — list all
• ClearAllJumpGates — admin reset

Orbital Integration

Jump gates are passively integrated every tick using the same Leapfrog integrator as stations (_update_station). This ensures they track their Lagrange point as the parent bodies orbit, rather than being frozen at their spawn position.

The physics step() method loads all jump gates, integrates them with _update_station, and batch-writes them back to Redis alongside bodies, ships, and stations.

Default Spawn

One default jump gate spawned during game initialization:

Name	Location	Purpose
Sol Gate	Earth-Luna L4	Player spawn point

Spawn Point

New players’ ships spawn at the Sol Gate position (Earth-Luna L4) instead of the previous default spawn location.

Proto Support

SpawnShipRequest includes an optional spawn_near_jumpgate field (string, field 6). When set, the physics service spawns the ship in co-orbit near the specified jump gate (1 km prograde offset), using the same logic as station co-orbit spawning.

Priority: spawn_near_station > spawn_near_jumpgate > auto-detect station > default body orbit.

Default Behavior

When neither spawn_near_station nor spawn_near_jumpgate is set, the players service auto-spawns near the first available jump gate (falling back to station, then Earth body orbit).

Respawn Selector

The cockpit spawn selector (R key) lists jump gates alongside stations under their parent body. Jump gates appear after stations with a gold/amber diamond icon (#ffaa00) and “co-orbit” label. Clicking sends jumpgate:<jumpgate_id> as the target body.

The physics request_service("reset") handler recognizes the jumpgate: prefix (analogous to station: prefix) and spawns the ship in co-orbit near the specified jump gate.

Web Client

3D Mesh

Octagonal structural frame (~200m diameter) with:

• Eight main struts forming an octagonal ring
• Cross-bracing between struts for structural detail
• Energy portal effect inside (emissive material, cyan/blue glow)
• Navigation beacons at each vertex
• Built at meter scale, scaled by SHIP_VISUAL_SCALE_TRUE

HUD Integration

• Cockpit view: Marker with distinct color (gold/amber #ffaa00) to differentiate from stations (cyan)
• Map view: Diamond marker in gold/amber, orbital path in matching color
• System tree: Listed under parent body with gate icon
• Targetable: Selectable as target (targetType: 'jumpgate')

State

state.jumpgateStates = {};  // jumpgate_id → { position, velocity, attitude, name, ... }

Admin API

Method	Path	Description
POST	/api/admin/jumpgate	Spawn jump gate
DELETE	/api/admin/jumpgate/{id}	Remove jump gate
GET	/api/admin/jumpgates	List all jump gates

Automation

Jump gates are targetable for rendezvous maneuvers with target_type: "jumpgate".

Files

• services/physics/src/models.py — JumpGate dataclass
• services/physics/src/redis_state.py — jumpgate CRUD
• services/physics/src/simulation.py — spawn_jumpgate_at_lagrange()
• services/physics/src/grpc_server.py — JumpGate RPCs
• services/physics/proto/physics.proto — JumpGate messages
• services/tick-engine/src/tick_loop.py — default jumpgate spawning
• services/tick-engine/src/state.py — get_jumpgate_data()
• services/tick-engine/src/automation.py — jumpgate as target
• services/api-gateway/src/routes.py — admin endpoints
• services/api-gateway/src/websocket_manager.py — tick broadcast + events
• services/web-client/src/state.js — jumpgateStates
• services/web-client/src/main.js — tick data + events
• services/web-client/src/cockpitView.js — mesh + indicator
• services/web-client/src/mapView.js — marker + tree + orbital path