create-threenative 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (343) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +10 -2
  3. package/agent-docs/asset-mcp-loop.md +33 -0
  4. package/agent-docs/ctx-surface.md +69 -0
  5. package/agent-docs/engine-capabilities.md +4 -0
  6. package/agent-docs/framework-blocks-you.md +60 -0
  7. package/agent-docs/look-at-it-and-budget-the-look.md +27 -0
  8. package/agent-docs/performance-default.md +42 -0
  9. package/agent-docs/pixel-budget.md +20 -0
  10. package/agent-docs/playtest-fail-closed.md +23 -0
  11. package/agent-docs/references/assertion-reference.md +652 -0
  12. package/agent-docs/references/capability-reference.md +3279 -0
  13. package/agent-docs/references/capture-the-frame.md +53 -0
  14. package/agent-docs/references/ctx-cookbook.md +51 -0
  15. package/agent-docs/references/debug-surface.md +63 -0
  16. package/agent-docs/references/finding-assets.md +147 -0
  17. package/agent-docs/references/gameplay-recipes.md +54 -0
  18. package/agent-docs/references/menu-screens.md +69 -0
  19. package/agent-docs/references/mobile-memory-budget.md +87 -0
  20. package/agent-docs/references/sculpt-from-a-reference.md +39 -0
  21. package/agent-docs/references/visual-baseline.md +133 -0
  22. package/agent-docs/references/webview-ui.md +113 -0
  23. package/agent-docs/sculpt-loop.md +16 -0
  24. package/agent-files/.agents/skills/threenative-builder/SKILL.md +7 -0
  25. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +7 -0
  26. package/agent-files/.claude/agents/threenative-builder.md +7 -0
  27. package/agent-files/.claude/agents/threenative-verifier.md +7 -0
  28. package/agent-files/.threenative/agents/builder.md +32 -0
  29. package/agent-files/.threenative/agents/verifier.md +31 -0
  30. package/agent-files/AGENT-ROLES.md +26 -0
  31. package/capabilities.json +3542 -0
  32. package/dist/index.d.ts +191 -3
  33. package/dist/index.js +1707 -73
  34. package/dist/threenative.d.ts +9 -2
  35. package/dist/threenative.js +1825 -148
  36. package/package.json +30 -6
  37. package/template-assets/loading.ts +315 -0
  38. package/template-assets/patches/three@0.185.1.patch +287 -0
  39. package/templates/action-rpg/.codex/config.toml +15 -0
  40. package/templates/action-rpg/.mcp.json +6 -2
  41. package/templates/action-rpg/AGENTS.md +370 -6
  42. package/templates/action-rpg/CLAUDE.md +370 -6
  43. package/templates/action-rpg/index.html +0 -1
  44. package/templates/action-rpg/package.json +15 -11
  45. package/templates/action-rpg/playtests/combat.playtest.json +23 -9
  46. package/templates/action-rpg/playtests/fail.playtest.json +3 -3
  47. package/templates/action-rpg/playtests/inventory.playtest.json +16 -10
  48. package/templates/action-rpg/playtests/performance.playtest.json +22 -0
  49. package/templates/action-rpg/playtests/progress.playtest.json +18 -13
  50. package/templates/action-rpg/playtests/win.playtest.json +10 -4
  51. package/templates/action-rpg/public/icon.png +0 -0
  52. package/templates/action-rpg/src/entities/Enemy.ts +14 -4
  53. package/templates/action-rpg/src/game.ts +21 -0
  54. package/templates/action-rpg/src/render/lighting.ts +6 -1
  55. package/templates/action-rpg/src/render/loading.ts +267 -42
  56. package/templates/action-rpg/src/render/postprocessing.ts +68 -15
  57. package/templates/action-rpg/src/render/worldEnvironment.ts +583 -0
  58. package/templates/action-rpg/src/scenes/Play.ts +49 -19
  59. package/templates/action-rpg/src/state.ts +4 -0
  60. package/templates/action-rpg/src/style.css +45 -1
  61. package/templates/action-rpg/src/ui/AbilityBar.tsx +9 -7
  62. package/templates/action-rpg/src/ui/App.tsx +9 -8
  63. package/templates/action-rpg/src/ui/CharacterPanel.tsx +10 -8
  64. package/templates/action-rpg/src/ui/GameUi.tsx +24 -0
  65. package/templates/action-rpg/src/ui/Hud.tsx +10 -8
  66. package/templates/action-rpg/src/ui/InventoryPanel.tsx +9 -7
  67. package/templates/action-rpg/src/ui/main.tsx +14 -0
  68. package/templates/action-rpg/threenative.config.ts +21 -8
  69. package/templates/action-rpg/vite.config.ts +32 -2
  70. package/templates/defense/.codex/config.toml +15 -0
  71. package/templates/defense/.mcp.json +6 -2
  72. package/templates/defense/AGENTS.md +371 -8
  73. package/templates/defense/CLAUDE.md +371 -8
  74. package/templates/defense/README.md +2 -1
  75. package/templates/defense/index.html +0 -1
  76. package/templates/defense/package.json +16 -12
  77. package/templates/defense/playtests/leak.playtest.json +9 -4
  78. package/templates/defense/playtests/performance.playtest.json +22 -0
  79. package/templates/defense/playtests/placement.playtest.json +5 -5
  80. package/templates/defense/playtests/pointer-placement.playtest.json +89 -0
  81. package/templates/defense/playtests/scan.playtest.json +3 -3
  82. package/templates/defense/playtests/survive.playtest.json +11 -6
  83. package/templates/defense/public/icon.png +0 -0
  84. package/templates/defense/src/attackers/Attacker.ts +28 -12
  85. package/templates/defense/src/game.ts +24 -2
  86. package/templates/defense/src/render/lighting.ts +6 -1
  87. package/templates/defense/src/render/loading.ts +263 -37
  88. package/templates/defense/src/render/postprocessing.ts +70 -13
  89. package/templates/defense/src/render/shapes.ts +38 -0
  90. package/templates/defense/src/render/worldEnvironment.ts +583 -0
  91. package/templates/defense/src/scenes/Defense.ts +109 -50
  92. package/templates/defense/src/state.ts +6 -0
  93. package/templates/defense/src/style.css +45 -1
  94. package/templates/defense/src/ui/App.tsx +9 -4
  95. package/templates/defense/src/ui/GameUi.tsx +20 -0
  96. package/templates/defense/src/ui/Hud.tsx +6 -5
  97. package/templates/defense/src/ui/main.tsx +14 -0
  98. package/templates/defense/threenative.config.ts +21 -8
  99. package/templates/defense/vite.config.ts +34 -1
  100. package/templates/minimal/.codex/config.toml +15 -0
  101. package/templates/minimal/.mcp.json +6 -2
  102. package/templates/minimal/AGENTS.md +360 -255
  103. package/templates/minimal/CLAUDE.md +360 -255
  104. package/templates/minimal/index.html +0 -1
  105. package/templates/minimal/package.json +14 -11
  106. package/templates/minimal/playtests/atmosphere.playtest.json +32 -0
  107. package/templates/minimal/playtests/play.playtest.json +17 -5
  108. package/templates/minimal/public/icon.png +0 -0
  109. package/templates/minimal/src/game.ts +1 -0
  110. package/templates/minimal/src/render/camera.ts +1 -1
  111. package/templates/minimal/src/render/hud.ts +24 -8
  112. package/templates/minimal/src/render/lighting.ts +23 -2
  113. package/templates/minimal/src/render/loading.ts +23 -103
  114. package/templates/minimal/src/render/postprocessing.ts +92 -14
  115. package/templates/minimal/src/render/sky.ts +37 -32
  116. package/templates/minimal/src/render/worldEnvironment.ts +583 -0
  117. package/templates/minimal/src/scenes/Play.ts +91 -13
  118. package/templates/minimal/src/state.ts +8 -1
  119. package/templates/minimal/threenative.config.ts +15 -10
  120. package/templates/minimal/vite.config.ts +28 -1
  121. package/templates/platformer/.codex/config.toml +15 -0
  122. package/templates/platformer/.mcp.json +6 -2
  123. package/templates/platformer/AGENTS.md +385 -130
  124. package/templates/platformer/CLAUDE.md +385 -130
  125. package/templates/platformer/index.html +0 -1
  126. package/templates/platformer/package.json +17 -14
  127. package/templates/platformer/playtests/avoidance.playtest.json +6 -1
  128. package/templates/platformer/playtests/branding.playtest.json +29 -0
  129. package/templates/platformer/playtests/buffer.playtest.json +1 -1
  130. package/templates/platformer/playtests/collect.playtest.json +1 -1
  131. package/templates/platformer/playtests/collision-layers.playtest.json +2 -2
  132. package/templates/platformer/playtests/coyote.playtest.json +42 -8
  133. package/templates/platformer/playtests/damage.playtest.json +4 -1
  134. package/templates/platformer/playtests/dash.playtest.json +2 -2
  135. package/templates/platformer/playtests/jump.playtest.json +2 -3
  136. package/templates/platformer/playtests/native/touch-controls.playtest.json +33 -0
  137. package/templates/platformer/playtests/oneway.playtest.json +1 -1
  138. package/templates/platformer/playtests/performance.playtest.json +6 -5
  139. package/templates/platformer/playtests/respawn.playtest.json +2 -2
  140. package/templates/platformer/playtests/stomp-rise.playtest.json +17 -3
  141. package/templates/platformer/playtests/stomp.playtest.json +11 -3
  142. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +13 -4
  143. package/templates/platformer/playtests/terminal-loop-win.playtest.json +3 -3
  144. package/templates/platformer/playtests/touch-controls-web.playtest.json +46 -0
  145. package/templates/platformer/public/icon.png +0 -0
  146. package/templates/platformer/src/entities/Character.ts +16 -10
  147. package/templates/platformer/src/entities/Patrol.ts +5 -0
  148. package/templates/platformer/src/game.ts +24 -1
  149. package/templates/platformer/src/render/lighting.ts +6 -1
  150. package/templates/platformer/src/render/loading.ts +270 -61
  151. package/templates/platformer/src/render/postprocessing.ts +68 -15
  152. package/templates/platformer/src/render/touch-controls.ts +54 -36
  153. package/templates/platformer/src/render/worldEnvironment.ts +583 -0
  154. package/templates/platformer/src/scenes/Level.ts +47 -22
  155. package/templates/platformer/src/state.ts +4 -0
  156. package/templates/platformer/src/style.css +45 -1
  157. package/templates/platformer/src/ui/App.tsx +9 -4
  158. package/templates/platformer/src/ui/GameUi.tsx +20 -0
  159. package/templates/platformer/src/ui/Hud.tsx +6 -5
  160. package/templates/platformer/src/ui/main.tsx +14 -0
  161. package/templates/platformer/threenative.config.ts +20 -10
  162. package/templates/platformer/vite.config.ts +34 -1
  163. package/templates/racing/.codex/config.toml +15 -0
  164. package/templates/racing/.mcp.json +6 -2
  165. package/templates/racing/AGENTS.md +370 -6
  166. package/templates/racing/CLAUDE.md +370 -6
  167. package/templates/racing/index.html +0 -1
  168. package/templates/racing/package.json +16 -12
  169. package/templates/racing/playtests/boost.playtest.json +5 -5
  170. package/templates/racing/playtests/outcome.playtest.json +14 -4
  171. package/templates/racing/playtests/performance.playtest.json +22 -0
  172. package/templates/racing/playtests/ranking.playtest.json +2 -2
  173. package/templates/racing/playtests/rescue.playtest.json +12 -6
  174. package/templates/racing/playtests/reverse.playtest.json +3 -3
  175. package/templates/racing/playtests/shortcut.playtest.json +3 -3
  176. package/templates/racing/public/icon.png +0 -0
  177. package/templates/racing/src/game.ts +24 -1
  178. package/templates/racing/src/render/camera.ts +10 -6
  179. package/templates/racing/src/render/lighting.ts +6 -1
  180. package/templates/racing/src/render/loading.ts +291 -34
  181. package/templates/racing/src/render/postprocessing.ts +70 -13
  182. package/templates/racing/src/render/worldEnvironment.ts +583 -0
  183. package/templates/racing/src/scenes/Race.ts +68 -36
  184. package/templates/racing/src/state.ts +4 -0
  185. package/templates/racing/src/style.css +45 -1
  186. package/templates/racing/src/track/Lap.ts +20 -9
  187. package/templates/racing/src/track/Ranking.ts +53 -14
  188. package/templates/racing/src/track/Track.ts +29 -16
  189. package/templates/racing/src/track/TrackSector.ts +14 -4
  190. package/templates/racing/src/ui/App.tsx +9 -4
  191. package/templates/racing/src/ui/GameUi.tsx +20 -0
  192. package/templates/racing/src/ui/Hud.tsx +6 -5
  193. package/templates/racing/src/ui/main.tsx +14 -0
  194. package/templates/racing/threenative.config.ts +21 -8
  195. package/templates/racing/vite.config.ts +34 -1
  196. package/templates/sailing/.codex/config.toml +15 -0
  197. package/templates/sailing/.mcp.json +20 -0
  198. package/templates/sailing/AGENTS.md +388 -0
  199. package/templates/sailing/CLAUDE.md +390 -0
  200. package/templates/sailing/README.md +25 -0
  201. package/templates/sailing/index.html +12 -0
  202. package/templates/sailing/kit.json +7 -0
  203. package/templates/sailing/native-playtests/survives.playtest.json +21 -0
  204. package/templates/sailing/package.json +52 -0
  205. package/templates/sailing/playtests/fail.playtest.json +24 -0
  206. package/templates/sailing/playtests/performance.playtest.json +21 -0
  207. package/templates/sailing/playtests/survives.playtest.json +38 -0
  208. package/templates/sailing/playtests/win.playtest.json +31 -0
  209. package/templates/sailing/public/favicon.svg +5 -0
  210. package/templates/sailing/public/icon.png +0 -0
  211. package/templates/sailing/src/entities/Ship.ts +96 -0
  212. package/templates/sailing/src/game.ts +40 -0
  213. package/templates/sailing/src/main.ts +15 -0
  214. package/templates/sailing/src/render/camera.ts +21 -0
  215. package/templates/sailing/src/render/lighting.ts +36 -0
  216. package/templates/sailing/src/render/loading.ts +315 -0
  217. package/templates/sailing/src/render/materials.ts +28 -0
  218. package/templates/sailing/src/render/palette.ts +24 -0
  219. package/templates/sailing/src/render/postprocessing.ts +33 -0
  220. package/templates/sailing/src/render/props.ts +52 -0
  221. package/templates/sailing/src/render/sky.ts +32 -0
  222. package/templates/sailing/src/render/water-material.ts +14 -0
  223. package/templates/sailing/src/render/water-shaders.ts +12 -0
  224. package/templates/sailing/src/render/wave-nodes.ts +10 -0
  225. package/templates/sailing/src/render/worldEnvironment.ts +590 -0
  226. package/templates/sailing/src/scenes/Boot.ts +12 -0
  227. package/templates/sailing/src/scenes/Sailing.ts +106 -0
  228. package/templates/sailing/src/state.ts +10 -0
  229. package/templates/sailing/src/style.css +61 -0
  230. package/templates/sailing/src/ui/App.tsx +15 -0
  231. package/templates/sailing/src/ui/GameUi.tsx +12 -0
  232. package/templates/sailing/src/ui/Hud.tsx +55 -0
  233. package/templates/sailing/src/ui/Menu.tsx +30 -0
  234. package/templates/sailing/src/ui/main.tsx +7 -0
  235. package/templates/sailing/tailwind.config.ts +2 -0
  236. package/templates/sailing/threenative.config.ts +34 -0
  237. package/templates/sailing/tsconfig.json +17 -0
  238. package/templates/sailing/vite.config.ts +34 -0
  239. package/templates/shooter/.codex/config.toml +15 -0
  240. package/templates/shooter/.mcp.json +6 -2
  241. package/templates/shooter/AGENTS.md +373 -7
  242. package/templates/shooter/CLAUDE.md +373 -7
  243. package/templates/shooter/index.html +0 -1
  244. package/templates/shooter/package.json +16 -11
  245. package/templates/shooter/playtests/fail.playtest.json +5 -4
  246. package/templates/shooter/playtests/input-control.playtest.json +131 -0
  247. package/templates/shooter/playtests/per-item.playtest.json +59 -0
  248. package/templates/shooter/playtests/performance.playtest.json +22 -0
  249. package/templates/shooter/playtests/shooter.playtest.json +22 -18
  250. package/templates/shooter/playtests/survives.playtest.json +1 -1
  251. package/templates/shooter/public/favicon.svg +1 -1
  252. package/templates/shooter/public/icon.png +0 -0
  253. package/templates/shooter/src/game.ts +24 -1
  254. package/templates/shooter/src/main.ts +3 -13
  255. package/templates/shooter/src/render/camera.ts +62 -12
  256. package/templates/shooter/src/render/lighting.ts +6 -1
  257. package/templates/shooter/src/render/loading.ts +262 -33
  258. package/templates/shooter/src/render/palette.ts +1 -1
  259. package/templates/shooter/src/render/postprocessing.ts +68 -16
  260. package/templates/shooter/src/render/shapes.ts +178 -0
  261. package/templates/shooter/src/render/ui.css +34 -1
  262. package/templates/shooter/src/render/worldEnvironment.ts +583 -0
  263. package/templates/shooter/src/scenes/Play.ts +246 -73
  264. package/templates/shooter/src/state.ts +13 -0
  265. package/templates/shooter/src/style.css +26 -0
  266. package/templates/shooter/src/ui/App.tsx +10 -12
  267. package/templates/shooter/src/ui/GameUi.tsx +20 -0
  268. package/templates/shooter/src/ui/Hud.tsx +8 -10
  269. package/templates/shooter/src/ui/Menu.tsx +24 -9
  270. package/templates/shooter/src/ui/main.tsx +15 -0
  271. package/templates/shooter/src/weapons/Projectile.ts +21 -10
  272. package/templates/shooter/threenative.config.ts +21 -8
  273. package/templates/shooter/vite.config.ts +32 -2
  274. package/templates/starter/.codex/config.toml +15 -0
  275. package/templates/starter/.mcp.json +6 -2
  276. package/templates/starter/AGENTS.md +429 -326
  277. package/templates/starter/CLAUDE.md +429 -326
  278. package/templates/starter/assets/pickup.wav +0 -0
  279. package/templates/starter/gitignore +4 -0
  280. package/templates/starter/index.html +0 -1
  281. package/templates/starter/native-playtests/react-hud.playtest.json +20 -0
  282. package/templates/starter/native-playtests/render-chain.playtest.json +12 -0
  283. package/templates/starter/package.json +16 -12
  284. package/templates/starter/playtests/assets.playtest.json +65 -0
  285. package/templates/starter/playtests/buffer.playtest.json +59 -9
  286. package/templates/starter/playtests/cloth.playtest.json +113 -0
  287. package/templates/starter/playtests/coyote.playtest.json +60 -8
  288. package/templates/starter/playtests/forward.playtest.json +29 -4
  289. package/templates/starter/playtests/gameover.playtest.json +66 -0
  290. package/templates/starter/playtests/goal.playtest.json +67 -0
  291. package/templates/starter/playtests/hot-reload.playtest.json +48 -8
  292. package/templates/starter/playtests/look.playtest.json +34 -6
  293. package/templates/starter/playtests/models-baseline.png +0 -0
  294. package/templates/starter/playtests/models.playtest.json +74 -0
  295. package/templates/starter/playtests/monitoring.playtest.json +38 -7
  296. package/templates/starter/playtests/odometer.playtest.json +54 -0
  297. package/templates/starter/playtests/pause.playtest.json +27 -4
  298. package/templates/starter/playtests/play.playtest.json +43 -7
  299. package/templates/starter/playtests/respawn.playtest.json +46 -6
  300. package/templates/starter/playtests/restart.playtest.json +65 -10
  301. package/templates/starter/playtests/seed.playtest.json +44 -8
  302. package/templates/starter/playtests/survives.playtest.json +27 -4
  303. package/templates/starter/playtests/textures-baseline.png +0 -0
  304. package/templates/starter/playtests/textures.playtest.json +74 -0
  305. package/templates/starter/playtests/zoom-pinch.playtest.json +86 -0
  306. package/templates/starter/playtests/zoom-wheel.playtest.json +59 -0
  307. package/templates/starter/public/icon.png +0 -0
  308. package/templates/starter/src/entities/Goal.ts +122 -0
  309. package/templates/starter/src/entities/Player.ts +40 -2
  310. package/templates/starter/src/game.ts +25 -0
  311. package/templates/starter/src/render/camera.ts +31 -5
  312. package/templates/starter/src/render/easing.ts +5 -0
  313. package/templates/starter/src/render/effects/gradualBackground.ts +48 -0
  314. package/templates/starter/src/render/effects/lensDistortion.ts +43 -0
  315. package/templates/starter/src/render/effects/sparkle.ts +49 -0
  316. package/templates/starter/src/render/lighting.ts +6 -1
  317. package/templates/starter/src/render/loading.ts +315 -0
  318. package/templates/starter/src/render/materials.ts +17 -1
  319. package/templates/starter/src/render/pennant.ts +54 -0
  320. package/templates/starter/src/render/postprocessing.ts +46 -15
  321. package/templates/starter/src/render/scenery.ts +83 -0
  322. package/templates/starter/src/render/shapes.ts +9 -21
  323. package/templates/starter/src/render/worldEnvironment.ts +583 -0
  324. package/templates/starter/src/scenes/Play.ts +146 -36
  325. package/templates/starter/src/state.ts +12 -0
  326. package/templates/starter/src/style.css +45 -1
  327. package/templates/starter/src/ui/App.tsx +9 -6
  328. package/templates/starter/src/ui/GameUi.tsx +20 -0
  329. package/templates/starter/src/ui/Hud.tsx +52 -29
  330. package/templates/starter/src/ui/Menu.tsx +25 -23
  331. package/templates/starter/src/ui/main.tsx +14 -0
  332. package/templates/starter/threenative.config.ts +27 -9
  333. package/templates/starter/tools/look.mjs +109 -0
  334. package/templates/starter/vite.config.ts +32 -2
  335. package/templates/minimal/assets/.gitkeep +0 -0
  336. package/templates/minimal/public/.gitkeep +0 -0
  337. package/templates/platformer/assets/.gitkeep +0 -0
  338. package/templates/platformer/public/.gitkeep +0 -0
  339. package/templates/starter/assets/.gitkeep +0 -0
  340. package/templates/starter/public/.gitkeep +0 -0
  341. package/templates/starter/public/pickup.ogg +0 -0
  342. /package/templates/starter/{public → assets}/native-proof.glb +0 -0
  343. /package/templates/starter/{public → assets}/native-proof.png +0 -0
