create-threenative 0.2.2 → 0.2.4

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 (588) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +61 -2
  3. package/agent-docs/references/assertion-reference.md +819 -0
  4. package/agent-docs/references/capability-reference.md +4483 -0
  5. package/agent-docs/references/capture-the-frame.md +60 -0
  6. package/agent-docs/references/creating-creatures.md +215 -0
  7. package/agent-docs/references/ctx-cookbook.md +120 -0
  8. package/agent-docs/references/debug-surface.md +68 -0
  9. package/agent-docs/references/dream-loop.md +150 -0
  10. package/agent-docs/references/finding-assets.md +215 -0
  11. package/agent-docs/references/gameplay-recipes.md +54 -0
  12. package/agent-docs/references/menu-screens.md +69 -0
  13. package/agent-docs/references/mobile-memory-budget.md +87 -0
  14. package/agent-docs/references/sculpt-from-a-reference.md +40 -0
  15. package/agent-docs/references/trace-a-slow-frame.md +99 -0
  16. package/agent-docs/references/visual-baseline.md +174 -0
  17. package/agent-docs/references/webview-ui.md +113 -0
  18. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
  19. package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
  20. package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
  21. package/agent-files/.agents/skills/threenative-builder/SKILL.md +7 -0
  22. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
  23. package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
  24. package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
  25. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
  26. package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
  27. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +7 -0
  28. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
  29. package/agent-files/.claude/agents/threenative-builder.md +7 -0
  30. package/agent-files/.claude/agents/threenative-verifier.md +7 -0
  31. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
  32. package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
  33. package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
  34. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
  35. package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
  36. package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
  37. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
  38. package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
  39. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
  40. package/agent-files/.threenative/agents/builder.md +32 -0
  41. package/agent-files/.threenative/agents/verifier.md +31 -0
  42. package/agent-files/AGENT-ROLES.md +26 -0
  43. package/agent-files/scripts/reference.mjs +705 -0
  44. package/agent-files/scripts/visual-loop.mjs +382 -0
  45. package/capabilities.json +5292 -0
  46. package/dist/index.d.ts +224 -3
  47. package/dist/index.js +1972 -73
  48. package/dist/threenative.d.ts +9 -2
  49. package/dist/threenative.js +2570 -176
  50. package/package.json +55 -6
  51. package/template-assets/icon.png +0 -0
  52. package/template-assets/loading.ts +325 -0
  53. package/template-assets/patches/three@0.185.1.patch +522 -0
  54. package/template-assets/worldEnvironment.ts +758 -0
  55. package/templates/action-rpg/.codex/config.toml +19 -0
  56. package/templates/action-rpg/.cursor/mcp.json +32 -0
  57. package/templates/action-rpg/.gemini/settings.json +32 -0
  58. package/templates/action-rpg/.mcp.json +18 -2
  59. package/templates/action-rpg/.vscode/mcp.json +36 -0
  60. package/templates/action-rpg/.zed/settings.json +36 -0
  61. package/templates/action-rpg/AGENTS.md +84 -29
  62. package/templates/action-rpg/CLAUDE.md +84 -29
  63. package/templates/action-rpg/index.html +0 -1
  64. package/templates/action-rpg/opencode.json +41 -0
  65. package/templates/action-rpg/package.json +15 -11
  66. package/templates/action-rpg/playtests/combat.playtest.json +32 -9
  67. package/templates/action-rpg/playtests/fail.playtest.json +3 -3
  68. package/templates/action-rpg/playtests/inventory.playtest.json +16 -10
  69. package/templates/action-rpg/playtests/performance.playtest.json +39 -0
  70. package/templates/action-rpg/playtests/progress.playtest.json +18 -13
  71. package/templates/action-rpg/playtests/survives.playtest.json +27 -0
  72. package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
  73. package/templates/action-rpg/playtests/win.playtest.json +10 -4
  74. package/templates/action-rpg/src/conventions.ts +35 -0
  75. package/templates/action-rpg/src/entities/Enemy.ts +16 -7
  76. package/templates/action-rpg/src/entities/Player.ts +20 -3
  77. package/templates/action-rpg/src/game.ts +21 -0
  78. package/templates/action-rpg/src/render/camera.ts +7 -2
  79. package/templates/action-rpg/src/render/lighting.ts +11 -4
  80. package/templates/action-rpg/src/render/loading.ts +278 -43
  81. package/templates/action-rpg/src/render/materials.ts +11 -0
  82. package/templates/action-rpg/src/render/palette.ts +10 -3
  83. package/templates/action-rpg/src/render/postprocessing.ts +32 -16
  84. package/templates/action-rpg/src/render/quality.ts +170 -0
  85. package/templates/action-rpg/src/render/shapes.ts +185 -26
  86. package/templates/action-rpg/src/render/touch-controls.ts +185 -0
  87. package/templates/action-rpg/src/render/vfx.ts +257 -0
  88. package/templates/action-rpg/src/render/worldEnvironment.ts +758 -0
  89. package/templates/action-rpg/src/scenes/Play.ts +91 -24
  90. package/templates/action-rpg/src/state.ts +4 -0
  91. package/templates/action-rpg/src/style.css +65 -1
  92. package/templates/action-rpg/src/ui/AbilityBar.tsx +9 -7
  93. package/templates/action-rpg/src/ui/App.tsx +9 -8
  94. package/templates/action-rpg/src/ui/CharacterPanel.tsx +10 -8
  95. package/templates/action-rpg/src/ui/GameUi.tsx +24 -0
  96. package/templates/action-rpg/src/ui/Hud.tsx +10 -8
  97. package/templates/action-rpg/src/ui/InventoryPanel.tsx +9 -7
  98. package/templates/action-rpg/src/ui/main.tsx +14 -0
  99. package/templates/action-rpg/threenative.config.ts +28 -8
  100. package/templates/action-rpg/vite.config.ts +32 -2
  101. package/templates/defense/.codex/config.toml +19 -0
  102. package/templates/defense/.cursor/mcp.json +32 -0
  103. package/templates/defense/.gemini/settings.json +32 -0
  104. package/templates/defense/.mcp.json +18 -2
  105. package/templates/defense/.vscode/mcp.json +36 -0
  106. package/templates/defense/.zed/settings.json +36 -0
  107. package/templates/defense/AGENTS.md +81 -41
  108. package/templates/defense/CLAUDE.md +81 -41
  109. package/templates/defense/README.md +2 -1
  110. package/templates/defense/index.html +0 -1
  111. package/templates/defense/opencode.json +41 -0
  112. package/templates/defense/package.json +16 -12
  113. package/templates/defense/playtests/leak.playtest.json +9 -4
  114. package/templates/defense/playtests/performance.playtest.json +39 -0
  115. package/templates/defense/playtests/placement.playtest.json +5 -5
  116. package/templates/defense/playtests/pointer-placement.playtest.json +156 -0
  117. package/templates/defense/playtests/scan.playtest.json +4 -4
  118. package/templates/defense/playtests/survive.playtest.json +25 -6
  119. package/templates/defense/src/attackers/Attacker.ts +32 -16
  120. package/templates/defense/src/board/Route.ts +22 -8
  121. package/templates/defense/src/conventions.ts +18 -0
  122. package/templates/defense/src/entities/Player.ts +11 -3
  123. package/templates/defense/src/game.ts +25 -4
  124. package/templates/defense/src/physics.ts +9 -39
  125. package/templates/defense/src/placement/Buildable.ts +4 -4
  126. package/templates/defense/src/render/camera.ts +9 -3
  127. package/templates/defense/src/render/lighting.ts +6 -1
  128. package/templates/defense/src/render/loading.ts +274 -38
  129. package/templates/defense/src/render/materials.ts +9 -0
  130. package/templates/defense/src/render/palette.ts +12 -5
  131. package/templates/defense/src/render/postprocessing.ts +32 -12
  132. package/templates/defense/src/render/quality.ts +170 -0
  133. package/templates/defense/src/render/shapes.ts +180 -23
  134. package/templates/defense/src/render/sky.ts +2 -2
  135. package/templates/defense/src/render/worldEnvironment.ts +758 -0
  136. package/templates/defense/src/scenes/Boot.ts +2 -2
  137. package/templates/defense/src/scenes/Defense.ts +122 -56
  138. package/templates/defense/src/state.ts +6 -0
  139. package/templates/defense/src/style.css +65 -1
  140. package/templates/defense/src/towers/Tower.ts +11 -12
  141. package/templates/defense/src/towers/targeting.ts +1 -1
  142. package/templates/defense/src/ui/App.tsx +11 -6
  143. package/templates/defense/src/ui/GameUi.tsx +20 -0
  144. package/templates/defense/src/ui/Hud.tsx +6 -5
  145. package/templates/defense/src/ui/main.tsx +14 -0
  146. package/templates/defense/threenative.config.ts +28 -8
  147. package/templates/defense/vite.config.ts +34 -1
  148. package/templates/minimal/.codex/config.toml +19 -0
  149. package/templates/minimal/.cursor/mcp.json +32 -0
  150. package/templates/minimal/.gemini/settings.json +32 -0
  151. package/templates/minimal/.mcp.json +18 -2
  152. package/templates/minimal/.vscode/mcp.json +36 -0
  153. package/templates/minimal/.zed/settings.json +36 -0
  154. package/templates/minimal/AGENTS.md +78 -382
  155. package/templates/minimal/CLAUDE.md +78 -382
  156. package/templates/minimal/index.html +0 -1
  157. package/templates/minimal/opencode.json +41 -0
  158. package/templates/minimal/package.json +14 -11
  159. package/templates/minimal/playtests/atmosphere.playtest.json +32 -0
  160. package/templates/minimal/playtests/play.playtest.json +18 -5
  161. package/templates/minimal/playtests/survives.playtest.json +48 -4
  162. package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
  163. package/templates/minimal/src/conventions.ts +18 -0
  164. package/templates/minimal/src/entities/Player.ts +39 -6
  165. package/templates/minimal/src/game.ts +1 -0
  166. package/templates/minimal/src/main.ts +14 -4
  167. package/templates/minimal/src/render/camera.ts +1 -1
  168. package/templates/minimal/src/render/hud.ts +24 -8
  169. package/templates/minimal/src/render/lighting.ts +23 -2
  170. package/templates/minimal/src/render/loading.ts +23 -103
  171. package/templates/minimal/src/render/materials.ts +7 -0
  172. package/templates/minimal/src/render/palette.ts +3 -3
  173. package/templates/minimal/src/render/postprocessing.ts +55 -16
  174. package/templates/minimal/src/render/quality.ts +162 -0
  175. package/templates/minimal/src/render/sky.ts +51 -32
  176. package/templates/minimal/src/render/touch-controls.ts +165 -0
  177. package/templates/minimal/src/render/worldEnvironment.ts +758 -0
  178. package/templates/minimal/src/scenes/Play.ts +128 -14
  179. package/templates/minimal/src/state.ts +8 -1
  180. package/templates/minimal/src/style.css +20 -0
  181. package/templates/minimal/threenative.config.ts +22 -10
  182. package/templates/minimal/vite.config.ts +28 -1
  183. package/templates/platformer/.codex/config.toml +19 -0
  184. package/templates/platformer/.cursor/mcp.json +32 -0
  185. package/templates/platformer/.gemini/settings.json +32 -0
  186. package/templates/platformer/.mcp.json +18 -2
  187. package/templates/platformer/.vscode/mcp.json +36 -0
  188. package/templates/platformer/.zed/settings.json +36 -0
  189. package/templates/platformer/AGENTS.md +81 -186
  190. package/templates/platformer/CLAUDE.md +81 -186
  191. package/templates/platformer/index.html +0 -1
  192. package/templates/platformer/opencode.json +41 -0
  193. package/templates/platformer/package.json +17 -14
  194. package/templates/platformer/playtests/avoidance.playtest.json +6 -1
  195. package/templates/platformer/playtests/branding.playtest.json +29 -0
  196. package/templates/platformer/playtests/buffer.playtest.json +1 -1
  197. package/templates/platformer/playtests/collect.playtest.json +1 -1
  198. package/templates/platformer/playtests/collision-layers.playtest.json +2 -2
  199. package/templates/platformer/playtests/coyote.playtest.json +42 -8
  200. package/templates/platformer/playtests/damage.playtest.json +4 -1
  201. package/templates/platformer/playtests/dash.playtest.json +2 -2
  202. package/templates/platformer/playtests/jump.playtest.json +2 -3
  203. package/templates/platformer/playtests/native/touch-controls.playtest.json +33 -0
  204. package/templates/platformer/playtests/oneway.playtest.json +30 -3
  205. package/templates/platformer/playtests/performance.playtest.json +7 -5
  206. package/templates/platformer/playtests/respawn.playtest.json +2 -2
  207. package/templates/platformer/playtests/stomp-rise.playtest.json +17 -3
  208. package/templates/platformer/playtests/stomp.playtest.json +11 -3
  209. package/templates/platformer/playtests/survives.playtest.json +31 -0
  210. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +16 -4
  211. package/templates/platformer/playtests/terminal-loop-win.playtest.json +3 -3
  212. package/templates/platformer/playtests/touch-controls-web.playtest.json +57 -0
  213. package/templates/platformer/src/conventions.ts +18 -0
  214. package/templates/platformer/src/entities/Character.ts +79 -11
  215. package/templates/platformer/src/entities/Patrol.ts +5 -0
  216. package/templates/platformer/src/game.ts +27 -2
  217. package/templates/platformer/src/level/Platform.ts +13 -1
  218. package/templates/platformer/src/render/lighting.ts +13 -5
  219. package/templates/platformer/src/render/loading.ts +281 -62
  220. package/templates/platformer/src/render/palette.ts +4 -1
  221. package/templates/platformer/src/render/postprocessing.ts +42 -14
  222. package/templates/platformer/src/render/quality.ts +170 -0
  223. package/templates/platformer/src/render/touch-controls.ts +54 -36
  224. package/templates/platformer/src/render/worldEnvironment.ts +758 -0
  225. package/templates/platformer/src/scenes/Level.ts +97 -32
  226. package/templates/platformer/src/state.ts +4 -0
  227. package/templates/platformer/src/style.css +65 -1
  228. package/templates/platformer/src/ui/App.tsx +9 -4
  229. package/templates/platformer/src/ui/GameUi.tsx +20 -0
  230. package/templates/platformer/src/ui/Hud.tsx +6 -5
  231. package/templates/platformer/src/ui/main.tsx +14 -0
  232. package/templates/platformer/threenative.config.ts +27 -10
  233. package/templates/platformer/vite.config.ts +34 -1
  234. package/templates/puzzle/.codex/config.toml +19 -0
  235. package/templates/puzzle/.cursor/mcp.json +32 -0
  236. package/templates/puzzle/.gemini/settings.json +32 -0
  237. package/templates/puzzle/.mcp.json +32 -0
  238. package/templates/puzzle/.vscode/mcp.json +36 -0
  239. package/templates/puzzle/.zed/settings.json +36 -0
  240. package/templates/puzzle/AGENTS.md +96 -0
  241. package/templates/puzzle/CLAUDE.md +98 -0
  242. package/templates/puzzle/README.md +43 -0
  243. package/templates/puzzle/index.html +12 -0
  244. package/templates/puzzle/kit.json +7 -0
  245. package/templates/puzzle/opencode.json +41 -0
  246. package/templates/puzzle/package.json +50 -0
  247. package/templates/puzzle/playtests/carry.playtest.json +71 -0
  248. package/templates/puzzle/playtests/performance.playtest.json +23 -0
  249. package/templates/puzzle/playtests/survives.playtest.json +51 -0
  250. package/templates/puzzle/playtests/swing.playtest.json +38 -0
  251. package/templates/puzzle/public/favicon.svg +5 -0
  252. package/templates/puzzle/src/conventions.ts +25 -0
  253. package/templates/puzzle/src/entities/Ball.ts +70 -0
  254. package/templates/puzzle/src/entities/Crate.ts +76 -0
  255. package/templates/puzzle/src/entities/Gripper.ts +69 -0
  256. package/templates/puzzle/src/entities/Pendulum.ts +89 -0
  257. package/templates/puzzle/src/game.ts +48 -0
  258. package/templates/puzzle/src/main.ts +15 -0
  259. package/templates/puzzle/src/physics.ts +19 -0
  260. package/templates/puzzle/src/render/camera.ts +37 -0
  261. package/templates/puzzle/src/render/lighting.ts +55 -0
  262. package/templates/puzzle/src/render/loading.ts +325 -0
  263. package/templates/puzzle/src/render/materials.ts +28 -0
  264. package/templates/puzzle/src/render/palette.ts +31 -0
  265. package/templates/puzzle/src/render/postprocessing.ts +34 -0
  266. package/templates/puzzle/src/render/quality.ts +170 -0
  267. package/templates/puzzle/src/render/shapes.ts +134 -0
  268. package/templates/puzzle/src/render/sky.ts +16 -0
  269. package/templates/puzzle/src/render/touch-controls.ts +185 -0
  270. package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
  271. package/templates/puzzle/src/room.ts +83 -0
  272. package/templates/puzzle/src/scenes/Boot.ts +12 -0
  273. package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
  274. package/templates/puzzle/src/state.ts +30 -0
  275. package/templates/puzzle/src/style.css +96 -0
  276. package/templates/puzzle/src/ui/App.tsx +22 -0
  277. package/templates/puzzle/src/ui/GameUi.tsx +20 -0
  278. package/templates/puzzle/src/ui/Hud.tsx +57 -0
  279. package/templates/puzzle/src/ui/Menu.tsx +7 -0
  280. package/templates/puzzle/src/ui/main.tsx +14 -0
  281. package/templates/puzzle/tailwind.config.ts +1 -0
  282. package/templates/puzzle/threenative.config.ts +49 -0
  283. package/templates/puzzle/tsconfig.json +17 -0
  284. package/templates/puzzle/vite.config.ts +38 -0
  285. package/templates/racing/.codex/config.toml +19 -0
  286. package/templates/racing/.cursor/mcp.json +32 -0
  287. package/templates/racing/.gemini/settings.json +32 -0
  288. package/templates/racing/.mcp.json +18 -2
  289. package/templates/racing/.vscode/mcp.json +36 -0
  290. package/templates/racing/.zed/settings.json +36 -0
  291. package/templates/racing/AGENTS.md +84 -36
  292. package/templates/racing/CLAUDE.md +84 -36
  293. package/templates/racing/index.html +0 -1
  294. package/templates/racing/native-playtests/survives.playtest.json +43 -0
  295. package/templates/racing/opencode.json +41 -0
  296. package/templates/racing/package.json +17 -12
  297. package/templates/racing/playtests/boost.playtest.json +5 -5
  298. package/templates/racing/playtests/outcome.playtest.json +14 -4
  299. package/templates/racing/playtests/performance.playtest.json +39 -0
  300. package/templates/racing/playtests/ranking.playtest.json +2 -2
  301. package/templates/racing/playtests/rescue.playtest.json +12 -6
  302. package/templates/racing/playtests/reverse.playtest.json +3 -3
  303. package/templates/racing/playtests/shortcut.playtest.json +3 -3
  304. package/templates/racing/playtests/survives.playtest.json +36 -4
  305. package/templates/racing/playtests/touch-controls.playtest.json +41 -0
  306. package/templates/racing/src/conventions.ts +6 -0
  307. package/templates/racing/src/entities/RacingCar.ts +16 -4
  308. package/templates/racing/src/entities/Rival.ts +5 -2
  309. package/templates/racing/src/game.ts +24 -1
  310. package/templates/racing/src/render/camera.ts +15 -8
  311. package/templates/racing/src/render/lighting.ts +28 -14
  312. package/templates/racing/src/render/loading.ts +302 -35
  313. package/templates/racing/src/render/materials.ts +54 -4
  314. package/templates/racing/src/render/palette.ts +23 -6
  315. package/templates/racing/src/render/postprocessing.ts +32 -12
  316. package/templates/racing/src/render/quality.ts +170 -0
  317. package/templates/racing/src/render/shapes.ts +537 -26
  318. package/templates/racing/src/render/sky.ts +5 -2
  319. package/templates/racing/src/render/touch-controls.ts +185 -0
  320. package/templates/racing/src/render/worldEnvironment.ts +758 -0
  321. package/templates/racing/src/scenes/Race.ts +84 -37
  322. package/templates/racing/src/state.ts +4 -0
  323. package/templates/racing/src/style.css +65 -1
  324. package/templates/racing/src/track/Lap.ts +20 -9
  325. package/templates/racing/src/track/Ranking.ts +53 -14
  326. package/templates/racing/src/track/Track.ts +284 -32
  327. package/templates/racing/src/track/TrackSector.ts +14 -4
  328. package/templates/racing/src/ui/App.tsx +9 -4
  329. package/templates/racing/src/ui/GameUi.tsx +20 -0
  330. package/templates/racing/src/ui/Hud.tsx +6 -5
  331. package/templates/racing/src/ui/main.tsx +14 -0
  332. package/templates/racing/threenative.config.ts +28 -8
  333. package/templates/racing/vite.config.ts +34 -1
  334. package/templates/runner/.codex/config.toml +19 -0
  335. package/templates/runner/.cursor/mcp.json +32 -0
  336. package/templates/runner/.gemini/settings.json +32 -0
  337. package/templates/runner/.mcp.json +32 -0
  338. package/templates/runner/.vscode/mcp.json +36 -0
  339. package/templates/runner/.zed/settings.json +36 -0
  340. package/templates/runner/AGENTS.md +96 -0
  341. package/templates/runner/CLAUDE.md +98 -0
  342. package/templates/runner/README.md +43 -0
  343. package/templates/runner/index.html +12 -0
  344. package/templates/runner/kit.json +7 -0
  345. package/templates/runner/opencode.json +41 -0
  346. package/templates/runner/package.json +50 -0
  347. package/templates/runner/playtests/performance.playtest.json +23 -0
  348. package/templates/runner/playtests/streams.playtest.json +38 -0
  349. package/templates/runner/playtests/survives.playtest.json +51 -0
  350. package/templates/runner/public/favicon.svg +5 -0
  351. package/templates/runner/src/conventions.ts +24 -0
  352. package/templates/runner/src/entities/Runner.ts +135 -0
  353. package/templates/runner/src/game.ts +50 -0
  354. package/templates/runner/src/main.ts +15 -0
  355. package/templates/runner/src/physics.ts +13 -0
  356. package/templates/runner/src/render/camera.ts +39 -0
  357. package/templates/runner/src/render/dust.ts +131 -0
  358. package/templates/runner/src/render/lighting.ts +57 -0
  359. package/templates/runner/src/render/loading.ts +325 -0
  360. package/templates/runner/src/render/materials.ts +27 -0
  361. package/templates/runner/src/render/palette.ts +30 -0
  362. package/templates/runner/src/render/postprocessing.ts +34 -0
  363. package/templates/runner/src/render/quality.ts +170 -0
  364. package/templates/runner/src/render/shapes.ts +68 -0
  365. package/templates/runner/src/render/sky.ts +51 -0
  366. package/templates/runner/src/render/touch-controls.ts +185 -0
  367. package/templates/runner/src/render/worldEnvironment.ts +758 -0
  368. package/templates/runner/src/scenes/Boot.ts +12 -0
  369. package/templates/runner/src/scenes/Run.ts +142 -0
  370. package/templates/runner/src/state.ts +29 -0
  371. package/templates/runner/src/style.css +96 -0
  372. package/templates/runner/src/track.ts +176 -0
  373. package/templates/runner/src/ui/App.tsx +22 -0
  374. package/templates/runner/src/ui/GameUi.tsx +20 -0
  375. package/templates/runner/src/ui/Hud.tsx +55 -0
  376. package/templates/runner/src/ui/Menu.tsx +7 -0
  377. package/templates/runner/src/ui/main.tsx +14 -0
  378. package/templates/runner/tailwind.config.ts +1 -0
  379. package/templates/runner/threenative.config.ts +49 -0
  380. package/templates/runner/tsconfig.json +17 -0
  381. package/templates/runner/vite.config.ts +38 -0
  382. package/templates/sailing/.codex/config.toml +19 -0
  383. package/templates/sailing/.cursor/mcp.json +32 -0
  384. package/templates/sailing/.gemini/settings.json +32 -0
  385. package/templates/sailing/.mcp.json +32 -0
  386. package/templates/sailing/.vscode/mcp.json +36 -0
  387. package/templates/sailing/.zed/settings.json +36 -0
  388. package/templates/sailing/AGENTS.md +95 -0
  389. package/templates/sailing/CLAUDE.md +97 -0
  390. package/templates/sailing/README.md +28 -0
  391. package/templates/sailing/index.html +12 -0
  392. package/templates/sailing/kit.json +7 -0
  393. package/templates/sailing/native-playtests/float.playtest.json +55 -0
  394. package/templates/sailing/native-playtests/survives.playtest.json +38 -0
  395. package/templates/sailing/opencode.json +41 -0
  396. package/templates/sailing/package.json +52 -0
  397. package/templates/sailing/playtests/fail.playtest.json +24 -0
  398. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
  399. package/templates/sailing/playtests/float.playtest.json +59 -0
  400. package/templates/sailing/playtests/performance.playtest.json +36 -0
  401. package/templates/sailing/playtests/survives.playtest.json +46 -0
  402. package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
  403. package/templates/sailing/playtests/win.playtest.json +31 -0
  404. package/templates/sailing/public/favicon.svg +5 -0
  405. package/templates/sailing/src/conventions.ts +8 -0
  406. package/templates/sailing/src/entities/Ship.ts +233 -0
  407. package/templates/sailing/src/game.ts +40 -0
  408. package/templates/sailing/src/main.ts +15 -0
  409. package/templates/sailing/src/render/camera.ts +28 -0
  410. package/templates/sailing/src/render/lighting.ts +41 -0
  411. package/templates/sailing/src/render/loading.ts +325 -0
  412. package/templates/sailing/src/render/materials.ts +44 -0
  413. package/templates/sailing/src/render/ocean.ts +179 -0
  414. package/templates/sailing/src/render/palette.ts +17 -0
  415. package/templates/sailing/src/render/postprocessing.ts +34 -0
  416. package/templates/sailing/src/render/props.ts +602 -0
  417. package/templates/sailing/src/render/quality.ts +140 -0
  418. package/templates/sailing/src/render/sky.ts +37 -0
  419. package/templates/sailing/src/render/touch-controls.ts +142 -0
  420. package/templates/sailing/src/render/worldEnvironment.ts +758 -0
  421. package/templates/sailing/src/scenes/Boot.ts +12 -0
  422. package/templates/sailing/src/scenes/Sailing.ts +133 -0
  423. package/templates/sailing/src/state.ts +10 -0
  424. package/templates/sailing/src/style.css +81 -0
  425. package/templates/sailing/src/ui/App.tsx +15 -0
  426. package/templates/sailing/src/ui/GameUi.tsx +12 -0
  427. package/templates/sailing/src/ui/Hud.tsx +55 -0
  428. package/templates/sailing/src/ui/Menu.tsx +30 -0
  429. package/templates/sailing/src/ui/main.tsx +7 -0
  430. package/templates/sailing/tailwind.config.ts +2 -0
  431. package/templates/sailing/threenative.config.ts +40 -0
  432. package/templates/sailing/tsconfig.json +17 -0
  433. package/templates/sailing/vite.config.ts +34 -0
  434. package/templates/shooter/.codex/config.toml +19 -0
  435. package/templates/shooter/.cursor/mcp.json +32 -0
  436. package/templates/shooter/.gemini/settings.json +32 -0
  437. package/templates/shooter/.mcp.json +18 -2
  438. package/templates/shooter/.vscode/mcp.json +36 -0
  439. package/templates/shooter/.zed/settings.json +36 -0
  440. package/templates/shooter/AGENTS.md +81 -54
  441. package/templates/shooter/CLAUDE.md +81 -54
  442. package/templates/shooter/index.html +0 -1
  443. package/templates/shooter/kit.json +2 -2
  444. package/templates/shooter/opencode.json +41 -0
  445. package/templates/shooter/package.json +16 -11
  446. package/templates/shooter/playtests/combat.playtest.json +48 -0
  447. package/templates/shooter/playtests/fail.playtest.json +5 -4
  448. package/templates/shooter/playtests/input-control.playtest.json +261 -0
  449. package/templates/shooter/playtests/per-item.playtest.json +59 -0
  450. package/templates/shooter/playtests/performance.playtest.json +39 -0
  451. package/templates/shooter/playtests/shooter.playtest.json +31 -21
  452. package/templates/shooter/playtests/survives.playtest.json +28 -1
  453. package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
  454. package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
  455. package/templates/shooter/public/favicon.svg +1 -1
  456. package/templates/shooter/src/combat/damage.ts +1 -2
  457. package/templates/shooter/src/conventions.ts +51 -0
  458. package/templates/shooter/src/entities/Player.ts +235 -18
  459. package/templates/shooter/src/entities/Target.ts +2 -2
  460. package/templates/shooter/src/game.ts +35 -3
  461. package/templates/shooter/src/main.ts +3 -13
  462. package/templates/shooter/src/render/camera.ts +78 -18
  463. package/templates/shooter/src/render/decals.ts +211 -0
  464. package/templates/shooter/src/render/lighting.ts +13 -4
  465. package/templates/shooter/src/render/loading.ts +274 -35
  466. package/templates/shooter/src/render/materials.ts +56 -3
  467. package/templates/shooter/src/render/palette.ts +6 -3
  468. package/templates/shooter/src/render/postprocessing.ts +32 -17
  469. package/templates/shooter/src/render/quality.ts +170 -0
  470. package/templates/shooter/src/render/scale.ts +22 -0
  471. package/templates/shooter/src/render/shapes.ts +519 -60
  472. package/templates/shooter/src/render/sky.ts +5 -1
  473. package/templates/shooter/src/render/touch-controls.ts +305 -0
  474. package/templates/shooter/src/render/ui.css +119 -1
  475. package/templates/shooter/src/render/ui.ts +19 -3
  476. package/templates/shooter/src/render/vfx.ts +215 -0
  477. package/templates/shooter/src/render/worldEnvironment.ts +758 -0
  478. package/templates/shooter/src/scenes/Play.ts +385 -97
  479. package/templates/shooter/src/state.ts +18 -0
  480. package/templates/shooter/src/style.css +46 -0
  481. package/templates/shooter/src/ui/App.tsx +10 -12
  482. package/templates/shooter/src/ui/Crosshair.tsx +25 -0
  483. package/templates/shooter/src/ui/GameUi.tsx +22 -0
  484. package/templates/shooter/src/ui/Hud.tsx +14 -10
  485. package/templates/shooter/src/ui/Menu.tsx +24 -9
  486. package/templates/shooter/src/ui/main.tsx +15 -0
  487. package/templates/shooter/src/weapons/Hitscan.ts +3 -4
  488. package/templates/shooter/src/weapons/Projectile.ts +29 -13
  489. package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
  490. package/templates/shooter/threenative.config.ts +28 -8
  491. package/templates/shooter/vite.config.ts +32 -2
  492. package/templates/starter/.codex/config.toml +19 -0
  493. package/templates/starter/.cursor/mcp.json +32 -0
  494. package/templates/starter/.gemini/settings.json +32 -0
  495. package/templates/starter/.mcp.json +18 -2
  496. package/templates/starter/.vscode/mcp.json +36 -0
  497. package/templates/starter/.zed/settings.json +36 -0
  498. package/templates/starter/AGENTS.md +72 -426
  499. package/templates/starter/CLAUDE.md +72 -426
  500. package/templates/starter/assets/pickup.wav +0 -0
  501. package/templates/starter/gitignore +4 -0
  502. package/templates/starter/index.html +0 -1
  503. package/templates/starter/native-playtests/react-hud.playtest.json +20 -0
  504. package/templates/starter/native-playtests/render-chain.playtest.json +81 -0
  505. package/templates/starter/opencode.json +41 -0
  506. package/templates/starter/package.json +16 -12
  507. package/templates/starter/playtests/assets.playtest.json +65 -0
  508. package/templates/starter/playtests/boot-failure.playtest.json +45 -0
  509. package/templates/starter/playtests/buffer.playtest.json +59 -9
  510. package/templates/starter/playtests/cloth.playtest.json +113 -0
  511. package/templates/starter/playtests/coyote.playtest.json +60 -8
  512. package/templates/starter/playtests/forward.playtest.json +29 -4
  513. package/templates/starter/playtests/gameover.playtest.json +66 -0
  514. package/templates/starter/playtests/goal.playtest.json +67 -0
  515. package/templates/starter/playtests/hot-reload.playtest.json +48 -8
  516. package/templates/starter/playtests/look.playtest.json +142 -10
  517. package/templates/starter/playtests/models-baseline.png +0 -0
  518. package/templates/starter/playtests/models.playtest.json +74 -0
  519. package/templates/starter/playtests/monitoring.playtest.json +38 -7
  520. package/templates/starter/playtests/odometer.playtest.json +54 -0
  521. package/templates/starter/playtests/pause.playtest.json +27 -4
  522. package/templates/starter/playtests/play.playtest.json +44 -7
  523. package/templates/starter/playtests/respawn.playtest.json +46 -6
  524. package/templates/starter/playtests/restart.playtest.json +65 -10
  525. package/templates/starter/playtests/seed.playtest.json +44 -8
  526. package/templates/starter/playtests/survives.playtest.json +48 -4
  527. package/templates/starter/playtests/textures-baseline.png +0 -0
  528. package/templates/starter/playtests/textures.playtest.json +74 -0
  529. package/templates/starter/playtests/touch-controls.playtest.json +42 -0
  530. package/templates/starter/playtests/zoom-pinch.playtest.json +86 -0
  531. package/templates/starter/playtests/zoom-wheel.playtest.json +59 -0
  532. package/templates/starter/src/conventions.ts +18 -0
  533. package/templates/starter/src/entities/Goal.ts +137 -0
  534. package/templates/starter/src/entities/Player.ts +111 -10
  535. package/templates/starter/src/game.ts +27 -0
  536. package/templates/starter/src/render/adaptiveQuality.ts +195 -0
  537. package/templates/starter/src/render/camera.ts +31 -5
  538. package/templates/starter/src/render/coast.ts +199 -0
  539. package/templates/starter/src/render/easing.ts +5 -0
  540. package/templates/starter/src/render/effects/gradualBackground.ts +48 -0
  541. package/templates/starter/src/render/effects/lensDistortion.ts +43 -0
  542. package/templates/starter/src/render/effects/sparkle.ts +49 -0
  543. package/templates/starter/src/render/hero.ts +88 -0
  544. package/templates/starter/src/render/implicitSurface.ts +199 -0
  545. package/templates/starter/src/render/kuwahara.ts +174 -0
  546. package/templates/starter/src/render/lighting.ts +10 -5
  547. package/templates/starter/src/render/loading.ts +325 -0
  548. package/templates/starter/src/render/materials.ts +39 -4
  549. package/templates/starter/src/render/outline.ts +141 -0
  550. package/templates/starter/src/render/painterly.ts +86 -0
  551. package/templates/starter/src/render/palette.ts +15 -6
  552. package/templates/starter/src/render/pennant.ts +54 -0
  553. package/templates/starter/src/render/postprocessing.ts +97 -15
  554. package/templates/starter/src/render/quality.ts +185 -0
  555. package/templates/starter/src/render/rockRidge.ts +198 -0
  556. package/templates/starter/src/render/rockRidge.worker.ts +77 -0
  557. package/templates/starter/src/render/scenery.ts +40 -0
  558. package/templates/starter/src/render/shapes.ts +9 -21
  559. package/templates/starter/src/render/textureLifetime.ts +53 -0
  560. package/templates/starter/src/render/touch-controls.ts +165 -0
  561. package/templates/starter/src/render/water.ts +38 -0
  562. package/templates/starter/src/render/watercolor.ts +85 -0
  563. package/templates/starter/src/render/worldEnvironment.ts +758 -0
  564. package/templates/starter/src/scenes/Play.ts +243 -46
  565. package/templates/starter/src/state.ts +12 -0
  566. package/templates/starter/src/style.css +72 -8
  567. package/templates/starter/src/ui/App.tsx +9 -6
  568. package/templates/starter/src/ui/GameUi.tsx +20 -0
  569. package/templates/starter/src/ui/Hud.tsx +52 -29
  570. package/templates/starter/src/ui/Menu.tsx +25 -23
  571. package/templates/starter/src/ui/main.tsx +14 -0
  572. package/templates/starter/threenative.config.ts +27 -9
  573. package/templates/starter/tools/look.mjs +109 -0
  574. package/templates/starter/vite.config.ts +32 -2
  575. package/templates/action-rpg/src/physics.ts +0 -40
  576. package/templates/minimal/assets/.gitkeep +0 -0
  577. package/templates/minimal/public/.gitkeep +0 -0
  578. package/templates/minimal/public/icon.png +0 -0
  579. package/templates/platformer/assets/.gitkeep +0 -0
  580. package/templates/platformer/public/.gitkeep +0 -0
  581. package/templates/platformer/public/icon.png +0 -0
  582. package/templates/shooter/src/physics.ts +0 -49
  583. package/templates/starter/assets/.gitkeep +0 -0
  584. package/templates/starter/public/.gitkeep +0 -0
  585. package/templates/starter/public/icon.png +0 -0
  586. package/templates/starter/public/pickup.ogg +0 -0
  587. /package/templates/starter/{public → assets}/native-proof.glb +0 -0
  588. /package/templates/starter/{public → assets}/native-proof.png +0 -0
