Debug Overlay

The host renders one unified debug stream overlay — a bottom-right, in-frame panel that combines the three developer surfaces behind a single toggle:

  1. Camera preview — a live, body-following crop of the host camera.
  2. Skeleton — the pose wireframe, drawn into the same crop.
  3. Perf metrics — CPU, render FPS, tracking FPS, memory, backend.

It is a host surface: it works in every session, over any game, with no game code and no query parameter. Your bundle ships nothing for it.

The F8 cycle

The overlay is available in player mode by default. Its mode cycle is the gate — off (the default) is the player state. Pressing F8 (or sending the debug-overlay-toggle remote action) cycles:

off  ->  preview  ->  preview-skeleton  ->  full  ->  off  ->  …
  • preview — camera crop only.
  • preview-skeleton — camera crop + pose wireframe.
  • full — everything, including perf metrics.

F8 works even when keyboard focus is inside the game iframe: the SDK forwards the keypress to the host (a sandboxed iframe's keydown never bubbles to the parent on its own). The overlay's DOM is created lazily on first show, so a session where nobody presses F8 stays DOM-clean.

F8 × 7: the developer-mode cheat code

Pressing the overlay toggle seven times within a rolling ~2.5 s window flips full developer mode at runtime:

  • The flag is persisted in localStorage (bltv.developerMode), a brief "Developer mode ON/OFF — reloading…" note is shown, and the page reloads after ~1 s so every developer gate re-evaluates — pose-source emulation (live / clip / keyboard), FTUE/menu skips, skip-to-round.
  • Toggling off removes the stored key rather than writing an explicit 0, so one toggle-off never becomes a permanent self-lock.
  • The seven presses visibly cycle the overlay while you enter them — that is expected.

The kill switch: ?developerMode=0

An explicit false anywhere in the developer-mode override chain — ?developerMode=0 on the URL, window.__bltvDeveloperMode = false, or a stored '0' — keeps the entire surface inert: no overlay, no F8 cycle, no cheat code, no DOM. This always wins, including over the manifest field below. Use it for demos, recordings, and kiosk installs.

coordinate.debugOverlay: the play-time initial mode

A bundle can declare where the overlay's cycle starts when the game is entered:

// bodylink.game.json
        {
          "coordinate": {
            "debugOverlay": "preview"   // "off" (default) | "preview" | "preview-skeleton" | "full"
          }
        }
  • Applies to all sessions, player mode included: entering the game starts the overlay at the declared position, and F8 cycles onward from there.
  • Unrecognized values fail quiet to "off" (the host records a warn diagnostic).
  • The ?developerMode=0 kill switch always wins — the overlay stays fully inert regardless of the declaration.
  • A bundle that declares nothing keeps the lazy, DOM-free default; a bundle declaring an on position intentionally mounts the overlay DOM at entry.

This is a manifest-contract 1.5.0 additive field on the coordinate namespace — older hosts ignore it.

What the preview shows: the body-following crop

The overlay's camera panel always renders a unit-scaled follow-crop (for every game, regardless of the game's coordinate mode): the framing box in real body units, centered on the framing anchor (shoulder midpoint for upper-body, hip midpoint for full-body), spanning ± 2 body units per axis. The unit is the same pose-invariant measure the ROI coordinate space uses — max(shoulderWidth, 0.7 × torsoHeight).

Because the unit scales with the player's distance from the camera, the crop zooms in and out as the player moves — keeping the body at constant apparent scale in the fixed panel. When no valid body basis exists (no landmarks, degenerate pose), the panel falls back to a fixed-fraction body-centered crop, so the preview never blanks.

Two things to know:

  • The overlay is the tracking view, not a coordinate-space mirror. For a roi-mode game the crop happens to coincide with the coordinate box; for full/undeclared games the crop is deliberately not the space your landmarks arrive in.
  • Known limitation: the zoom's scale invariance saturates at close range. The crop cannot grow beyond the camera frame, so once the player is close enough that the ± 2-unit box exceeds the frame, the crop clamps to the frame bounds and the body's apparent size starts growing again.

Related pages