create-threenative 0.2.3 → 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 (447) hide show
  1. package/README.md +53 -2
  2. package/agent-docs/references/assertion-reference.md +173 -6
  3. package/agent-docs/references/capability-reference.md +1303 -99
  4. package/agent-docs/references/capture-the-frame.md +7 -0
  5. package/agent-docs/references/creating-creatures.md +215 -0
  6. package/agent-docs/references/ctx-cookbook.md +69 -0
  7. package/agent-docs/references/debug-surface.md +8 -3
  8. package/agent-docs/references/dream-loop.md +150 -0
  9. package/agent-docs/references/finding-assets.md +70 -2
  10. package/agent-docs/references/sculpt-from-a-reference.md +3 -2
  11. package/agent-docs/references/trace-a-slow-frame.md +99 -0
  12. package/agent-docs/references/visual-baseline.md +41 -0
  13. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
  14. package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
  15. package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
  16. package/agent-files/.agents/skills/threenative-builder/SKILL.md +1 -1
  17. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
  18. package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
  19. package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
  20. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
  21. package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
  22. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +1 -1
  23. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
  24. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
  25. package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
  26. package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
  27. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
  28. package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
  29. package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
  30. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
  31. package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
  32. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
  33. package/agent-files/scripts/reference.mjs +705 -0
  34. package/agent-files/scripts/visual-loop.mjs +382 -0
  35. package/capabilities.json +1881 -131
  36. package/dist/index.d.ts +39 -6
  37. package/dist/index.js +297 -32
  38. package/dist/threenative.js +822 -105
  39. package/package.json +30 -5
  40. package/template-assets/loading.ts +12 -2
  41. package/template-assets/patches/three@0.185.1.patch +249 -14
  42. package/template-assets/worldEnvironment.ts +758 -0
  43. package/templates/action-rpg/.codex/config.toml +4 -0
  44. package/templates/action-rpg/.cursor/mcp.json +32 -0
  45. package/templates/action-rpg/.gemini/settings.json +32 -0
  46. package/templates/action-rpg/.mcp.json +15 -3
  47. package/templates/action-rpg/.vscode/mcp.json +36 -0
  48. package/templates/action-rpg/.zed/settings.json +36 -0
  49. package/templates/action-rpg/AGENTS.md +69 -378
  50. package/templates/action-rpg/CLAUDE.md +69 -378
  51. package/templates/action-rpg/opencode.json +41 -0
  52. package/templates/action-rpg/package.json +7 -7
  53. package/templates/action-rpg/playtests/combat.playtest.json +9 -0
  54. package/templates/action-rpg/playtests/performance.playtest.json +24 -7
  55. package/templates/action-rpg/playtests/survives.playtest.json +27 -0
  56. package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
  57. package/templates/action-rpg/src/conventions.ts +35 -0
  58. package/templates/action-rpg/src/entities/Enemy.ts +2 -3
  59. package/templates/action-rpg/src/entities/Player.ts +20 -3
  60. package/templates/action-rpg/src/render/camera.ts +7 -2
  61. package/templates/action-rpg/src/render/lighting.ts +5 -3
  62. package/templates/action-rpg/src/render/loading.ts +12 -2
  63. package/templates/action-rpg/src/render/materials.ts +11 -0
  64. package/templates/action-rpg/src/render/palette.ts +10 -3
  65. package/templates/action-rpg/src/render/postprocessing.ts +21 -58
  66. package/templates/action-rpg/src/render/quality.ts +170 -0
  67. package/templates/action-rpg/src/render/shapes.ts +185 -26
  68. package/templates/action-rpg/src/render/touch-controls.ts +185 -0
  69. package/templates/action-rpg/src/render/vfx.ts +257 -0
  70. package/templates/action-rpg/src/render/worldEnvironment.ts +208 -33
  71. package/templates/action-rpg/src/scenes/Play.ts +43 -6
  72. package/templates/action-rpg/src/style.css +20 -0
  73. package/templates/action-rpg/threenative.config.ts +7 -0
  74. package/templates/defense/.codex/config.toml +4 -0
  75. package/templates/defense/.cursor/mcp.json +32 -0
  76. package/templates/defense/.gemini/settings.json +32 -0
  77. package/templates/defense/.mcp.json +15 -3
  78. package/templates/defense/.vscode/mcp.json +36 -0
  79. package/templates/defense/.zed/settings.json +36 -0
  80. package/templates/defense/AGENTS.md +62 -385
  81. package/templates/defense/CLAUDE.md +62 -385
  82. package/templates/defense/opencode.json +41 -0
  83. package/templates/defense/package.json +7 -7
  84. package/templates/defense/playtests/performance.playtest.json +24 -7
  85. package/templates/defense/playtests/pointer-placement.playtest.json +87 -20
  86. package/templates/defense/playtests/scan.playtest.json +1 -1
  87. package/templates/defense/playtests/survive.playtest.json +14 -0
  88. package/templates/defense/src/attackers/Attacker.ts +4 -4
  89. package/templates/defense/src/board/Route.ts +22 -8
  90. package/templates/defense/src/conventions.ts +18 -0
  91. package/templates/defense/src/entities/Player.ts +11 -3
  92. package/templates/defense/src/game.ts +2 -3
  93. package/templates/defense/src/physics.ts +9 -39
  94. package/templates/defense/src/placement/Buildable.ts +4 -4
  95. package/templates/defense/src/render/camera.ts +9 -3
  96. package/templates/defense/src/render/loading.ts +12 -2
  97. package/templates/defense/src/render/materials.ts +9 -0
  98. package/templates/defense/src/render/palette.ts +12 -5
  99. package/templates/defense/src/render/postprocessing.ts +21 -58
  100. package/templates/defense/src/render/quality.ts +170 -0
  101. package/templates/defense/src/render/shapes.ts +142 -23
  102. package/templates/defense/src/render/sky.ts +2 -2
  103. package/templates/defense/src/render/worldEnvironment.ts +208 -33
  104. package/templates/defense/src/scenes/Boot.ts +2 -2
  105. package/templates/defense/src/scenes/Defense.ts +13 -6
  106. package/templates/defense/src/style.css +20 -0
  107. package/templates/defense/src/towers/Tower.ts +11 -12
  108. package/templates/defense/src/towers/targeting.ts +1 -1
  109. package/templates/defense/src/ui/App.tsx +2 -2
  110. package/templates/defense/threenative.config.ts +7 -0
  111. package/templates/minimal/.codex/config.toml +4 -0
  112. package/templates/minimal/.cursor/mcp.json +32 -0
  113. package/templates/minimal/.gemini/settings.json +32 -0
  114. package/templates/minimal/.mcp.json +15 -3
  115. package/templates/minimal/.vscode/mcp.json +36 -0
  116. package/templates/minimal/.zed/settings.json +36 -0
  117. package/templates/minimal/AGENTS.md +76 -485
  118. package/templates/minimal/CLAUDE.md +76 -485
  119. package/templates/minimal/opencode.json +41 -0
  120. package/templates/minimal/package.json +6 -6
  121. package/templates/minimal/playtests/play.playtest.json +2 -1
  122. package/templates/minimal/playtests/survives.playtest.json +48 -4
  123. package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
  124. package/templates/minimal/src/conventions.ts +18 -0
  125. package/templates/minimal/src/entities/Player.ts +39 -6
  126. package/templates/minimal/src/main.ts +14 -4
  127. package/templates/minimal/src/render/materials.ts +7 -0
  128. package/templates/minimal/src/render/palette.ts +3 -3
  129. package/templates/minimal/src/render/postprocessing.ts +17 -56
  130. package/templates/minimal/src/render/quality.ts +162 -0
  131. package/templates/minimal/src/render/sky.ts +23 -9
  132. package/templates/minimal/src/render/touch-controls.ts +165 -0
  133. package/templates/minimal/src/render/worldEnvironment.ts +208 -33
  134. package/templates/minimal/src/scenes/Play.ts +47 -11
  135. package/templates/minimal/src/style.css +20 -0
  136. package/templates/minimal/threenative.config.ts +7 -0
  137. package/templates/platformer/.codex/config.toml +4 -0
  138. package/templates/platformer/.cursor/mcp.json +32 -0
  139. package/templates/platformer/.gemini/settings.json +32 -0
  140. package/templates/platformer/.mcp.json +15 -3
  141. package/templates/platformer/.vscode/mcp.json +36 -0
  142. package/templates/platformer/.zed/settings.json +36 -0
  143. package/templates/platformer/AGENTS.md +70 -430
  144. package/templates/platformer/CLAUDE.md +70 -430
  145. package/templates/platformer/opencode.json +41 -0
  146. package/templates/platformer/package.json +7 -7
  147. package/templates/platformer/playtests/oneway.playtest.json +29 -2
  148. package/templates/platformer/playtests/performance.playtest.json +2 -1
  149. package/templates/platformer/playtests/survives.playtest.json +31 -0
  150. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +3 -0
  151. package/templates/platformer/playtests/touch-controls-web.playtest.json +15 -4
  152. package/templates/platformer/src/conventions.ts +18 -0
  153. package/templates/platformer/src/entities/Character.ts +63 -1
  154. package/templates/platformer/src/game.ts +3 -1
  155. package/templates/platformer/src/level/Platform.ts +13 -1
  156. package/templates/platformer/src/render/lighting.ts +7 -4
  157. package/templates/platformer/src/render/loading.ts +12 -2
  158. package/templates/platformer/src/render/palette.ts +4 -1
  159. package/templates/platformer/src/render/postprocessing.ts +32 -57
  160. package/templates/platformer/src/render/quality.ts +170 -0
  161. package/templates/platformer/src/render/worldEnvironment.ts +208 -33
  162. package/templates/platformer/src/scenes/Level.ts +52 -12
  163. package/templates/platformer/src/style.css +20 -0
  164. package/templates/platformer/threenative.config.ts +7 -0
  165. package/templates/puzzle/.codex/config.toml +19 -0
  166. package/templates/puzzle/.cursor/mcp.json +32 -0
  167. package/templates/puzzle/.gemini/settings.json +32 -0
  168. package/templates/puzzle/.mcp.json +32 -0
  169. package/templates/puzzle/.vscode/mcp.json +36 -0
  170. package/templates/puzzle/.zed/settings.json +36 -0
  171. package/templates/puzzle/AGENTS.md +96 -0
  172. package/templates/puzzle/CLAUDE.md +98 -0
  173. package/templates/puzzle/README.md +43 -0
  174. package/templates/puzzle/index.html +12 -0
  175. package/templates/puzzle/kit.json +7 -0
  176. package/templates/puzzle/opencode.json +41 -0
  177. package/templates/puzzle/package.json +50 -0
  178. package/templates/puzzle/playtests/carry.playtest.json +71 -0
  179. package/templates/puzzle/playtests/performance.playtest.json +23 -0
  180. package/templates/puzzle/playtests/survives.playtest.json +51 -0
  181. package/templates/puzzle/playtests/swing.playtest.json +38 -0
  182. package/templates/puzzle/public/favicon.svg +5 -0
  183. package/templates/puzzle/src/conventions.ts +25 -0
  184. package/templates/puzzle/src/entities/Ball.ts +70 -0
  185. package/templates/puzzle/src/entities/Crate.ts +76 -0
  186. package/templates/puzzle/src/entities/Gripper.ts +69 -0
  187. package/templates/puzzle/src/entities/Pendulum.ts +89 -0
  188. package/templates/puzzle/src/game.ts +48 -0
  189. package/templates/puzzle/src/main.ts +15 -0
  190. package/templates/puzzle/src/physics.ts +19 -0
  191. package/templates/puzzle/src/render/camera.ts +37 -0
  192. package/templates/puzzle/src/render/lighting.ts +55 -0
  193. package/templates/puzzle/src/render/loading.ts +325 -0
  194. package/templates/puzzle/src/render/materials.ts +28 -0
  195. package/templates/puzzle/src/render/palette.ts +31 -0
  196. package/templates/puzzle/src/render/postprocessing.ts +34 -0
  197. package/templates/puzzle/src/render/quality.ts +170 -0
  198. package/templates/puzzle/src/render/shapes.ts +134 -0
  199. package/templates/puzzle/src/render/sky.ts +16 -0
  200. package/templates/puzzle/src/render/touch-controls.ts +185 -0
  201. package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
  202. package/templates/puzzle/src/room.ts +83 -0
  203. package/templates/puzzle/src/scenes/Boot.ts +12 -0
  204. package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
  205. package/templates/puzzle/src/state.ts +30 -0
  206. package/templates/puzzle/src/style.css +96 -0
  207. package/templates/puzzle/src/ui/App.tsx +22 -0
  208. package/templates/puzzle/src/ui/GameUi.tsx +20 -0
  209. package/templates/puzzle/src/ui/Hud.tsx +57 -0
  210. package/templates/puzzle/src/ui/Menu.tsx +7 -0
  211. package/templates/puzzle/src/ui/main.tsx +14 -0
  212. package/templates/puzzle/tailwind.config.ts +1 -0
  213. package/templates/puzzle/threenative.config.ts +49 -0
  214. package/templates/puzzle/tsconfig.json +17 -0
  215. package/templates/puzzle/vite.config.ts +38 -0
  216. package/templates/racing/.codex/config.toml +4 -0
  217. package/templates/racing/.cursor/mcp.json +32 -0
  218. package/templates/racing/.gemini/settings.json +32 -0
  219. package/templates/racing/.mcp.json +15 -3
  220. package/templates/racing/.vscode/mcp.json +36 -0
  221. package/templates/racing/.zed/settings.json +36 -0
  222. package/templates/racing/AGENTS.md +63 -379
  223. package/templates/racing/CLAUDE.md +63 -379
  224. package/templates/racing/native-playtests/survives.playtest.json +43 -0
  225. package/templates/racing/opencode.json +41 -0
  226. package/templates/racing/package.json +8 -7
  227. package/templates/racing/playtests/performance.playtest.json +24 -7
  228. package/templates/racing/playtests/survives.playtest.json +36 -4
  229. package/templates/racing/playtests/touch-controls.playtest.json +41 -0
  230. package/templates/racing/src/conventions.ts +6 -0
  231. package/templates/racing/src/entities/RacingCar.ts +16 -4
  232. package/templates/racing/src/entities/Rival.ts +5 -2
  233. package/templates/racing/src/render/camera.ts +7 -4
  234. package/templates/racing/src/render/lighting.ts +22 -13
  235. package/templates/racing/src/render/loading.ts +12 -2
  236. package/templates/racing/src/render/materials.ts +54 -4
  237. package/templates/racing/src/render/palette.ts +23 -6
  238. package/templates/racing/src/render/postprocessing.ts +21 -58
  239. package/templates/racing/src/render/quality.ts +170 -0
  240. package/templates/racing/src/render/shapes.ts +537 -26
  241. package/templates/racing/src/render/sky.ts +5 -2
  242. package/templates/racing/src/render/touch-controls.ts +185 -0
  243. package/templates/racing/src/render/worldEnvironment.ts +208 -33
  244. package/templates/racing/src/scenes/Race.ts +17 -2
  245. package/templates/racing/src/style.css +20 -0
  246. package/templates/racing/src/track/Track.ts +270 -31
  247. package/templates/racing/threenative.config.ts +7 -0
  248. package/templates/runner/.codex/config.toml +19 -0
  249. package/templates/runner/.cursor/mcp.json +32 -0
  250. package/templates/runner/.gemini/settings.json +32 -0
  251. package/templates/runner/.mcp.json +32 -0
  252. package/templates/runner/.vscode/mcp.json +36 -0
  253. package/templates/runner/.zed/settings.json +36 -0
  254. package/templates/runner/AGENTS.md +96 -0
  255. package/templates/runner/CLAUDE.md +98 -0
  256. package/templates/runner/README.md +43 -0
  257. package/templates/runner/index.html +12 -0
  258. package/templates/runner/kit.json +7 -0
  259. package/templates/runner/opencode.json +41 -0
  260. package/templates/runner/package.json +50 -0
  261. package/templates/runner/playtests/performance.playtest.json +23 -0
  262. package/templates/runner/playtests/streams.playtest.json +38 -0
  263. package/templates/runner/playtests/survives.playtest.json +51 -0
  264. package/templates/runner/public/favicon.svg +5 -0
  265. package/templates/runner/src/conventions.ts +24 -0
  266. package/templates/runner/src/entities/Runner.ts +135 -0
  267. package/templates/runner/src/game.ts +50 -0
  268. package/templates/runner/src/main.ts +15 -0
  269. package/templates/runner/src/physics.ts +13 -0
  270. package/templates/runner/src/render/camera.ts +39 -0
  271. package/templates/runner/src/render/dust.ts +131 -0
  272. package/templates/runner/src/render/lighting.ts +57 -0
  273. package/templates/runner/src/render/loading.ts +325 -0
  274. package/templates/runner/src/render/materials.ts +27 -0
  275. package/templates/runner/src/render/palette.ts +30 -0
  276. package/templates/runner/src/render/postprocessing.ts +34 -0
  277. package/templates/runner/src/render/quality.ts +170 -0
  278. package/templates/runner/src/render/shapes.ts +68 -0
  279. package/templates/runner/src/render/sky.ts +51 -0
  280. package/templates/runner/src/render/touch-controls.ts +185 -0
  281. package/templates/runner/src/render/worldEnvironment.ts +758 -0
  282. package/templates/runner/src/scenes/Boot.ts +12 -0
  283. package/templates/runner/src/scenes/Run.ts +142 -0
  284. package/templates/runner/src/state.ts +29 -0
  285. package/templates/runner/src/style.css +96 -0
  286. package/templates/runner/src/track.ts +176 -0
  287. package/templates/runner/src/ui/App.tsx +22 -0
  288. package/templates/runner/src/ui/GameUi.tsx +20 -0
  289. package/templates/runner/src/ui/Hud.tsx +55 -0
  290. package/templates/runner/src/ui/Menu.tsx +7 -0
  291. package/templates/runner/src/ui/main.tsx +14 -0
  292. package/templates/runner/tailwind.config.ts +1 -0
  293. package/templates/runner/threenative.config.ts +49 -0
  294. package/templates/runner/tsconfig.json +17 -0
  295. package/templates/runner/vite.config.ts +38 -0
  296. package/templates/sailing/.codex/config.toml +4 -0
  297. package/templates/sailing/.cursor/mcp.json +32 -0
  298. package/templates/sailing/.gemini/settings.json +32 -0
  299. package/templates/sailing/.mcp.json +15 -3
  300. package/templates/sailing/.vscode/mcp.json +36 -0
  301. package/templates/sailing/.zed/settings.json +36 -0
  302. package/templates/sailing/AGENTS.md +62 -355
  303. package/templates/sailing/CLAUDE.md +62 -355
  304. package/templates/sailing/README.md +12 -9
  305. package/templates/sailing/native-playtests/float.playtest.json +55 -0
  306. package/templates/sailing/native-playtests/survives.playtest.json +20 -3
  307. package/templates/sailing/opencode.json +41 -0
  308. package/templates/sailing/package.json +8 -8
  309. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
  310. package/templates/sailing/playtests/float.playtest.json +59 -0
  311. package/templates/sailing/playtests/performance.playtest.json +21 -6
  312. package/templates/sailing/playtests/survives.playtest.json +8 -0
  313. package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
  314. package/templates/sailing/src/conventions.ts +8 -0
  315. package/templates/sailing/src/entities/Ship.ts +150 -13
  316. package/templates/sailing/src/render/camera.ts +15 -8
  317. package/templates/sailing/src/render/lighting.ts +10 -5
  318. package/templates/sailing/src/render/loading.ts +12 -2
  319. package/templates/sailing/src/render/materials.ts +24 -8
  320. package/templates/sailing/src/render/ocean.ts +179 -0
  321. package/templates/sailing/src/render/palette.ts +14 -21
  322. package/templates/sailing/src/render/postprocessing.ts +23 -22
  323. package/templates/sailing/src/render/props.ts +584 -34
  324. package/templates/sailing/src/render/quality.ts +140 -0
  325. package/templates/sailing/src/render/sky.ts +8 -3
  326. package/templates/sailing/src/render/touch-controls.ts +142 -0
  327. package/templates/sailing/src/render/worldEnvironment.ts +206 -38
  328. package/templates/sailing/src/scenes/Sailing.ts +43 -16
  329. package/templates/sailing/src/style.css +20 -0
  330. package/templates/sailing/threenative.config.ts +7 -1
  331. package/templates/shooter/.codex/config.toml +4 -0
  332. package/templates/shooter/.cursor/mcp.json +32 -0
  333. package/templates/shooter/.gemini/settings.json +32 -0
  334. package/templates/shooter/.mcp.json +15 -3
  335. package/templates/shooter/.vscode/mcp.json +36 -0
  336. package/templates/shooter/.zed/settings.json +36 -0
  337. package/templates/shooter/AGENTS.md +76 -415
  338. package/templates/shooter/CLAUDE.md +76 -415
  339. package/templates/shooter/kit.json +2 -2
  340. package/templates/shooter/opencode.json +41 -0
  341. package/templates/shooter/package.json +7 -7
  342. package/templates/shooter/playtests/combat.playtest.json +48 -0
  343. package/templates/shooter/playtests/input-control.playtest.json +165 -35
  344. package/templates/shooter/playtests/per-item.playtest.json +3 -3
  345. package/templates/shooter/playtests/performance.playtest.json +24 -7
  346. package/templates/shooter/playtests/shooter.playtest.json +13 -7
  347. package/templates/shooter/playtests/survives.playtest.json +27 -0
  348. package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
  349. package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
  350. package/templates/shooter/src/combat/damage.ts +1 -2
  351. package/templates/shooter/src/conventions.ts +51 -0
  352. package/templates/shooter/src/entities/Player.ts +235 -18
  353. package/templates/shooter/src/entities/Target.ts +2 -2
  354. package/templates/shooter/src/game.ts +13 -4
  355. package/templates/shooter/src/render/camera.ts +49 -39
  356. package/templates/shooter/src/render/decals.ts +211 -0
  357. package/templates/shooter/src/render/lighting.ts +7 -3
  358. package/templates/shooter/src/render/loading.ts +12 -2
  359. package/templates/shooter/src/render/materials.ts +56 -3
  360. package/templates/shooter/src/render/palette.ts +6 -3
  361. package/templates/shooter/src/render/postprocessing.ts +21 -58
  362. package/templates/shooter/src/render/quality.ts +170 -0
  363. package/templates/shooter/src/render/scale.ts +22 -0
  364. package/templates/shooter/src/render/shapes.ts +343 -62
  365. package/templates/shooter/src/render/sky.ts +5 -1
  366. package/templates/shooter/src/render/touch-controls.ts +305 -0
  367. package/templates/shooter/src/render/ui.css +85 -0
  368. package/templates/shooter/src/render/ui.ts +19 -3
  369. package/templates/shooter/src/render/vfx.ts +215 -0
  370. package/templates/shooter/src/render/worldEnvironment.ts +208 -33
  371. package/templates/shooter/src/scenes/Play.ts +171 -56
  372. package/templates/shooter/src/state.ts +5 -0
  373. package/templates/shooter/src/style.css +20 -0
  374. package/templates/shooter/src/ui/Crosshair.tsx +25 -0
  375. package/templates/shooter/src/ui/GameUi.tsx +2 -0
  376. package/templates/shooter/src/ui/Hud.tsx +7 -1
  377. package/templates/shooter/src/weapons/Hitscan.ts +3 -4
  378. package/templates/shooter/src/weapons/Projectile.ts +8 -3
  379. package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
  380. package/templates/shooter/threenative.config.ts +7 -0
  381. package/templates/starter/.codex/config.toml +4 -0
  382. package/templates/starter/.cursor/mcp.json +32 -0
  383. package/templates/starter/.gemini/settings.json +32 -0
  384. package/templates/starter/.mcp.json +15 -3
  385. package/templates/starter/.vscode/mcp.json +36 -0
  386. package/templates/starter/.zed/settings.json +36 -0
  387. package/templates/starter/AGENTS.md +70 -527
  388. package/templates/starter/CLAUDE.md +70 -527
  389. package/templates/starter/native-playtests/render-chain.playtest.json +73 -4
  390. package/templates/starter/opencode.json +41 -0
  391. package/templates/starter/package.json +7 -7
  392. package/templates/starter/playtests/boot-failure.playtest.json +45 -0
  393. package/templates/starter/playtests/look.playtest.json +110 -6
  394. package/templates/starter/playtests/play.playtest.json +3 -2
  395. package/templates/starter/playtests/survives.playtest.json +21 -0
  396. package/templates/starter/playtests/touch-controls.playtest.json +42 -0
  397. package/templates/starter/src/conventions.ts +18 -0
  398. package/templates/starter/src/entities/Goal.ts +18 -3
  399. package/templates/starter/src/entities/Player.ts +72 -9
  400. package/templates/starter/src/game.ts +2 -0
  401. package/templates/starter/src/render/adaptiveQuality.ts +195 -0
  402. package/templates/starter/src/render/camera.ts +1 -1
  403. package/templates/starter/src/render/coast.ts +199 -0
  404. package/templates/starter/src/render/hero.ts +88 -0
  405. package/templates/starter/src/render/implicitSurface.ts +199 -0
  406. package/templates/starter/src/render/kuwahara.ts +174 -0
  407. package/templates/starter/src/render/lighting.ts +4 -4
  408. package/templates/starter/src/render/loading.ts +12 -2
  409. package/templates/starter/src/render/materials.ts +25 -6
  410. package/templates/starter/src/render/outline.ts +141 -0
  411. package/templates/starter/src/render/painterly.ts +86 -0
  412. package/templates/starter/src/render/palette.ts +15 -6
  413. package/templates/starter/src/render/postprocessing.ts +87 -36
  414. package/templates/starter/src/render/quality.ts +185 -0
  415. package/templates/starter/src/render/rockRidge.ts +198 -0
  416. package/templates/starter/src/render/rockRidge.worker.ts +77 -0
  417. package/templates/starter/src/render/scenery.ts +16 -59
  418. package/templates/starter/src/render/textureLifetime.ts +53 -0
  419. package/templates/starter/src/render/touch-controls.ts +165 -0
  420. package/templates/starter/src/render/water.ts +38 -0
  421. package/templates/starter/src/render/watercolor.ts +85 -0
  422. package/templates/starter/src/render/worldEnvironment.ts +208 -33
  423. package/templates/starter/src/scenes/Play.ts +103 -16
  424. package/templates/starter/src/style.css +27 -7
  425. package/templates/starter/threenative.config.ts +7 -7
  426. package/agent-docs/asset-mcp-loop.md +0 -33
  427. package/agent-docs/ctx-surface.md +0 -69
  428. package/agent-docs/engine-capabilities.md +0 -4
  429. package/agent-docs/framework-blocks-you.md +0 -60
  430. package/agent-docs/look-at-it-and-budget-the-look.md +0 -27
  431. package/agent-docs/performance-default.md +0 -42
  432. package/agent-docs/pixel-budget.md +0 -20
  433. package/agent-docs/playtest-fail-closed.md +0 -23
  434. package/agent-docs/sculpt-loop.md +0 -16
  435. package/templates/action-rpg/src/physics.ts +0 -40
  436. package/templates/defense/public/icon.png +0 -0
  437. package/templates/minimal/public/icon.png +0 -0
  438. package/templates/platformer/public/icon.png +0 -0
  439. package/templates/racing/public/icon.png +0 -0
  440. package/templates/sailing/public/icon.png +0 -0
  441. package/templates/sailing/src/render/water-material.ts +0 -14
  442. package/templates/sailing/src/render/water-shaders.ts +0 -12
  443. package/templates/sailing/src/render/wave-nodes.ts +0 -10
  444. package/templates/shooter/public/icon.png +0 -0
  445. package/templates/shooter/src/physics.ts +0 -49
  446. package/templates/starter/public/icon.png +0 -0
  447. /package/{templates/action-rpg/public → template-assets}/icon.png +0 -0
