Assertion reference

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: web, desktop, bevy · Requires: device.metrics

{
  "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: web, desktop, bevy · Requires: browser.screenshot

{
  "framebufferCoverage": {
    "backdrop": [
      5,
      7,
      11
    ],
    "grid": {
      "columns": 32,
      "rows": 18
    },
    "tolerance": 8,
    "window": {
      "endStep": "loading-end",
      "startStep": "loading-start"
    }
  }
}

reachability

Checks every consecutive platform against a measured static movement-envelope fit; it does not simulate traversal, walls, ceilings, run-up, or air control. Use when that is the thing the scenario must prove.

• Supported on: web, desktop, bevy · Requires: entity.observe

{
  "reachability": {
    "artifact": "artifacts/character-envelope/player.json",
    "entities": [
      "platform.a",
      "platform.b"
    ]
  }
}

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: web, desktop, bevy · Requires: runtime.fixedStep, runtime.physics

{
  "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: web · Requires: browser.screenshot

{
  "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: web, desktop, bevy · Requires: entity.observe

{
  "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: web, desktop, bevy · Requires: camera.observe, entity.observe

{
  "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: web, desktop, bevy · Requires: runtime.components

{
  "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: web, desktop, bevy · Requires: runtime.resources

{
  "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: web, desktop, bevy · Requires: runtime.tags

{
  "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: web, desktop, bevy · Requires: runtime.events

{
  "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: web, desktop, bevy · Requires: runtime.state

{
  "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: web · Requires: browser.dom

{
  "hud": [
    {
      "id": "score-label",
      "textIncludes": "Score"
    }
  ]
}

overlayNodes

Proves DOM state inside a same-origin webview overlay iframe. Use when that is the thing the scenario must prove.

• Supported on: web · Requires: browser.dom

{
  "overlayNodes": [
    {
      "attribute": "data-aiming",
      "equals": "true",
      "overlayId": "game-ui",
      "selector": "[data-testid=fps-crosshair]",
      "visible": false
    }
  ]
}

diagnostics

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

• Supported on: web · Requires: browser.console, browser.network, runtime.diagnostics

{
  "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: web, desktop, bevy · Requires: runtime.performance

{
  "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: web, desktop, bevy · Requires: runtime.performance

{
  "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: web · Requires: entity.bounds

{
  "visibility": [
    {
      "entity": "player",
      "minProjectedPixels": 1200,
      "maxOffscreenRatio": 0.05
    }
  ]
}

world

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

• Supported on: web, desktop, bevy · Requires: runtime.world

{
  "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: web, desktop, bevy · Requires: runtime.contacts

{
  "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: web, desktop, bevy · Requires: runtime.physics

{
  "settled": [
    {
      "atStep": "fall-and-settle",
      "minBodies": 15
    }
  ]
}

occluded

Proves rendered scene geometry occludes the segment between an origin entity and target. Use when that is the thing the scenario must prove.

• Supported on: web, desktop, bevy · Requires: runtime.physics

{
  "occluded": [
    {
      "entity": "listener",
      "target": "emitter"
    }
  ]
}

animation

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

• Supported on: web, desktop, bevy · Requires: runtime.animation

{
  "animation": [
    {
      "entity": "player",
      "clip": "run",
      "entered": true,
      "advancedFrames": 5,
      "finished": false
    }
  ]
}

audio

Proves which labelled audio cues the game actually played, and how often. Every other audio check is about the file — it exists, it decodes, it is inside its budget — and all of them stay green while a one-shot line sounds a second time mid-match. Use when that is the thing the scenario must prove.

Label a cue by passing a cue name to the audio bus when the game plays it; unlabelled sounds are never counted. When it fails, observations.json/runtimeObservations/gameplay/audio/recentCues says when each play happened.

• Supported on: web, desktop · Requires: runtime.audio

{
  "audio": [
    {
      "cue": "speech:p01",
      "minPlays": 1,
      "maxPlays": 1,
      "minGapMs": 500
    }
  ]
}

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: web, desktop, bevy · Requires: scene.observe

{
  "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: web, desktop, bevy · Requires: scene.nodes

{
  "sceneNodes": [
    {
      "inFrustum": true,
      "select": {
        "nameContains": "crate"
      },
      "texturesLoaded": true,
      "visible": 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: web, desktop, bevy · Requires: runtime.transitions

{
  "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: web, desktop, bevy · Requires: runtime.startup

{
  "startup": {
    "maxEnteredMs": 2500,
    "maxReadyMs": 8000
  }
}

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: web, desktop, bevy · Requires: runtime.renderChain

{
  "renderChain": {
    "tier": "high",
    "stages": {
      "includes": [
        "outline",
        "kuwahara",
        "watercolor"
      ],
      "order": [
        "outline",
        "kuwahara",
        "watercolor"
      ]
    },
    "contributions": {
      "graphOutputChanged": [
        "outline",
        "kuwahara",
        "watercolor"
      ]
    }
  }
}

Captured tone

Use tone to gate exposure from decoded frame pixels. Each row takes an optional atStep (named step; omitted means final frame) and at least one metric bound. mean, p1, p50, p99 use display luminance 0..255; clipFraction and blackFraction use 0..1. Bounds take inclusive min/max numbers. Empty, invalid and contradictory bounds throw at load; a missing capture fails.

{ "tone": [{ "atStep": "landed", "mean": { "min": 60, "max": 140 }, "p99": { "min": 150 }, "clipFraction": { "max": 0.005 } }] }

The host uses one rounded 256-bin Rec.709 luminance histogram; fully transparent pixels are excluded. The CLI command threenative-playtest tone shot.png other.png reports the same six metrics plus an unweighted frame-average row without starting a browser. Tone is an exposure gate, not an aesthetic verdict. Retain and inspect the actual runtime screenshots.