@womp/kakapo-sdk

Typed Node.js and browser SDK for manipulating a Kakapo scene through its JSON-RPC WebSocket.

yarn install
yarn build

import { KakapoAPI } from "@womp/kakapo-sdk";

const kakapo = new KakapoAPI();
await kakapo.connect();

const union = await kakapo.editScene((scene) => {
  const root = scene.createNode({
    kind: "union",
    parentId: 0,
    name: "Agent Model",
  });

  const box = scene.createNode({
    kind: "primitive",
    parentId: root.id,
    name: "Body",
    properties: {
      primitive: "box",
      transform: { scale: { x: 10, y: 4, z: 6 } },
    },
  });

  const red = scene.createMaterial({
    color: { x: 1, y: 0.05, z: 0.05 },
    roughness: 0.4,
  });

  const body = scene.node(box.id, "primitive");
  body.materialId = red.id;
  body.position = { x: 0, y: 4, z: 0 };
  body.round = 0.2;
  body.save();
  return root;
});

console.log(await kakapo.getNodeBoundingBox(union.id));

kakapo.disconnect();

The transport uses the browser's native WebSocket when bundled for the web and loads ws dynamically in Node.js.

All public inputs are checked at runtime as well as by TypeScript. Invalid calls throw structured KakapoValidationError objects with a stable code, offending path, expected rule, and a correction hint intended for automated agents.

editScene() refreshes once, exposes synchronous JSON reads and mutations, then validates and sends one RFC 6902 patch after the callback succeeds. Callback or commit failures discard the draft and refresh the authoritative scene. node(id, kind) returns a typed editable handle; save() applies its staged properties synchronously to the transaction draft.

Engine-backed reads such as bounding boxes and screenshots remain asynchronous. Run them before the first draft mutation or after editScene() commits.

Each editScene() refreshes before creating its private draft. Top-level edits are serialized per client. Calling a scene-mutating method through raw rpc() deliberately marks the cache stale.

Mesh, field, and decal names are syntax-checked, but their existence cannot be enumerated by the current engine RPC surface. Font family/weight/style combinations are checked against listFonts().

Verification

yarn test       # fake WebSocket protocol and API behavior
yarn test:live  # launches ../kakapo/kakapo_app.exe and runs named live tests per API method
yarn test:all   # runs both suites

The live suite starts Kakapo once, runs methods sequentially, and reports failures as names such as live:setNodeParent or live:createNode:mesh. Mutations refresh the authoritative engine scene before asserting their result. See TEST_MATRIX.md for the exact unit/live mapping.