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
@@ -1,9 +1,22 @@
1
1
  import { type ICtx, InstancedBatch, PathFollow3D } from "@threenative/core";
2
2
  import { Area3D, CollisionShape3D, type IPhysicsContext, RigidBody3D } from "@threenative/physics";
3
- import { BoxGeometry, Color, Group, Mesh, MeshStandardMaterial, Raycaster, Vector3 } from "three";
3
+ import {
4
+ BoxGeometry,
5
+ CapsuleGeometry,
6
+ Group,
7
+ Mesh,
8
+ MeshStandardMaterial,
9
+ Raycaster,
10
+ SphereGeometry,
11
+ Vector3,
12
+ } from "three";
13
+
14
+ /** Reused by the grandstand crowd placement; a fresh axis per seat is pure garbage. */
15
+ const UP = new Vector3(0, 1, 0);
4
16
  import { Boost } from "../kart/boost.js";
5
17
  import { createMaterials } from "../render/materials.js";
6
18
  import { palette } from "../render/palette.js";
19
+ import { grandstand, hoardingGeometry, treeGeometry, tyreStackGeometry } from "../render/shapes.js";
7
20
  import type { GameState } from "../state.js";
8
21
  import { Checkline } from "./Checkline.js";
9
22
  import type { IRayHit, IntersectRay } from "./TrackSector.js";
