Recipes

Assertion reference

Every assertion kind the playtest validator accepts, generated from the registry the validator itself reads, so this page cannot disagree with the runtime. Assertions fail closed: a malformed assertion throws at load, and a scenario whose assertions all hold trivially fails TN_PLAYTEST_SCENARIO_ASSERTS_NOTHING.

tone

Bounds display-referred luminance from a captured PNG frame, using a shared 256-bin histogram. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: browser.screenshot
Field Type Required
atStep non-empty string no
region { x: number, y: number, width: number, height: number } no
compare { region: object, metric: string, minDelta: number } no
mean { min?: number, max?: number } no
p1 { min?: number, max?: number } no
p50 { min?: number, max?: number } no
p99 { min?: number, max?: number } no
clipFraction { min?: number, max?: number } no
blackFraction { min?: number, max?: number } no
json
{
  "tone": [
    {
      "atStep": "landed",
      "mean": {
        "min": 60,
        "max": 140
      },
      "p99": {
        "min": 150
      }
    }
  ]
}

deviceMetrics

Reports the device's thermal, power and battery state around the run and judges whether the run is comparable with a cool one. Use when that is the thing the scenario must prove.

  • Supported on: android · Requires: device.metrics
Field Type Required
maxTemperatureRiseC finite non-negative number no
maxThermalStatus non-negative integer 0..6 no
notThermallyConfounded true no
json
{
  "deviceMetrics": {
    "maxTemperatureRiseC": 5,
    "notThermallyConfounded": true
  }
}

framebufferCoverage

Samples the framebuffer on every render frame inside a labeled loading window and requires every coarse-grid RGB sample to match the declared backdrop. Use when that is the thing the scenario must prove.

  • Supported on: browser, android · Requires: browser.screenshot
Field Type Required
backdrop [integer 0..255, integer 0..255, integer 0..255] yes
grid { columns: positive integer <= 256, rows: positive integer <= 256 } no
tolerance integer 0..255 yes
window { startStep: string, endStep: string } yes
json
{
  "framebufferCoverage": {
    "backdrop": [
      5,
      7,
      11
    ],
    "grid": {
      "columns": 32,
      "rows": 18
    },
    "tolerance": 8,
    "window": {
      "endStep": "loading-end",
      "startStep": "loading-start"
    }
  }
}

aerodynamics

