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 |
{
"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 |
{
"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 |
{
"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' |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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' |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"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 |
{
"geometry": {
"limit": 20,
"sort": "triangles"
}
}