Server Operations

Pause and Resume

Pausing halts tick processing, freezing the game world. All connected clients receive a pause notification and see the “GAME PAUSED” overlay.

Dashboard: Use the Pause and Resume buttons on the Game Status card.

CLI:

galaxy-admin pause
galaxy-admin resume

API:

POST /api/admin/game/pause
POST /api/admin/game/resume

Important: Always pause the game before restarting stateful services (physics, tick-engine, api-gateway, players, galaxy) to prevent position disruption. Stateless services like web-client do not require pausing.

Tick Rate

The tick rate controls how many times per second the physics simulation advances. Default is 1 Hz.

Dashboard: Enter a value (0.1–100 Hz) in the Tick Rate Control card and click Set Rate.

CLI:

galaxy-admin tick-rate get       # View current rate
galaxy-admin tick-rate set 2.0   # Set to 2 Hz

API:

PUT /api/admin/game/tick-rate
Body: {"tick_rate": 2.0}

Note: Higher tick rates increase CPU usage. Monitor the “Ticks Behind” metric — if it consistently shows values above 0, the server can’t keep up with the configured rate.

Time Scale

The time scale multiplier controls how fast game time progresses relative to real time. At 1.0x, one real second equals one game second. At 10x, ten game seconds pass per real second.

Dashboard: Disable Time Sync first, then enter a value (0.1–100x) and click Set Scale.

CLI: Use the API directly for time scale changes.

API:

PUT /api/admin/game/time-scale
Body: {"time_scale": 10.0}

Time Synchronization

When enabled, the game automatically adjusts its time scale to keep game time synchronized with wall-clock UTC. This prevents drift over long running sessions.

Dashboard: Click Toggle Sync on the Time Sync card. The UTC Drift and Effective Scale fields show synchronization status.

API:

POST /api/admin/game/time-sync
Body: {"enabled": true}

Drift monitoring color thresholds:

Green: ≤10 seconds drift
Yellow: ≤60 seconds drift
Red: >60 seconds drift

Snapshot Management

Snapshots save a complete copy of the game state that can be restored later.

Create a Snapshot

Dashboard: Click Create Snapshot on the Snapshots card.

CLI:

galaxy-admin snapshot create

API:

POST /api/admin/snapshot

List Snapshots

Dashboard: The Snapshots card shows the 10 most recent snapshots.

CLI:

galaxy-admin snapshot list

API:

GET /api/admin/snapshots

Restore from Snapshot

Restoring replaces the current game state with the snapshot’s state. The current state is lost unless you create a snapshot first.

Dashboard: Click Restore next to a snapshot (requires confirmation).

CLI:

galaxy-admin snapshot restore <snapshot_id>
galaxy-admin snapshot restore <snapshot_id> --yes   # Skip confirmation

API:

POST /api/admin/restore
Body: {"snapshot_id": 42}

Player Management

List Players

Dashboard: The Players table shows all accounts with their online status.

CLI:

galaxy-admin players list

API:

GET /api/admin/players

Delete a Player

Permanently removes a player account and their ship.

Dashboard: Click the Delete button on a player’s row (requires confirmation).

API:

DELETE /api/admin/players/{player_id}

Station Management

Space stations are passive orbital objects that can be spawned around any celestial body.

Spawn a Station

API:

POST /api/admin/station
Body: {
  "name": "Gateway Station",
  "parent_body": "Earth",
  "altitude": 5500.0
}

The altitude is in kilometers above the parent body’s surface.

List Stations

API:

GET /api/admin/stations

Remove a Station

API:

DELETE /api/admin/station/{station_id}

Monitoring

Integration Health

The Energy Drift and Momentum Drift metrics on the Game Status card indicate physics simulation accuracy. These should stay in the green range (< 1e-6). Increasing drift may indicate:

Tick rate too low for the time scale
Numerical precision issues with extreme maneuvers

Ticks Behind

Shows how many ticks the server is lagging behind its target schedule. A consistently positive value means the server can’t process ticks fast enough. Consider:

Lowering the tick rate
Reducing the time scale
Checking server resource usage

Factory Reset

Completely wipes all game data: players, ships, snapshots, and game state. This cannot be undone.

Dashboard: Click Factory Reset in the Danger Zone card (requires double confirmation).

CLI:

galaxy-admin reset
galaxy-admin reset --yes   # Skip confirmations (dangerous)

API:

POST /api/admin/game/reset