@ksp-gonogo/kerbcast 1.10.2 → 1.11.0-rc.10

package/README.md

@@ -59,6 +59,10 @@ client.on("adaptive-shed", (event) => {
 client.disconnect();
 ```
 
+Commands can be sent as soon as `connect` resolves. Any sent before the
+control channel has opened wait for it, and reject if it has not opened
+within 10 s or the client disconnects first.
+
 ### Pre-handshake discovery
 
 ```ts
@@ -85,6 +89,65 @@ const setLayers: ClientMessage = {
 controlChannel.send(JSON.stringify(setLayers));
 ```
 
+### Encoded-frame transforms
+
+`cam.setEncodedTransform(factory)` runs your transform on a camera's encoded
+frames before the browser decodes them. It always runs before Kerbcast's
+static and frame lock, so anything it does (holding frames back, dropping
+them) shows up in `cam.mediaStream` with the static still drawn on top.
+
+Kerbcast installs the transform on whichever receiver carries the camera. A
+transform instance works on one receiver only, so you pass a factory:
+Kerbcast calls it for a fresh instance when the camera is bound, again when a
+slot rebind moves the camera to another receiver, and again after a
+reconnect. A receiver the camera leaves goes back to passthrough, and frames
+the old instance still holds are dropped. `setEncodedTransform(null)`
+detaches. It works in both legacy and dynamic slot modes.
+
+It needs `encodedTransforms: true` when the client is constructed, and
+`setEncodedTransform` throws without it. The option gives every receiver a
+passthrough transform from the start, because Chrome only honours a receiver
+transform that was in place before negotiation. It costs a worker hop per
+frame for every camera, so leave it off unless you use this. The passthrough
+worker loads from a `blob:` URL, so a Content Security Policy must allow
+`worker-src blob:`. `setEncodedTransform` also throws when the browser has no
+install path; `client.encodedTransformPath` reports which one you will get:
+
+- `"script"`: return an `RTCRtpScriptTransform` (Chrome, Safari and Firefox)
+- `"streams"`: return a `TransformStream` of `RTCEncodedVideoFrame`, run on the main thread over `createEncodedStreams()` (older Chrome)
+
+A one-second delay on the `"script"` path:
+
+```ts
+const client = new KerbcastClient({ host, port, encodedTransforms: true });
+const worker = new Worker(new URL("./delay-worker.js", import.meta.url));
+
+client.camera(2592004302).setEncodedTransform(({ flightId, path }) =>
+  path === "script"
+    ? new RTCRtpScriptTransform(worker, { flightId, delayMs: 1000 })
+    : delayStream(1000),
+);
+
+// delay-worker.js
+onrtctransform = ({ transformer }) => {
+  const { delayMs } = transformer.options;
+  transformer.readable
+    .pipeThrough(
+      new TransformStream({
+        transform(frame, controller) {
+          setTimeout(() => controller.enqueue(frame), delayMs);
+        },
+      }),
+    )
+    .pipeTo(transformer.writable)
+    .catch(() => {}); // a replaced instance is aborted
+};
+```
+
+`delayStream` is the same `TransformStream` built on the main thread. A
+factory that throws, or returns the wrong kind for the path, is reported as a
+client `error` event carrying the camera's `flightId`.
+
 ## Per-camera capabilities
 
 `CameraState` includes capability flags so consumers render only the
@@ -106,8 +169,9 @@ controls each part actually supports.
   skip, producing the macroblocking and stuttering aesthetic of
   in-game CommNet signal loss. Also a real CPU optimisation when
   every consumer wants degraded video.
-- `kind` (`"part"` | `"kerbal"`) and, for a kerbal face camera,
-  `crewLocation` (`"seat"` | `"eva"`). Distinguish crew face cameras
+- `kind` (`"part"` | `"kerbal"` | `"command"`) and, for a kerbal face
+  camera, `crewLocation` (`"seat"` | `"eva"`). Distinguish crew face
+  cameras and command cameras (see [Command cameras](#command-cameras))
   from part cameras.
 - `trackMode` (`"none"` | `"activeVessel"` | `"target"`). Server-authoritative
   auto-track state on a pan+zoom camera, so every consumer reflects the same
@@ -123,6 +187,254 @@ controls each part actually supports.
   the active vessel or its target (`TrackMode`), or `"none"` to stop. The
   chosen mode is published back on `CameraState.trackMode`.
 
+## Command cameras
+
+A command camera is a camera that stands on the ground (or rides a craft)
+and watches a craft from there, the way a tracking station would. The
+game's settings give each scene one, the Launchpad camera, and a client can
+create more at any vantage. Each appears in `client.cameras` with
+`kind: "command"` and a `commandCentre` describing where it stands and what
+it watches.
+
+A created camera lasts for the rest of the game scene (a flight, or the
+Space Center while the game's command camera setting is on); leaving the
+scene removes it. Every connected client sees it, and any of them can aim
+or destroy it.
+
+The vantage is one of:
+
+- `launchSite`: beside a launch site. `site` names it (`"LaunchPad"`,
+  `"Runway"`, a Making History or Kerbal Konstructs site); omit it for the
+  active craft's launch site. `distance` (default 500 m), `bearing` from the
+  site (default 180, due south) and `height` (default 5 m)
+- `station`: at a CommNet ground station, by its node name (`"KSC"`), with
+  `height` above it (default 30 m)
+- `surface`: at any `latitude` and `longitude` on a `body`, `height` metres
+  above the ground there (above the sea over water; default 5 m)
+- `vessel`: riding the craft with that `persistentId`. Keep that craft
+  beyond physics range of the active one, or the lens sits inside its parts.
+  If the craft docks into another (or is grabbed by a claw), the camera rides
+  the combined craft. If the craft is destroyed or recovered, the camera is
+  removed and its feed ends
+
+`createCommandCamera` resolves with the new camera's `CameraState` once the
+game has built it and reported what it is watching, normally within a
+second or two, so `commandCentre.subjectPersistentId` and
+`commandCentre.targets` are already filled in. If that report has not come
+5 s after the camera appeared, it resolves with the state as it stands. The
+request carries a token (random unless you pass `token`) that the camera
+reports back as `commandCentre.token`; that is how the promise finds it,
+and how any other code can. A vantage the game can not find (an unknown
+body, site, station or craft) builds nothing, and the promise rejects after
+`timeoutMs` (default 35 s, since the game waits up to 30 s for a site to be
+placed).
+
+Lens reach depends on the vantage: a launch site camera has the tracking
+camera's lens at every Tracking Station level, a station's lens follows the
+Tracking Station's level in career, and surface and vessel vantages zoom
+fully.
+
+### Aiming
+
+`client.setCommandAim(flightId, aim)` points any command camera, and `null`
+returns it to its default: the active craft in flight, the configured craft
+at the Space Center. `createCommandCamera` takes the same `aim` as an option.
+The aim is one of:
+
+- `vessel`: follows the craft with that `persistentId` (any entry of
+  `commandCentre.targets`, whatever its eligibility)
+- `orbit`: follows a conic (`body`, `inclination`, `eccentricity`,
+  `semiMajorAxis`, `lan`, `argumentOfPeriapsis` in degrees and metres,
+  `meanAnomalyAtEpoch` in radians, `epoch`)
+- `positionAt`: follows a position you propagate yourself: `position` and
+  `velocity` as `[x, y, z]` relative to `body` in its non-rotating frame at
+  `ut`, carried on linearly
+- `surface`: holds a point on a `body` (`latitude`, `longitude`, `altitude`
+  in metres above sea level), turning with the planet
+- `direction`: holds a direction from the camera's local horizon,
+  `azimuth` degrees clockwise from north and `elevation` degrees above the
+  horizon
+
+The subject is the craft the camera draws (where it truly is, so an aim off
+the craft shows it off centre), brackets, sizes its zoom by and reads out. A
+`vessel` aim's craft is its subject; `orbit` and `positionAt` take an
+optional `subjectPersistentId`; otherwise the default craft stays the
+subject. A `direction` aim zooms for the subject's range, so the subject is
+framed as it passes through. Every kind takes `framingMarginM`, metres of
+view kept around the subject's own size. `commandCentre.aimKind` (absent for
+the default) and `commandCentre.subjectPersistentId` report what the game
+applied.
+
+### A launchpad camera
+
+```ts
+import { CommandVantageKind, KerbcastClient } from "@ksp-gonogo/kerbcast";
+
+const client = new KerbcastClient({ host: "192.168.1.74", port: 8088 });
+await client.connect([], { slots: 2 });
+
+// 500 m south of the active craft's launch site, 5 m up.
+const pad = await client.createCommandCamera(
+  { kind: CommandVantageKind.LaunchSite },
+  { name: "Pad south" },
+);
+
+const video = document.querySelector("video")!;
+client.camera(pad.flightId).on("stream", (stream) => {
+  video.srcObject = stream;
+});
+await client.subscribe(pad.flightId);
+
+// Later: the feed ends for every client.
+await client.destroyCommandCamera(pad.flightId);
+```
+
+`{ kind: CommandVantageKind.LaunchSite, site: "Runway", distance: 800,
+bearing: 90, height: 20 }` stands one 800 m east of the runway, 20 m up.
+
+### Between two vantages
+
+Here a camera stands on a rise west of the KSC and watches the launch pad,
+then a particular craft, then the sky above the pad, then whichever craft
+is active. The coordinates are illustrative.
+
+```ts
+import {
+  CommandAimKind,
+  CommandVantageKind,
+  type KerbcastClient,
+} from "@ksp-gonogo/kerbcast";
+
+declare const client: KerbcastClient; // connected as above
+
+const hill = await client.createCommandCamera(
+  {
+    kind: CommandVantageKind.Surface,
+    body: "Kerbin",
+    latitude: -0.08,
+    longitude: -74.75,
+    height: 10,
+  },
+  {
+    name: "West ridge",
+    // The pad: altitude is metres above sea level, and the margin keeps
+    // 60 m of view around the subject.
+    aim: {
+      kind: CommandAimKind.Surface,
+      body: "Kerbin",
+      latitude: -0.0972,
+      longitude: -74.5577,
+      altitude: 70,
+      framingMarginM: 60,
+    },
+  },
+);
+
+// Follow a particular craft, by Vessel.persistentId.
+await client.setCommandAim(hill.flightId, {
+  kind: CommandAimKind.Vessel,
+  persistentId: 4000000001,
+});
+
+// Hold still, looking east and 30 degrees up, for a launch to climb into.
+await client.setCommandAim(hill.flightId, {
+  kind: CommandAimKind.Direction,
+  azimuth: 90,
+  elevation: 30,
+});
+
+// Back to the default: the active craft.
+await client.setCommandAim(hill.flightId, null);
+```
+
+A station watching a craft is the same with
+`{ kind: CommandVantageKind.Station, station: "KSC" }` and a `vessel` aim.
+
+### The command lock
+
+A mod in game can take a lock on every command camera's aim
+(`KerbcastControl.SetCommandAuthority(owner)`). While it holds the lock only
+its own aims are accepted: `setCommandAim` rejects with a
+`CommandLockedError` (its `owner` names the holder) whenever the camera's
+`commandTrack.authority` reports one, and a call that races the lock being
+taken comes back as an `error` event with code `ErrorCode.CommandLocked`.
+`createCommandCamera` still creates the camera, at its default aim. When the
+lock is released every command camera returns to its default; aims set
+before or during the lock are not restored.
+
+The lock holds until its holder releases it (or the scene changes); it never
+times out. A holder that stops calling for 5 s blanks every command feed
+("gonogo not responding") but keeps the lock, so aims from anyone else are
+still refused. This is deliberate: a holder that delays commands (gonogo
+applies signal delay) can not be bypassed while it is unresponsive.
+
+### In game (C#)
+
+Another KSP mod can do the same through `Kerbcast.KerbcastControl`, with
+no sidecar round trip:
+
+```csharp
+using Kerbcast;
+
+// Returns the flightId the feed will have, or 0 when refused.
+uint pad = KerbcastControl.CreateCommandCamera(CommandVantage.LaunchSite());
+
+uint ridge = KerbcastControl.CreateCommandCamera(
+    CommandVantage.Surface("Kerbin", -0.08, -74.75, height: 10), "West ridge",
+    CommandAim.Surface("Kerbin", -0.0972, -74.5577, 70, framingMarginM: 60));
+KerbcastControl.SetCommandAim(ridge, CommandAim.Vessel(vessel.persistentId));
+KerbcastControl.SetCommandAim(ridge, CommandAim.Direction(azimuth: 90, elevation: 30));
+KerbcastControl.SetCommandAim(ridge, null); // back to the default
+
+KerbcastControl.DestroyCommandCamera(ridge);
+```
+
+Holding the lock:
+
+```csharp
+// Re-take it on every scene load; a different owner is refused.
+KerbcastControl.SetCommandAuthority("gonogo");
+
+// Only calls passing the owner are accepted now, and each is a heartbeat.
+KerbcastControl.SetCommandAim(pad, CommandAim.PositionAt("Kerbin", ut, pos, vel,
+    subject: craft.persistentId, framingMarginM: uncertaintyM), "gonogo");
+KerbcastControl.SetCommandAim(pad, CommandAim.Vessel(other)); // false: locked
+
+// Every command camera returns to its default.
+KerbcastControl.ClearCommandAuthority("gonogo");
+```
+
+- `CommandVantage.LaunchSite(site, distance, bearing, height)`,
+  `CommandVantage.Station(nodeName, height)`,
+  `CommandVantage.Surface(body, latitude, longitude, height)` and
+  `CommandVantage.Vessel(persistentId)` mirror the vantage kinds above, with
+  the same defaults
+- `CommandAim.Vessel(persistentId, framingMarginM = 0)`,
+  `Orbit(body, inc, e, sma, lan, argPe, meanAnomalyAtEpoch, epoch, subject = 0, framingMarginM = 0)`,
+  `PositionAt(body, ut, pos, vel, subject = 0, framingMarginM = 0)`,
+  `Surface(body, lat, lon, alt, framingMarginM = 0)` and
+  `Direction(azimuth, elevation, framingMarginM = 0)` mirror the aim kinds
+- `CreateCommandCamera(vantage, name = null, aim = null)` returns the
+  flightId at once; the feed appears when the vantage resolves, and
+  `SetCommandAim` works on it before then too. Under a held lock the aim is
+  not applied
+- `SetCommandAim(flightId, aim, owner = null)` returns false when the lock
+  refuses it, the feed is not a command feed, or the aim is unusable (a
+  craft that no longer exists, such as one docked into another, is
+  unusable)
+- The lock holds until `ClearCommandAuthority` or a scene change, and fails
+  closed: a holder that makes no call (`SetCommandAuthority`, `SetCommandAim`
+  with its owner, `SetCommandBlank`) for 5 s of real time blanks every
+  command feed "gonogo not responding" and keeps the lock, so everyone else
+  stays refused. `SetCommandBlank(flightId, reason)` blanks one feed
+- `DestroyCommandCamera(flightId)` returns false for the settings camera or
+  an unknown id
+- `CommandFeeds()` lists every built command camera, with its `Aim`,
+  `SubjectPersistentId`, and `Created` set on the ones made at runtime;
+  `CommandTargets(flightId)` lists the craft it could follow (a craft docked
+  into another drops out; the combined craft keeps the survivor's
+  `persistentId`)
+
 ## Pan/zoom input helper
 
 Driving pan and zoom from a gamepad stick, nudge buttons, or an FoV