@@ -61,17 +74,41 @@ function roadSegment(
61
74
  * draws exactly what a per-segment `BoxGeometry` drew — as one draw for the whole track instead of
62
75
  * two per sector. Change `materials.curb` and every kerb changes with it; the batch picks nothing.
63
76
  */
64
- function addCurb(curbs: InstancedBatch, a: Vector3, b: Vector3, side: number): void {
77
+ function addCurb(
78
+ curbs: InstancedBatch,
79
+ alternate: InstancedBatch,
80
+ a: Vector3,
81
+ b: Vector3,
82
+ side: number,
83
+ ): void {
65
84
  const direction = b.clone().sub(a).setY(0).normalize();
66
85
  const normal = new Vector3(-direction.z, 0, direction.x).multiplyScalar(
67
86
  side * (TRACK_WIDTH / 2 + 0.28),
68
87
  );
69
- const midpoint = a.clone().lerp(b, 0.5).add(normal);
70
- curbs.place({
71
- position: [midpoint.x, 0.08, midpoint.z],
72
- rotation: [0, Math.atan2(direction.z, direction.x), 0],
73
- scale: [a.distanceTo(b), 0.18, 0.42],
74
- });
88
+ // Both ends are pulled in by half the track width plus the kerb's own offset. Run to the raw
89
+ // route point and the kerbs of two sectors cross at right angles inside the corner; the overlap
90
+ // shows as a bitten-out notch in the middle of the stripe pattern. The square corner blocks that
91
+ // `buildTrack` places take over from here.
92
+ const inset = TRACK_WIDTH / 2 + 0.28;
93
+ const from = a.clone().addScaledVector(direction, inset);
94
+ const length = Math.max(a.distanceTo(b) - inset * 2, 0.6);
95
+ // Kerbing is **striped**, and the stripes are what make a corner readable at speed. One long
96
+ // cream box per sector is what shipped, and the first frame showed a plain white line: correct
97
+ // geometry, no information. Two batches alternating along the sector cost one extra draw for the
98
+ // whole circuit.
99
+ const blocks = Math.max(2, Math.round(length / 1.3));
100
+ const step = length / blocks;
101
+ for (let index = 0; index < blocks; index += 1) {
102
+ const centre = from
103
+ .clone()
104
+ .addScaledVector(direction, step * (index + 0.5))
105
+ .add(normal);
106
+ (index % 2 === 0 ? curbs : alternate).place({
107
+ position: [centre.x, 0.08, centre.z],
108
+ rotation: [0, Math.atan2(direction.z, direction.x), 0],
109
+ scale: [step * 0.98, 0.18, 0.5],
110
+ });
111
+ }
75
112
  }
76
113
 
77
114
  function gate(
@@ -87,15 +124,21 @@ function gate(
87
124
  metalness: 0.2,
88
125
  roughness: 0.45,
89
126
  });
90
- const post = new Mesh(new BoxGeometry(0.24, 2.5, 0.24), material);
127
+ const post = new Mesh(new BoxGeometry(0.28, 3.4, 0.28), material);
91
128
  const otherPost = post.clone();
92
- const top = new Mesh(new BoxGeometry(width, 0.24, 0.24), material);
93
- post.position.set(-width / 2, 1.25, 0);
94
- otherPost.position.set(width / 2, 1.25, 0);
95
- top.position.y = 2.45;
96
- group.add(post, otherPost, top);
129
+ const top = new Mesh(new BoxGeometry(width + 1.2, 0.34, 0.34), material);
130
+ const banner = new Mesh(new BoxGeometry(width + 0.6, 0.7, 0.08), material);
131
+ post.position.set(-(width / 2 + 0.5), 1.7, 0);
132
+ otherPost.position.set(width / 2 + 0.5, 1.7, 0);
133
+ top.position.y = 3.55;
134
+ banner.position.y = 3.0;
135
+ for (const mesh of [post, otherPost, top, banner]) mesh.castShadow = true;
136
+ group.add(post, otherPost, top, banner);
97
137
  group.position.set(at.x, 0, at.z);
98
- if (Math.abs(forward.z) > Math.abs(forward.x)) group.rotation.y = Math.PI / 2;
138
+ // A gate spans the road, so it is rotated when the road runs along **X**, not along Z. The
139
+ // condition used to be the other way round, which laid both gantries down the racing line: from
140
+ // the chase camera the finish gantry read as a stray yellow post and a bar going nowhere.
141
+ if (Math.abs(forward.x) > Math.abs(forward.z)) group.rotation.y = Math.PI / 2;
99
142
  ctx.add(group);
100
143
  const area = new Area3D({
101
144
  collisionMask: 1,
@@ -116,9 +159,23 @@ function boostPad(
116
159
  at: Vector3,
117
160
  materials: ReturnType<typeof createMaterials>,
118
161
  ): { area: Area3D; boost: Boost } {
119
- const pad = new Mesh(new BoxGeometry(3.2, 0.08, TRACK_WIDTH - 0.6), materials.boost);
162
+ // Chevrons, not a slab. A flat yellow rectangle across the road reads as a painting mistake;
163
+ // arrows read as "drive here and go faster" without a word of UI.
164
+ const pad = new Group();
165
+ const base = new Mesh(new BoxGeometry(3.2, 0.04, TRACK_WIDTH - 0.6), materials.carbon);
166
+ base.position.y = 0.005;
167
+ base.receiveShadow = true;
168
+ pad.add(base);
169
+ for (let index = 0; index < 3; index += 1) {
170
+ for (const side of [-1, 1]) {
171
+ const arm = new Mesh(new BoxGeometry(1.5, 0.05, 0.42), materials.boost);
172
+ arm.position.set(-1.0 + index * 1.0, 0.03, side * 0.9);
173
+ arm.rotation.y = side * 0.62;
174
+ arm.receiveShadow = true;
175
+ pad.add(arm);
176
+ }
177
+ }
120
178
  pad.position.set(at.x, 0.12, at.z);
121
- pad.receiveShadow = true;
122
179
  ctx.add(pad);
123
180
  const boost = new Boost();
124
181
  const area = new Area3D({
@@ -208,6 +265,10 @@ export function buildTrack(ctx: TrackCtx): ITrackBuild {
208
265
  geometry: new BoxGeometry(1, 1, 1),
209
266
  material: materials.curb,
210
267
  });
268
+ const curbsAlt = new InstancedBatch({
269
+ geometry: new BoxGeometry(1, 1, 1),
270
+ material: materials.kerbAlt,
271
+ });
211
272
 
212
273
  const roadMeshes: Mesh[] = [];
213
274
  for (let index = 0; index < ROUTE_POINTS.length; index += 1) {
@@ -215,28 +276,206 @@ export function buildTrack(ctx: TrackCtx): ITrackBuild {
215
276
  const b = ROUTE_POINTS[(index + 1) % ROUTE_POINTS.length];
216
277
  if (a === undefined || b === undefined) continue;
217
278
  roadMeshes.push(roadSegment(ctx, a, b, materials));
218
- addCurb(curbs, a, b, 1);
219
- addCurb(curbs, a, b, -1);
279
+ addCurb(curbs, curbsAlt, a, b, 1);
280
+ addCurb(curbs, curbsAlt, a, b, -1);
220
281
  }
282
+ // A square of tarmac at every route point. Two straight sectors meeting at a right angle leave
283
+ // the corner itself unpaved, and the frame showed grass biting into the racing line exactly
284
+ // where the driver is turning.
285
+ for (const point of ROUTE_POINTS) {
286
+ const patch = new Mesh(new BoxGeometry(TRACK_WIDTH, 0.28, TRACK_WIDTH), materials.road);
287
+ patch.position.set(point.x, -0.14, point.z);
288
+ patch.receiveShadow = true;
289
+ ctx.add(patch);
290
+ new RigidBody3D({
291
+ collisionLayer: 2,
292
+ collisionMask: 1,
293
+ object: patch,
294
+ physics: ctx.physics,
295
+ shape: CollisionShape3D.box(TRACK_WIDTH, 0.28, TRACK_WIDTH),
296
+ type: "fixed",
297
+ });
298
+ roadMeshes.push(patch);
299
+ }
300
+
301
+ // The outside corner of the kerbing, filling the right angle the two inset runs leave open.
302
+ for (const point of ROUTE_POINTS) {
303
+ for (const [dx, dz] of [
304
+ [1, 1],
305
+ [1, -1],
306
+ [-1, 1],
307
+ [-1, -1],
308
+ ] as const) {
309
+ curbs.place({
310
+ position: [
311
+ point.x + dx * (TRACK_WIDTH / 2 + 0.28),
312
+ 0.08,
313
+ point.z + dz * (TRACK_WIDTH / 2 + 0.28),
314
+ ],
315
+ rotation: [0, 0, 0],
316
+ scale: [0.5, 0.18, 0.5],
317
+ });
318
+ }
319
+ }
320
+
221
321
  const curbMesh = curbs.build({ castShadow: true, name: "track-curbs" });
222
322
  if (curbMesh !== undefined) ctx.add(curbMesh);
323
+ const curbAltMesh = curbsAlt.build({ castShadow: true, name: "track-curbs-alt" });
324
+ if (curbAltMesh !== undefined) ctx.add(curbAltMesh);
223
325
 
224
326
  const gates = [
225
327
  gate(ctx, "mid", new Vector3(18, 0, 0), new Vector3(0, 0, 1), TRACK_WIDTH),
226
328
  gate(ctx, "finish", new Vector3(10, 0, -18), new Vector3(1, 0, 0), TRACK_WIDTH),
227
329
  ];
228
330
  const pad = boostPad(ctx, new Vector3(14, 0, -18), materials);
229
- // The five corner markers stay ordinary meshes on purpose: a batch is worth its two extra lines
230
- // when the count is unknown or large, and five is neither.
231
- for (const [index, point] of ROUTE_POINTS.entries()) {
232
- const marker = new Mesh(
233
- new BoxGeometry(0.2, 1.2, 0.2),
234
- new MeshStandardMaterial({
235
- color: new Color(index % 2 === 0 ? palette.accent : palette.skyLow),
236
- }),
237
- );
238
- marker.position.set(point.x, 0.6, point.z);
239
- ctx.add(marker);
240
- }
331
+ dressCircuit(ctx, materials);
241
332
  return { boost: pad.boost, boostArea: pad.area, gates, roadMeshes, route: RACING_LINE };
242
333
  }
334
+
335
+ /**
336
+ * Everything beside the road.
337
+ *
338
+ * This used to be five thin coloured posts at the route corners, and the first frame showed why
339
+ * that is not enough: past the kerbs the world was one unbroken green plane to the horizon, so a
340
+ * corner arrived with nothing to judge it against and the circuit had no sense of place. Stands,
341
+ * trees, tyre walls and hoardings cost one function and give the driver landmarks.
342
+ *
343
+ * Delete a line here and that piece of furniture is gone; nothing else depends on it.
344
+ */
345
+ function dressCircuit(ctx: TrackCtx, materials: ReturnType<typeof createMaterials>): void {
346
+ // Grass run-off inside the kerbs, a shade drier than the outfield, so the two read as two
347
+ // surfaces rather than one flat colour.
348
+ const apron = new Mesh(new BoxGeometry(52, 0.16, 52), materials.runoff);
349
+ apron.position.y = -0.5;
350
+ apron.receiveShadow = true;
351
+ ctx.add(apron);
352
+
353
+ // Grandstands, set back past the hoardings. Placed nearer the road they climbed into the chase
354
+ // camera and hid the corner the driver was aiming at.
355
+ const crowd = new InstancedBatch({
356
+ geometry: new CapsuleGeometry(0.16, 0.24, 1, 4),
357
+ material: materials.crowd,
358
+ });
359
+ for (const [x, z, turn, seats] of [
360
+ [2, -34, 0, materials.kerbAlt],
361
+ [-2, 34, Math.PI, materials.hoardingBoard],
362
+ ] as const) {
363
+ const stand = grandstand(materials.structure, seats);
364
+ stand.group.position.set(x, 0, z);
365
+ stand.group.rotation.y = turn;
366
+ ctx.add(stand.group);
367
+ for (const [seatX, seatY, seatZ] of stand.crowd) {
368
+ const turned = new Vector3(seatX, seatY, seatZ).applyAxisAngle(UP, turn);
369
+ crowd.place({ position: [x + turned.x, turned.y, z + turned.z], scale: [1, 1, 1] });
370
+ }
371
+ }
372
+ const crowdMesh = crowd.build({ castShadow: true, name: "grandstand-crowd" });
373
+ if (crowdMesh !== undefined) ctx.add(crowdMesh);
374
+
375
+ // Tyre walls on the outside of all four corners, five stacks to an arc.
376
+ const tyres = new InstancedBatch({
377
+ geometry: tyreStackGeometry(3),
378
+ material: materials.tire,
379
+ });
380
+ for (const [cornerX, cornerZ] of [
381
+ [24.5, -24.5],
382
+ [24.5, 24.5],
383
+ [-24.5, 24.5],
384
+ [-24.5, -24.5],
385
+ ] as const) {
386
+ const radius = Math.hypot(cornerX, cornerZ);
387
+ for (let index = 0; index < 5; index += 1) {
388
+ const angle = Math.atan2(cornerZ, cornerX) + (index - 2) * 0.09;
389
+ tyres.place({
390
+ position: [Math.cos(angle) * radius, 0, Math.sin(angle) * radius],
391
+ rotation: [0, angle, 0],
392
+ scale: [1, 1, 1],
393
+ });
394
+ }
395
+ }
396
+ const tyreMesh = tyres.build({ castShadow: true, name: "tyre-walls" });
397
+ if (tyreMesh !== undefined) ctx.add(tyreMesh);
398
+
399
+ // Sponsor hoardings around all four straights, turned to **face** the road. Left unrotated they
400
+ // presented their broad faces down the racing line, which from the chase camera looked like
401
+ // blue plates hanging in the air.
402
+ const board = hoardingGeometry(5);
403
+ const frames = new InstancedBatch({ geometry: board.frame, material: materials.structure });
404
+ const boardsA = new InstancedBatch({ geometry: board.board, material: materials.hoardingBoard });
405
+ const boardsB = new InstancedBatch({ geometry: board.board, material: materials.kerbAlt });
406
+ const OUTSIDE = 22.8;
407
+ for (let index = 0; index < 7; index += 1) {
408
+ const along = -18 + index * 6;
409
+ for (const side of [-1, 1] as const) {
410
+ for (const [position, turn, batch] of [
411
+ [
412
+ [along, 0, side * OUTSIDE] as const,
413
+ side < 0 ? Math.PI / 2 : -Math.PI / 2,
414
+ side < 0 ? boardsA : boardsB,
415
+ ],
416
+ [[side * OUTSIDE, 0, along] as const, side < 0 ? Math.PI : 0, side < 0 ? boardsB : boardsA],
417
+ ] as const) {
418
+ const placement = {
419
+ position: [position[0], position[1], position[2]] as [number, number, number],
420
+ rotation: [0, turn, 0] as [number, number, number],
421
+ scale: [1, 1, 1] as [number, number, number],
422
+ };
423
+ frames.place(placement);
424
+ batch.place(placement);
425
+ }
426
+ }
427
+ }
428
+ for (const [batch, name] of [
429
+ [frames, "hoarding-frames"],
430
+ [boardsA, "hoarding-boards-a"],
431
+ [boardsB, "hoarding-boards-b"],
432
+ ] as const) {
433
+ const mesh = batch.build({ castShadow: true, name });
434
+ if (mesh !== undefined) ctx.add(mesh);
435
+ }
436
+
437
+ // A treeline outside the circuit. Deterministic placement — a seeded jitter, not Math.random —
438
+ // so two captures of the same build frame the same world.
439
+ const pine = treeGeometry();
440
+ const trunks = new InstancedBatch({ geometry: pine.trunk, material: materials.trunk });
441
+ const canopies = new InstancedBatch({ geometry: pine.canopy, material: materials.canopy });
442
+ let seed = 6132;
443
+ const jitter = (): number => {
444
+ seed = (seed * 1103515245 + 12345) & 0x7fffffff;
445
+ return seed / 0x7fffffff;
446
+ };
447
+ for (let index = 0; index < 44; index += 1) {
448
+ const angle = (index / 44) * Math.PI * 2 + jitter() * 0.1;
449
+ const distance = 42 + jitter() * 22;
450
+ const scale = 1.4 + jitter() * 1.5;
451
+ const placement = {
452
+ position: [Math.cos(angle) * distance, 0, Math.sin(angle) * distance] as [
453
+ number,
454
+ number,
455
+ number,
456
+ ],
457
+ rotation: [0, jitter() * Math.PI, 0] as [number, number, number],
458
+ scale: [scale, scale, scale] as [number, number, number],
459
+ };
460
+ trunks.place(placement);
461
+ canopies.place(placement);
462
+ }
463
+ for (const [batch, name] of [
464
+ [trunks, "treeline-trunks"],
465
+ [canopies, "treeline-canopies"],
466
+ ] as const) {
467
+ const mesh = batch.build({ castShadow: true, name });
468
+ if (mesh !== undefined) ctx.add(mesh);
469
+ }
470
+
471
+ // Distant hills: three low domes past the treeline to give the horizon a shape.
472
+ for (const [x, z, radius] of [
473
+ [-70, -110, 46],
474
+ [90, -120, 58],
475
+ [130, 60, 40],
476
+ ] as const) {
477
+ const hill = new Mesh(new SphereGeometry(radius, 12, 6), materials.distant);
478
+ hill.position.set(x, -radius * 0.72, z);
479
+ ctx.add(hill);
480
+ }
481
+ }
@@ -19,6 +19,7 @@ const config: IThreeNativeConfig = {
19
19
  title: "__PROJECT_NAME__",
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__ runner
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 track, the runner, the obstacles, the dust, the HUD and the
8
+ 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. No navmesh is imported, so this kit runs on every
18
+ target; `@threenative/physics/navigation` would make it web and desktop only. `GPUParticles3D`
19
+ is WebGPU-only and the dust depends on it.
20
+ 4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and
21
+ `npx @threenative/playtest doctor`; missing observations are not zero.
22
+ 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.
23
+
24
+ ## When the framework blocks you, write plain Three.js
25
+
26
+ When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
27
+ piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
28
+ bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
29
+ (API, expectation, result, replacement); never stall the game.
30
+
31
+ ## Workflow skills
32
+
33
+ - `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
34
+ - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search.
35
+ - `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
36
+ - `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
37
+ - `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
38
+ - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets.
39
+ - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
40
+ - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
41
+ - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro.
42
+
43
+ ## Commands and map
44
+
45
+ ```sh
46
+ pnpm dev
47
+ pnpm build
48
+ pnpm build --target desktop
49
+ pnpm test
50
+ pnpm typecheck
51
+ ```
52
+
53
+ `src/track.ts` is a ring of six chunks **moved and rewritten**, never rebuilt: each chunk's
54
+ obstacle `InstancedMesh` is built once at a fixed slot count and its matrices rewritten on
55
+ recycle. The obstacle *bodies* are the exception — disposed and recreated, because `RigidBody3D`
56
+ cannot reposition a fixed body. The runner is not a rigid body — a lane snap and a jump
57
+ arc feel worse in a solver — but the collision is real: `src/entities/Runner.ts` carries an
58
+ `Area3D` masked to the obstacle layer and listens for `bodyEntered`, so a hit is an overlap the
59
+ engine reports rather than a hand-maintained distance check. Gravity is zero in `src/game.ts` on purpose;
60
+ nothing falls. The track comes from `ctx.random`, so `defineGame({ seed })` **is** the level.
61
+ Register entities with `ctx.entities`; the React HUD reads `GameState`, never an entity. Keep `playtests/survives.playtest.json` as smoke proof, and `streams` honest
62
+ when chunk recycling changes.
63
+
64
+ ## Portable authoring contracts
65
+
66
+ 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.
67
+
68
+ 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.
69
+ Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable. Generated conventions call `GroundSnap` for floor contact and `normaliseToMetres` for authored model scale.
70
+ The camera reads the runner **after** the step through `afterPhysics` — in the frame function that
71
+ is 0.4 m of lag at 26 m/s. `CameraShake` returns an offset; `src/render/camera.ts` adds it.
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`.