@@ -0,0 +1,60 @@
1
+ # Capture the frame — screenshots that actually render WebGPU
2
+
3
+ Companion to the `Budget real time for the look` section in this project's `AGENTS.md`. Run
4
+ `pnpm dev`, then get eyes on the game. In rough order of preference:
5
+
6
+ **First, though, when the complaint is "it looks wrong" rather than "show me":** run
7
+ `npx @threenative/playtest doctor --url http://127.0.0.1:5173 --text`. A capture shows you a black
8
+ or washed-out frame; it cannot tell you *why*. The doctor's lighting, materials and camera
9
+ lines can, and they name the three cases that kill a frame while every other number stays healthy —
10
+ lit materials with no visible light, a fog far plane in front of the scene it fogs, and a camera
11
+ far plane that clips it. Capture after that, to see what the numbers already told you.
12
+
13
+ 1. **Browser automation against the user's real Chrome**, if you have it — Claude in Chrome
14
+ or any equivalent MCP browser tool. This is the best option by a wide margin: it runs on
15
+ a real GPU, so WebGPU works, and you can navigate, press keys, screenshot, and read the
16
+ console in the same loop you are already coding in. Drive the game, do not just load the
17
+ menu.
18
+ 2. **`npx @threenative/playtest <scenario> --browser-recipe webgpu --headed`.** The recipe
19
+ carries the Chromium flags a WebGPU capture needs, including `--enable-features=Vulkan`.
20
+ Do not hand-roll the flag list: without that one flag Chromium never reaches the Linux
21
+ Vulkan driver and serves WebGPU from SwiftShader, its CPU rasteriser — no error, healthy
22
+ limits, and a software renderer's picture. The runner fails such a run with
23
+ `TN_PLAYTEST_SOFTWARE_ADAPTER` and prints the adapter it got; `--allow-software` accepts
24
+ the fallback if you truly want it.
25
+ 3. **Ask the user to look**, and say specifically what you want them to check.
26
+
27
+ ## Virtual displays
28
+
29
+ On a machine with no screen, run any of those under a virtual display. **Do not use
30
+ `xvfb-run`:** on `xorg-server-xvfb` 21.1.x its cleanup `kill` fails after Xvfb has already
31
+ exited and that failing kill's status replaces the real one, so
32
+ `xvfb-run -a -s '-screen 0 1600x900x24' true` exits `1`. Every gate wrapped in it reports
33
+ failure whether it passed or not. Start `Xvfb` yourself on a free display and export
34
+ `DISPLAY`, or check the command's own exit code separately.
35
+
36
+ ## Headless Chromium usually cannot render WebGPU
37
+
38
+ The page loads, the HUD paints, and the 3D canvas comes out blank or black. That looks
39
+ exactly like a bug in your scene, and it is not. Symptoms are `Instance dropped in
40
+ popErrorScope` and `createBuffer failed, size (N) is too large for the implementation` in
41
+ the console.
42
+
43
+ So: if a screenshot comes back black or empty, suspect the capture before you rewrite the
44
+ scene. Confirm the renderer works at all before you go debugging your materials.
45
+
46
+ ## The silhouette checklist
47
+
48
+ 1. **Look at it.** Boot the game, get the thing on screen, take a screenshot, open the
49
+ screenshot. Reading your own diff is not looking at it.
50
+ 2. **Silhouette first.** Can you tell what it is from its outline alone? Break up long
51
+ straight edges — overhangs, fringes, props crossing the line.
52
+ 3. **Give it depth.** Something bright behind it, something dark under it. Contact shadows
53
+ and a rim make a prop sit in the world instead of floating on top of it.
54
+ 4. **Make it move.** Idle bob, a squash on impact, a particle on pickup, a screen shake on
55
+ damage. A few frames of motion is the cheapest quality-per-line in the whole project.
56
+ 5. **Finish the HUD too.** Spacing, hierarchy, a transition on every number that changes.
57
+
58
+ When you think you are done, ask yourself, honestly: *would a player screenshot this?* If
59
+ the answer is no, you are not finished — and no command in this project is going to tell
60
+ you that.
@@ -0,0 +1,215 @@
1
+ # Creating an animated creature through the asset MCP
2
+
3
+ Use this recipe when the game needs a bespoke, animated creature. The asset MCP owns the
4
+ packaged anyCreature compiler and local preview/check tools; the game owns the authored spec,
5
+ claims, render source, cook and playback. Do not add anyCreature to `src/` or the player bundle.
6
+
7
+ ## 1. Choose the input route
8
+
9
+ For a conventional model, use `finding-assets.md`. For a supplied reference image, first follow
10
+ `sculpt-from-a-reference.md`: record the reference credit, inventory its recognizable regions and
11
+ decide which details are geometry. Then translate that brief into a creature spec. The creature
12
+ tools accept JSON, not an image, and a successful compile is not proof that the result resembles a
13
+ reference.
14
+
15
+ For a thin request such as “a dragon”, call `creature_guide` with `section: "overview"` and ask
16
+ the single direction question described there. Freeze one identity, one signature part, one
17
+ exaggeration, the mass hierarchy, the two focal parts, the stance, the value plan and the attack
18
+ before writing geometry. A specific request still needs one winner when several parts compete for
19
+ attention.
20
+
21
+ ## 2. Check the installed tools
22
+
23
+ Start the MCP session from the game root. It reads `.mcp.json` from the launch directory. Put the
24
+ project-local directory in place before starting or restarting the server:
25
+
26
+ ```text
27
+ .threenative/creatures/
28
+ ```
29
+
30
+ Call:
31
+
32
+ ```json
33
+ // creature_status
34
+ {}
35
+ ```
36
+
37
+ Then call `creature_guide` for `overview`, `syntax`, and the stage you are entering. The guide
38
+ returned by the pinned server is the authority for supported spec fields and current limits; do
39
+ not copy a wolf example's coordinates or invent fields from memory.
40
+
41
+ `creature_status` separates the fixed compiler from optional render dependencies:
42
+
43
+ - Compiler availability is enough for a compile-only loop. It needs no Python, Chromium, account,
44
+ LLM key, setup script or runtime download.
45
+ - Silhouettes need either the reported Python outline backend or the reported Chromium fallback.
46
+ - Hero images and browser claims measurement need Chromium. A missing optional dependency is an
47
+ actionable unavailable result, not visual approval.
48
+
49
+ If `creature_compile`, `creature_preview` or `creature_check` is unavailable because the launch
50
+ root has no `.threenative` directory, create it and restart the MCP. Keep the server's paths
51
+ project-relative; never pass an absolute path, executable, URL or custom working directory.
52
+
53
+ ## 3. Author two editable files
54
+
55
+ Keep the source of truth under `.threenative/creatures/`:
56
+
57
+ ```text
58
+ .threenative/creatures/wyvern.json
59
+ .threenative/creatures/wyvern-claims.json
60
+ ```
61
+
62
+ The first file is the anyCreature spec. Use `creature_guide` with `section: "syntax"` for the
63
+ complete language. At minimum, author the metre `height`, a nonempty `palette`, named `joints`,
64
+ `chains`, `volumes` with `chain` and `material`, and all three animations. A wing or other
65
+ membrane, a conspicuous jaw/horn, and an articulated tail should be authored as the parts they
66
+ are, not as unrelated straight spikes. Keep the bind pose planted and include a forward-
67
+ committing `attack`.
68
+
69
+ The claims file is also ordinary JSON and must have a nonempty `claims` array. Replace every
70
+ placeholder with names and materials in the spec:
71
+
72
+ ```json
73
+ {
74
+ "name": "wyvern",
75
+ "claims": [
76
+ {
77
+ "type": "part_exists",
78
+ "part": "wing_skin",
79
+ "stage": "MID",
80
+ "enforce": "block",
81
+ "when": "verify"
82
+ },
83
+ {
84
+ "type": "part_signature",
85
+ "part": "wing_skin",
86
+ "view": "side",
87
+ "min_share": 0.12,
88
+ "or_min_span": 0.1,
89
+ "stage": "MID",
90
+ "enforce": "advise",
91
+ "when": "allocate"
92
+ },
93
+ {
94
+ "type": "rig_skinned",
95
+ "stage": "HIGH",
96
+ "enforce": "block",
97
+ "when": "verify"
98
+ },
99
+ {
100
+ "type": "anim_named",
101
+ "names": ["idle", "move", "attack"],
102
+ "stage": "HIGH",
103
+ "enforce": "block",
104
+ "when": "verify"
105
+ },
106
+ {
107
+ "type": "tri_budget",
108
+ "min": 400,
109
+ "max": 9000,
110
+ "stage": "LOW",
111
+ "enforce": "advise",
112
+ "when": "allocate"
113
+ }
114
+ ]
115
+ }
116
+ ```
117
+
118
+ Claims are measurements, not permission to skip a visual review. `stage` is exactly `LOW`,
119
+ `MID` or `HIGH`; `enforce` is `block` or `advise`; `when` is `allocate` or `verify`. An unknown
120
+ claim, empty stage after filtering, missing required observation or non-finite value fails closed.
121
+ Use the current `creature_guide` claims section for the complete claim-type field list.
122
+
123
+ ## 4. Compile into the normal asset source
124
+
125
+ Read the game's asset configuration and pass an explicit output path under its source asset
126
+ directory, normally `assets/creatures/`. Do not put generated source in `public/`, and do not use
127
+ the MCP's provider download directory as a creature default.
128
+
129
+ ```json
130
+ // creature_compile
131
+ {
132
+ "specPath": ".threenative/creatures/wyvern.json",
133
+ "outputPath": "assets/creatures/wyvern.glb"
134
+ }
135
+ ```
136
+
137
+ The successful result is the record for this round: retain its `inputSha256`, `outputSha256`,
138
+ `checksSha256`, measurements, clip names, diagnostics path, checks path, source snapshot path and
139
+ receipt path. Read compiler diagnostics, including warnings, before deciding what to revise. The
140
+ MCP validates the emitted GLB and publishes it atomically; a blocked or failed revision must not
141
+ replace the last good file. When revising an existing output, pass its last known
142
+ `expectedOutputSha256` so a stale writer returns `OUTPUT_CONFLICT` instead of overwriting newer
143
+ work. Edit the JSON spec, never the generated GLB.
144
+
145
+ ## 5. Inspect, preview and review each round
146
+
147
+ After a successful compile, inspect actual bytes before judging the look:
148
+
149
+ ```json
150
+ // creature_check — structural
151
+ {
152
+ "glbPath": "assets/creatures/wyvern.glb",
153
+ "mode": "structural"
154
+ }
155
+ ```
156
+
157
+ Confirm the returned measurements include reachable skin bindings, materials, bounds and clip
158
+ details. A structural pass still returns `visualReview: "notReviewed"`.
159
+
160
+ Request fresh images from the same compiled GLB:
161
+
162
+ ```json
163
+ // creature_preview — silhouettes
164
+ {
165
+ "glbPath": "assets/creatures/wyvern.glb",
166
+ "mode": "silhouettes"
167
+ }
168
+ ```
169
+
170
+ For a colour/lighting view, call the same tool with `"mode": "hero"`. The result names the
171
+ backend, native view names, camera and resolution, preview ID, artifact paths and hashes. Inspect
172
+ the actual images for the identity, signature part, tail, jaw/horn, planted stance and readable
173
+ value hierarchy. The MCP never grades its own images: `visualReview` remains `notReviewed`.
174
+
175
+ Record one small round note beside the returned artifacts: the spec hash, GLB hash, backend,
176
+ what changed, what the independent visual reviewer saw, and the next edit. Do not overwrite a
177
+ previous round's receipt, claims metrics or preview. A comparison using `previousPreviewId` is
178
+ valid only when the server reports matching backend, cameras and resolutions; a backend switch
179
+ requires a new baseline.
180
+
181
+ Run claims by stage, keeping the output for each stage:
182
+
183
+ ```json
184
+ // creature_check — LOW, then MID, then HIGH
185
+ {
186
+ "glbPath": "assets/creatures/wyvern.glb",
187
+ "mode": "claims",
188
+ "claimsPath": ".threenative/creatures/wyvern-claims.json",
189
+ "stage": "HIGH"
190
+ }
191
+ ```
192
+
193
+ Run LOW and MID while allocating big forms, then HIGH after colour and animation are authored.
194
+ Treat `advise` as measured feedback and `block` as a required fix. A passing claim response is
195
+ not a substitute for an independent human or host-side visual review.
196
+
197
+ ## 6. Deliver it to the game
198
+
199
+ Delivery requires all three real clips: `idle`, `move`, and `attack`. HIGH must find nonempty
200
+ tracks bound to the actual loaded rig, and `attack` must commit toward the space in front of the
201
+ body. Do not rename a missing clip in the game or claim success from a spec field alone.
202
+
203
+ Use the existing asset cook and loader. The source GLB stays under `assets/`; let the normal build
204
+ produce its cooked output, then load it through the same path as every other model. In the
205
+ existing scene, use `SkeletalMesh3D` and `AnimationPlayer` (search the engine capability manifest
206
+ first), set the authored body as `strideRoot` when the scene needs locomotion, and use the measured
207
+ height rather than a universal scale workaround. Play `idle -> move -> attack` in the game and
208
+ assert visible geometry, expected size, skin deformation, bound animation tracks and stable bone
209
+ lengths on every target you claim.
210
+
211
+ The final artifact is complete only after both machine results and independent visual review are
212
+ recorded. If Python or Chromium is unavailable, report a compile-only or structural result and
213
+ leave preview/claims delivery outstanding; never turn an unavailable optional tool into approval.
214
+ If the target is browser and native, run the same consumer scenario on both. Android and iOS stay
215
+ unclaimed unless their own playtests execute.
@@ -0,0 +1,120 @@
1
+ # The ctx cookbook — recipes behind the `ctx` surface table
2
+
3
+ Companion to the `The ctx surface` section in this project's `AGENTS.md`. The table there is
4
+ the contract; this page is the how and the why.
5
+
6
+ ## Pointer picking with `ctx.raycast()`
7
+
8
+ It defaults to the current pointer position and the whole scene, returns the nearest
9
+ `THREE.Intersection`, and stays under a millisecond on meshes large enough that a plain
10
+ `Raycaster` visibly stutters — it keeps an acceleration structure per geometry and rebuilds it
11
+ when that geometry's positions change. Pass `{ origin, direction }` for a world ray, `{ far }`
12
+ to cap its distance, `{ exclude }` to remove subtrees, and `{ targets }` to narrow it. Use
13
+ `raycastAll` when occlusion or another query needs every hit; results are sorted nearest first.
14
+ `{ screen }` tests a point that is not the pointer. Skinned, instanced and morphed meshes fall
15
+ back to the stock Three.js path automatically, so the result always matches
16
+ `Raycaster.intersectObject`.
17
+
18
+ When scene collapse runs on a large static scene, a mesh with non-empty `userData` stays as the
19
+ original object in the live graph. Put the target or entity metadata you already use for picking
20
+ on the mesh; `ctx.raycast()` then still returns that mesh and its metadata. Meshes without
21
+ `userData` may be merged into fewer draws.
22
+
23
+ ## Scene rebuild semantics
24
+
25
+ Calling `ctx.goto("<scene-name>")` from inside the matching scene tears it down and rebuilds
26
+ it: `exit()` runs, scheduled callbacks are cleared, registered entities are cleared, the Three
27
+ scene is emptied, then a fresh instance runs `load()` and `enter()`. Values in `ctx.state` —
28
+ health, score, inventory, or any other game-owned state — survive this scene rebuild. When
29
+ death-and-retry should reset gameplay, reset your own state explicitly before calling
30
+ `ctx.goto()`.
31
+
32
+ Do **not** write a `#reset()` that walks your entities putting them back. It is ~15 lines that
33
+ look right and quietly miss the scheduler and anything you spawned after `enter()`, so the
34
+ second playthrough behaves differently from the first — and no gate in this project will catch
35
+ that.
36
+
37
+ ## Timing with `ctx.tween` and `ctx.after`
38
+
39
+ **`ctx.tween` is for timing, not for looks.** Use it for the *when* — a pickup rising over
40
+ 0.4s, a door opening, a hit flash — and keep the *what* (colour, shape, easing feel) in
41
+ `src/render/`. Motion driven by a persistent `Math.sin(elapsed)` in `update()` is still the
42
+ right tool for a continuous idle bob; `tween` is for anything that starts, runs once, and
43
+ finishes. `ctx.after(seconds, fn)` and `ctx.every(fn)` schedule on the same clock the scene
44
+ runs on; both handles are cleared when the scene exits.
45
+
46
+ ## Seeded randomness
47
+
48
+ **`ctx.random` is deterministic only when `defineGame({ seed })` is configured.** Check
49
+ `src/game.ts`: a declared seed gives replayable values for spawn positions, patrol offsets,
50
+ and level variation; without one, `ctx.random` falls back to `Math.random()`. Add a fixed
51
+ seed when a playtest needs replayable randomness.
52
+
53
+ ## Streaming a second asset tier with `ctx.startup.hold()`
54
+
55
+ `ctx.startup.whenReady()` covers **the framework's** launch work — first-use compilation and a
56
+ sustained in-budget frame window — and nothing after it. If your game loads a cheap tier, enters,
57
+ and then streams the rest, readiness resolves in the middle of that and you get one of two bugs.
58
+
59
+ Show the world at `whenReady()` and the player watches it build itself. Measured in a forest game:
60
+ the loading screen lifted on one tree and a black sky, and the wood, the undergrowth, the animals
61
+ and the sky arrived over the next several seconds.
62
+
63
+ Hold your own curtain past `whenReady()` instead and the picture is right, but every
64
+ framework-owned observation of startup now describes a moment nobody experienced:
65
+ `startup.progress` sits pinned at `1`, `startup.phase` reads `ready`, `timeline.readyMs` reports
66
+ the framework's 1.5 s rather than the player's 8.8 s, and `assert.startup`'s `maxReadyMs` passes a
67
+ game that takes nearly nine seconds to show anything.
68
+
69
+ So register the tier instead, in `load()`, before the framework's gate can resolve:
70
+
71
+ ```ts
72
+ override async load(ctx: GameCtx): Promise<void> {
73
+ const detail = this.#loadDetailTier(ctx); // not awaited: enter() runs on the critical tier
74
+ ctx.startup.hold("detail-tier", detail);
75
+ await this.#loadCriticalTier(ctx);
76
+ }
77
+ ```
78
+
79
+ `whenReady()`, `progress`, `phase` and `timeline.readyMs` now all wait for `detail`, so a loading
80
+ screen written the obvious way — hide it when `whenReady()` resolves — is correct again, and the
81
+ proof of startup time is a proof about the player.
82
+
83
+ Three things to know:
84
+
85
+ - **It fails open, twice.** A hold that rejects counts as settled, and the third argument bounds
86
+ how long it may delay the world (45 s by default). A launch slower than it could be is a
87
+ disappointment; a launch that never finishes because one texture 404'd is a bug.
88
+ `timeline.frameworkReadyMs` still reports the framework's own cost, so a slow tier of yours
89
+ cannot hide a framework regression inside it.
90
+ - **It fails closed on your mistakes.** An empty or duplicate label throws, and so does a hold
91
+ registered after startup already resolved — each means you believe you are gating something you
92
+ are not.
93
+ - **Do the loading, then hold, then enter.** Registering the hold is not what starts the work;
94
+ pass a promise that is already running. And register it in `load()`: a hold added from `enter()`
95
+ races the framework's gate on a warm cache.
96
+
97
+ ### The one trap: never start held work from `whenReady()`
98
+
99
+ A hold makes readiness wait for your work. So work *started* from `whenReady()` is waiting for a
100
+ gate that is waiting for it:
101
+
102
+ ```ts
103
+ // DEADLOCK. Only the hold's budget breaks it, and it presents as a very slow load.
104
+ void ctx.startup.whenReady().then(() => this.#loadDetailTier(ctx));
105
+ ```
106
+
107
+ Measured, when exactly this was written: the valley sat on its loading screen for the full 45 s
108
+ budget and then revealed the critical tier, `TN_VALLEY_REVEAL trees=1`. Nothing errored. It reads
109
+ like a slow network, not like a cycle.
110
+
111
+ There is a real reason to want that shape — the framework's first-use compilation is competing for
112
+ the main thread, and streaming into it makes both slower. So wait on the framework's own gate
113
+ instead, which resolves before the holds:
114
+
115
+ ```ts
116
+ void ctx.startup.whenFrameworkReady().then(() => this.#loadDetailTier(ctx));
117
+ ```
118
+
119
+ `timeline.frameworkReadyMs` is when that fires; `timeline.readyMs` is when the player got the
120
+ world.
@@ -0,0 +1,68 @@
1
+ # The debug surface — probing a running game
2
+
3
+ The bridge globals exist but were discovered by trial: six throwaway probe scripts in one
4
+ day, each re-finding the shapes through TypeErrors. This page lists every global a running
5
+ game exposes, what it returns, and how to read it from the browser console. All of them are
6
+ read-only observation surfaces; none exists to drive gameplay.
7
+
8
+ ## `window.__THREENATIVE__` — entity snapshot (dev builds only)
9
+
10
+ Installed by `defineGame` when the dev-server flag is on (`installDevTools`); absent in
11
+ production builds.
12
+
13
+ ```js
14
+ window.__THREENATIVE__.snapshot()
15
+ // → { entities: [{ id, kind?, ...entity debug fields }], ... }
16
+ ```
17
+
18
+ `snapshot()` prefers an entity's own `debug()` and falls back to `autoFields`. This is the
19
+ fastest "what does the game think exists" probe; playtest assertions and the dev overlay
20
+ read the same registry.
21
+
22
+ ## `window.__THREENATIVE_PLAYTEST_BRIDGE__` — the harness channel
23
+
24
+ Installed by `playtest()` (core plugin) or `installThreePlaytestBridge`
25
+ (`@threenative/playtest/three`). One object, JSON-safe in and out:
26
+
27
+ | Member | Shape | Use |
28
+ | --- | --- | --- |
29
+ | `describe()` | `{ name, protocolVersion, capabilities, limits }` | First call. Tells you what this game's bridge supports and the protocol limits. |
30
+ | `ready()` | `{ ready: true }` | Liveness check before sampling. |
31
+ | `sample(request)` | JSON-safe observation snapshot (entities, camera, renderer stats, resources, components, and `scene`: the lights, materials, fog, background, camera framing and world extent) | The main probe. Pass `{}` for the default sample; `request.include` names optional series such as `physicsDebugSeries`. |
32
+ | `advance(ticks)` | fixed-step bridges only: advances exactly N ticks and returns `{ clock, ticks }`; throws if the step count mismatches | Deterministic stepping without wall-clock waits. Throws when the bridge is render-frame. |
33
+ | `applySetup(request)` | applies scenario `setup` placements/resources through the registry | What scenario setup uses; also usable by hand for one-off staging. |
34
+ | `drainEvents(limit)` | event-queue bridges only: returns up to `limit` queued events | Reads events shorter than one state flush. |
35
+
36
+ A console one-liner that works on any bridged game:
37
+
38
+ ```js
39
+ await window.__THREENATIVE_PLAYTEST_BRIDGE__.describe()
40
+ ```
41
+
42
+ Missing global means no bridge is installed — semantic assertions against that page fail
43
+ `TN_PLAYTEST_BRIDGE_MISSING`, which is the harness being right, not a bug to work around.
44
+
45
+ ## `window.__THREENATIVE_NATIVE__` — native host channel
46
+
47
+ Present only under the native runtime. The host injects its side; core's viewport and
48
+ `@threenative/playtest/three`'s device reporting read it (adapter identity, host snapshot).
49
+ On web this global does not exist — do not probe for it in portable code.
50
+
51
+ ## Runner-side markers
52
+
53
+ Two further globals are set by tooling, not the game, and are named here so a stray
54
+ assignment is recognisable: `__THREENATIVE_PLAYTEST_RUNNER_EXPECTED__` (core's playtest
55
+ plugin marks the expected runner contract) and `__THREENATIVE_FRAMEBUFFER_COVERAGE_PROBE__`
56
+ (the framebufferCoverage assertion installs its sampler). Leave both alone in game code.
57
+
58
+ ## What does not exist
59
+
60
+ There is no `__THREENATIVE_SCENE__` global. Scene-graph inspection goes through
61
+ `sample()` — which reports counts, extents and visibility, and under `scene` the lights,
62
+ materials, fog, background and camera framing the renderer was handed — or through your
63
+ own registered entities' `debug()` output, never by reaching into three.js objects from
64
+ the console and treating what you find as an observation surface.
65
+
66
+ `scene` counts and names; it does not read texture contents or shader graphs, and a scene
67
+ past the walk's cap reports `truncated: true` so a floor is never read as a total. A value
68
+ the scene does not carry is absent rather than zero.
@@ -0,0 +1,150 @@
1
+ # Dream Loop: target-driven authoring
2
+
3
+ Use this workflow when a user supplies a target image, asks for a target to be generated, or
4
+ wants to improve an existing game while preserving its identity. It is an explicit authoring
5
+ workflow, not a background scheduler. The builder edits the game; a fresh verifier reviews the
6
+ real capture; the two small generated scripts validate evidence and accounting.
7
+
8
+ ## Upstream notice
9
+
10
+ This workflow adapts the mechanics of Dream Loop at revision
11
+ `9bddb901f7d071cfefdd21e264267c757177a9df` by Anshu Chimala:
12
+ https://github.com/achimala/dream-loop/tree/9bddb901f7d071cfefdd21e264267c757177a9df
13
+
14
+ Copyright (c) 2025 Anshu Chimala
15
+
16
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software
17
+ and associated documentation files (the "Software"), to deal in the Software without
18
+ restriction, including without limitation the rights to use, copy, modify, merge, publish,
19
+ distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
20
+ Software is furnished to do so, subject to the following conditions:
21
+
22
+ The above copyright notice and this permission notice shall be included in all copies or
23
+ substantial portions of the Software.
24
+
25
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
26
+ BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
27
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
28
+ DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
29
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
30
+
31
+ ## 1. Lock the target and constraints
32
+
33
+ Start from the user's target. A supplied image takes precedence and needs no image-service key.
34
+ If no image is available, ask the user to choose an existing host image tool or explicitly opt in
35
+ to the generated `scripts/reference.mjs` route. Never invent a target or silently switch models.
36
+
37
+ Create one run directory under `.dream-loop/`, for example `.dream-loop/run-20260909-01/`, and
38
+ keep its `run.json`, prompt, target, captures, and verdicts together. Do not use a `current`
39
+ symlink as evidence. A run record is project-local and must contain at least:
40
+
41
+ ```json
42
+ {
43
+ "schemaVersion": 1,
44
+ "runId": "run-20260909-01",
45
+ "projectRoot": "/absolute/path/to/game",
46
+ "artifactRoot": ".dream-loop/run-20260909-01",
47
+ "builderIdentity": "builder-session-id",
48
+ "currentSourceSha256": "sha256-of-current-source-or-dirty-tree",
49
+ "target": { "path": ".dream-loop/run-20260909-01/target.png", "sha256": "...", "revision": 1 },
50
+ "limits": {
51
+ "startedAt": "2026-09-09T00:00:00.000Z",
52
+ "deadlineAt": "2026-09-09T00:30:00.000Z",
53
+ "maxRounds": 6,
54
+ "maxImageRequests": 4
55
+ },
56
+ "requests": { "pending": [], "completed": [], "unknown": [], "failed": [] },
57
+ "rounds": [],
58
+ "decisionHistory": []
59
+ }
60
+ ```
61
+
62
+ Record the original target bytes and hash. A user-authorized refinement creates a new target
63
+ revision and preserves the original target, prior scores, start time, and remaining allowance.
64
+ The builder cannot improve a score by replacing the target or by reviewing its own work.
65
+
66
+ ## 2. Build and capture the real game
67
+
68
+ Read the existing capture, playtest, asset, and performance recipes. Search the engine capability
69
+ manifest before adding a mechanic or render stage. Keep appearance in the game's `src/render/`.
70
+ The target is a playable camera view: preserve the requested layout, controls, HUD, landmark,
71
+ and identity. A Blender render, a target image displayed over the canvas, or one frozen camera is
72
+ not a gameplay result.
73
+
74
+ For every round, store a capture record with the actual project-relative path and SHA-256,
75
+ target hash, source hash, viewport, deterministic input/scenario identity, adapter/platform,
76
+ and nonempty functional assertions. Store measured steady frame windows and a positive target
77
+ FPS bound. If display configuration is uncapped or the observation is missing, the round cannot
78
+ be accepted. Capture from a second gameplay position when the subject or asset is central to the
79
+ request.
80
+
81
+ ## 3. Independent review and validation
82
+
83
+ Start the read-only verifier in a fresh context. Give it the target, current captures, request,
84
+ rubric, functional observations, and performance windows. It returns exactly `PASS`,
85
+ `REQUEST_CHANGES`, or `NOT_OBSERVED`; it does not receive the builder's self-assessment and it
86
+ must not edit the game. Scores are framing/composition 0–3, lighting/readability 0–3,
87
+ material/shape fidelity 0–3, and finish/HUD detail 0–1. The validator recomputes the total.
88
+ Gaps name visible locations and a proposed correction.
89
+
90
+ After the review, run:
91
+
92
+ ```sh
93
+ node scripts/visual-loop.mjs --record .dream-loop/run-20260909-01/run.json
94
+ ```
95
+
96
+ Exit 0 means the record was valid and a JSON decision was written; read its `decision`. It is
97
+ one of `continue`, `replan`, `accepted`, `stalled`, `budget-exhausted`, or `unavailable`.
98
+ Exit 2 means the record is malformed. A valid exit 0 is never acceptance by itself.
99
+
100
+ The validator refuses stale capture or target hashes, source changes, missing or empty
101
+ assertions, missing independent review, invalid score ranges, missing performance windows,
102
+ cross-run paths, symlink escapes, and a zero/uncapped FPS bound. It retains the best eligible
103
+ round and the latest gaps. Repeated gaps get one changed approach; if that replan does not
104
+ improve the result, the decision is `stalled`.
105
+
106
+ Acceptance requires a fresh capture, all functional assertions passing, a distinct critic,
107
+ `PASS`, a recomputed score of at least 8/10, no required blocker, and every measured performance
108
+ bound passing. Missing, interrupted, exhausted, and stalled runs are not accepted; they report
109
+ the best eligible evidence and the exact stop reason.
110
+
111
+ ## 4. Optional OpenRouter target generation
112
+
113
+ Only use this route after the user has chosen it and `OPENROUTER_API_KEY` is present. The default
114
+ candidate is `meta/muse-image`; `--model` is an explicit override. The script qualifies the
115
+ selected model's advertised image input/output support, then uses one non-streaming chat request.
116
+ It does not retry, download a returned URL, forward credentials, or send unrelated project files.
117
+ Reference editing uses `--reference <local-image>` and includes the original screenshot bytes in
118
+ the request. If the model does not advertise the required capability, preserve the run and
119
+ report `unavailable` rather than substituting another endpoint or model.
120
+
121
+ ```sh
122
+ node scripts/reference.mjs \
123
+ --record .dream-loop/run-20260909-01/run.json \
124
+ --request-id target-001 \
125
+ --prompt-file .dream-loop/run-20260909-01/prompt.txt \
126
+ --out .dream-loop/run-20260909-01/target.png \
127
+ --model meta/muse-image
128
+ ```
129
+
130
+ The script reserves the unique request ID and allowance under an exclusive run lock before its
131
+ one POST. It validates the deadline, response size, raster signature, dimensions where available,
132
+ MIME/extension agreement, and the atomic output. A completed ID returns its verified artifact;
133
+ pending or unknown IDs never POST again. A crash after dispatch remains pending and is reconciled
134
+ as unknown on resume. Usage or cost is recorded when returned, otherwise as `unknown`—never zero.
135
+ Errors name a safe category and HTTP status, and may include `Retry-After`; they never print the
136
+ authorization header or raw provider body.
137
+
138
+ ## 5. Assets and release evidence
139
+
140
+ Use the existing asset/license and sculpt decision tree. For a bespoke landmark without a
141
+ reference, delegate to target acquisition first; do not invent a reference. Generated reference
142
+ images stay in authoring evidence, not the runtime build. Imported assets retain their returned
143
+ license and credits. Validate UVs, color space, normals, scale, floor contact, silhouette, and
144
+ multiple gameplay positions in browser and every actually executed native target.
145
+
146
+ Keep `.dream-loop/` ignored while the run is active. Promote the final target/captures, sanitized
147
+ request metadata, verdicts, and command output into a cited `docs/verification/` record before
148
+ cleanup. Never stage `.env`, `.env.authoring`, base64 payloads, scratch records, provider keys,
149
+ or upstream preview media. A missing host, provider, platform, or human visual result remains
150
+ `UNVERIFIED`; it does not become a green claim through a file-presence check.