Recipes
The debug surface — probing a running game
The bridge globals exist but were discovered by trial: six throwaway probe scripts in one day, each re-finding the shapes through TypeErrors. This page lists every global a running game exposes, what it returns, and how to read it from the browser console. All of them are read-only observation surfaces; none exists to drive gameplay.
On this page
One debug switch and one report window
Set TN_DEBUG=1 in the host environment, add ?tnDebug=1 to the browser URL, or assign
globalThis.__THREENATIVE_DEBUG__ = true before the game boots. A console assignment after boot
does not install instrumentation retroactively. Worker boot must receive the flag before its game
module evaluates. The switch enables incumbent spans/counters and debug producers for bridge,
callbacks, scene/renderer/GPU, memory, loading, host and UI activity.
TN_FRAME_BUDGET.counters.engine contains numeric per-frame summaries by name (samples, mean,
percentiles and max). One TN_DEBUG_REPORT for that same window ranks observed costs with
basis, caller and a matching lever where available. Read the units before comparing:
| Basis | Meaning |
|---|---|
| Measured CPU milliseconds/share | Timed synchronous work divided by the observed frame interval. Parent phases and nested callbacks overlap; adding them double-counts work. |
| Getter-equivalent estimate | Crossing count times a measured getter calibration. This estimates boundary overhead; it does not time every invoke, set or write. |
| Counts and bytes | Work or traffic observed, with unavailable cost unless separately timed. A large total alone is no measured CPU share. |
| Asynchronous wall time | Time until a decode, GPU sample or completion arrives; it can overlap other work and is not synchronous CPU/GPU duration. |
Debug windows expose durationMs between completed report boundaries, including host gaps.
Count/byte observations include perSecond derived from that duration. The first window,
zero/unavailable duration, missing frame samples or a truncated summary ring leave the rate null.
Worker traffic reports shallow UTF-16/primitive byte estimates and explicit unmeasured nested
fields, rather than claiming structured-clone wire sizes. HUD serialized bytes are exact UTF-8.
Asset dispatch costs name each URL; asynchronous load/decode wall time stays out of CPU rankings.
textureMainThreadDecodeFallbacks identifies the image-element path, whose later decode CPU cost
is unavailable. Shared TRS writes include unchanged writes; pure math values stay outside the
scene-transform census. GPU created/freed bytes begin at diagnostic activation, without claiming
an inventory of earlier allocations.
Native V8 installs GC prologue/epilogue callbacks only after debug activation and reports
gcPauses/gcPauseMs; shutdown removes them. Browser/Wasm GC entries are optional platform
observations, so an unavailable GC observer leaves those counters absent.
GPU query results can arrive in a later frame. Join requested/resolved/delivered sample identity
before comparing cadence or attributing a duration to a world draw. Queue completion delivery
delay, host gaps and measured GPU execution are separate observations. An unsupported observer or
counter remains absent; treat it as unmeasured rather than a zero. Shared Wasm/native counter names
do not establish that desktop or Android has executed; those claims require their actual lanes.
The owned renderer's current CMake adapters reject Android/iOS; forwarding a debug flag to the
legacy host supplies no shared-renderer parity on those platforms.
findings.share: null means the finding has no corresponding measured cost; it is not zero cost.
TN_HOT_CALL, TN_BRIDGE_WARNING and TN_SCENE_WARNING are actionable performance warnings;
playtest fails them even when console-error checks are opted out. TN_DEBUG_REPORT is diagnostic
and does not itself fail a run. Bound its numeric source through assert.engineCost, using the
exact names from TN_FRAME_BUDGET.counters.engine; a missing or unmeasured bounded counter fails.
The engine-only smoke scenario reuses the native-smoke game without changing its gameplay:
node packages/playtest/dist/runner/cli.js examples/native-smoke/playtests/debug-telemetry.playtest.json \
--url 'http://127.0.0.1:5173/?tnDebug=1' \
--server-command 'pnpm --filter threenative-native-smoke dev --host 127.0.0.1 --port 5173' \
--browser-recipe webgpu --headedIt requires a debug-only callback counter in an actual budget window and bounds it by the loop's five-step cap. This proves the observation path when run; it does not qualify every producer or claim a device lane. Debug-off retains the existing census without installing debug observers, timers or call stacks.
window.__THREENATIVE__ — entity snapshot (dev builds only)
Installed by defineGame when the dev-server flag is on (installDevTools); absent in
production builds.
window.__THREENATIVE__.snapshot()
// → { entities: [{ id, kind?, ...entity debug fields }], ... }snapshot() prefers an entity's own debug() and falls back to autoFields. This is the
fastest "what does the game think exists" probe; playtest assertions and the dev overlay
read the same registry.
window.__THREENATIVE_PLAYTEST_BRIDGE__ — the harness channel
Installed by playtest() (core plugin) or installThreePlaytestBridge
(@threenative/playtest/three). One object, JSON-safe in and out:
| Member | Shape | Use |
|---|---|---|
describe() |
{ name, protocolVersion, capabilities, limits } |
First call. Tells you what this game's bridge supports and the protocol limits. |
ready() |
{ ready: true } |
Liveness check before sampling. |
sample(request) |
JSON-safe observation snapshot (entities, camera, renderer stats, resources, components, and scene: the lights, materials, fog, background, camera framing and world extent) |
The main probe. Pass {} for the default sample; request.include names optional series such as physicsDebugSeries. |
advance(ticks) |
fixed-step bridges only: advances exactly N ticks and returns { clock, ticks }; throws if the step count mismatches |
Deterministic stepping without wall-clock waits. Throws when the bridge is render-frame. |
applySetup(request) |
applies scenario setup placements/resources through the registry |
What scenario setup uses; also usable by hand for one-off staging. |
drainEvents(limit) |
event-queue bridges only: returns up to limit queued events |
Reads events shorter than one state flush. |
A console one-liner that works on any bridged game:
await window.__THREENATIVE_PLAYTEST_BRIDGE__.describe()Missing global means no bridge is installed — semantic assertions against that page fail
TN_PLAYTEST_BRIDGE_MISSING, which is the harness being right, not a bug to work around.
window.__THREENATIVE_NATIVE__ — native host channel
Present only under the native runtime. The host injects its side; core's viewport and
@threenative/playtest/three's device reporting read it (adapter identity, host snapshot).
On web this global does not exist — do not probe for it in portable code.
Scene-entry markers
TN_ENVIRONMENT_TOO_SMALL: scene-entry console error; use an equirectangular environment at least 64 pixels wide for PMREM.
TN_OPACITY_TRANSPARENT: scene-entry console warning; the engine turned transparent on for visible materials with opacity < 1 so the authored opacity takes effect. Override on the material: alphaHash: true, or opacity: 1 for an opaque surface.
TN_OPACITY_IGNORED: printed by a direct renderTrapAudit(scene) call for a material that still ignores its opacity.
Markers print at the Verbose (console.debug) level in the browser console, so DevTools hides them
by default; harnesses still receive them. Open the page with ?tnLog=1 to print them normally.
Runner-side markers
Two further globals are set by tooling, not the game, and are named here so a stray
assignment is recognisable: __THREENATIVE_PLAYTEST_RUNNER_EXPECTED__ (core's playtest
plugin marks the expected runner contract) and __THREENATIVE_FRAMEBUFFER_COVERAGE_PROBE__
(the framebufferCoverage assertion installs its sampler). Leave both alone in game code.
What does not exist
There is no __THREENATIVE_SCENE__ global. Scene-graph inspection goes through
sample() — which reports counts, extents and visibility, and under scene the lights,
materials, fog, background and camera framing the renderer was handed — or through your
own registered entities' debug() output, never by reaching into three.js objects from
the console and treating what you find as an observation surface.
scene counts and names; it does not read texture contents or shader graphs, and a scene
past the walk's cap reports truncated: true so a floor is never read as a total. A value
the scene does not carry is absent rather than zero.