@@ -3,6 +3,13 @@
3
3
  Companion to the `Budget real time for the look` section in this project's `AGENTS.md`. Run
4
4
  `pnpm dev`, then get eyes on the game. In rough order of preference:
5
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
+
6
13
  1. **Browser automation against the user's real Chrome**, if you have it — Claude in Chrome
7
14
  or any equivalent MCP browser tool. This is the best option by a wide margin: it runs on
8
15
  a real GPU, so WebGPU works, and you can navigate, press keys, screenshot, and read the
@@ -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.
@@ -49,3 +49,72 @@ runs on; both handles are cleared when the scene exits.
49
49
  `src/game.ts`: a declared seed gives replayable values for spawn positions, patrol offsets,
50
50
  and level variation; without one, `ctx.random` falls back to `Math.random()`. Add a fixed
51
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.
@@ -28,7 +28,7 @@ Installed by `playtest()` (core plugin) or `installThreePlaytestBridge`
28
28
  | --- | --- | --- |
29
29
  | `describe()` | `{ name, protocolVersion, capabilities, limits }` | First call. Tells you what this game's bridge supports and the protocol limits. |
30
30
  | `ready()` | `{ ready: true }` | Liveness check before sampling. |
31
- | `sample(request)` | JSON-safe observation snapshot (entities, camera, renderer stats, resources, components) | The main probe. Pass `{}` for the default sample; `request.include` names optional series such as `physicsDebugSeries`. |
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
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
33
  | `applySetup(request)` | applies scenario `setup` placements/resources through the registry | What scenario setup uses; also usable by hand for one-off staging. |
