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,4 +1,5 @@
1
- // Generated for you. This file owns the sailing kit's surface decisions.
1
+ // Generated for you. This file owns the sailing kit's surface decisions, and nothing in
2
+ // `props.ts` names a colour: change the ship's timber, canvas or cordage entirely from here.
2
3
  import { DoubleSide, MeshBasicMaterial, MeshStandardMaterial } from "three";
3
4
  import { palette } from "./palette.js";
4
5
 
@@ -9,20 +10,35 @@ export interface ISailingMaterials {
9
10
  readonly sail: MeshStandardMaterial;
10
11
  readonly island: MeshStandardMaterial;
11
12
  readonly horizon: MeshBasicMaterial;
13
+ /** Masts, yards, bowsprit, palm trunks. */
14
+ readonly spar: MeshStandardMaterial;
15
+ /** Standing rigging: thinner and darker than the spars, or it reads as more mast. */
16
+ readonly cordage: MeshStandardMaterial;
17
+ /** Rails, wale strakes, pennant — the ship's one saturated accent. */
18
+ readonly trim: MeshStandardMaterial;
19
+ readonly sand: MeshStandardMaterial;
20
+ readonly foliage: MeshStandardMaterial;
12
21
  }
13
22
 
14
23
  export function createMaterials(): ISailingMaterials {
15
24
  return {
16
- deck: new MeshStandardMaterial({ color: palette.player, roughness: 0.5, metalness: 0.15 }),
17
- hull: new MeshStandardMaterial({ color: 0x7f403a, roughness: 0.62, metalness: 0.12 }),
18
- buoy: new MeshStandardMaterial({ color: palette.accent, roughness: 0.35, metalness: 0.1 }),
25
+ // Holystoned deck: pale, and clearly not the hull. One timber colour for both made the ship
26
+ // read as a single carved lump.
27
+ deck: new MeshStandardMaterial({ color: 0xd9b98a, roughness: 0.68, metalness: 0 }),
28
+ hull: new MeshStandardMaterial({ color: 0x8a5a3a, roughness: 0.72, metalness: 0.03 }),
29
+ buoy: new MeshStandardMaterial({ color: palette.accent, roughness: 0.4, metalness: 0.08 }),
19
30
  sail: new MeshStandardMaterial({
20
- color: 0xf4eee0,
31
+ color: 0xf2e7d2,
21
32
  metalness: 0,
22
- roughness: 0.92,
33
+ roughness: 0.95,
23
34
  side: DoubleSide,
24
35
  }),
25
- island: new MeshStandardMaterial({ color: palette.floor, roughness: 0.95, metalness: 0 }),
26
- horizon: new MeshBasicMaterial({ color: palette.shadow }),
36
+ island: new MeshStandardMaterial({ color: 0x4c6b45, roughness: 0.96, metalness: 0 }),
37
+ horizon: new MeshBasicMaterial({ color: palette.skyLow }),
38
+ spar: new MeshStandardMaterial({ color: 0x8a6238, roughness: 0.72, metalness: 0 }),
39
+ cordage: new MeshStandardMaterial({ color: 0x3b2c22, roughness: 0.94, metalness: 0 }),
40
+ trim: new MeshStandardMaterial({ color: 0xa33f2c, roughness: 0.6, metalness: 0.05 }),
41
+ sand: new MeshStandardMaterial({ color: 0xe4d3a6, roughness: 0.98, metalness: 0 }),
42
+ foliage: new MeshStandardMaterial({ color: 0x3f7a48, roughness: 0.94, metalness: 0 }),
27
43
  };
28
44
  }
