BodyLink Developer Docs

BodyLink brings full-body and hand tracking to XR. As a game developer, you build a small web game, package it as a self-contained Runtime v1 iframe bundle, and ship it to the BodyLink catalog — where it runs inside any BodyLink host with live body-pose input streamed to your game.

Your game receives tracking frames (hand/body pose) over a sandboxed iframe bridge and sends back gesture and gameplay events. You never touch the host runtime or the tracking pipeline directly — you target one small, stable SDK surface, and the platform does the rest.

This site is the canonical, public home for building on BodyLink — start here, and read in this order.

Build your first game (read in order)

New to BodyLink? Follow this path top to bottom and you'll go from an empty folder to a submittable game.

  1. Your First Game with Vite — the complete happy path: create-bodylink-game → npm run dev → edit + hot-reload → the Dev HUD → build / validate / export:zip. Copy-paste, with a "what you should see" after every step.
  2. game-kit API Reference — createBodyLinkGame(...), the tracking-frame shape, input events, tracking-readiness, and the handshake.
  3. Manifest Reference — every bodylink.game.json field, annotated (runtimeRange, coordinate, trackingTier, launcher.trackingPolicy).
  4. Dev HUD & Debug Modes — press `, not URLs. Every debug toggle and its URL-flag fallback.
  5. Vite Config & Build — how the build works, the codeSplitting:false blank-bundle trap, and dev:hosted.
  6. SDK Channels — Alpha / Beta / Stable: develop on Alpha, ship on Stable (production requires it).
  7. Getting Updates — your folder is a snapshot: why merges never touch your disk, the two-command update, the npm ls bodylink-platform truth-check, and the recovery block.
  8. Troubleshooting (Vite) — blank bundle, white-screen, SDK/SRI failure, missing tracking frames, export failures.

Reference & submission

  • External Developer Agent Release Runbook — the one paste-ready prompt for a nonprogrammer. The agent tests, builds, authorizes with one-shot OAuth, confirms the exact digest, produces staging evidence, and prepares the separate human-reviewed production submission.
  • Developer Guide — the end-to-end story: build a valid bundle, run the validation gate locally, and submit through the developer portal.
  • Validation Reference — the named-check codes the submission gate emits, what each means, and the recommended fix. Consult this when a submission is rejected.
  • Developer Portal Guide — signup, upload, the validation report, reviewer approval, and resubmission.

Feature guides

  • Camera Preview & Coordinates — the coordinate modes (full / roi), the framing axis, consuming normalized tracking frames, and directing the host-composited camera preview slot.
  • No-Calibration Opt-In — stream pose frames at entry with no get-ready ceremony (coordinate.calibration: "none").
  • Debug Overlay — the host tracking view: the F8 mode cycle, the developer-mode cheat code, and the coordinate.debugOverlay manifest field.
  • Camera Photo — the capability-gated, single-shot host-captured still photo.

Shipping & delivery

  • Allowed Parent Origins — what to list in allowedParentOrigins, local dev ports, and host-origin migrations.
  • SDK Delivery & SRI — the hashed runtime SDK files, the integrity pins that must agree, and line-ending discipline.

What you ship

A shipped BodyLink game is a Runtime v1 iframe bundle: an offline, opaque-origin iframe rooted at games/<slug>/, containing:

  • index.html — the entry point (an entry.kind: "iframe" entry).
  • bodylink.game.json — the game manifest (id, version, entry, capabilities, the launcher display/tracking block, the iframe-session security policy).
  • bodylink.bundle.lock.json — an integrity lock that SRI-pins the runtime SDK.
  • Your built game assets, all bundle-relative.

Bundles are immutable per <slug>@<version> — a new release is a new version under the same slug. You do not hand-assemble a bundle: the SDK toolchain scaffolds, builds, and exports it for you.

Quickstart

The path from nothing to a live game is: scaffold → build → validate → submit.

1. Scaffold

Start from the canonical game template (Node 20+ required). The scaffolder creates a standalone game project wired against the BodyLink SDK:

npx create-bodylink-game ring-rally
        cd ring-rally
        npm install
        npm run dev   # standalone dev server; open the in-game developer tour

Your game imports only the SDK surface (game-kit and iframe-sdk). Most games use the high-level createBodyLinkGame(...) entry point; a lower-level client is available when you need direct control of the bridge.

2. Build the bundle

When your game is ready, export it. The export step builds your game and emits a downloadable, self-contained bundle — every module specifier resolved and inlined, the runtime SDK SRI-pinned:

npm run export:zip   # build -> SDK-only bundle -> <id>@<ver>.zip

This is the single most important habit: a real bundle is built output, not raw source. Opaque-origin iframes cannot fetch modules at runtime, so unbuilt source (bare imports, dev-server paths) is always rejected.

3. Validate locally

Run the exact same gate the developer portal runs, before you ever upload:

node scripts/validate-submission.mjs <bundle-dir> --report

The gate is fail-closed: it rejects by default and only passes a bundle that satisfies every static check. Each failure names the failing check and a one-line recommended fix — the same report the portal shows you. See the Validation Reference for every code.

4. Submit

First run the scaffold's release preflight — it dry-runs every submission requirement (version sync, live-SDK SRI pin, the size cap, release hygiene) and tells you exactly what to fix before the portal does:

npm run release:preflight   # only submit on `PREFLIGHT: PASS`

If you use a coding agent, give it the External Developer Agent Release Runbook. The direct one-shot OAuth upload confirms exact bytes and produces validation/ staging evidence only (productionEligible=false). Current external production is a separate authenticated Portal upload of a new higher version, followed by a distinct BodyLink human reviewer who plays the staged game and approves or rejects it.

You do not get direct write access to the catalog. Every game reaches production through authenticated submission → validation → staging play → distinct human review → publish.

Ready to build? Start with the Developer Guide.