34
34
  | `drainEvents(limit)` | event-queue bridges only: returns up to `limit` queued events | Reads events shorter than one state flush. |
@@ -58,6 +58,11 @@ plugin marks the expected runner contract) and `__THREENATIVE_FRAMEBUFFER_COVERA
58
58
  ## What does not exist
59
59
 
60
60
  There is no `__THREENATIVE_SCENE__` global. Scene-graph inspection goes through
61
- `sample()` (which reports counts, extents and visibility) or through your own
62
- registered entities' `debug()` output — never by reaching into three.js objects from
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
63
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.
@@ -6,9 +6,16 @@ asset tools when the asset is conventional; build anything specific to this game
6
6
 
7
7
  Installing `@threenative/core` writes the `.mcp.json` that launches `threenative-asset-mcp`, so
8
8
  your host lists its tools alongside your own. Your host reads that file from the directory it was
9
- launched in: start the session in this project, not in a parent of it. It advertises 34; these 8
9
+ launched in: start the session in this project, not in a parent of it. It advertises 40; these 8
10
10
  are the loop you will use for nearly everything:
11
11
 
12
+ For a bespoke animated creature, use the complete [`creating-creatures.md`](creating-creatures.md)
13
+ recipe. It keeps the editable spec and claims under `.threenative/creatures/`, compiles the GLB
14
+ into the configured `assets/` source, and requires independent preview review before game
15
+ delivery. The five creature tools are `creature_status`, `creature_guide`, `creature_compile`,
16
+ `creature_preview` and `creature_check`; call `creature_status` first because compile can work
17
+ without optional preview dependencies while a complete preview/check loop may not.
18
+
12
19
  1. `asset_search_sources` — start here, never at a provider. It returns every catalogued
13
20
  source with its license summary, attribution requirement, browse URL, and whether an agent
14
21
  can complete a download from it. **That output is the authority on what is reachable** —
@@ -28,6 +35,17 @@ are the loop you will use for nearly everything:
28
35
  ends**. Poly Haven requires a visible Poly Haven credit when its API is used, ambientCG is
29
36
  CC0 per asset page, and audio and bundle licenses are per pack.
30
37
 
38
+ **For a Poly Haven *model*, steps 3-4 collapse into `polyhaven_import_model`.** Poly Haven
39
+ publishes models as a `.gltf` beside a `.bin` and loose texture files and **never as a `.glb`**, so
40
+ doing it by hand means fetching five to eight URLs and rebuilding the directory layout the glTF's
41
+ relative URIs expect before anything will load. Pass `assetId`, an `outputPath` ending in `.glb`,
42
+ a `resolution` (it defaults to `1k`, which is what a game floor wants), and `acceptLicense: true`;
43
+ it downloads through the same guarded path, packs one self-contained GLB that
44
+ `ctx.assets.model()` loads directly, and returns **triangle count and per-texture dimensions** —
45
+ the two numbers `create-threenative inspect` does not report and that every triangle and texture
46
+ budget is written in. Ask for a resolution the asset does not publish and it names the ones that
47
+ exist. Textures and HDRIs still use `asset_download_file`.
48
+
31
49
  **Never state a license you did not read off a tool result.** If `polyhaven_list_files` or
32
50
  `ambientcg_search_assets` did not tell you, you do not know it.
33
51
 
@@ -112,9 +130,29 @@ GLBs up from `assets/` with no extra configuration.
112
130
 
113
131
  What the import will and will not do:
114
132
 
133
+ - **A pack of uncooked editor assets cannot be converted at all**, and this is the common case for
134
+ marketplace packs, which ship as Unreal *source* projects. Cooking is what writes the renderable
135
+ vertex and index buffers into the file; an uncooked package keeps only the editable source mesh
136
+ and lets the editor derive the rest, so there is no geometry for UE Viewer to read. The import
137
+ detects this and fails `UNREAL_SOURCE_UNCOOKED` naming the evidence it found —
138
+ `/Script/UnrealEd`, `AssetImportData`, `SourceModels`. **Believe it and stop.** No engine
139
+ version, `packages` filter or flag changes the answer, and the download is gigabytes each time
140
+ you try. The only route to those meshes is opening the pack in Unreal Editor and exporting FBX
141
+ or glTF yourself. Prefer a listing that ships a non-Unreal format, and treat one that does not as
142
+ a likely dead end before you spend the bandwidth.
143
+ - **A free listing still has to be in the library first.** `fab_import_asset` refuses with
144
+ `FABCLI_NOT_OWNED` until the listing is claimed, and it never claims — by design. Run
145
+ `fabcli claim <uid>`, which needs the interactive `fabcli auth login` session rather
146
+ than the API token `fabcli auth status` reports as authenticated. Note also that `fab_get_asset`
147
+ reports a free CC-BY offer as `isFree: false` with an empty `freeLicenseSlugs`; the listing
148
+ appearing in `fab_search_assets` with `priceMode: "free"` at `startingPrice.amount: 0` is the
149
+ reliable signal, so check the search before concluding a listing costs money.
115
150
  - **Only assets you already own**, and only under **Fab Standard (Personal or Professional) or
116
151
  CC-BY**. Unreal-Engine-only and legacy entitlements are refused, and a licence it cannot read is
117
- refused too. It never logs in, claims, or purchases — run `fabcli auth login` yourself once.
152
+ refused too. The MCP never logs in, claims, or purchases. If FabCLI needs a session, the agent
153
+ must proactively run `fabcli auth login` and complete it through Claude browser or Codex's
154
+ `chrome:control-chrome`, reusing the user's active signed-in browser session. Never inspect,
155
+ copy, print, or persist cookies or tokens; interact with the login page instead.
118
156
  Searching and `fab_get_asset` stay anonymous, so the licence check never depends on the
119
157
  authenticated path it is guarding.
120
158
  - **Two external tools install themselves on first use** (FabCLI and UE Viewer). Set
@@ -134,6 +172,36 @@ What the import will and will not do:
134
172
  `glb`/`fbx`/`obj`/`unity` file with no account at all. Use it when the listing already ships a
135
173
  format you can load, and the importer only when it does not.
136
174
 
175
+ ## From a downloaded `.fbx` to a running character
176
+
177
+ An `.fbx`, `.blend`, `.obj` or `.dae` is not a file the runtime can load. Put it in your assets
178
+ directory anyway and the build converts it:
179
+
180
+ 1. Download it — `fab_download_free_asset`, `asset_import_unreal`, `asset_download_bundle_entry`,
181
+ or by hand.
182
+ 2. Write it into `assets/`, beside your `.glb` files. Nothing else to configure.
183
+ 3. Build. `compileAssets` classifies it as a model, converts it to GLB through Blender, then
184
+ optimizes it exactly like an authored GLB — skeleton, animation clips, materials and embedded
185
+ textures survive.
186
+ 4. Load it the ordinary way: `ctx.assets.model("hero")`.
187
+
188
+ **Blender must be installed**, and the framework never installs it for you. With no Blender the
189
+ build fails and names the install command for your platform — it does not copy the unusable file
190
+ through and report success. Ask the user before installing anything; it is roughly 350 MB.
191
+
192
+ The `threenative-blender` MCP server answers the rest:
193
+
194
+ - `blender_status` — can this machine convert at all? Never fails; with no Blender it returns
195
+ `available: false` and the install command. Call it first.
196
+ - `blender_inspect` — what is in this file? Mesh, triangle, vertex and bone counts, material
197
+ names, clip names, image names. Use it before committing a download.
198
+ - `blender_convert` — write a GLB somewhere other than the build's output. Zero meshes out is a
199
+ failure, never an empty GLB.
200
+ - `blender_recipes` — the shipped bpy recipes (`decimate`, `unwrap`, `bake_ao`, `retarget`) and
201
+ their **full source text**. Read one and adapt it; do not write bpy cold.
202
+ - `blender_run_python` — run a bpy script of your own. It is not a sandbox and does not claim to
203
+ be; it gives you a resolved Blender and the same fail-closed handling, not extra privilege.
204
+
137
205
  ## The narrower tools
138
206
 
139
207
  The directory spells out the conditions on each. The Fab tools are covered above; the server
@@ -12,8 +12,9 @@ Companion to the short `Building what you cannot download` section in this proje
12
12
  - **Bespoke, with a reference image** — an identity-bearing creature, vehicle, hero prop,
13
13
  landmark, scenery composition, or environment set piece whose silhouette must match. Use
14
14
  the sculpt tools to turn that reference into editable `src/render/` source.
15
- - **Bespoke, without a reference image** — ask for one, or write it and accept that it will
16
- be generic. Do not invent a reference: comparison without evidence is unguided iteration.
15
+ - **Bespoke, without a reference image** — read `agent-docs/dream-loop.md` and acquire one from
16
+ the user or an explicitly selected host/provider tool. Do not invent a reference: comparison
17
+ without evidence is unguided iteration.
17
18
 
18
19
  For a full environment, split the decision: sculpt the signature landmark or bounded scene
19
20
  kit that makes the reference recognisable; use the asset tools for interchangeable trees,