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,18 +3,17 @@ import {
3
3
  Scene,
4
4
  type SceneFrame,
5
5
  isMobile,
6
- isNative,
7
6
  isTouchscreenAvailable,
8
7
  } from "@threenative/core";
9
8
  import { CollisionShape3D, RigidBody3D } from "@threenative/physics";
10
9
  import type { IPhysicsContext } from "@threenative/physics";
11
- import { BoxGeometry, Mesh, type PerspectiveCamera, Vector3 } from "three";
10
+ import { BoxGeometry, Group, Mesh, type PerspectiveCamera, Vector3 } from "three";
12
11
  import { Character, PLATFORMER_FEEL } from "../entities/Character.js";
13
12
  import { Chaser } from "../entities/Chaser.js";
14
13
  import { Patrol } from "../entities/Patrol.js";
15
14
  import { Pickup, coinArc } from "../entities/Pickup.js";
16
15
  import { Checkpoints } from "../level/Checkpoints.js";
17
- import { createPlatform } from "../level/Platform.js";
16
+ import { type IPlatform, createPlatform } from "../level/Platform.js";
18
17
  import { emitPlaytestEvent } from "../playtest-events.js";
19
18
  import { setupCamera } from "../render/camera.js";
20
19
  import { setupLighting } from "../render/lighting.js";
@@ -27,6 +26,8 @@ import { TouchControls } from "../render/touch-controls.js";
27
26
  import { type GameState, TERMINAL, type TerminalState } from "../state.js";
28
27
  export type GameCtx = ICtx<GameState, IPhysicsContext>;
29
28
  const SPAWN = new Vector3(0, 0.75, 0);
29
+ const PATROL_FROM = new Vector3(5.2, 0.66, 0);
30
+ const PATROL_TO = new Vector3(7.4, 0.66, 0);
30
31
  const KILL_PLANE = -8;
31
32
  const GOAL_X = 21.5;