@@ -0,0 +1,179 @@
1
+ // Generated for you. The sea's tuning and its entire look live in this file, and ThreeNative does
2
+ // not read it. `SpectralOcean` runs the simulation and draws nothing: the mesh, the material, the
3
+ // colours, the foam line and the tessellation are all decisions this game makes here.
4
+ //
5
+ // This replaces a two-wave `WaveField` under a `MeshBasicNodeMaterial`. Both halves of that were
6
+ // the problem. Two analytic waves plus one domain warp is a corrugated sheet — it repeats visibly
7
+ // within a boat length, and no amount of colour work hides a surface with two frequencies in it.
8
+ // And a *basic* material takes no lights at all, so the sea could not respond to the sun the rest
9
+ // of the scene is lit by: its brightness had to be hand-computed with a `pow(dot(n, sun), 30)`
10
+ // term standing in for a specular highlight. Water is one of the few surfaces where the specular
11
+ // *is* the material, so that read as plastic.
12
+ //
13
+ // A spectral ocean is cascaded wave spectra inverse-transformed on the GPU every frame, which is
14
+ // what real water is, and a standard node material puts it back under the scene's own lights.
15
+ import { type ISpectralOceanOptions, SpectralOcean } from "@threenative/core";
16
+ import { Mesh, PlaneGeometry } from "three";
17
+ import {
18
+ color,
19
+ float,
20
+ mix,
21
+ positionLocal,
22
+ positionWorld,
23
+ smoothstep,
24
+ transformNormalToView,
25
+ vec3,
26
+ } from "three/tsl";
27
+ import type { Node } from "three/webgpu";
28
+ import { MeshStandardNodeMaterial } from "three/webgpu";
29
+ import { palette } from "./palette.js";
30
+
31
+ /**
32
+ * The sea state. Every number is this game's.
33
+ *
34
+ * `windSpeed` and `amplitude` are the two to reach for: wind sets which wavelengths carry energy,
35
+ * amplitude scales the whole spectrum. `choppiness` above zero displaces horizontally as well as
36
+ * vertically, which is what sharpens a crest into something a hull can be thrown by.
37
+ */
38
+ export const SEA = {
39
+ amplitude: 0.0082,
40
+ // Largest patch first, and the bands do not overlap. One cascade is a toy — the join between
41
+ // bands is where a spectral ocean visibly fails, so there is nothing to look at until there are
42
+ // two.
43
+ cascades: [{ patchSize: 190 }, { patchSize: 37 }],
44
+ choppiness: 1.2,
45
+ directionality: 2.6,
46
+ gravity: 9.81,
47
+ // The ship reads this field on the CPU for its buoyancy and its attitude, so the copy has to
48
+ // land often enough — and be fine enough — to steer by.
49
+ //
50
+ // 32 samples across the largest patch is one height every six metres, which is coarser than the
51
+ // waves themselves: the hull then sat at a smoothed mean sea level while the drawn surface moved
52
+ // three metres either side of it, so the ship hung in the air over its own troughs and pitched
53
+ // on differences between samples that were nowhere near it. 64 halves that spacing, and the
54
+ // calmer sea state below closes the rest of the gap. This is the cost of a spectral ocean over
55
+ // an analytic one, and it is worth paying — but it has to be paid.
56
+ readbackEveryFrames: 3,
57
+ readbackResolution: 32,
58
+ resolution: 128,
59
+ seed: 20_260_906,
60
+ smallWaveCutoff: 0.32,
61
+ windDirection: 0.55,
62
+ windSpeed: 10.5,
63
+ } satisfies ISpectralOceanOptions;
64
+
65
+ /** The drawn surface's edge length in metres, and how finely it is tessellated. */
66
+ export const SURFACE = { segments: 160, size: 300 } as const;
67
+
68
+ /** Crest foam. Near-white, and not a seventh palette role: the sea's look is owned here. */
69
+ const FOAM = 0xe9f4f6;
70
+
71
+ export function createOcean(): SpectralOcean {
72
+ return new SpectralOcean(SEA);
73
+ }
74
+
75
+ /**
76
+ * Read one cascade's displacement at a world position, **bilinearly**.
77
+ *
78
+ * Nearest-texel sampling is the obvious way to write this and it is visibly wrong here. The mesh
79
+ * carries one vertex per 1.6 m while the fine cascade's texel is 0.29 m, so every vertex grabbed a
80
+ * different texel of a field it was far too coarse to resolve — and the normal, being a difference
81
+ * of two of those, came out piecewise-constant. The frame showed the sun's reflection broken into
82
+ * hard axis-aligned white rectangles, which is a sampling artefact and reads as a bug in the water.
83
+ *
84
+ * The two `mod`s are not redundant: the first is still negative for a vertex left of the origin,
85
+ * and a negative index reads whatever happens to sit behind the buffer.
86
+ */
87
+ function cascadeAt(
88
+ ocean: SpectralOcean,
89
+ index: number,
90
+ x: Node<"float">,
91
+ z: Node<"float">,
92
+ ): Node<"vec4"> {
93
+ const grid = float(ocean.resolution);
94
+ const patch = float(ocean.cascadePatchSize(index));
95
+ const buffer = ocean.cascadeDisplacement(index);
96
+ const u = x.div(patch).mul(grid);
97
+ const v = z.div(patch).mul(grid);
98
+ const u0 = u.floor();
99
+ const v0 = v.floor();
100
+ const wrap = (value: Node<"float">): Node<"float"> => value.mod(grid).add(grid).mod(grid);
101
+ const read = (cx: Node<"float">, cz: Node<"float">): Node<"vec4"> =>
102
+ buffer.element(wrap(cz).mul(grid).add(wrap(cx)).toUint()) as Node<"vec4">;
103
+ const near = mix(read(u0, v0), read(u0.add(1), v0), u.sub(u0));
104
+ const far = mix(read(u0, v0.add(1)), read(u0.add(1), v0.add(1)), u.sub(u0));
105
+ return mix(near, far, v.sub(v0)) as Node<"vec4">;
106
+ }
107
+
108
+ /** Summed displacement of both cascades at a world position. */
109
+ function displacementAt(ocean: SpectralOcean, x: Node<"float">, z: Node<"float">): Node<"vec3"> {
110
+ const broad = cascadeAt(ocean, 0, x, z);
111
+ const fine = cascadeAt(ocean, 1, x, z);
112
+ return vec3(broad.x.add(fine.x), broad.y.add(fine.y), broad.z.add(fine.z));
113
+ }
114
+
115
+ /**
116
+ * The sea surface: displaced by the simulation, and lit by the scene.
117
+ *
118
+ * The vertex stage reads the cascade buffers directly, so what is drawn is the same field the
119
+ * height query is copied from. If the two disagreed the ship would ride water nothing renders and
120
+ * every assertion in this template would still be green.
121
+ */
122
+ export function createWaterMesh(ocean: SpectralOcean): Mesh {
123
+ const geometry = new PlaneGeometry(
124
+ SURFACE.size,
125
+ SURFACE.size,
126
+ SURFACE.segments,
127
+ SURFACE.segments,
128
+ );
129
+ geometry.rotateX(-Math.PI / 2);
130
+
131
+ // Standard, not basic. This is the whole reason the sea now has a sun on it rather than a
132
+ // hand-rolled `pow()` blob: a lit material gets the scene's key light, its hemisphere fill and
133
+ // its specular response for free, and gets them consistent with the hull floating on it.
134
+ const material = new MeshStandardNodeMaterial({
135
+ metalness: 0.02,
136
+ // Not glass. At 0.08 the key light landed as one blown white disc on the swell in front of the
137
+ // camera; water this side of a dead calm scatters enough to spread that into a glitter path.
138
+ roughness: 0.29,
139
+ });
140
+
141
+ const offset = displacementAt(ocean, positionLocal.x, positionLocal.z);
142
+ material.positionNode = positionLocal.add(offset);
143
+
144
+ // Normals by central difference. Without this the surface is lit by the flat plane's normals —
145
+ // every vertex pointing straight up — and a perfectly simulated ocean shades like a sheet of
146
+ // paper.
147
+ //
148
+ // The step is the mesh's own quad size, not a texel. Differencing finer than the mesh can
149
+ // represent measures detail that is never drawn and turns the highlight into noise.
150
+ const step = float(SURFACE.size / SURFACE.segments);
151
+ const east = displacementAt(ocean, positionLocal.x.add(step), positionLocal.z);
152
+ const west = displacementAt(ocean, positionLocal.x.sub(step), positionLocal.z);
153
+ const north = displacementAt(ocean, positionLocal.x, positionLocal.z.add(step));
154
+ const south = displacementAt(ocean, positionLocal.x, positionLocal.z.sub(step));
155
+ const twice = step.mul(2);
156
+ // `transformNormalToView`, not the raw vector. `normalNode` overrides `normalView`, so a
157
+ // material handed a world-space normal lights the surface in the camera's frame instead of the
158
+ // world's: the sun's reflection stopped being a place on the sea and became a column of glare
159
+ // pointing at the camera, sliding across the water as the ship turned.
160
+ material.normalNode = transformNormalToView(
161
+ vec3(west.y.sub(east.y).div(twice), float(1), south.y.sub(north.y).div(twice)).normalize(),
162
+ );
163
+
164
+ // Colour by height: deep in the troughs, lit water on the shoulders, foam on the crests. The
165
+ // band is narrower than the wave amplitude on purpose, so the tops read as foam-lit rather than
166
+ // as a gentle gradient.
167
+ const shade = smoothstep(float(-2.4), float(1.8), positionWorld.y);
168
+ const water = mix(color(palette.floor), color(palette.accent), shade);
169
+ const crest = smoothstep(float(1.6), float(3), positionWorld.y);
170
+ material.colorNode = mix(water, color(FOAM), crest);
171
+ // Foam is not a mirror. Roughening the crests is what stops them reading as chrome.
172
+ material.roughnessNode = mix(float(0.29), float(0.82), crest);
173
+
174
+ const mesh = new Mesh(geometry, material);
175
+ mesh.receiveShadow = true;
176
+ mesh.frustumCulled = false;
177
+ mesh.name = "sea-surface";
178
+ return mesh;
179
+ }
@@ -1,24 +1,17 @@
1
1
  // Generated for you. These six roles are the sailing kit's editable visual vocabulary.
