Skip to content

SDK Overview

The Plantangenet SDK gives external clients a way to interact with a running world-runner instance — reading simulation state, subscribing to the frame stream, and (in Phase II) issuing movement commands to drive hobs through the locations system.

Two language implementations are maintained side-by-side under sdk/:

SDK Path Primary use
JavaScript sdk/js/ Browser tooling, Node.js scripts, headless test automation
Python sdk/py/ Pytest integration tests, data-science pipelines, CLI tooling

Both SDKs share the same design philosophy:

  • WorldRunnerHarness — spawns and terminates plant_world_runner for testing; bootstraps the magic-link auth flow automatically.
  • WorldRunnerClient — authenticated HTTP + WebSocket client covering /status, /clock, /atoms, /services, and the /stream WebSocket.
  • HobDriver — high-level per-hob wrapper for reading state and observing stream events; will gain movement methods in Phase II.

Authentication

world-runner uses cookie-session auth backed by a magic-link flow. In --dev mode (used by all test harnesses):

  1. POST /auth/magic {"email": "..."} — the server prints MAGIC_LINK_TOKEN token=<T> email=<E> to stdout.
  2. GET /auth/verify?token=<T> — exchanges the token for a Set-Cookie session header.
  3. All subsequent requests carry that cookie.

The harnesses in both SDKs automate this entirely — callers just call harness.start() / await harness.start() and receive a fully authenticated client.

WebSocket stream

The /stream WebSocket endpoint broadcasts StreamEvent messages as the simulation advances. Events carry:

{ "event": "heartbeat", "path": "world/runtime/frame_id", "value": 0 }

The stream is filtered server-side by prefix and/or entity_id query parameters. An initial heartbeat is delivered immediately on connect so clients can validate the message shape.

Next steps