create-threenative 0.2.3 → 0.2.5

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
@@ -0,0 +1,382 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { createHash, randomUUID } from "node:crypto";
4
+ import { open, readFile, realpath, rename, rm, stat } from "node:fs/promises";
5
+ import path from "node:path";
6
+
7
+ const SCHEMA_VERSION = 1;
8
+ const DECISIONS = new Set([
9
+ "continue",
10
+ "replan",
11
+ "accepted",
12
+ "stalled",
13
+ "budget-exhausted",
14
+ "unavailable",
15
+ ]);
16
+
17
+ class InputError extends Error {
18
+ constructor(message) {
19
+ super(message);
20
+ this.name = "InputError";
21
+ }
22
+ }
23
+
24
+ function fail(message) {
25
+ throw new InputError(message);
26
+ }
27
+
28
+ function sha256(bytes) {
29
+ return createHash("sha256").update(bytes).digest("hex");
30
+ }
31
+
32
+ function safeRelative(root, candidate, label) {
33
+ const resolved = path.resolve(candidate);
34
+ const relative = path.relative(root, resolved);
35
+ if (
36
+ relative === "" ||
37
+ relative === ".." ||
38
+ relative.startsWith(`..${path.sep}`) ||
39
+ path.isAbsolute(relative)
40
+ )
41
+ fail(`${label} escapes its declared artifact root`);
42
+ return resolved;
43
+ }
44
+
45
+ async function assertInside(root, candidate, label) {
46
+ const resolved = safeRelative(root, candidate, label);
47
+ const existing = await realpath(resolved).catch(() => undefined);
48
+ if (existing !== undefined) safeRelative(root, existing, label);
49
+ else {
50
+ const parent = await realpath(path.dirname(resolved)).catch(() => undefined);
51
+ if (parent !== undefined && parent !== root) safeRelative(root, parent, label);
52
+ }
53
+ return resolved;
54
+ }
55
+
56
+ async function atomicWriteJson(file, value) {
57
+ const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
58
+ const handle = await open(temporary, "wx");
59
+ try {
60
+ await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, "utf8");
61
+ await handle.sync();
62
+ } finally {
63
+ await handle.close();
64
+ }
65
+ await rename(temporary, file);
66
+ }
67
+
68
+ async function acquireLock(recordFile) {
69
+ const lockFile = `${recordFile}.lock`;
70
+ for (let attempt = 0; attempt < 2; attempt += 1) {
71
+ try {
72
+ const handle = await open(lockFile, "wx");
73
+ await handle.writeFile(
74
+ `${JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() })}\n`,
75
+ "utf8",
76
+ );
77
+ await handle.close();
78
+ return async () => rm(lockFile, { force: true });
79
+ } catch (error) {
80
+ if (error?.code !== "EEXIST") throw error;
81
+ const owner = JSON.parse(await readFile(lockFile, "utf8").catch(() => "{}"));
82
+ const pid = Number(owner.pid);
83
+ let live = false;
84
+ if (Number.isInteger(pid) && pid > 0) {
85
+ try {
86
+ process.kill(pid, 0);
87
+ live = true;
88
+ } catch {
89
+ live = false;
90
+ }
91
+ }
92
+ if (live) throw new InputError("run is locked by another writer");
93
+ await rm(lockFile, { force: true });
94
+ }
95
+ }
96
+ throw new InputError("could not acquire run lock");
97
+ }
98
+
99
+ function parseArgs(argv) {
100
+ if (argv.includes("--help")) return { help: true };
101
+ if (argv.length !== 2 || argv[0] !== "--record" || argv[1] === "")
102
+ fail("usage: node scripts/visual-loop.mjs --record RUN.json");
103
+ return { record: argv[1] };
104
+ }
105
+
106
+ function ensureRecord(record) {
107
+ if (
108
+ !record ||
109
+ record.schemaVersion !== SCHEMA_VERSION ||
110
+ typeof record.runId !== "string" ||
111
+ typeof record.projectRoot !== "string"
112
+ )
113
+ fail("record schemaVersion, runId and projectRoot are required");
114
+ if (!path.isAbsolute(record.projectRoot)) fail("record projectRoot must be absolute");
115
+ if (typeof record.builderIdentity !== "string" || record.builderIdentity === "")
116
+ fail("record builderIdentity is required");
117
+ if (
118
+ !record.limits ||
119
+ !Number.isInteger(record.limits.maxRounds) ||
120
+ record.limits.maxRounds < 1 ||
121
+ !Number.isInteger(record.limits.maxImageRequests) ||
122
+ record.limits.maxImageRequests < 1
123
+ )
124
+ fail("record limits.maxRounds and limits.maxImageRequests are required");
125
+ if (!record.limits.deadlineAt || Number.isNaN(Date.parse(record.limits.deadlineAt)))
126
+ fail("record limits.deadlineAt is required");
127
+ if (
128
+ !record.target ||
129
+ typeof record.target.path !== "string" ||
130
+ !/^[a-f0-9]{64}$/u.test(record.target.sha256 ?? "")
131
+ )
132
+ fail("record target path and SHA-256 are required");
133
+ if (!Array.isArray(record.rounds)) fail("record rounds must be an array");
134
+ record.requests ??= {};
135
+ for (const key of ["pending", "completed", "unknown", "failed"]) {
136
+ if (!Array.isArray(record.requests[key])) fail(`record requests.${key} must be an array`);
137
+ }
138
+ return record;
139
+ }
140
+
141
+ function recordRoots(record, recordFile) {
142
+ const projectRoot = path.resolve(record.projectRoot);
143
+ const artifactRoot = path.resolve(
144
+ projectRoot,
145
+ record.artifactRoot ?? path.relative(projectRoot, path.dirname(recordFile)),
146
+ );
147
+ if (artifactRoot !== projectRoot) safeRelative(projectRoot, artifactRoot, "artifactRoot");
148
+ return { projectRoot, artifactRoot };
149
+ }
150
+
151
+ function countRequests(record) {
152
+ return (
153
+ record.requests.pending.length +
154
+ record.requests.completed.length +
155
+ record.requests.unknown.length
156
+ );
157
+ }
158
+
159
+ async function fileHash(root, relativePath, label) {
160
+ const file = await assertInside(root, path.resolve(root, relativePath), label);
161
+ const bytes = await readFile(file).catch(() => {
162
+ throw new InputError(`${label} is missing: ${relativePath}`);
163
+ });
164
+ if (bytes.length === 0) fail(`${label} is empty: ${relativePath}`);
165
+ return { file, sha256: sha256(bytes) };
166
+ }
167
+
168
+ function scoreFor(review) {
169
+ const categories = {
170
+ framing: review.framing,
171
+ lighting: review.lighting,
172
+ material: review.material,
173
+ finish: review.finish,
174
+ };
175
+ const bounds = { framing: 3, lighting: 3, material: 3, finish: 1 };
176
+ for (const [name, maximum] of Object.entries(bounds)) {
177
+ if (!Number.isInteger(categories[name]) || categories[name] < 0 || categories[name] > maximum)
178
+ fail(`critic score '${name}' must be an integer from 0 to ${maximum}`);
179
+ }
180
+ return categories.framing + categories.lighting + categories.material + categories.finish;
181
+ }
182
+
183
+ function normalizedGaps(gaps) {
184
+ return JSON.stringify(
185
+ (Array.isArray(gaps) ? gaps : [])
186
+ .map((gap) => (typeof gap === "string" ? gap : JSON.stringify(gap)))
187
+ .sort(),
188
+ );
189
+ }
190
+
191
+ function allAssertionsPassed(functional) {
192
+ if (!functional || !Array.isArray(functional.assertions) || functional.assertions.length === 0)
193
+ return false;
194
+ return functional.assertions.every(
195
+ (assertion) => assertion?.passed === true || assertion?.status === "passed",
196
+ );
197
+ }
198
+
199
+ function performancePassed(performance) {
200
+ if (!performance || !Number.isFinite(performance.targetFps) || performance.targetFps <= 0)
201
+ return false;
202
+ if (!Number.isFinite(performance.displayMaxFps) || performance.displayMaxFps <= 0) return false;
203
+ if (!Array.isArray(performance.windows) || performance.windows.length === 0) return false;
204
+ return performance.windows.every(
205
+ (window) => Number.isFinite(window?.fps) && window.fps >= performance.targetFps,
206
+ );
207
+ }
208
+
209
+ async function validateRound(record, round, roots) {
210
+ if (
211
+ !round ||
212
+ typeof round.round !== "number" ||
213
+ !Number.isInteger(round.round) ||
214
+ round.round < 1
215
+ )
216
+ fail("round number is invalid");
217
+ const target = await fileHash(roots.projectRoot, record.target.path, "target");
218
+ if (target.sha256 !== record.target.sha256)
219
+ return { accepted: false, decision: "unavailable", reason: "target-hash-mismatch" };
220
+ if (
221
+ !round.capture ||
222
+ typeof round.capture.path !== "string" ||
223
+ !/^[a-f0-9]{64}$/u.test(round.capture.sha256 ?? "")
224
+ )
225
+ return { accepted: false, decision: "unavailable", reason: "capture-receipt-missing" };
226
+ const capture = await fileHash(roots.projectRoot, round.capture.path, "capture");
227
+ if (capture.sha256 !== round.capture.sha256)
228
+ return { accepted: false, decision: "unavailable", reason: "capture-hash-mismatch" };
229
+ if (round.capture.targetSha256 !== record.target.sha256)
230
+ return { accepted: false, decision: "unavailable", reason: "capture-target-stale" };
231
+ if (
232
+ record.currentSourceSha256 !== undefined &&
233
+ round.capture.sourceSha256 !== record.currentSourceSha256
234
+ )
235
+ return { accepted: false, decision: "unavailable", reason: "capture-source-stale" };
236
+ if (!round.platform || !round.adapter)
237
+ return { accepted: false, decision: "unavailable", reason: "capture-platform-missing" };
238
+ if (!allAssertionsPassed(round.functional))
239
+ return { accepted: false, decision: "unavailable", reason: "functional-observation-missing" };
240
+ if (!round.review || !["PASS", "REQUEST_CHANGES", "NOT_OBSERVED"].includes(round.review.status))
241
+ return { accepted: false, decision: "unavailable", reason: "independent-review-missing" };
242
+ if (
243
+ round.review.criticIdentity === undefined ||
244
+ round.review.criticIdentity === record.builderIdentity
245
+ )
246
+ return {
247
+ accepted: false,
248
+ decision: "unavailable",
249
+ reason: "independent-review-identity-missing",
250
+ };
251
+ if (
252
+ round.review.targetSha256 !== record.target.sha256 ||
253
+ round.review.captureSha256 !== round.capture.sha256
254
+ )
255
+ return { accepted: false, decision: "unavailable", reason: "reviewed-artifact-stale" };
256
+ const score = scoreFor(round.review);
257
+ if (!performancePassed(round.performance))
258
+ return {
259
+ accepted: false,
260
+ decision: "unavailable",
261
+ reason: "performance-observation-missing",
262
+ score,
263
+ };
264
+ if (round.review.status !== "PASS")
265
+ return {
266
+ accepted: false,
267
+ decision: "continue",
268
+ reason:
269
+ round.review.status === "NOT_OBSERVED"
270
+ ? "independent-review-not-observed"
271
+ : "critic-requested-changes",
272
+ score,
273
+ gaps: round.review.gaps ?? [],
274
+ };
275
+ if (score < 8)
276
+ return {
277
+ accepted: false,
278
+ decision: "continue",
279
+ reason: "visual-score-below-8",
280
+ score,
281
+ gaps: round.review.gaps ?? [],
282
+ };
283
+ if ((round.review.blockers ?? []).length > 0)
284
+ return {
285
+ accepted: false,
286
+ decision: "continue",
287
+ reason: "visual-blocker-present",
288
+ score,
289
+ gaps: round.review.gaps ?? [],
290
+ };
291
+ return {
292
+ accepted: true,
293
+ decision: "accepted",
294
+ reason: "all-required-evidence-observed",
295
+ score,
296
+ gaps: round.review.gaps ?? [],
297
+ };
298
+ }
299
+
300
+ function reconcilePending(record) {
301
+ if (record.requests.pending.length === 0) return false;
302
+ const now = new Date().toISOString();
303
+ for (const pending of record.requests.pending.splice(0))
304
+ record.requests.unknown.push({ ...pending, finishedAt: now, category: "interrupted" });
305
+ return true;
306
+ }
307
+
308
+ function boundedDecision(record, result) {
309
+ if (result.accepted) return result;
310
+ if (countRequests(record) >= record.limits.maxImageRequests)
311
+ return { ...result, decision: "budget-exhausted", reason: "image-request-limit" };
312
+ if (record.rounds.length >= record.limits.maxRounds)
313
+ return { ...result, decision: "budget-exhausted", reason: "round-limit" };
314
+ if (Date.now() >= Date.parse(record.limits.deadlineAt))
315
+ return { ...result, decision: "budget-exhausted", reason: "deadline" };
316
+ return result;
317
+ }
318
+
319
+ function applyGapStall(record, result) {
320
+ if (
321
+ !result.gaps ||
322
+ result.gaps.length === 0 ||
323
+ record.rounds.length < 2 ||
324
+ result.decision !== "continue"
325
+ )
326
+ return result;
327
+ const previous = record.rounds.at(-2);
328
+ if (normalizedGaps(previous?.review?.gaps) !== normalizedGaps(result.gaps)) return result;
329
+ const latestRound = record.rounds.at(-1).round;
330
+ if (record.replanUsed === true && record.replanRound === latestRound)
331
+ return { ...result, decision: "replan", reason: "repeated-gaps-require-one-replan" };
332
+ if (record.replanUsed === true)
333
+ return { ...result, decision: "stalled", reason: "replan-did-not-improve-repeated-gaps" };
334
+ record.replanUsed = true;
335
+ record.replanRound = latestRound;
336
+ return { ...result, decision: "replan", reason: "repeated-gaps-require-one-replan" };
337
+ }
338
+
339
+ async function main() {
340
+ const options = parseArgs(process.argv.slice(2));
341
+ if (options.help) {
342
+ console.log("Usage: node scripts/visual-loop.mjs --record RUN.json");
343
+ return;
344
+ }
345
+ const recordFile = path.resolve(process.cwd(), options.record);
346
+ const record = ensureRecord(JSON.parse(await readFile(recordFile, "utf8")));
347
+ const roots = recordRoots(record, recordFile);
348
+ const release = await acquireLock(recordFile);
349
+ try {
350
+ const reconciled = reconcilePending(record);
351
+ const latest = record.rounds.at(-1);
352
+ let result =
353
+ latest === undefined
354
+ ? { decision: "continue", reason: "no-round-evidence", gaps: [] }
355
+ : await validateRound(record, latest, roots);
356
+ result = applyGapStall(record, result);
357
+ result = boundedDecision(record, result);
358
+ if (reconciled && result.decision === "continue") {
359
+ result = { ...result, decision: "unavailable", reason: "interrupted-request-reconciled" };
360
+ }
361
+ if (!DECISIONS.has(result.decision)) fail(`invalid decision '${result.decision}'`);
362
+ const decision = { at: new Date().toISOString(), round: latest?.round ?? 0, ...result };
363
+ record.decision = decision;
364
+ record.decisionHistory.push(decision);
365
+ await atomicWriteJson(recordFile, record);
366
+ console.log(JSON.stringify(decision));
367
+ } finally {
368
+ await release();
369
+ }
370
+ }
371
+
372
+ main().catch((error) => {
373
+ console.log(
374
+ JSON.stringify({
375
+ action: "failed",
376
+ decision: "unavailable",
377
+ category: "invalid-input",
378
+ message: error instanceof Error ? error.message : "invalid record",
379
+ }),
380
+ );
381
+ process.exitCode = 2;
382
+ });