Proves aerodynamic force telemetry and signed control-surface delivery for a flight entity. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: runtime.fixedStep, runtime.physics
Field Type Required
entity string yes
minForceSamples positive integer no
controls Array<{ surface: string, sign: 'negative' 'positive', minAbs?: number }>
torques Array<{ label: string, relativeToLabel?: string, axis: 'x' 'y'
json
{
  "aerodynamics": [
    {
      "controls": [
        {
          "sign": "negative",
          "surface": "elevator"
        }
      ],
      "entity": "aircraft",
      "minForceSamples": 4
    }
  ]
}

visual

Proves screenshot change, populated coordinate or DOM element-bound regions, dark-pixel bounds, and sustained projected entity visibility. Use when that is the thing the scenario must prove.

  • Supported on: browser · Requires: browser.screenshot
Field Type Required
frameDiff { baselineImage?: project-relative PNG, minChangedPixelRatio?: number, maxChangedPixelRatio?: number } no
region static bounds { x: number, y: number, width: number, height: number, minSharpness?: number, minNonblankPixelRatio?: number, maxDarkPixelRatio?: number, minDarkPixelRatio?: number, maxLuminance?: number } or element bounds { element: { id?: string, selector?: string }, minNonblankPixelRatio?: number, maxDarkPixelRatio?: number, minDarkPixelRatio?: number, maxLuminance?: number } no
entityVisible { entity: string, minProjectedPixels: number, throughoutFrames?: boolean } no
json
{
  "visual": [
    {
      "frameDiff": {
        "baselineImage": "artifacts/baseline.png",
        "minChangedPixelRatio": 0.01
      },
      "entityVisible": {
        "entity": "board.e4",
        "minProjectedPixels": 20,
        "throughoutFrames": true
      },
      "region": {
        "element": {
          "id": "error"
        },
        "minNonblankPixelRatio": 0.002
      }
    }
  ]
}

movement

Proves the subject moved, reached a minimum velocity, or changed rotation during held input. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: entity.observe
Field Type Required
entity string no
closesDistanceToPosition { position: [number, number, number], min: number } no
facesMovementWithinDegrees number no
axis string no
minAxisDelta { axis: string, min: number } no
minResolvedAxisDelta { axis: string, min: number } no
maxTiltDegrees number in [0, 180] no
minDistance number no
maxDistance number no
minVelocity number no
pathLength number no
notFacing { entity: string, minDegrees: number } no
notFacingPosition { position: [number, number, number], minDegrees: number } no
reachesPositionWithin { position: [number, number, number], maxDistance: number, atStep?: string } no
rotationChanged boolean no
json
{
  "movement": {
    "entity": "player",
    "minDistance": 0.5,
    "minVelocity": 0.01,
    "rotationChanged": true
  }
}

camera

Proves a camera follows an entity or keeps a target in view. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: camera.observe, entity.observe
Field Type Required
entity string no
follows string no
within number no
targetInViewport boolean no
json
{
  "camera": {
    "entity": "camera.main",
    "follows": "player",
    "within": 10,
    "targetInViewport": true
  }
}

components

Proves a live entity component value after the scenario or at named steps. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: runtime.components
Field Type Required
entity string yes
component string yes
path string no
equals json no
gte number no
lte number no
changed boolean no
atSteps Array<{ label: string, equals: json }> no
allowTrivial triviality reason no
json
{
  "components": [
    {
      "component": "Camera",
      "entity": "camera.main",
      "path": "fovY",
      "equals": 22,
      "changed": true
    }
  ]
}

resources

Proves resource state after the scenario through equals, gte, lte, textIncludes, or changed checks. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: runtime.resources
Field Type Required
id string yes
path string no
equals json no
gte number no
lte number no
textIncludes string no
changed boolean no
throughoutSteps boolean no
atSteps Array<{ label: string, equals?: json, lte?: number, textIncludes?: string }> no
allowTrivial triviality reason no
anyOf Array<{ path: string, equals?: json, gte?: number, lte?: number, textIncludes?: string, changed?: boolean }> no
json
{
  "resources": [
    {
      "id": "GameState",
      "path": "score",
      "gte": 1,
      "changed": true
    }
  ]
}

tags

Proves the final count of entities carrying a bounded runtime tag. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: runtime.tags
Field Type Required
tag string yes
count non-negative integer no
gte non-negative integer no
lte non-negative integer no
allowTrivial triviality reason no
json
{
  "tags": [
    {
      "tag": "coin",
      "count": 10
    }
  ]
}

signals

Proves a named Godot signal was emitted by the application during the run or at a labeled step. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: runtime.events
Field Type Required
atStep string no
entity string no
maxCount non-negative integer no
minCount non-negative integer no
name string yes
json
{
  "signals": [
    {
      "name": "collected",
      "entity": "player",
      "minCount": 3,
      "atStep": "last-coin"
    }
  ]
}

states

Proves an observed entity's final runtime-owned state-machine state. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: runtime.state
Field Type Required
entity string no
equals string yes
allowTrivial triviality reason no
json
{
  "states": [
    {
      "equals": "completed"
    }
  ]
}

hud

Proves retained UI/HUD text or values after the scenario. Use when that is the thing the scenario must prove.

  • Supported on: browser · Requires: browser.dom
Field Type Required
id string yes
path string no
equals json no
gte number no
lte number no
textIncludes string no
changed boolean no
allowTrivial triviality reason no
visible boolean no
json
{
  "hud": [
    {
      "id": "score-label",
      "textIncludes": "Score"
    }
  ]
}

diagnostics

Proves console, network, runtime, and readiness diagnostics stayed clean. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: browser.console, browser.network, runtime.diagnostics
Field Type Required
noConsoleErrors boolean no
noNetworkErrors boolean no
noRuntimeDiagnostics boolean no
consoleErrorsOptOutReason non-empty string no
networkErrorsOptOutReason non-empty string no
runtimeDiagnosticsOptOutReason non-empty string no
runtimeReady boolean no
json
{
  "diagnostics": {
    "noConsoleErrors": true,
    "noNetworkErrors": true,
    "noRuntimeDiagnostics": true,
    "runtimeReady": true
  }
}

performance

Proves a live render sample exists and optionally bounds frame time, an fps floor, per-phase frame budget, whole-frame or per-pass draw calls and triangles. Use when that is the thing the scenario must prove.

  • Supported on: browser, desktop · Requires: runtime.performance
Field Type Required
maxFrameMsP95 number no
maxFrameMsReason non-empty string no
minFps number no
maxPhaseMsP95 { [phase]: number } no
maxDrawCalls number no
maxPassDrawCalls { [pass: 'main' 'shadow'
maxPassTriangles { [pass: 'main' 'shadow'
maxTriangles number no
json
{
  "performance": {
    "maxPassDrawCalls": {
      "shadow": 400
    },
    "maxPhaseMsP95": {
      "render": 12
    },
    "minFps": 30
  }
}

parity

PRD-222 Tier 2: proves the fps ratio of a parity pair — the same scene on the same device, once in the browser and once native. Lives in the second run and names the first run's saved report; refuses a pair whose halves ran on different devices, a thermally confounded half, or a missing series on either side. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: runtime.performance
Field Type Required
minFpsRatio positive number no
minRenderParity positive number no
referenceReport non-empty string no
referenceSide 'browser' or 'native' no
reference object no
json
{
  "parity": {
    "minFpsRatio": 0.85,
    "referenceReport": "reports/native.json",
    "referenceSide": "native"
  }
}

visibility

Proves projected entity visibility in the viewport. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: entity.bounds
Field Type Required
entity string no
minProjectedPixels number no
maxOffscreenRatio number no
present boolean no
allowTrivial triviality reason no
json
{
  "visibility": [
    {
      "entity": "player",
      "minProjectedPixels": 1200,
      "maxOffscreenRatio": 0.05
    }
  ]
}

audio

Proves which labelled audio cues the game actually played, and how often. Use when that is the thing the scenario must prove.

  • Supported on: browser, desktop · Requires: runtime.audio
Field Type Required
cue string yes
minPlays non-negative integer no
maxPlays non-negative integer no
minGapMs non-negative integer no
json
{
  "audio": [
    {
      "cue": "speech:p01",
      "maxPlays": 1
    }
  ]
}

world

Proves runtime world metadata exposed by the application bridge. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: runtime.world
Field Type Required
seed json yes
runtime object no
json
{
  "world": {
    "seed": 90210
  }
}

contacts

Proves contact or trigger evidence appeared in the effect log. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: runtime.contacts
Field Type Required
atStep string no
entity string no
with string no
kind string no
minCount number no
maxCount non-negative integer no
requiredOn Array<'web' 'desktop'
json
{
  "contacts": [
    {
      "entity": "player",
      "with": "pickup",
      "kind": "trigger",
      "minCount": 1
    }
  ]
}

settled

Proves an observed cohort of matching physics bodies is asleep in a retained physics-debug sample. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: runtime.physics
Field Type Required
entity string no
atStep string no
minBodies positive integer no
compareToStep string no
minMeanPoseDistance positive number no
requiredOn Array<'web' 'desktop'
allowTrivial triviality reason no
json
{
  "settled": [
    {
      "atStep": "fall-and-settle",
      "minBodies": 15
    }
  ]
}

animation

Proves animation evidence appeared in the effect log or runtime observation. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: runtime.animation
Field Type Required
entity string no
clip string no
atStep string no
entered boolean no
advancedFrames number no
finished boolean no
maxFootSlide number no
strideSynced boolean no
allowTrivial triviality reason no
json
{
  "animation": [
    {
      "entity": "player",
      "clip": "run",
      "entered": true,
      "advancedFrames": 5,
      "finished": false
    }
  ]
}

scene

Bounds the room the game is played in — the lights, materials, fog and camera framing the renderer was handed. Fails closed on a bridge that does not report the scene. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: scene.observe
Field Type Required
cameraClearsScene boolean no
fogClearsScene boolean no
litMaterialsAreLit boolean no
minVisibleLights number no
allowTrivial triviality reason no
json
{
  "scene": {
    "litMaterialsAreLit": true,
    "minVisibleLights": 1
  }
}

sceneNodes

Bounds on named nodes of the scene graph — where an object is, whether it is on screen, whether its textures loaded. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: scene.nodes
Field Type Required
select object no
visible boolean no
inFrustum boolean no
texturesLoaded boolean no
animated boolean no
minCount number no
maxCount number no
minTriangles number no
json
{
  "sceneNodes": [
    {
      "inFrustum": true,
      "select": {
        "nameContains": "crate"
      },
      "texturesLoaded": true,
      "visible": true
    }
  ]
}

footSlip

Bounds how far a planted foot slides while the subject moves, measured every tick from named foot nodes' world positions, so it holds a procedural rig to the feet-meet-the-floor convention as well as a clip. Browser target only; another target fails it as unobserved. Use when that is the thing the scenario must prove.

  • Supported on: browser · Requires: entity.observe, scene.nodes
Field Type Required
atStep string no
feet Array no
maxSlip positive number no
maxSlideSpeed positive number no
stepSeconds positive number no
entity string no
json
{
  "footSlip": [
    {
      "atStep": "run",
      "feet": [
        "footL",
        "footR"
      ],
      "maxSlip": 0.35
    }
  ]
}

sightLine

Bounds the share of the run in which solid geometry stood between the camera and the subject's world bounds centre, so a camera that clips through a pillar or a wall that eats the framing fails. Browser target only; another target fails it as unobserved. Use when that is the thing the scenario must prove.

  • Supported on: browser · Requires: camera.observe, entity.observe
Field Type Required
entity string no
maxBlockedRatio number yes
json
{
  "sightLine": {
    "maxBlockedRatio": 0.02
  }
}

engineCost

Bounds the engine's own work counters, read off each TN_FRAME_BUDGET window's counters.engine (and counters.bridgeCrossings): JS-to-Wasm crossings, children reads, scene-walk visits, hierarchy moves, matrix composes, handle shares, content classification, GPU allocations, physics crossings and any counter an engine module adds to globalThis.__tnEngineCost. Each window must hold every bound; a run with fewer windows than minWindows, or a window missing a bounded counter, fails closed. A failure names the counter, the window and the top caller of the TN_BRIDGE_CENSUS before it. Use when that is the thing the scenario must prove.

  • Supported on: browser, desktop · Requires: browser.console
Field Type Required
maxPerFrame { [counter: string]: number } no
maxInFrame { [counter: string]: number } no
minWindows positive integer no
skipWindows non-negative integer no
still { windows: positive integer, maxPerFrame: { [counter: string]: number } } no
moving { maxPerFrame?: { [counter: string]: number }, maxInFrame?: { [counter: string]: number } } no
source string yes
json
{
  "engineCost": {
    "maxPerFrame": {
      "bridgeCrossings": 2000,
      "childrenReads": 60
    },
    "skipWindows": 1,
    "source": "shooter after-value 1,024 per frame on 2026-10-27, about 2x headroom"
  }
}

hudAudit

Audits the text the page draws for the player: developer left-overs such as debug, TODO, placeholder or an unresolved undefined, and text whose colour is too close to its backing colour. Browser target only; another target fails it as unobserved. Use when that is the thing the scenario must prove.

  • Supported on: browser · Requires: browser.dom
Field Type Required
minContrast number no
noDebugText true no
json
{
  "hudAudit": {
    "minContrast": 3,
    "noDebugText": true
  }
}

causedBy

Relates a tick-stamped effect to the tick-stamped cause that must precede it — the 'because' a terminal state needs. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: runtime.transitions
Field Type Required
cause object no
effect object no
neverBefore boolean no
withinTicks number no
json
{
  "causedBy": [
    {
      "cause": {
        "contact": {
          "entity": "player",
          "kind": "trigger",
          "with": "seal"
        }
      },
      "effect": {
        "becomes": "won",
        "path": "state.status"
      },
      "neverBefore": true,
      "withinTicks": 4
    }
  ]
}

startup

Bounds when the application's startup milestones happened: the world entered, first-use compilation settled, readiness reached — in milliseconds since navigation, from the runtime's own startup timeline. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: runtime.startup
Field Type Required
maxEnteredMs number no
maxCompileSettledMs number no
maxReadyMs number no
maxOffscreenBytes number no
steadyCover boolean no
json
{
  "startup": {
    "maxEnteredMs": 2500,
    "maxReadyMs": 8000
  }
}

pipelineCensus

Bounds node-builder state builds and render-pipeline creations after a complete runtime capture proves that explicit shader warm-up settled; a named streamed scope must also prove its target-bound first visible world frame, and missing, incomplete, or malformed census evidence fails closed. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: runtime.pipelineCensus
Field Type Required
maxNodeBuildsAfterWarmUpSettled non-negative integer no
maxRenderPipelineCreationsAfterWarmUpSettled non-negative integer no
warmUpScope string no
maxNodeBuildsAfterWarmUpScope non-negative integer no
maxRenderPipelineCreationsAfterWarmUpScope non-negative integer no
json
{
  "pipelineCensus": {
    "maxNodeBuildsAfterWarmUpSettled": 0,
    "maxRenderPipelineCreationsAfterWarmUpSettled": 0
  }
}

renderChain

Proves the render chain reports its quality tier, authored stage ids/order, graph-output changes for named stages, and, when asserted, a bounded temporal-history rejection fraction. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: runtime.renderChain
Field Type Required
tier string no
stages object no
contributions object no
velocity object no
perAdapter object no
json
{
  "renderChain": {
    "tier": "high",
    "stages": {
      "includes": [
        "outline",
        "kuwahara",
        "watercolor"
      ],
      "order": [
        "outline",
        "kuwahara",
        "watercolor"
      ]
    },
    "contributions": {
      "graphOutputChanged": [
        "outline",
        "kuwahara",
        "watercolor"
      ]
    }
  }
}

geometry

Arms a per-object geometry capture (triangles, draws, projected size) and requires the bridge to report a captured frame; the request carries no bounds of its own. Use when that is the thing the scenario must prove.

  • Supported on: browser, android, desktop, ios · Requires: runtime.geometry
Field Type Required
limit number no
sort string no
timeoutMs positive number no
json
{
  "geometry": {
    "limit": 20,
    "sort": "triangles"
  }
}
Edit this page on GitHub ↗