2
+ // Open water at mid-morning. The values these replace put a pale cyan at the top of the sky dome
3
+ // *and* used a near-cyan accent for the wave crests, so sea and sky met at the same value and the
4
+ // frame photographed as one flat sheet with no horizon in it. Sea and sky have to disagree.
2
5
  export const palette = {
3
- skyHigh: 0x75c9d8,
4
- skyLow: 0x061b2b,
5
- floor: 0x12384a,
6
- player: 0xffd27a,
7
- accent: 0x6fe8ff,
8
- shadow: 0x0b2a3b,
6
+ /** Zenith. Properly blue, so the dome has somewhere to fall from. */
7
+ skyHigh: 0x2f6fae,
8
+ /** Horizon haze, and the fog colour. Where sea meets sky, this is the value. */
9
+ skyLow: 0x9dc2d2,
10
+ /** Deep water in the troughs. */
11
+ floor: 0x0a2c3e,
12
+ /** The sun's own colour, used for the glint on the water. */
13
+ player: 0xffe6b8,
14
+ /** Crest water: green-lit shallow, not cyan. */
15
+ accent: 0x2b8496,
16
+ shadow: 0x143243,
9
17
  } as const;
10
-
11
- /** The kit's readable wave vocabulary; tune the sea here without touching the ship or rules. */
12
- export const SAILING_WAVES = [
13
- { amplitude: 0.18, direction: [1, 0.18] as const, speed: 0.9, wavelength: 7.5 },
14
- { amplitude: 0.09, direction: [-0.35, 1] as const, speed: 0.55, wavelength: 3.2, phase: 1.4 },
15
- ] as const;
16
-
17
- export const SAILING_DOMAIN_WARP = [
18
- {
19
- amplitude: 0.18,
20
- direction: [0.65, -0.35] as const,
21
- speed: 0.2,
22
- wavelength: 11,
23
- },
24
- ] as const;
@@ -1,33 +1,34 @@
1
- // Generated for you: ordinary Three.js; the stage order and fallback report are game-owned.
1
+ // Generated for you: ordinary Three.js; ThreeNative does not read this file.
2
+ //
3
+ // This file wires two things together and decides nothing itself. `quality.ts`, in this folder,
4
+ // owns which stages run at which tier and records what each one measured. `WorldEnvironment`,
5
+ // also in this folder, builds them and prints `TN_WORLD_ENVIRONMENT` naming every stage as
6
+ // applied or refused **with a reason**, so a stage that silently no-op'd is never mistaken for
7
+ // one you turned off.
8
+ //
9
+ // To make the game cheaper or prettier everywhere, edit `quality.ts`. To force one tier for one
10
+ // run — a desktop that is dropping frames, a capture you want to compare — pass it:
11
+ // `setupPost(renderer, scene, camera, { tier: "low" })`. Overriding does not silence the report:
12
+ // `TN_QUALITY_TIER` names the tier that ran either way.
2
13
  import type { Camera, DirectionalLight, Scene } from "three";