32
33
  export class Level extends Scene<GameState, IPhysicsContext> {
@@ -47,6 +48,16 @@ export class Level extends Scene<GameState, IPhysicsContext> {
47
48
  terminal: TERMINAL.playing,
48
49
  topSpeed: 0,
49
50
  };
51
+
52
+ override load(ctx: GameCtx): void {
53
+ // A runner applies setup after load() but before enter(). Keep a transform-bearing placeholder
54
+ // for the patrol so a setup can position/freeze it before Patrol creates its authoritative
55
+ // trigger in enter(). The placeholder is never rendered or stepped.
56
+ const patrol = new Group();
57
+ patrol.position.copy(PATROL_FROM);
58
+ ctx.entities.add("patrol", patrol);
59
+ }
60
+
50
61
  override enter(ctx: GameCtx): SceneFrame<GameState, IPhysicsContext> {
51
62
  setupSky(ctx.scene);
52
63
  const sun = setupLighting(ctx.scene, ctx.renderer.raw as Parameters<typeof setupLighting>[1]);
@@ -57,15 +68,25 @@ export class Level extends Scene<GameState, IPhysicsContext> {
57
68
  setupCamera(camera);
58
69
  const loading = createLoadingScreen(ctx);
59
70
  ctx.add(camera);
60
- const showTouchControls = isNative() && isMobile() && isTouchscreenAvailable();
71
+ const showTouchControls = isMobile() && isTouchscreenAvailable();
61
72
  const touchControls = showTouchControls
62
73
  ? ctx.entities.add("touch-controls", new TouchControls(camera))
63
74
  : undefined;
64
75
  ctx.viewport.resize();
65
- createPlatform(ctx, new Vector3(0, 0, 0), 18, { depth: 7, seed: 3 });
66
- createPlatform(ctx, new Vector3(14, 0, 0), 10, { depth: 7, seed: 7 });
67
- createPlatform(ctx, new Vector3(25, 0, 0), 8, { depth: 7, seed: 11 });
68
- createPlatform(ctx, new Vector3(0, 2.6, 0), 6, { depth: 5, oneWay: true, seed: 17 });
76
+ const platforms: IPlatform[] = [
77
+ createPlatform(ctx, new Vector3(0, 0, 0), 18, { depth: 7, seed: 3 }),
78
+ createPlatform(ctx, new Vector3(14, 0, 0), 10, { depth: 7, seed: 7 }),
79
+ createPlatform(ctx, new Vector3(25, 0, 0), 8, { depth: 7, seed: 11 }),
80
+ createPlatform(ctx, new Vector3(0, 2.6, 0), 6, { depth: 5, oneWay: true, seed: 17 }),
81
+ ];
82
+ const supportSurfaceY = (position: Pick<Vector3, "x" | "y" | "z">): number | undefined => {
83
+ let surfaceY: number | undefined;
84
+ for (const platform of platforms) {
85
+ if (!platform.contains(position) || platform.surfaceY > position.y) continue;
86
+ if (surfaceY === undefined || platform.surfaceY > surfaceY) surfaceY = platform.surfaceY;
87
+ }
88
+ return surfaceY;
89
+ };
69
90
  const crate = crateMesh();
70
91
  crate.position.set(-3, 1, 0);
71
92
  crate.castShadow = crate.receiveShadow = true;
@@ -108,26 +129,44 @@ export class Level extends Scene<GameState, IPhysicsContext> {
108
129
  ctx.entities.add(id, pickup);
109
130
  };
110
131
  const followCamera = (target: Vector3, dt: number): void => {
111
- const desired = cameraAnchor.set(target.x, target.y + 4.4, target.z + 8.5);
132
+ // The eye stays **below** the one-way platform, which sits at y = 2.6 directly over the
133
+ // spawn because `oneway.playtest.json` jumps straight up from there and lands on it. At the
134
+ // old +4.4 the camera looked down onto that slab and the character it is standing under, so
135
+ // the opening frame was a green rectangle with the player hidden behind it; raising the
136
+ // camera further only made it worse. Under the slab, the level reads and the platform
137
+ // overhead reads as an overhang, which is what it is.
138
+ const desired = cameraAnchor.set(target.x + 1.4, target.y + 1.75, target.z + 10.6);
112
139
  if (dt >= 1) camera.position.copy(desired);
113
140
  else camera.position.lerp(desired, 1 - Math.exp(-dt / 0.18));
114
- camera.lookAt(target.x, target.y + 0.9, target.z);
141
+ camera.lookAt(target.x + 2.2, target.y + 0.35, target.z - 0.4);
115
142
  };
116
143
  addPickup(new Vector3(2, 1.05, 0));
117
144
  addPickup(new Vector3(3.2, 1.05, 0));
118
145
  addPickup(new Vector3(4.4, 1.05, 0));
119
146
  for (const point of coinArc(new Vector3(11, 1.05, 0), 4, 3.6, 1.4)) addPickup(point);
147
+ const patrolSetup = ctx.entities.get<Group>("patrol");
148
+ const patrolPosition = patrolSetup?.position.clone() ?? PATROL_FROM.clone();
149
+ const patrolQuaternion = patrolSetup?.quaternion.clone();
150
+ const patrolScale = patrolSetup?.scale.clone();
151
+ const patrolUserData = patrolSetup === undefined ? undefined : { ...patrolSetup.userData };
152
+ if (patrolSetup !== undefined) ctx.entities.remove("patrol");
120
153
  const patrol = new Patrol(
121
154
  ctx,
122
155
  character,
123
- new Vector3(5.2, 0.66, 0),
124
- new Vector3(7.4, 0.66, 0),
156
+ PATROL_FROM,
157
+ PATROL_TO,
125
158
  () => {
126
159
  defeated += 1;
127
160
  },
128
161
  (fromX) => checkpoints.hurt(character, fromX),
129
162
  PLATFORMER_FEEL,
130
163
  );
164
+ patrol.mesh.position.copy(patrolPosition);
165
+ if (patrolQuaternion !== undefined) patrol.mesh.quaternion.copy(patrolQuaternion);
166
+ if (patrolScale !== undefined) patrol.mesh.scale.copy(patrolScale);
167
+ if (patrolUserData !== undefined) Object.assign(patrol.mesh.userData, patrolUserData);
168
+ patrol.mesh.updateMatrix();
169
+ patrol.area.setPosition(patrol.mesh.position);
131
170
  ctx.entities.add("patrol", patrol);
132
171
  const chaser = new Chaser(ctx, new Vector3(7.5, 0.66, 0));
133
172
  const avoidanceChaser = new Chaser(ctx, new Vector3(8.2, 0.66, 0.7));
@@ -150,6 +189,7 @@ export class Level extends Scene<GameState, IPhysicsContext> {
150
189
  frameCtx,
151
190
  dt,
152
191
  touchControls?.update(frameCtx.input.raw.pointers, frameCtx.viewport.size),
192
+ supportSurfaceY,
153
193
  );
154
194
  // The chasers walk a measured route, and `pathLength` assertions read how much of it was
155
195
  // walked while a runner was watching. Stepping them before the world reports startup ready
@@ -41,6 +41,26 @@ body {
41
41
  background: var(--color-ink);
42
42
  }
43
43
 
44
+ /* Boot failures are a page state, so the generated game owns their presentation. */
45
+ [data-threenative-canvas-error="true"] {
46
+ position: fixed;
47
+ inset: 0;
48
+ z-index: 1000;
49
+ display: grid;
50
+ place-items: center;
51
+ box-sizing: border-box;
52
+ padding: clamp(1.5rem, 8vw, 6rem);
53
+ overflow: auto;
54
+ background: #fff7ed;
55
+ color: var(--color-ink);
56
+ font-family: inherit;
57
+ font-size: clamp(1rem, 2vw, 1.5rem);
58
+ line-height: 1.5;
59
+ text-align: center;
60
+ white-space: pre-wrap;
61
+ overflow-wrap: anywhere;
62
+ }
63
+
44
64
  /* The debug surface is framework plumbing; its default presentation is yours to change. */
45
65
  [data-threenative-debug-overlay="true"] {
46
66
  position: fixed;
@@ -19,6 +19,7 @@ const config: IThreeNativeConfig = {
19
19
  title: "__PROJECT_NAME__", // Desktop window title.
20
20
  width: 1280,
21
21
  height: 720,
22
+ maximized: false,
22
23
  resizable: true,
23
24
  },
24
25
  bootSplash: {
@@ -31,6 +32,12 @@ const config: IThreeNativeConfig = {
31
32
  // the scale it settled on in every `TN_FRAME_BUDGET` window. Replace with a number in (0, 1]
32
33
  // to pin it — the loop stops and the reporting does not. CSS, UI and camera framing never move.
33
34
  resolutionScale: "auto",
35
+ // Multisampling resolves triangle edges. A cutout silhouette — foliage, a fence, hair — is
36
+ // carved inside the triangle by an alpha test, so it resolves through the coverage mask or
37
+ // not at all, which is what this spends the samples above on. It costs no target and no
38
+ // extra pass; set it false for a deliberately hard-edged look. `TN_ALPHA_ANTIALIASING`
39
+ // reports what it did, and says so when a single-sampled surface leaves it nothing to do.
40
+ alphaAntialiasing: true,
34
41
  },
35
42
  // One UI on every target: src/ui/ renders through the platform's own browser-class renderer,
36
43
  // so the same React, Tailwind, CSS and SVG run on web, desktop, Android and iOS alike.
@@ -0,0 +1,19 @@
1
+ [mcp_servers.threenative-assets]
2
+ command = "node"
3
+ args = ["./node_modules/@threenative/core/mcp/assets.mjs"]
4
+
5
+ [mcp_servers.threenative-assets.env]
6
+ ASSET_DOWNLOAD_DIR = "./public/assets"
7
+ AUDIO_DOWNLOAD_DIR = "./public/audio"
8
+
9
+ [mcp_servers.threenative-sculpt]
10
+ command = "node"
11
+ args = ["./node_modules/@threenative/core/mcp/sculpt.mjs"]
12
+
13
+ [mcp_servers.threenative-engine]
14
+ command = "node"
15
+ args = ["./node_modules/@threenative/core/mcp/engine.mjs"]
16
+
17
+ [mcp_servers.threenative-blender]
18
+ command = "node"
19
+ args = ["./node_modules/@threenative/core/mcp/blender.mjs"]
@@ -0,0 +1,32 @@
1
+ {
2
+ "mcpServers": {
3
+ "threenative-assets": {
4
+ "command": "node",
5
+ "args": [
6
+ "./node_modules/@threenative/core/mcp/assets.mjs"
7
+ ],
8
+ "env": {
9
+ "ASSET_DOWNLOAD_DIR": "./public/assets",
10
+ "AUDIO_DOWNLOAD_DIR": "./public/audio"
11
+ }
12
+ },
13
+ "threenative-sculpt": {
14
+ "command": "node",
15
+ "args": [
16
+ "./node_modules/@threenative/core/mcp/sculpt.mjs"
17
+ ]
18
+ },
19
+ "threenative-engine": {
20
+ "command": "node",
21
+ "args": [
22
+ "./node_modules/@threenative/core/mcp/engine.mjs"
23
+ ]
24
+ },
25
+ "threenative-blender": {
26
+ "command": "node",
27
+ "args": [
28
+ "./node_modules/@threenative/core/mcp/blender.mjs"
29
+ ]
30
+ }
31
+ }
32
+ }
@@ -0,0 +1,32 @@
1
+ {
2
+ "mcpServers": {
3
+ "threenative-assets": {
4
+ "command": "node",
5
+ "args": [
6
+ "./node_modules/@threenative/core/mcp/assets.mjs"
7
+ ],
8
+ "env": {
9
+ "ASSET_DOWNLOAD_DIR": "./public/assets",
10
+ "AUDIO_DOWNLOAD_DIR": "./public/audio"
11
+ }
12
+ },
13
+ "threenative-sculpt": {
14
+ "command": "node",
15
+ "args": [
16
+ "./node_modules/@threenative/core/mcp/sculpt.mjs"
17
+ ]
18
+ },
19
+ "threenative-engine": {
20
+ "command": "node",
21
+ "args": [
22
+ "./node_modules/@threenative/core/mcp/engine.mjs"
23
+ ]
24
+ },
25
+ "threenative-blender": {
26
+ "command": "node",
27
+ "args": [
28
+ "./node_modules/@threenative/core/mcp/blender.mjs"
29
+ ]
30
+ }
31
+ }
32
+ }
@@ -0,0 +1,32 @@
1
+ {
2
+ "mcpServers": {
3
+ "threenative-assets": {
4
+ "command": "node",
5
+ "args": [
6
+ "./node_modules/@threenative/core/mcp/assets.mjs"
7
+ ],
8
+ "env": {
9
+ "ASSET_DOWNLOAD_DIR": "./public/assets",
10
+ "AUDIO_DOWNLOAD_DIR": "./public/audio"
11
+ }
12
+ },
13
+ "threenative-sculpt": {
14
+ "command": "node",
15
+ "args": [
16
+ "./node_modules/@threenative/core/mcp/sculpt.mjs"
17
+ ]
18
+ },
19
+ "threenative-engine": {
20
+ "command": "node",
21
+ "args": [
22
+ "./node_modules/@threenative/core/mcp/engine.mjs"
23
+ ]
24
+ },
25
+ "threenative-blender": {
26
+ "command": "node",
27
+ "args": [
28
+ "./node_modules/@threenative/core/mcp/blender.mjs"
29
+ ]
30
+ }
31
+ }
32
+ }
@@ -0,0 +1,36 @@
1
+ {
2
+ "servers": {
3
+ "threenative-assets": {
4
+ "type": "stdio",
5
+ "command": "node",
6
+ "args": [
7
+ "./node_modules/@threenative/core/mcp/assets.mjs"
8
+ ],
9
+ "env": {
10
+ "ASSET_DOWNLOAD_DIR": "./public/assets",
11
+ "AUDIO_DOWNLOAD_DIR": "./public/audio"
12
+ }
13
+ },
14
+ "threenative-sculpt": {
15
+ "type": "stdio",
16
+ "command": "node",
17
+ "args": [
18
+ "./node_modules/@threenative/core/mcp/sculpt.mjs"
19
+ ]
20
+ },
21
+ "threenative-engine": {
22
+ "type": "stdio",
23
+ "command": "node",
24
+ "args": [
25
+ "./node_modules/@threenative/core/mcp/engine.mjs"
26
+ ]
27
+ },
28
+ "threenative-blender": {
29
+ "type": "stdio",
30
+ "command": "node",
31
+ "args": [
32
+ "./node_modules/@threenative/core/mcp/blender.mjs"
33
+ ]
34
+ }
35
+ }
36
+ }
@@ -0,0 +1,36 @@
1
+ {
2
+ "context_servers": {
3
+ "threenative-assets": {
4
+ "source": "custom",
5
+ "command": "node",
6
+ "args": [
7
+ "./node_modules/@threenative/core/mcp/assets.mjs"
8
+ ],
9
+ "env": {
10
+ "ASSET_DOWNLOAD_DIR": "./public/assets",
11
+ "AUDIO_DOWNLOAD_DIR": "./public/audio"
12
+ }
13
+ },
14
+ "threenative-sculpt": {
15
+ "source": "custom",
16
+ "command": "node",
17
+ "args": [
18
+ "./node_modules/@threenative/core/mcp/sculpt.mjs"
19
+ ]
20
+ },
21
+ "threenative-engine": {
22
+ "source": "custom",
23
+ "command": "node",
24
+ "args": [
25
+ "./node_modules/@threenative/core/mcp/engine.mjs"
26
+ ]
27
+ },
28
+ "threenative-blender": {
29
+ "source": "custom",
30
+ "command": "node",
31
+ "args": [
32
+ "./node_modules/@threenative/core/mcp/blender.mjs"
33
+ ]
34
+ }
35
+ }
36
+ }
@@ -0,0 +1,96 @@
1
+ # AGENTS.md — __PROJECT_NAME__ puzzle
2
+
3
+ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
4
+
5
+ ## Ownership
6
+
7
+ ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the room, the crates, the hinge, the ball, the goal, the HUD
8
+ and the look; `src/game.ts` is portable and React mounts only from `src/main.ts`.
9
+
10
+ ## Start every change
11
+
12
+ 1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
13
+ `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
14
+ matches with `engine_capability_detail`, and record a capability or no-match for the plan.
15
+ 2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
16
+ direct the user to review it, and wait for explicit approval plus an instruction to implement it.
17
+ 3. Treat returned constraints as binding. This kit needs no navmesh and imports none, so it runs
18
+ on every target; adding `@threenative/physics/navigation` would make it web and desktop only.
19
+ 4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and
20
+ `npx @threenative/playtest doctor`; missing observations are not zero.
21
+ For *"a bullet passes through a wall"*, `RigidBody3D` defaults to continuous collision; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web/native.
22
+
23
+ ## When the framework blocks you, write plain Three.js
24
+
25
+ When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
26
+ piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
27
+ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
28
+ (API, expectation, result, replacement); never stall the game.
29
+
30
+ ## Workflow skills
31
+
32
+ - `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
33
+ - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search.
34
+ - `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
35
+ - `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
36
+ - `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
37
+ - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
38
+ - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
39
+ - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
40
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
41
+
42
+ ## Commands and map
43
+
44
+ ```sh
45
+ pnpm dev
46
+ pnpm build
47
+ pnpm build --target desktop
48
+ pnpm test
49
+ pnpm typecheck
50
+ ```
51
+
52
+ `src/room.ts` builds the room's geometry and hands it to `buildStaticColliders`, so collision is
53
+ the geometry rather than a second hand-written list of boxes: move a wall and its collider moves.
54
+ The same file places the floor grid through one `InstancedBatch`, which is why 100+ tiles cost one
55
+ draw. `src/entities/Pendulum.ts` hangs a bob from a fixed beam with `Joint3D.hinge` — anchors are
56
+ in each body's **local** space. `src/entities/Ball.ts` owns the goal as an `Area3D` and listens for
57
+ `bodyEntered`; a distance check instead would fire on a ball that flew over the ring. A carried
58
+ crate is steered by velocity in `src/entities/Crate.ts` and never teleported, because snapping a
59
+ dynamic body each frame pushes it through walls. Register gameplay entities with `ctx.entities`;
60
+ the single React HUD reads `GameState`, never an entity. Keep `playtests/survives.playtest.json`
61
+ as smoke proof, and `carry` and `swing` honest when you change what they assert.
62
+
63
+ ## Portable authoring contracts
64
+
65
+ Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `models: "none"` / `textures: "none"` / `audio: "none"` skip those passes and report uncooked bytes. Android/iOS currently skip compression and model dedupe. `assets.exclude` defaults to `[]`; source-relative globs (for example `["unused/**"]`) omit matching files and report saved bytes. `assets.budget` accepts `{ uncooked?: number | "none", total?: number | "none" }`, default `{ uncooked: 64_000_000, total: "none" }`: only bytes left uncooked where cooking was possible count toward `uncooked`. A number sets that ceiling; `"none"` disables both gates. Either disabled gate still reports bytes. Automatic texture cooking retains unaligned source images unchanged and reports `block-size`; those bytes still count toward the uncooked budget. An explicit compression codec override must satisfy four-pixel block alignment; `codec: "none"` opts out. Cooking never silently resizes an image to fix alignment.
66
+
67
+ Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out. Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window.
68
+ Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable.
69
+ Generated conventions call `GroundSnap` for floor contact and `normaliseToMetres` for authored model scale.
70
+ The camera reads the claw **after** the step through `afterPhysics`; reading it in the frame function
71
+ is one step of lag, and on a swinging weight one step of lag is visible.
72
+ `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive
73
+ `AnimationPlayer` beside its entity. `ctx.goto(name)` rebuilds without resetting game state; from
74
+ a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })`
75
+ is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's
76
+ state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
77
+
78
+ When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a
79
+ retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's
80
+ own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is
81
+ caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing
82
+ (the `<bone>.undefined` failure that plays the bind pose instead of the animation),
83
+ `clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous
84
+ clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is
85
+ supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches 256 per presented frame so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement.
86
+
87
+ ## Budget real time for the look — see `agent-docs/dream-loop.md`
88
+
89
+ Edit `src/render/` directly; `postprocessing.ts` reports stages but decides no game colour. Quality
90
+ tiers live in `src/render/quality.ts`: `low`, `medium`, `high`; `isMobile()` chooses `low`, otherwise
91
+ `high`; override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER`
92
+ reports the source. A scenario with no assertions or missing observations fails; open a real capture.
93
+
94
+ Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
95
+ ## Optional multiplayer transport
96
+ For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
@@ -0,0 +1,98 @@
1
+ <!-- Generated mirror of AGENTS.md. Do not edit; edit AGENTS.md. -->
2
+
3
+ # AGENTS.md — __PROJECT_NAME__ puzzle
4
+
5
+ Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
6
+
7
+ ## Ownership
8
+
9
+ ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the room, the crates, the hinge, the ball, the goal, the HUD
10
+ and the look; `src/game.ts` is portable and React mounts only from `src/main.ts`.
11
+
12
+ ## Start every change
13
+
14
+ 1. **Critical planning gate:** invoke `threenative-capabilities` before `prd-creator`. Search
15
+ `engine_search_capabilities` for the full request and each concrete mechanic, inspect relevant
16
+ matches with `engine_capability_detail`, and record a capability or no-match for the plan.
17
+ 2. Then invoke `prd-creator`. Draft the plan around those capabilities and binding constraints,
18
+ direct the user to review it, and wait for explicit approval plus an instruction to implement it.
19
+ 3. Treat returned constraints as binding. This kit needs no navmesh and imports none, so it runs
20
+ on every target; adding `@threenative/physics/navigation` would make it web and desktop only.
21
+ 4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and
22
+ `npx @threenative/playtest doctor`; missing observations are not zero.
23
+ For *"a bullet passes through a wall"*, `RigidBody3D` defaults to continuous collision; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web/native.
24
+
25
+ ## When the framework blocks you, write plain Three.js
26
+
27
+ When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
28
+ piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
29
+ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
30
+ (API, expectation, result, replacement); never stall the game.
31
+
32
+ ## Workflow skills
33
+
34
+ - `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
35
+ - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search.
36
+ - `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
37
+ - `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
38
+ - `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
39
+ - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
40
+ - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
41
+ - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
42
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
43
+
44
+ ## Commands and map
45
+
46
+ ```sh
47
+ pnpm dev
48
+ pnpm build
49
+ pnpm build --target desktop
50
+ pnpm test
51
+ pnpm typecheck
52
+ ```
53
+
54
+ `src/room.ts` builds the room's geometry and hands it to `buildStaticColliders`, so collision is
55
+ the geometry rather than a second hand-written list of boxes: move a wall and its collider moves.
56
+ The same file places the floor grid through one `InstancedBatch`, which is why 100+ tiles cost one
57
+ draw. `src/entities/Pendulum.ts` hangs a bob from a fixed beam with `Joint3D.hinge` — anchors are
58
+ in each body's **local** space. `src/entities/Ball.ts` owns the goal as an `Area3D` and listens for
59
+ `bodyEntered`; a distance check instead would fire on a ball that flew over the ring. A carried
60
+ crate is steered by velocity in `src/entities/Crate.ts` and never teleported, because snapping a
61
+ dynamic body each frame pushes it through walls. Register gameplay entities with `ctx.entities`;
62
+ the single React HUD reads `GameState`, never an entity. Keep `playtests/survives.playtest.json`
63
+ as smoke proof, and `carry` and `swing` honest when you change what they assert.
64
+
65
+ ## Portable authoring contracts
66
+
67
+ Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `models: "none"` / `textures: "none"` / `audio: "none"` skip those passes and report uncooked bytes. Android/iOS currently skip compression and model dedupe. `assets.exclude` defaults to `[]`; source-relative globs (for example `["unused/**"]`) omit matching files and report saved bytes. `assets.budget` accepts `{ uncooked?: number | "none", total?: number | "none" }`, default `{ uncooked: 64_000_000, total: "none" }`: only bytes left uncooked where cooking was possible count toward `uncooked`. A number sets that ceiling; `"none"` disables both gates. Either disabled gate still reports bytes. Automatic texture cooking retains unaligned source images unchanged and reports `block-size`; those bytes still count toward the uncooked budget. An explicit compression codec override must satisfy four-pixel block alignment; `codec: "none"` opts out. Cooking never silently resizes an image to fix alignment.
68
+
69
+ Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out. Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window.
70
+ Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable.
71
+ Generated conventions call `GroundSnap` for floor contact and `normaliseToMetres` for authored model scale.
72
+ The camera reads the claw **after** the step through `afterPhysics`; reading it in the frame function
73
+ is one step of lag, and on a swinging weight one step of lag is visible.
74
+ `input.vector("move").y` is +up, so forward uses one explicit `-move.y` conversion. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive
75
+ `AnimationPlayer` beside its entity. `ctx.goto(name)` rebuilds without resetting game state; from
76
+ a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })`
77
+ is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's
78
+ state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
79
+
80
+ When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a
81
+ retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's
82
+ own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is
83
+ caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing
84
+ (the `<bone>.undefined` failure that plays the bind pose instead of the animation),
85
+ `clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous
86
+ clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is
87
+ supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches 256 per presented frame so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement.
88
+
89
+ ## Budget real time for the look — see `agent-docs/dream-loop.md`
90
+
91
+ Edit `src/render/` directly; `postprocessing.ts` reports stages but decides no game colour. Quality
92
+ tiers live in `src/render/quality.ts`: `low`, `medium`, `high`; `isMobile()` chooses `low`, otherwise
93
+ `high`; override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER`
94
+ reports the source. A scenario with no assertions or missing observations fails; open a real capture.
95
+
96
+ Recipes shipped in the project: `agent-docs/assertion-reference.md`, `agent-docs/capability-reference.md`, `agent-docs/capture-the-frame.md`, `agent-docs/creating-creatures.md`, `agent-docs/ctx-cookbook.md`, `agent-docs/debug-surface.md`, `agent-docs/finding-assets.md`, `agent-docs/gameplay-recipes.md`, `agent-docs/menu-screens.md`, `agent-docs/mobile-memory-budget.md`, `agent-docs/sculpt-from-a-reference.md`, `agent-docs/trace-a-slow-frame.md`, `agent-docs/visual-baseline.md`, and `agent-docs/webview-ui.md`.
97
+ ## Optional multiplayer transport
98
+ For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
@@ -0,0 +1,43 @@
1
+ # Puzzle starter kit
2
+
3
+ A contraption room. A ball has to reach a ring on the far side of a lip it cannot roll over, and
4
+ everything in the room is a way of getting it there: three crates you carry into a ramp, and a
5
+ 90 kg weight hanging from a hinge that you can set swinging.
6
+
7
+ Nothing here is downloaded. Every shape is a box, cylinder, sphere or torus built in
8
+ `src/render/shapes.ts`, so the kit has no asset licence, no loading wait, and nothing to fetch.
9
+
10
+ ```sh
11
+ pnpm dev # play it
12
+ pnpm test # the committed scenarios, in a real browser
13
+ pnpm build # web
14
+ pnpm build --target desktop
15
+ ```
16
+
17
+ ## Controls
18
+
19
+ | Input | Does |
20
+ | --- | --- |
21
+ | `W A S D` / arrows | move the claw |
22
+ | `E` or `Space`, or tap a crate | grab and drop the nearest crate |
23
+ | `F` | shove the hanging weight |
24
+ | `R` | reset the room |
25
+
26
+ On a touch device a left thumbstick and two buttons appear instead; the same code path runs.
27
+
28
+ ## What each piece is
29
+
30
+ | File | Owns |
31
+ | --- | --- |
32
+ | `src/room.ts` | the room's geometry, its static colliders, and the instanced floor grid |
33
+ | `src/entities/Crate.ts` | a carried box — steered by velocity, never teleported |
34
+ | `src/entities/Pendulum.ts` | the beam, the bob, and the hinge between them |
35
+ | `src/entities/Ball.ts` | the ball and the goal volume that notices it |
36
+ | `src/entities/Gripper.ts` | the player |
37
+ | `src/render/` | everything that decides how it looks. Yours to rewrite. |
38
+
39
+ ## Where to take it
40
+
41
+ The room is one `buildRoom()` call and three crate spawns. Move the lip, add a second ball, hang
42
+ two weights on one beam, or make the goal move. If you want a second room, add a scene beside
43
+ `Puzzle` and `goto` it — the state shape and HUD already carry a status.
@@ -0,0 +1,12 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
+ <title>__PROJECT_NAME__</title>
7
+ </head>
8
+ <body>
9
+ <div id="root"></div>
10
+ <script type="module" src="/src/main.ts"></script>
11
+ </body>
12
+ </html>
@@ -0,0 +1,7 @@
1
+ {
2
+ "name": "puzzle",
3
+ "title": "Physics puzzle",
4
+ "blurb": "A contraption room: drag crates into a ramp, swing a hinged weight, and roll the ball into the goal.",
5
+ "genre": "physics-puzzle",
6
+ "kit": true
7
+ }