KSP-MissionControl/ksp/README.md

KSP-side Telemetry Bridge

This directory will hold the bridge between a running Kerbal Space Program game and the kerbal-rt API. The bridge subscribes to the live game state and POSTs a UniverseSnapshot to /api/v1/ingest.

Status: Phase 1c — not yet implemented. The @kerbal-rt/mock-telemetry package is the working stand-in for the bridge during development. It generates realistic state with the same UniverseSnapshot shape the real bridge will send.

Two implementation options

Option A — kRPC (recommended, fastest to ship)

kRPC is the modern, well-maintained RPC framework for KSP 1.12.x. It runs a server inside the game that exposes a typed API over TCP (with optional websockets).

Setup:

1. Install KSP 1.12.5 + ckan
2. ckan install kRPC — pulls in the server mod + protobuf defs
3. Start KSP, load your save, start a kRPC server (default port 50000)
4. Run a small Node client that subscribes to streams:
   • vessel.orbit (returns a tuple of orbital elements)
   • vessel.situation
   • space_center.ut
   • body.orbit for each body
   • space_center.transform_position/rotation for ground stations
5. The client formats a UniverseSnapshot and POSTs to POST http://api:4000/api/v1/ingest with the x-api-key header set to your INGEST_API_KEY

Node client skeleton:

import krpc from 'krpc-node';
// or: import { Client } from 'node-krpc';

const client = krpc.connect({ host: 'localhost', rpcPort: 50000 });
const sc = client.spaceCenter;

// Subscribe to streams (push every 1s)
const ut = client.addStream(() => sc.ut);
const vessels = await sc.vessels;

setInterval(async () => {
  const snap = {
    ut: ut.get(),
    capturedAt: new Date().toISOString(),
    activeVesselId: sc.activeVessel?.id.toString() ?? null,
    bodies: await buildBodies(client),
    vessels: await Promise.all(vessels.map(v => buildVessel(client, v))),
    groundStations: await buildGroundStations(client),
  };
  await fetch('http://localhost:4000/api/v1/ingest', {
    method: 'POST',
    headers: { 'content-type': 'application/json', 'x-api-key': process.env.INGEST_API_KEY! },
    body: JSON.stringify(snap),
  });
}, 1000);

(There's no official kRPC Node client, but a quick protobufjs setup using the .proto files from the kRPC mod works in <300 lines.)

Option B — Custom KSP mod (most flexible)

A C# KSP mod that uses Harmony to patch into FlightGlobals and publishes state on each physics tick. Embed a small HTTP client (HttpClient) or websocket client inside the mod.

• Pro: Total control, can publish events (stage, maneuver node, collision) not just state. Can disable the publish path with a toggle in the mod's UI.
• Con: You own the codebase forever. Have to maintain it across KSP updates. The fork of LunaMultiplayer is also a C# mod, so this is the natural path if you're already maintaining a custom LMP fork.

When to use this: only if kRPC can't give you the data you need (e.g. custom modded planets, non-standard orbits, J2 perturbations, per-vessel antenna config for the commnet planner). For the stock Kerbol system, kRPC is enough.

What the bridge sends

A UniverseSnapshot per the schema in @kerbal-rt/shared-types/src/schemas.ts. The mock publisher's output (apps/tools/mock-telemetry/src/index.ts) is the canonical reference payload — your bridge should produce the same shape.

Running the real bridge

# 1. Make sure KSP is running with the kRPC mod enabled
# 2. Make sure the API is running (Phase 1a)
# 3. Run the bridge (Phase 1c — TBD)
pnpm --filter @kerbal-rt/ksp-bridge start
# (this script doesn't exist yet; see Option A/B above)

Why this isn't done yet

The real bridge requires:

1. A real KSP 1.12.5 install with kRPC mod loaded
2. A save with vessels, in a state interesting enough to publish
3. Iterating on the protocol against the real game (KSP exposes orbital data in KSP-specific frames; you have to translate to the heliocentric ecliptic frame for the API)

We can do all of that, but the value of a working mock-driven pipeline (which the user already has) is much higher than a real bridge sitting unused. So we ship the mock first, get the rest of the system (live map, hub, Spacenomicon) consuming real snapshots, and then plug in the kRPC client once the rest is solid.