14
+ import { type QualityTier, qualityPreset, resolveQualityTier } from "./quality.js";
3
15
  import type { OutputRenderer } from "./worldEnvironment.js";
4
16
  import { WorldEnvironment } from "./worldEnvironment.js";
5
17
 
6
- const desktopPreset = {
7
- bloomEnabled: true,
8
- bloomStrength: 0.38,
9
- denoiseEnabled: false,
10
- exposure: 1.12,
11
- ssgiEnabled: false,
12
- ssrEnabled: false,
13
- tonemapMode: "aces",
14
- } as const;
15
-
16
- const mobilePreset = {
17
- bloomEnabled: true,
18
- bloomStrength: 0.28,
19
- exposure: 1.12,
20
- ssgiEnabled: false,
21
- ssrEnabled: false,
22
- tonemapMode: "aces",
23
- } as const;
24
-
25
18
  export function setupPost(
26
19
  renderer: OutputRenderer,
27
20
  scene: Scene,
28
21
  camera: Camera,
29
- environment: { godraysLight?: DirectionalLight; mobile?: boolean } = {},
22
+ environment: {
23
+ godraysLight?: DirectionalLight;
24
+ mobile?: boolean;
25
+ /** Forces a tier, ignoring `mobile`. An unknown name throws rather than falling back. */
26
+ tier?: QualityTier;
27
+ } = {},
30
28
  ): void {
31
- const world = new WorldEnvironment(environment.mobile === true ? mobilePreset : desktopPreset);
29
+ const tier = resolveQualityTier({ mobile: environment.mobile, tier: environment.tier });
30
+ const source = environment.tier === undefined ? "platform" : "override";
31
+ console.info(`TN_QUALITY_TIER ${tier} mobile=${environment.mobile === true} source=${source}`);
32
+ const world = new WorldEnvironment(qualityPreset(tier));
32
33
  world.apply(renderer, scene, camera, { godraysLight: environment.godraysLight });
33
34
  }