@@ -0,0 +1,652 @@
1
+ <!-- Generated by scripts/generate-assertion-reference.ts from PLAYTEST_ASSERTION_REGISTRY — do not hand-edit. -->
2
+ <!-- Regenerate: pnpm --filter @threenative/playtest build && pnpm tsx scripts/generate-assertion-reference.ts -->
3
+
4
+ # Assertion reference
5
+
6
+ Every assertion kind the playtest validator accepts, generated from the registry the
7
+ validator itself reads, so this page cannot disagree with the runtime. Assertions fail
8
+ closed: a malformed assertion throws at load, and a scenario whose assertions all hold
9
+ trivially fails `TN_PLAYTEST_SCENARIO_ASSERTS_NOTHING`.
10
+
11
+ ### `deviceMetrics`
12
+
13
+ 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.
14
+
15
+ - **Supported on:** web, desktop, bevy · **Requires:** device.metrics
16
+
17
+ | Field | Type | Required |
18
+ | --- | --- | --- |
19
+ | `maxTemperatureRiseC` | finite non-negative number | no |
20
+ | `maxThermalStatus` | non-negative integer 0..6 | no |
21
+ | `notThermallyConfounded` | true | no |
22
+
23
+
24
+ ```json
25
+ {
26
+ "deviceMetrics": {
27
+ "maxTemperatureRiseC": 5,
28
+ "notThermallyConfounded": true
29
+ }
30
+ }
31
+ ```
32
+
33
+ ### `framebufferCoverage`
34
+
35
+ 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.
36
+
37
+ - **Supported on:** web, desktop, bevy · **Requires:** browser.screenshot
38
+
39
+ | Field | Type | Required |
40
+ | --- | --- | --- |
41
+ | `backdrop` | [integer 0..255, integer 0..255, integer 0..255] | yes |
42
+ | `grid` | { columns: positive integer <= 256, rows: positive integer <= 256 } | no |
43
+ | `tolerance` | integer 0..255 | yes |
44
+ | `window` | { startStep: string, endStep: string } | yes |
45
+
46
+
47
+ ```json
48
+ {
49
+ "framebufferCoverage": {
50
+ "backdrop": [
51
+ 5,
52
+ 7,
53
+ 11
54
+ ],
55
+ "grid": {
56
+ "columns": 32,
57
+ "rows": 18
58
+ },
59
+ "tolerance": 8,
60
+ "window": {
61
+ "endStep": "loading-end",
62
+ "startStep": "loading-start"
63
+ }
64
+ }
65
+ }
66
+ ```
67
+
68
+ ### `reachability`
69
+
70
+ 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.
71
+
72
+ - **Supported on:** web, desktop, bevy · **Requires:** entity.observe
73
+
74
+ | Field | Type | Required |
75
+ | --- | --- | --- |
76
+ | `artifact` | string | yes |
77
+ | `entities` | string[] (minimum 2) | yes |
78
+
79
+
80
+ ```json
81
+ {
82
+ "reachability": {
83
+ "artifact": "artifacts/character-envelope/player.json",
84
+ "entities": [
85
+ "platform.a",
86
+ "platform.b"
87
+ ]
88
+ }
89
+ }
90
+ ```
91
+
92
+ ### `aerodynamics`
93
+
94
+ Proves aerodynamic force telemetry and signed control-surface delivery for a flight entity. **Use when** that is the thing the scenario must prove.
95
+
96
+ - **Supported on:** web, desktop, bevy · **Requires:** runtime.fixedStep, runtime.physics
97
+
98
+ | Field | Type | Required |
99
+ | --- | --- | --- |
100
+ | `entity` | string | yes |
101
+ | `minForceSamples` | positive integer | no |
102
+ | `controls` | Array<{ surface: string, sign: 'negative' | 'positive', minAbs?: number }> | no |
103
+ | `torques` | Array<{ label: string, relativeToLabel?: string, axis: 'x' | 'y' | 'z', sign: 'negative' | 'positive', minAbs?: number }> | no |
104
+
105
+
106
+ ```json
107
+ {
108
+ "aerodynamics": [
109
+ {
110
+ "controls": [
111
+ {
112
+ "sign": "negative",
113
+ "surface": "elevator"
114
+ }
115
+ ],
116
+ "entity": "aircraft",
117
+ "minForceSamples": 4
118
+ }
119
+ ]
120
+ }
121
+ ```
122
+
123
+ ### `visual`
124
+
125
+ Proves screenshot change, populated regions, and sustained projected entity visibility. **Use when** that is the thing the scenario must prove.
126
+
127
+ - **Supported on:** web · **Requires:** browser.screenshot
128
+
129
+ | Field | Type | Required |
130
+ | --- | --- | --- |
131
+ | `frameDiff` | { baselineImage?: project-relative PNG, minChangedPixelRatio?: number, maxChangedPixelRatio?: number } | no |
132
+ | `region` | { x: number, y: number, width: number, height: number, minNonblankPixelRatio?: number, minDarkPixelRatio?: number, maxLuminance?: number } | no |
133
+ | `entityVisible` | { entity: string, minProjectedPixels: number, throughoutFrames?: boolean } | no |
134
+
135
+
136
+ ```json
137
+ {
138
+ "visual": [
139
+ {
140
+ "frameDiff": {
141
+ "baselineImage": "artifacts/baseline.png",
142
+ "minChangedPixelRatio": 0.01
143
+ },
144
+ "entityVisible": {
145
+ "entity": "board.e4",
146
+ "minProjectedPixels": 20,
147
+ "throughoutFrames": true
148
+ }
149
+ }
150
+ ]
151
+ }
152
+ ```
153
+
154
+ ### `movement`
155
+
156
+ Proves the subject moved, reached a minimum velocity, or changed rotation during held input. **Use when** that is the thing the scenario must prove.
157
+
158
+ - **Supported on:** web, desktop, bevy · **Requires:** entity.observe
159
+
160
+ | Field | Type | Required |
161
+ | --- | --- | --- |
162
+ | `entity` | string | no |
163
+ | `closesDistanceToPosition` | { position: [number, number, number], min: number } | no |
164
+ | `facesMovementWithinDegrees` | number | no |
165
+ | `axis` | string | no |
166
+ | `minAxisDelta` | { axis: string, min: number } | no |
167
+ | `minResolvedAxisDelta` | { axis: string, min: number } | no |
168
+ | `maxTiltDegrees` | number in [0, 180] | no |
169
+ | `minDistance` | number | no |
170
+ | `maxDistance` | number | no |
171
+ | `minVelocity` | number | no |
172
+ | `pathLength` | number | no |
173
+ | `notFacing` | { entity: string, minDegrees: number } | no |
174
+ | `notFacingPosition` | { position: [number, number, number], minDegrees: number } | no |
175
+ | `reachesPositionWithin` | { position: [number, number, number], maxDistance: number, atStep?: string } | no |
176
+ | `rotationChanged` | boolean | no |
177
+
178
+
179
+ ```json
180
+ {
181
+ "movement": {
182
+ "entity": "player",
183
+ "minDistance": 0.5,
184
+ "minVelocity": 0.01,
185
+ "rotationChanged": true
186
+ }
187
+ }
188
+ ```
189
+
190
+ ### `camera`
191
+
192
+ Proves a camera follows an entity or keeps a target in view. **Use when** that is the thing the scenario must prove.
193
+
194
+ - **Supported on:** web, desktop, bevy · **Requires:** camera.observe, entity.observe
195
+
196
+ | Field | Type | Required |
197
+ | --- | --- | --- |
198
+ | `entity` | string | no |
199
+ | `follows` | string | no |
200
+ | `within` | number | no |
201
+ | `targetInViewport` | boolean | no |
202
+
203
+
204
+ ```json
205
+ {
206
+ "camera": {
207
+ "entity": "camera.main",
208
+ "follows": "player",
209
+ "within": 10,
210
+ "targetInViewport": true
211
+ }
212
+ }
213
+ ```
214
+
215
+ ### `components`
216
+
217
+ Proves a live entity component value after the scenario or at named steps. **Use when** that is the thing the scenario must prove.
218
+
219
+ - **Supported on:** web, desktop, bevy · **Requires:** runtime.components
220
+
221
+ | Field | Type | Required |
222
+ | --- | --- | --- |
223
+ | `entity` | string | yes |
224
+ | `component` | string | yes |
225
+ | `path` | string | no |
226
+ | `equals` | json | no |
227
+ | `gte` | number | no |
228
+ | `lte` | number | no |
229
+ | `changed` | boolean | no |
230
+ | `atSteps` | Array<{ label: string, equals: json }> | no |
231
+ | `allowTrivial` | triviality reason | no |
232
+
233
+
234
+ ```json
235
+ {
236
+ "components": [
237
+ {
238
+ "component": "Camera",
239
+ "entity": "camera.main",
240
+ "path": "fovY",
241
+ "equals": 22,
242
+ "changed": true
243
+ }
244
+ ]
245
+ }
246
+ ```
247
+
248
+ ### `resources`
249
+
250
+ Proves resource state after the scenario through equals, gte, lte, textIncludes, or changed checks. **Use when** that is the thing the scenario must prove.
251
+
252
+ - **Supported on:** web, desktop, bevy · **Requires:** runtime.resources
253
+
254
+ | Field | Type | Required |
255
+ | --- | --- | --- |
256
+ | `id` | string | yes |
257
+ | `path` | string | no |
258
+ | `equals` | json | no |
259
+ | `gte` | number | no |
260
+ | `lte` | number | no |
261
+ | `textIncludes` | string | no |
262
+ | `changed` | boolean | no |
263
+ | `throughoutSteps` | boolean | no |
264
+ | `atSteps` | Array<{ label: string, equals?: json, textIncludes?: string }> | no |
265
+ | `allowTrivial` | triviality reason | no |
266
+ | `anyOf` | Array<{ path: string, equals?: json, gte?: number, lte?: number, textIncludes?: string, changed?: boolean }> | no |
267
+
268
+
269
+ ```json
270
+ {
271
+ "resources": [
272
+ {
273
+ "id": "GameState",
274
+ "path": "score",
275
+ "gte": 1,
276
+ "changed": true
277
+ }
278
+ ]
279
+ }
280
+ ```
281
+
282
+ ### `tags`
283
+
284
+ Proves the final count of entities carrying a bounded runtime tag. **Use when** that is the thing the scenario must prove.
285
+
286
+ - **Supported on:** web, desktop, bevy · **Requires:** runtime.tags
287
+
288
+ | Field | Type | Required |
289
+ | --- | --- | --- |
290
+ | `tag` | string | yes |
291
+ | `count` | non-negative integer | no |
292
+ | `gte` | non-negative integer | no |
293
+ | `lte` | non-negative integer | no |
294
+ | `allowTrivial` | triviality reason | no |
295
+
296
+
297
+ ```json
298
+ {
299
+ "tags": [
300
+ {
301
+ "tag": "coin",
302
+ "count": 10
303
+ }
304
+ ]
305
+ }
306
+ ```
307
+
308
+ ### `signals`
309
+
310
+ 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.
311
+
312
+ - **Supported on:** web, desktop, bevy · **Requires:** runtime.events
313
+
314
+ | Field | Type | Required |
315
+ | --- | --- | --- |
316
+ | `atStep` | string | no |
317
+ | `entity` | string | no |
318
+ | `maxCount` | non-negative integer | no |
319
+ | `minCount` | non-negative integer | no |
320
+ | `name` | string | yes |
321
+
322
+
323
+ ```json
324
+ {
325
+ "signals": [
326
+ {
327
+ "name": "collected",
328
+ "entity": "player",
329
+ "minCount": 3,
330
+ "atStep": "last-coin"
331
+ }
332
+ ]
333
+ }
334
+ ```
335
+
336
+ ### `states`
337
+
338
+ Proves an observed entity's final runtime-owned state-machine state. **Use when** that is the thing the scenario must prove.
339
+
340
+ - **Supported on:** web, desktop, bevy · **Requires:** runtime.state
341
+
342
+ | Field | Type | Required |
343
+ | --- | --- | --- |
344
+ | `entity` | string | no |
345
+ | `equals` | string | yes |
346
+ | `allowTrivial` | triviality reason | no |
347
+
348
+
349
+ ```json
350
+ {
351
+ "states": [
352
+ {
353
+ "equals": "completed"
354
+ }
355
+ ]
356
+ }
357
+ ```
358
+
359
+ ### `hud`
360
+
361
+ Proves retained UI/HUD text or values after the scenario. **Use when** that is the thing the scenario must prove.
362
+
363
+ - **Supported on:** web · **Requires:** runtime.ui
364
+
365
+ | Field | Type | Required |
366
+ | --- | --- | --- |
367
+ | `id` | string | yes |
368
+ | `path` | string | no |
369
+ | `equals` | json | no |
370
+ | `gte` | number | no |
371
+ | `lte` | number | no |
372
+ | `textIncludes` | string | no |
373
+ | `changed` | boolean | no |
374
+ | `allowTrivial` | triviality reason | no |
375
+
376
+
377
+ ```json
378
+ {
379
+ "hud": [
380
+ {
381
+ "id": "score-label",
382
+ "textIncludes": "Score"
383
+ }
384
+ ]
385
+ }
386
+ ```
387
+
388
+ ### `overlayNodes`
389
+
390
+ Proves DOM state inside a same-origin webview overlay iframe. **Use when** that is the thing the scenario must prove.
391
+
392
+ - **Supported on:** web · **Requires:** browser.dom
393
+
394
+ | Field | Type | Required |
395
+ | --- | --- | --- |
396
+ | `overlayId` | string | yes |
397
+ | `selector` | string | yes |
398
+ | `attribute` | string | no |
399
+ | `equals` | json | no |
400
+ | `textIncludes` | string | no |
401
+ | `visible` | boolean | no |
402
+
403
+
404
+ ```json
405
+ {
406
+ "overlayNodes": [
407
+ {
408
+ "attribute": "data-aiming",
409
+ "equals": "true",
410
+ "overlayId": "game-ui",
411
+ "selector": "[data-testid=fps-crosshair]",
412
+ "visible": false
413
+ }
414
+ ]
415
+ }
416
+ ```
417
+
418
+ ### `diagnostics`
419
+
420
+ Proves console, network, runtime, and readiness diagnostics stayed clean. **Use when** that is the thing the scenario must prove.
421
+
422
+ - **Supported on:** web · **Requires:** browser.console, browser.network, runtime.diagnostics
423
+
424
+ | Field | Type | Required |
425
+ | --- | --- | --- |
426
+ | `noConsoleErrors` | boolean | no |
427
+ | `noNetworkErrors` | boolean | no |
428
+ | `noRuntimeDiagnostics` | boolean | no |
429
+ | `consoleErrorsOptOutReason` | non-empty string | no |
430
+ | `networkErrorsOptOutReason` | non-empty string | no |
431
+ | `runtimeDiagnosticsOptOutReason` | non-empty string | no |
432
+ | `runtimeReady` | boolean | no |
433
+
434
+
435
+ ```json
436
+ {
437
+ "diagnostics": {
438
+ "noConsoleErrors": true,
439
+ "noNetworkErrors": true,
440
+ "noRuntimeDiagnostics": true,
441
+ "runtimeReady": true
442
+ }
443
+ }
444
+ ```
445
+
446
+ ### `performance`
447
+
448
+ Proves a live render sample exists and optionally bounds frame time, an fps floor, per-phase frame budget, draw calls, and triangles. **Use when** that is the thing the scenario must prove.
449
+
450
+ - **Supported on:** web, desktop, bevy · **Requires:** runtime.performance
451
+
452
+ | Field | Type | Required |
453
+ | --- | --- | --- |
454
+ | `maxFrameMsP95` | number | no |
455
+ | `minFps` | number | no |
456
+ | `maxPhaseMsP95` | { [phase]: number } | no |
457
+ | `maxDrawCalls` | number | no |
458
+ | `maxTriangles` | number | no |
459
+
460
+
461
+ ```json
462
+ {
463
+ "performance": {
464
+ "maxPhaseMsP95": {
465
+ "render": 12
466
+ },
467
+ "minFps": 30
468
+ }
469
+ }
470
+ ```
471
+
472
+ ### `visibility`
473
+
474
+ Proves projected entity visibility in the viewport. **Use when** that is the thing the scenario must prove.
475
+
476
+ - **Supported on:** web · **Requires:** entity.bounds
477
+
478
+ | Field | Type | Required |
479
+ | --- | --- | --- |
480
+ | `entity` | string | no |
481
+ | `minProjectedPixels` | number | no |
482
+ | `maxOffscreenRatio` | number | no |
483
+ | `present` | boolean | no |
484
+ | `allowTrivial` | triviality reason | no |
485
+
486
+
487
+ ```json
488
+ {
489
+ "visibility": [
490
+ {
491
+ "entity": "player",
492
+ "minProjectedPixels": 1200,
493
+ "maxOffscreenRatio": 0.05
494
+ }
495
+ ]
496
+ }
497
+ ```
498
+
499
+ ### `world`
500
+
501
+ Proves runtime world metadata exposed by the application bridge. **Use when** that is the thing the scenario must prove.
502
+
503
+ - **Supported on:** web, desktop, bevy · **Requires:** runtime.world
504
+
505
+ | Field | Type | Required |
506
+ | --- | --- | --- |
507
+ | `seed` | json | yes |
508
+ | `runtime` | object | no |
509
+
510
+
511
+ ```json
512
+ {
513
+ "world": {
514
+ "seed": 90210
515
+ }
516
+ }
517
+ ```
518
+
519
+ ### `contacts`
520
+
521
+ Proves contact or trigger evidence appeared in the effect log. **Use when** that is the thing the scenario must prove.
522
+
523
+ - **Supported on:** web, desktop, bevy · **Requires:** runtime.contacts
524
+
525
+ | Field | Type | Required |
526
+ | --- | --- | --- |
527
+ | `atStep` | string | no |
528
+ | `entity` | string | no |
529
+ | `with` | string | no |
530
+ | `kind` | string | no |
531
+ | `minCount` | number | no |
532
+ | `maxCount` | non-negative integer | no |
533
+ | `requiredOn` | Array<'web' | 'desktop' | 'bevy'> | no |
534
+
535
+
536
+ ```json
537
+ {
538
+ "contacts": [
539
+ {
540
+ "entity": "player",
541
+ "with": "pickup",
542
+ "kind": "trigger",
543
+ "minCount": 1
544
+ }
545
+ ]
546
+ }
547
+ ```
548
+
549
+ ### `settled`
550
+
551
+ 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.
552
+
553
+ - **Supported on:** web, desktop, bevy · **Requires:** runtime.physics
554
+
555
+ | Field | Type | Required |
556
+ | --- | --- | --- |
557
+ | `entity` | string | no |
558
+ | `atStep` | string | no |
559
+ | `minBodies` | positive integer | no |
560
+ | `compareToStep` | string | no |
561
+ | `minMeanPoseDistance` | positive number | no |
562
+ | `requiredOn` | Array<'web' | 'desktop' | 'bevy'> | no |
563
+ | `allowTrivial` | triviality reason | no |
564
+
565
+
566
+ ```json
567
+ {
568
+ "settled": [
569
+ {
570
+ "atStep": "fall-and-settle",
571
+ "minBodies": 15
572
+ }
573
+ ]
574
+ }
575
+ ```
576
+
577
+ ### `occluded`
578
+
579
+ Proves rendered scene geometry occludes the segment between an origin entity and target. **Use when** that is the thing the scenario must prove.
580
+
581
+ - **Supported on:** web, desktop, bevy · **Requires:** runtime.physics
582
+
583
+ | Field | Type | Required |
584
+ | --- | --- | --- |
585
+ | `entity` | string | no |
586
+ | `target` | string | no |
587
+ | `allowTrivial` | triviality reason | no |
588
+
589
+
590
+ ```json
591
+ {
592
+ "occluded": [
593
+ {
594
+ "entity": "listener",
595
+ "target": "emitter"
596
+ }
597
+ ]
598
+ }
599
+ ```
600
+
601
+ ### `animation`
602
+
603
+ Proves animation evidence appeared in the effect log or runtime observation. **Use when** that is the thing the scenario must prove.
604
+
605
+ - **Supported on:** web, desktop, bevy · **Requires:** runtime.animation
606
+
607
+ | Field | Type | Required |
608
+ | --- | --- | --- |
609
+ | `entity` | string | no |
610
+ | `clip` | string | no |
611
+ | `entered` | boolean | no |
612
+ | `advancedFrames` | number | no |
613
+ | `finished` | boolean | no |
614
+ | `allowTrivial` | triviality reason | no |
615
+
616
+
617
+ ```json
618
+ {
619
+ "animation": [
620
+ {
621
+ "entity": "player",
622
+ "clip": "run",
623
+ "entered": true,
624
+ "advancedFrames": 5,
625
+ "finished": false
626
+ }
627
+ ]
628
+ }
629
+ ```
630
+
631
+ ### `renderChain`
632
+
633
+ Proves the render chain reports the requested quality tier and, when asserted, a bounded temporal-history rejection fraction. **Use when** that is the thing the scenario must prove.
634
+
635
+ - **Supported on:** web, desktop, bevy · **Requires:** runtime.renderChain
636
+
637
+ | Field | Type | Required |
638
+ | --- | --- | --- |
639
+ | `tier` | string | no |
640
+ | `velocity` | object | no |
641
+
642
+
643
+ ```json
644
+ {
645
+ "renderChain": {
646
+ "tier": "high",
647
+ "velocity": {
648
+ "maxRejectionFraction": 0.2
649
+ }
650
+ }
651
+ }
652
+ ```