create-threenative 0.2.3 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (447) hide show
  1. package/README.md +53 -2
  2. package/agent-docs/references/assertion-reference.md +173 -6
  3. package/agent-docs/references/capability-reference.md +1303 -99
  4. package/agent-docs/references/capture-the-frame.md +7 -0
  5. package/agent-docs/references/creating-creatures.md +215 -0
  6. package/agent-docs/references/ctx-cookbook.md +69 -0
  7. package/agent-docs/references/debug-surface.md +8 -3
  8. package/agent-docs/references/dream-loop.md +150 -0
  9. package/agent-docs/references/finding-assets.md +70 -2
  10. package/agent-docs/references/sculpt-from-a-reference.md +3 -2
  11. package/agent-docs/references/trace-a-slow-frame.md +99 -0
  12. package/agent-docs/references/visual-baseline.md +41 -0
  13. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
  14. package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
  15. package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
  16. package/agent-files/.agents/skills/threenative-builder/SKILL.md +1 -1
  17. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
  18. package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
  19. package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
  20. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
  21. package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
  22. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +1 -1
  23. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
  24. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
  25. package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
  26. package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
  27. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
  28. package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
  29. package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
  30. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
  31. package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
  32. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
  33. package/agent-files/scripts/reference.mjs +705 -0
  34. package/agent-files/scripts/visual-loop.mjs +382 -0
  35. package/capabilities.json +1881 -131
  36. package/dist/index.d.ts +39 -6
  37. package/dist/index.js +297 -32
  38. package/dist/threenative.js +822 -105
  39. package/package.json +30 -5
  40. package/template-assets/loading.ts +12 -2
  41. package/template-assets/patches/three@0.185.1.patch +249 -14
  42. package/template-assets/worldEnvironment.ts +758 -0
  43. package/templates/action-rpg/.codex/config.toml +4 -0
  44. package/templates/action-rpg/.cursor/mcp.json +32 -0
  45. package/templates/action-rpg/.gemini/settings.json +32 -0
  46. package/templates/action-rpg/.mcp.json +15 -3
  47. package/templates/action-rpg/.vscode/mcp.json +36 -0
  48. package/templates/action-rpg/.zed/settings.json +36 -0
  49. package/templates/action-rpg/AGENTS.md +69 -378
  50. package/templates/action-rpg/CLAUDE.md +69 -378
  51. package/templates/action-rpg/opencode.json +41 -0
  52. package/templates/action-rpg/package.json +7 -7
  53. package/templates/action-rpg/playtests/combat.playtest.json +9 -0
  54. package/templates/action-rpg/playtests/performance.playtest.json +24 -7
  55. package/templates/action-rpg/playtests/survives.playtest.json +27 -0
  56. package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
  57. package/templates/action-rpg/src/conventions.ts +35 -0
  58. package/templates/action-rpg/src/entities/Enemy.ts +2 -3
  59. package/templates/action-rpg/src/entities/Player.ts +20 -3
  60. package/templates/action-rpg/src/render/camera.ts +7 -2
  61. package/templates/action-rpg/src/render/lighting.ts +5 -3
  62. package/templates/action-rpg/src/render/loading.ts +12 -2
  63. package/templates/action-rpg/src/render/materials.ts +11 -0
  64. package/templates/action-rpg/src/render/palette.ts +10 -3
  65. package/templates/action-rpg/src/render/postprocessing.ts +21 -58
  66. package/templates/action-rpg/src/render/quality.ts +170 -0
  67. package/templates/action-rpg/src/render/shapes.ts +185 -26
  68. package/templates/action-rpg/src/render/touch-controls.ts +185 -0
  69. package/templates/action-rpg/src/render/vfx.ts +257 -0
  70. package/templates/action-rpg/src/render/worldEnvironment.ts +208 -33
  71. package/templates/action-rpg/src/scenes/Play.ts +43 -6
  72. package/templates/action-rpg/src/style.css +20 -0
  73. package/templates/action-rpg/threenative.config.ts +7 -0
  74. package/templates/defense/.codex/config.toml +4 -0
  75. package/templates/defense/.cursor/mcp.json +32 -0
  76. package/templates/defense/.gemini/settings.json +32 -0
  77. package/templates/defense/.mcp.json +15 -3
  78. package/templates/defense/.vscode/mcp.json +36 -0
  79. package/templates/defense/.zed/settings.json +36 -0
  80. package/templates/defense/AGENTS.md +62 -385
  81. package/templates/defense/CLAUDE.md +62 -385
  82. package/templates/defense/opencode.json +41 -0
  83. package/templates/defense/package.json +7 -7
  84. package/templates/defense/playtests/performance.playtest.json +24 -7
  85. package/templates/defense/playtests/pointer-placement.playtest.json +87 -20
  86. package/templates/defense/playtests/scan.playtest.json +1 -1
  87. package/templates/defense/playtests/survive.playtest.json +14 -0
  88. package/templates/defense/src/attackers/Attacker.ts +4 -4
  89. package/templates/defense/src/board/Route.ts +22 -8
  90. package/templates/defense/src/conventions.ts +18 -0
  91. package/templates/defense/src/entities/Player.ts +11 -3
  92. package/templates/defense/src/game.ts +2 -3
  93. package/templates/defense/src/physics.ts +9 -39
  94. package/templates/defense/src/placement/Buildable.ts +4 -4
  95. package/templates/defense/src/render/camera.ts +9 -3
  96. package/templates/defense/src/render/loading.ts +12 -2
  97. package/templates/defense/src/render/materials.ts +9 -0
  98. package/templates/defense/src/render/palette.ts +12 -5
  99. package/templates/defense/src/render/postprocessing.ts +21 -58
  100. package/templates/defense/src/render/quality.ts +170 -0
  101. package/templates/defense/src/render/shapes.ts +142 -23
  102. package/templates/defense/src/render/sky.ts +2 -2
  103. package/templates/defense/src/render/worldEnvironment.ts +208 -33
  104. package/templates/defense/src/scenes/Boot.ts +2 -2
  105. package/templates/defense/src/scenes/Defense.ts +13 -6
  106. package/templates/defense/src/style.css +20 -0
  107. package/templates/defense/src/towers/Tower.ts +11 -12
  108. package/templates/defense/src/towers/targeting.ts +1 -1
  109. package/templates/defense/src/ui/App.tsx +2 -2
  110. package/templates/defense/threenative.config.ts +7 -0
  111. package/templates/minimal/.codex/config.toml +4 -0
  112. package/templates/minimal/.cursor/mcp.json +32 -0
  113. package/templates/minimal/.gemini/settings.json +32 -0
  114. package/templates/minimal/.mcp.json +15 -3
  115. package/templates/minimal/.vscode/mcp.json +36 -0
  116. package/templates/minimal/.zed/settings.json +36 -0
  117. package/templates/minimal/AGENTS.md +76 -485
  118. package/templates/minimal/CLAUDE.md +76 -485
  119. package/templates/minimal/opencode.json +41 -0
  120. package/templates/minimal/package.json +6 -6
  121. package/templates/minimal/playtests/play.playtest.json +2 -1
  122. package/templates/minimal/playtests/survives.playtest.json +48 -4
  123. package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
  124. package/templates/minimal/src/conventions.ts +18 -0
  125. package/templates/minimal/src/entities/Player.ts +39 -6
  126. package/templates/minimal/src/main.ts +14 -4
  127. package/templates/minimal/src/render/materials.ts +7 -0
  128. package/templates/minimal/src/render/palette.ts +3 -3
  129. package/templates/minimal/src/render/postprocessing.ts +17 -56
  130. package/templates/minimal/src/render/quality.ts +162 -0
  131. package/templates/minimal/src/render/sky.ts +23 -9
  132. package/templates/minimal/src/render/touch-controls.ts +165 -0
  133. package/templates/minimal/src/render/worldEnvironment.ts +208 -33
  134. package/templates/minimal/src/scenes/Play.ts +47 -11
  135. package/templates/minimal/src/style.css +20 -0
  136. package/templates/minimal/threenative.config.ts +7 -0
  137. package/templates/platformer/.codex/config.toml +4 -0
  138. package/templates/platformer/.cursor/mcp.json +32 -0
  139. package/templates/platformer/.gemini/settings.json +32 -0
  140. package/templates/platformer/.mcp.json +15 -3
  141. package/templates/platformer/.vscode/mcp.json +36 -0
  142. package/templates/platformer/.zed/settings.json +36 -0
  143. package/templates/platformer/AGENTS.md +70 -430
  144. package/templates/platformer/CLAUDE.md +70 -430
  145. package/templates/platformer/opencode.json +41 -0
  146. package/templates/platformer/package.json +7 -7
  147. package/templates/platformer/playtests/oneway.playtest.json +29 -2
  148. package/templates/platformer/playtests/performance.playtest.json +2 -1
  149. package/templates/platformer/playtests/survives.playtest.json +31 -0
  150. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +3 -0
  151. package/templates/platformer/playtests/touch-controls-web.playtest.json +15 -4
  152. package/templates/platformer/src/conventions.ts +18 -0
  153. package/templates/platformer/src/entities/Character.ts +63 -1
  154. package/templates/platformer/src/game.ts +3 -1
  155. package/templates/platformer/src/level/Platform.ts +13 -1
  156. package/templates/platformer/src/render/lighting.ts +7 -4
  157. package/templates/platformer/src/render/loading.ts +12 -2
  158. package/templates/platformer/src/render/palette.ts +4 -1
  159. package/templates/platformer/src/render/postprocessing.ts +32 -57
  160. package/templates/platformer/src/render/quality.ts +170 -0
  161. package/templates/platformer/src/render/worldEnvironment.ts +208 -33
  162. package/templates/platformer/src/scenes/Level.ts +52 -12
  163. package/templates/platformer/src/style.css +20 -0
  164. package/templates/platformer/threenative.config.ts +7 -0
  165. package/templates/puzzle/.codex/config.toml +19 -0
  166. package/templates/puzzle/.cursor/mcp.json +32 -0
  167. package/templates/puzzle/.gemini/settings.json +32 -0
  168. package/templates/puzzle/.mcp.json +32 -0
  169. package/templates/puzzle/.vscode/mcp.json +36 -0
  170. package/templates/puzzle/.zed/settings.json +36 -0
  171. package/templates/puzzle/AGENTS.md +96 -0
  172. package/templates/puzzle/CLAUDE.md +98 -0
  173. package/templates/puzzle/README.md +43 -0
  174. package/templates/puzzle/index.html +12 -0
  175. package/templates/puzzle/kit.json +7 -0
  176. package/templates/puzzle/opencode.json +41 -0
  177. package/templates/puzzle/package.json +50 -0
  178. package/templates/puzzle/playtests/carry.playtest.json +71 -0
  179. package/templates/puzzle/playtests/performance.playtest.json +23 -0
  180. package/templates/puzzle/playtests/survives.playtest.json +51 -0
  181. package/templates/puzzle/playtests/swing.playtest.json +38 -0
  182. package/templates/puzzle/public/favicon.svg +5 -0
  183. package/templates/puzzle/src/conventions.ts +25 -0
  184. package/templates/puzzle/src/entities/Ball.ts +70 -0
  185. package/templates/puzzle/src/entities/Crate.ts +76 -0
  186. package/templates/puzzle/src/entities/Gripper.ts +69 -0
  187. package/templates/puzzle/src/entities/Pendulum.ts +89 -0
  188. package/templates/puzzle/src/game.ts +48 -0
  189. package/templates/puzzle/src/main.ts +15 -0
  190. package/templates/puzzle/src/physics.ts +19 -0
  191. package/templates/puzzle/src/render/camera.ts +37 -0
  192. package/templates/puzzle/src/render/lighting.ts +55 -0
  193. package/templates/puzzle/src/render/loading.ts +325 -0
  194. package/templates/puzzle/src/render/materials.ts +28 -0
  195. package/templates/puzzle/src/render/palette.ts +31 -0
  196. package/templates/puzzle/src/render/postprocessing.ts +34 -0
  197. package/templates/puzzle/src/render/quality.ts +170 -0
  198. package/templates/puzzle/src/render/shapes.ts +134 -0
  199. package/templates/puzzle/src/render/sky.ts +16 -0
  200. package/templates/puzzle/src/render/touch-controls.ts +185 -0
  201. package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
  202. package/templates/puzzle/src/room.ts +83 -0
  203. package/templates/puzzle/src/scenes/Boot.ts +12 -0
  204. package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
  205. package/templates/puzzle/src/state.ts +30 -0
  206. package/templates/puzzle/src/style.css +96 -0
  207. package/templates/puzzle/src/ui/App.tsx +22 -0
  208. package/templates/puzzle/src/ui/GameUi.tsx +20 -0
  209. package/templates/puzzle/src/ui/Hud.tsx +57 -0
  210. package/templates/puzzle/src/ui/Menu.tsx +7 -0
  211. package/templates/puzzle/src/ui/main.tsx +14 -0
  212. package/templates/puzzle/tailwind.config.ts +1 -0
  213. package/templates/puzzle/threenative.config.ts +49 -0
  214. package/templates/puzzle/tsconfig.json +17 -0
  215. package/templates/puzzle/vite.config.ts +38 -0
  216. package/templates/racing/.codex/config.toml +4 -0
  217. package/templates/racing/.cursor/mcp.json +32 -0
  218. package/templates/racing/.gemini/settings.json +32 -0
  219. package/templates/racing/.mcp.json +15 -3
  220. package/templates/racing/.vscode/mcp.json +36 -0
  221. package/templates/racing/.zed/settings.json +36 -0
  222. package/templates/racing/AGENTS.md +63 -379
  223. package/templates/racing/CLAUDE.md +63 -379
  224. package/templates/racing/native-playtests/survives.playtest.json +43 -0
  225. package/templates/racing/opencode.json +41 -0
  226. package/templates/racing/package.json +8 -7
  227. package/templates/racing/playtests/performance.playtest.json +24 -7
  228. package/templates/racing/playtests/survives.playtest.json +36 -4
  229. package/templates/racing/playtests/touch-controls.playtest.json +41 -0
  230. package/templates/racing/src/conventions.ts +6 -0
  231. package/templates/racing/src/entities/RacingCar.ts +16 -4
  232. package/templates/racing/src/entities/Rival.ts +5 -2
  233. package/templates/racing/src/render/camera.ts +7 -4
  234. package/templates/racing/src/render/lighting.ts +22 -13
  235. package/templates/racing/src/render/loading.ts +12 -2
  236. package/templates/racing/src/render/materials.ts +54 -4
  237. package/templates/racing/src/render/palette.ts +23 -6
  238. package/templates/racing/src/render/postprocessing.ts +21 -58
  239. package/templates/racing/src/render/quality.ts +170 -0
  240. package/templates/racing/src/render/shapes.ts +537 -26
  241. package/templates/racing/src/render/sky.ts +5 -2
  242. package/templates/racing/src/render/touch-controls.ts +185 -0
  243. package/templates/racing/src/render/worldEnvironment.ts +208 -33
  244. package/templates/racing/src/scenes/Race.ts +17 -2
  245. package/templates/racing/src/style.css +20 -0
  246. package/templates/racing/src/track/Track.ts +270 -31
  247. package/templates/racing/threenative.config.ts +7 -0
  248. package/templates/runner/.codex/config.toml +19 -0
  249. package/templates/runner/.cursor/mcp.json +32 -0
  250. package/templates/runner/.gemini/settings.json +32 -0
  251. package/templates/runner/.mcp.json +32 -0
  252. package/templates/runner/.vscode/mcp.json +36 -0
  253. package/templates/runner/.zed/settings.json +36 -0
  254. package/templates/runner/AGENTS.md +96 -0
  255. package/templates/runner/CLAUDE.md +98 -0
  256. package/templates/runner/README.md +43 -0
  257. package/templates/runner/index.html +12 -0
  258. package/templates/runner/kit.json +7 -0
  259. package/templates/runner/opencode.json +41 -0
  260. package/templates/runner/package.json +50 -0
  261. package/templates/runner/playtests/performance.playtest.json +23 -0
  262. package/templates/runner/playtests/streams.playtest.json +38 -0
  263. package/templates/runner/playtests/survives.playtest.json +51 -0
  264. package/templates/runner/public/favicon.svg +5 -0
  265. package/templates/runner/src/conventions.ts +24 -0
  266. package/templates/runner/src/entities/Runner.ts +135 -0
  267. package/templates/runner/src/game.ts +50 -0
  268. package/templates/runner/src/main.ts +15 -0
  269. package/templates/runner/src/physics.ts +13 -0
  270. package/templates/runner/src/render/camera.ts +39 -0
  271. package/templates/runner/src/render/dust.ts +131 -0
  272. package/templates/runner/src/render/lighting.ts +57 -0
  273. package/templates/runner/src/render/loading.ts +325 -0
  274. package/templates/runner/src/render/materials.ts +27 -0
  275. package/templates/runner/src/render/palette.ts +30 -0
  276. package/templates/runner/src/render/postprocessing.ts +34 -0
  277. package/templates/runner/src/render/quality.ts +170 -0
  278. package/templates/runner/src/render/shapes.ts +68 -0
  279. package/templates/runner/src/render/sky.ts +51 -0
  280. package/templates/runner/src/render/touch-controls.ts +185 -0
  281. package/templates/runner/src/render/worldEnvironment.ts +758 -0
  282. package/templates/runner/src/scenes/Boot.ts +12 -0
  283. package/templates/runner/src/scenes/Run.ts +142 -0
  284. package/templates/runner/src/state.ts +29 -0
  285. package/templates/runner/src/style.css +96 -0
  286. package/templates/runner/src/track.ts +176 -0
  287. package/templates/runner/src/ui/App.tsx +22 -0
  288. package/templates/runner/src/ui/GameUi.tsx +20 -0
  289. package/templates/runner/src/ui/Hud.tsx +55 -0
  290. package/templates/runner/src/ui/Menu.tsx +7 -0
  291. package/templates/runner/src/ui/main.tsx +14 -0
  292. package/templates/runner/tailwind.config.ts +1 -0
  293. package/templates/runner/threenative.config.ts +49 -0
  294. package/templates/runner/tsconfig.json +17 -0
  295. package/templates/runner/vite.config.ts +38 -0
  296. package/templates/sailing/.codex/config.toml +4 -0
  297. package/templates/sailing/.cursor/mcp.json +32 -0
  298. package/templates/sailing/.gemini/settings.json +32 -0
  299. package/templates/sailing/.mcp.json +15 -3
  300. package/templates/sailing/.vscode/mcp.json +36 -0
  301. package/templates/sailing/.zed/settings.json +36 -0
  302. package/templates/sailing/AGENTS.md +62 -355
  303. package/templates/sailing/CLAUDE.md +62 -355
  304. package/templates/sailing/README.md +12 -9
  305. package/templates/sailing/native-playtests/float.playtest.json +55 -0
  306. package/templates/sailing/native-playtests/survives.playtest.json +20 -3
  307. package/templates/sailing/opencode.json +41 -0
  308. package/templates/sailing/package.json +8 -8
  309. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
  310. package/templates/sailing/playtests/float.playtest.json +59 -0
  311. package/templates/sailing/playtests/performance.playtest.json +21 -6
  312. package/templates/sailing/playtests/survives.playtest.json +8 -0
  313. package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
  314. package/templates/sailing/src/conventions.ts +8 -0
  315. package/templates/sailing/src/entities/Ship.ts +150 -13
  316. package/templates/sailing/src/render/camera.ts +15 -8
  317. package/templates/sailing/src/render/lighting.ts +10 -5
  318. package/templates/sailing/src/render/loading.ts +12 -2
  319. package/templates/sailing/src/render/materials.ts +24 -8
  320. package/templates/sailing/src/render/ocean.ts +179 -0
  321. package/templates/sailing/src/render/palette.ts +14 -21
  322. package/templates/sailing/src/render/postprocessing.ts +23 -22
  323. package/templates/sailing/src/render/props.ts +584 -34
  324. package/templates/sailing/src/render/quality.ts +140 -0
  325. package/templates/sailing/src/render/sky.ts +8 -3
  326. package/templates/sailing/src/render/touch-controls.ts +142 -0
  327. package/templates/sailing/src/render/worldEnvironment.ts +206 -38
  328. package/templates/sailing/src/scenes/Sailing.ts +43 -16
  329. package/templates/sailing/src/style.css +20 -0
  330. package/templates/sailing/threenative.config.ts +7 -1
  331. package/templates/shooter/.codex/config.toml +4 -0
  332. package/templates/shooter/.cursor/mcp.json +32 -0
  333. package/templates/shooter/.gemini/settings.json +32 -0
  334. package/templates/shooter/.mcp.json +15 -3
  335. package/templates/shooter/.vscode/mcp.json +36 -0
  336. package/templates/shooter/.zed/settings.json +36 -0
  337. package/templates/shooter/AGENTS.md +76 -415
  338. package/templates/shooter/CLAUDE.md +76 -415
  339. package/templates/shooter/kit.json +2 -2
  340. package/templates/shooter/opencode.json +41 -0
  341. package/templates/shooter/package.json +7 -7
  342. package/templates/shooter/playtests/combat.playtest.json +48 -0
  343. package/templates/shooter/playtests/input-control.playtest.json +165 -35
  344. package/templates/shooter/playtests/per-item.playtest.json +3 -3
  345. package/templates/shooter/playtests/performance.playtest.json +24 -7
  346. package/templates/shooter/playtests/shooter.playtest.json +13 -7
  347. package/templates/shooter/playtests/survives.playtest.json +27 -0
  348. package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
  349. package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
  350. package/templates/shooter/src/combat/damage.ts +1 -2
  351. package/templates/shooter/src/conventions.ts +51 -0
  352. package/templates/shooter/src/entities/Player.ts +235 -18
  353. package/templates/shooter/src/entities/Target.ts +2 -2
  354. package/templates/shooter/src/game.ts +13 -4
  355. package/templates/shooter/src/render/camera.ts +49 -39
  356. package/templates/shooter/src/render/decals.ts +211 -0
  357. package/templates/shooter/src/render/lighting.ts +7 -3
  358. package/templates/shooter/src/render/loading.ts +12 -2
  359. package/templates/shooter/src/render/materials.ts +56 -3
  360. package/templates/shooter/src/render/palette.ts +6 -3
  361. package/templates/shooter/src/render/postprocessing.ts +21 -58
  362. package/templates/shooter/src/render/quality.ts +170 -0
  363. package/templates/shooter/src/render/scale.ts +22 -0
  364. package/templates/shooter/src/render/shapes.ts +343 -62
  365. package/templates/shooter/src/render/sky.ts +5 -1
  366. package/templates/shooter/src/render/touch-controls.ts +305 -0
  367. package/templates/shooter/src/render/ui.css +85 -0
  368. package/templates/shooter/src/render/ui.ts +19 -3
  369. package/templates/shooter/src/render/vfx.ts +215 -0
  370. package/templates/shooter/src/render/worldEnvironment.ts +208 -33
  371. package/templates/shooter/src/scenes/Play.ts +171 -56
  372. package/templates/shooter/src/state.ts +5 -0
  373. package/templates/shooter/src/style.css +20 -0
  374. package/templates/shooter/src/ui/Crosshair.tsx +25 -0
  375. package/templates/shooter/src/ui/GameUi.tsx +2 -0
  376. package/templates/shooter/src/ui/Hud.tsx +7 -1
  377. package/templates/shooter/src/weapons/Hitscan.ts +3 -4
  378. package/templates/shooter/src/weapons/Projectile.ts +8 -3
  379. package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
  380. package/templates/shooter/threenative.config.ts +7 -0
  381. package/templates/starter/.codex/config.toml +4 -0
  382. package/templates/starter/.cursor/mcp.json +32 -0
  383. package/templates/starter/.gemini/settings.json +32 -0
  384. package/templates/starter/.mcp.json +15 -3
  385. package/templates/starter/.vscode/mcp.json +36 -0
  386. package/templates/starter/.zed/settings.json +36 -0
  387. package/templates/starter/AGENTS.md +70 -527
  388. package/templates/starter/CLAUDE.md +70 -527
  389. package/templates/starter/native-playtests/render-chain.playtest.json +73 -4
  390. package/templates/starter/opencode.json +41 -0
  391. package/templates/starter/package.json +7 -7
  392. package/templates/starter/playtests/boot-failure.playtest.json +45 -0
  393. package/templates/starter/playtests/look.playtest.json +110 -6
  394. package/templates/starter/playtests/play.playtest.json +3 -2
  395. package/templates/starter/playtests/survives.playtest.json +21 -0
  396. package/templates/starter/playtests/touch-controls.playtest.json +42 -0
  397. package/templates/starter/src/conventions.ts +18 -0
  398. package/templates/starter/src/entities/Goal.ts +18 -3
  399. package/templates/starter/src/entities/Player.ts +72 -9
  400. package/templates/starter/src/game.ts +2 -0
  401. package/templates/starter/src/render/adaptiveQuality.ts +195 -0
  402. package/templates/starter/src/render/camera.ts +1 -1
  403. package/templates/starter/src/render/coast.ts +199 -0
  404. package/templates/starter/src/render/hero.ts +88 -0
  405. package/templates/starter/src/render/implicitSurface.ts +199 -0
  406. package/templates/starter/src/render/kuwahara.ts +174 -0
  407. package/templates/starter/src/render/lighting.ts +4 -4
  408. package/templates/starter/src/render/loading.ts +12 -2
  409. package/templates/starter/src/render/materials.ts +25 -6
  410. package/templates/starter/src/render/outline.ts +141 -0
  411. package/templates/starter/src/render/painterly.ts +86 -0
  412. package/templates/starter/src/render/palette.ts +15 -6
  413. package/templates/starter/src/render/postprocessing.ts +87 -36
  414. package/templates/starter/src/render/quality.ts +185 -0
  415. package/templates/starter/src/render/rockRidge.ts +198 -0
  416. package/templates/starter/src/render/rockRidge.worker.ts +77 -0
  417. package/templates/starter/src/render/scenery.ts +16 -59
  418. package/templates/starter/src/render/textureLifetime.ts +53 -0
  419. package/templates/starter/src/render/touch-controls.ts +165 -0
  420. package/templates/starter/src/render/water.ts +38 -0
  421. package/templates/starter/src/render/watercolor.ts +85 -0
  422. package/templates/starter/src/render/worldEnvironment.ts +208 -33
  423. package/templates/starter/src/scenes/Play.ts +103 -16
  424. package/templates/starter/src/style.css +27 -7
  425. package/templates/starter/threenative.config.ts +7 -7
  426. package/agent-docs/asset-mcp-loop.md +0 -33
  427. package/agent-docs/ctx-surface.md +0 -69
  428. package/agent-docs/engine-capabilities.md +0 -4
  429. package/agent-docs/framework-blocks-you.md +0 -60
  430. package/agent-docs/look-at-it-and-budget-the-look.md +0 -27
  431. package/agent-docs/performance-default.md +0 -42
  432. package/agent-docs/pixel-budget.md +0 -20
  433. package/agent-docs/playtest-fail-closed.md +0 -23
  434. package/agent-docs/sculpt-loop.md +0 -16
  435. package/templates/action-rpg/src/physics.ts +0 -40
  436. package/templates/defense/public/icon.png +0 -0
  437. package/templates/minimal/public/icon.png +0 -0
  438. package/templates/platformer/public/icon.png +0 -0
  439. package/templates/racing/public/icon.png +0 -0
  440. package/templates/sailing/public/icon.png +0 -0
  441. package/templates/sailing/src/render/water-material.ts +0 -14
  442. package/templates/sailing/src/render/water-shaders.ts +0 -12
  443. package/templates/sailing/src/render/wave-nodes.ts +0 -10
  444. package/templates/shooter/public/icon.png +0 -0
  445. package/templates/shooter/src/physics.ts +0 -49
  446. package/templates/starter/public/icon.png +0 -0
  447. /package/{templates/action-rpg/public → template-assets}/icon.png +0 -0
@@ -143,6 +143,34 @@ export interface IWorldEnvironmentOptions {
143
143
  readonly gtaoSamples?: number;
144
144
  /** Fraction of display resolution the occlusion is traced at. */
145
145
  readonly gtaoResolutionScale?: number;
146
+ /**
147
+ * The fraction of the frame SSGI actually gathers at. Half by default.
148
+ *
149
+ * `GTAONode` and `SSRNode` both carry a `resolutionScale` of their own; **`SSGINode` does not**,
150
+ * and its `setSize` passes width and height straight into its render target with no factor. So
151
+ * screen-space GI — a low-frequency effect every production renderer gathers at half or quarter
152
+ * res — was the only stage in this chain running at full resolution, and it cost accordingly.
153
+ *
154
+ * Measured on a 46,190-instance forest at 1600x900 on an RTX 2080, with the resolution scaler
155
+ * left on auto so the engine's own verdict is part of the result:
156
+ *
157
+ * fps still/walk scale it settled on interior median dead shadow
158
+ * full res 38.0 / 47.2 0.44 704x396 0.0299 19.19%
159
+ * off 60.0 / 60.0 0.61 976x549 0.0987 4.54%
160
+ * half res 59.8 / 60.0 0.72 1152x648 0.0301 18.58%
161
+ *
162
+ * Half res is better than both: it holds the budget like switching SSGI off, keeps the look
163
+ * within noise of full res, and produces the *sharpest* frame of the three — because the budget
164
+ * it hands back is spent by the scaler on pixels rather than on a gather nobody can see at full
165
+ * rate. Full-res SSGI was not buying quality, it was trading it.
166
+ *
167
+ * Fixed without touching three: `setSize` is public and the pass drives the node through it with
168
+ * the full frame size, so the instance is wrapped to hand it a smaller one. The node's own maths
169
+ * reads the `_resolution` uniform that `setSize` writes, so it stays self-consistent, and the
170
+ * result is sampled by UV rather than by texel — which is what makes the upsample free and is
171
+ * exactly the mechanism `GTAONode` uses internally.
172
+ */
173
+ readonly ssgiResolutionScale?: number;
146
174
  /**
147
175
  * Contrast-adaptive sharpening (RCAS) over the finished frame.
148
176
  *
@@ -163,6 +191,30 @@ export interface IWorldEnvironmentOptions {
163
191
  readonly bloomRadius?: number;
164
192
  /** Luminance a pixel must exceed before it blooms at all. */
165
193
  readonly bloomThreshold?: number;
194
+ /**
195
+ * Which of this kit's authored stages to run.
196
+ *
197
+ * Separate from the graph below, and not for tidiness: the chain has to know whether anything
198
+ * was requested at all before the scene pass exists — with nothing requested it sets an
199
+ * exposure and returns, and no pass is ever built. So the request is a static decision the kit
200
+ * makes from its own config, and only the graph needs the pass.
201
+ */
202
+ readonly authoredStageNames?: readonly string[];
203
+ /**
204
+ * This kit's own stages, composed after the built-ins.
205
+ *
206
+ * A factory because an authored stage needs the two things only this file can produce: the
207
+ * scene pass's depth texture node, which does not exist until the pass is built, and the
208
+ * resolved tier. It returns the complete graph — including stages left dormant this frame — so
209
+ * that an anchor like `watercolor after kuwahara` keeps naming a stage that exists.
210
+ *
211
+ * Naming specific stages here instead — an `outlineEnabled`, a `kuwaharaRadius` — is what put
212
+ * one kit's look inside the plumbing every kit copies verbatim, which
213
+ * `shared-render-sources.spec.ts` exists to refuse.
214
+ */
215
+ readonly authoredStages?: (context: IWorldEnvironmentStageContext) => readonly ChainStage[];
216
+ /** Quality tier passed to the measured chain; the quality module owns this value. */
217
+ readonly renderChainTier?: ChainTier;
166
218
  readonly tonemapMode?: TonemapMode;
167
219
  /**
168
220
  * Scene-referred exposure: multiplied into the scene pass **before** the tone curve, so
@@ -198,12 +250,33 @@ export interface IWorldEnvironmentTarget {
198
250
  * compiler checks the composition instead of taking a cast's word for it.
199
251
  */
200
252
  type ChainNode = Node<"vec4">;
253
+ /**
254
+ * The scene pass's depth texture, as the pass itself types it.
255
+ *
256
+ * Named through `pass()` rather than written out because the addon's return type is the only
257
+ * honest spelling of it, and a hand-written alias here would drift the first time three changes it.
258
+ */
259
+ export type DepthTextureNode = ReturnType<ReturnType<typeof pass>["getTextureNode"]>;
260
+ type ChainTier = "high" | "medium" | "low" | "off";
201
261
  type ChainContext = {
202
- readonly tier: "high" | "medium" | "low" | "off";
262
+ readonly tier: ChainTier;
203
263
  };
204
- type ChainStage = {
205
- readonly name: "ambientOcclusion" | "ssgi" | "godRays" | "ssr" | "sharpen" | "bloom" | "vignette";
264
+ /**
265
+ * What a kit's `authoredStages` factory is handed. The depth node is the scene pass's, so a
266
+ * stage that reads depth gets the same texture the built-in stages read rather than its own.
267
+ */
268
+ export interface IWorldEnvironmentStageContext {
269
+ readonly depthNode: DepthTextureNode;
270
+ readonly tier: ChainTier;
271
+ }
272
+
273
+ export type ChainStage = {
274
+ readonly name: string;
275
+ readonly before?: string;
276
+ readonly after?: string;
206
277
  readonly available?: (context: ChainContext) => boolean | string;
278
+ readonly dispose?: () => void;
279
+ readonly minimumTier?: ChainTier;
207
280
  /** The chain plumbing is stage-agnostic, so it names the node it carries `unknown`. */
208
281
  readonly build: (input: unknown, context: ChainContext) => unknown;
209
282
  };
@@ -218,6 +291,7 @@ type ChainStage = {
218
291
  */
219
292
  function stage(definition: {
220
293
  readonly name: ChainStage["name"];
294
+ readonly dispose?: () => void;
221
295
  readonly available?: (context: ChainContext) => boolean | string;
222
296
  readonly build: (input: ChainNode, context: ChainContext) => ChainNode;
223
297
  }): ChainStage {
@@ -248,10 +322,12 @@ export type OutputRenderer = {
248
322
  setOutputNode?: (node: unknown) => void;
249
323
  createRenderChain?: (options: {
250
324
  input?: unknown;
325
+ worldPass?: unknown;
251
326
  request?: { stages?: readonly string[]; tier?: ChainContext["tier"] };
252
327
  stages?: readonly ChainStage[];
253
328
  }) => {
254
329
  applied: { dropped: readonly { name: string; reason: string }[]; stages: readonly string[] };
330
+ dispose(): void;
255
331
  };
256
332
  };
257
333
 
@@ -281,7 +357,17 @@ export class WorldEnvironment {
281
357
  `Unknown tonemapMode '${String(tonemapMode)}'. Use one of: ${Object.keys(TONEMAP).join(", ")}.`,
282
358
  );
283
359
  }
360
+ const renderChainTier = options.renderChainTier ?? "high";
361
+ if (!isChainTier(renderChainTier)) {
362
+ throw new Error(
363
+ `Unknown render chain tier '${String(renderChainTier)}'. Use high, medium, low, or off.`,
364
+ );
365
+ }
284
366
  this.#options = {
367
+ // A kit with no stages of its own is the common case, so both default to empty rather
368
+ // than to a branch every call site has to remember.
369
+ authoredStageNames: options.authoredStageNames ?? [],
370
+ authoredStages: options.authoredStages ?? (() => []),
285
371
  ssgiEnabled: options.ssgiEnabled ?? false,
286
372
  ssgiQuality: quality,
287
373
  ssgiIntensity: options.ssgiIntensity ?? 1,
@@ -301,6 +387,7 @@ export class WorldEnvironment {
301
387
  gtaoScale: options.gtaoScale ?? 1,
302
388
  gtaoSamples: options.gtaoSamples ?? 16,
303
389
  gtaoResolutionScale: options.gtaoResolutionScale ?? 1,
390
+ ssgiResolutionScale: options.ssgiResolutionScale ?? 0.5,
304
391
  sharpenEnabled: options.sharpenEnabled ?? false,
305
392
  sharpenStrength: options.sharpenStrength ?? 0.2,
306
393
  vignetteAmount: options.vignetteAmount ?? 0,
@@ -308,6 +395,7 @@ export class WorldEnvironment {
308
395
  bloomStrength: options.bloomStrength ?? 0.7,
309
396
  bloomRadius: options.bloomRadius ?? 0.5,
310
397
  bloomThreshold: options.bloomThreshold ?? 0.2,
398
+ renderChainTier,
311
399
  tonemapMode,
312
400
  exposure: options.exposure ?? 1,
313
401
  };
@@ -325,12 +413,13 @@ export class WorldEnvironment {
325
413
  ): {
326
414
  dropped: readonly { name: string; reason: string }[];
327
415
  stages: readonly string[];
416
+ dispose?: () => void;
328
417
  } {
329
418
  const options = this.#options;
330
419
  const raw = renderer.raw as { toneMapping?: number; toneMappingExposure?: number };
331
420
  raw.toneMapping = TONEMAP[options.tonemapMode];
332
421
 
333
- const requested = (
422
+ const requested: string[] = (
334
423
  ["ssgi", "ambientOcclusion", "godRays", "ssr", "sharpen", "bloom", "vignette"] as const
335
424
  ).filter(
336
425
  (name) =>
@@ -342,6 +431,7 @@ export class WorldEnvironment {
342
431
  (name === "bloom" && options.bloomEnabled) ||
343
432
  (name === "vignette" && options.vignetteAmount > 0),
344
433
  );
434
+ requested.push(...options.authoredStageNames);
345
435
 
346
436
  // With no stage running there is no node graph to install — the renderer's own
347
437
  // tone-mapping path renders the frame, and the exposure scalar is live there (measured:
@@ -364,17 +454,25 @@ export class WorldEnvironment {
364
454
  if (options.ssgiEnabled || options.ssrEnabled || options.gtaoEnabled) {
365
455
  scenePass.setMRT(mrt({ output, normal: normalView, metalness, roughness }));
366
456
  }
367
- const depth = scenePass.getTextureNode("depth");
368
- // PassNode adds every named colour texture requested through getTextureNode() to its
369
- // framebuffer. Keep the surface-data attachments lazy: a bloom-only outdoor scene does
370
- // not need MRT, and asking for normal/metalness/roughness here would give ordinary
371
- // materials extra targets with no fragment outputs.
372
- const normal = (): ReturnType<typeof scenePass.getTextureNode> =>
373
- scenePass.getTextureNode("normal");
374
- const metal = (): ReturnType<typeof scenePass.getTextureNode> =>
375
- scenePass.getTextureNode("metalness");
376
- const rough = (): ReturnType<typeof scenePass.getTextureNode> =>
377
- scenePass.getTextureNode("roughness");
457
+ // Requested lazily, and this is not a micro-optimisation. **Asking a pass for `normal`,
458
+ // `metalness` or `roughness` is what creates the extra render target.** A tier that runs none
459
+ // of the stages needing them — the mobile look is bloom and the tone curve — must not ask, or
460
+ // the pass carries a colour target no fragment shader writes and WebGPU refuses the pipeline:
461
+ // *"Color target has no corresponding fragment stage output but writeMask … is not zero.
462
+ // While validating targets[1]"*. The frame then comes out **black** while the chain still
463
+ // reports every stage as applied, which is the worst shape a failure can take here.
464
+ const nodes = new Map<string, ReturnType<typeof scenePass.getTextureNode>>();
465
+ const textureNode = (name: string): ReturnType<typeof scenePass.getTextureNode> => {
466
+ const cached = nodes.get(name);
467
+ if (cached !== undefined) return cached;
468
+ const node = scenePass.getTextureNode(name);
469
+ nodes.set(name, node);
470
+ return node;
471
+ };
472
+ const depth = (): ReturnType<typeof scenePass.getTextureNode> => textureNode("depth");
473
+ const normal = (): ReturnType<typeof scenePass.getTextureNode> => textureNode("normal");
474
+ const metal = (): ReturnType<typeof scenePass.getTextureNode> => textureNode("metalness");
475
+ const rough = (): ReturnType<typeof scenePass.getTextureNode> => textureNode("roughness");
378
476
  // Every stage here is perspective-camera maths — view-space reconstruction from depth,
379
477
  // and a projection matrix inverse. The scene's camera is the one the pass rendered with.
380
478
  const view = camera as PerspectiveCamera;
@@ -382,17 +480,39 @@ export class WorldEnvironment {
382
480
  const base = target.baseColour?.(scenePass) ?? scenePass.getTextureNode("output");
383
481
  const exposed = convertToTexture(base).mul(options.exposure);
384
482
  const giDenoise = (node: ChainNode): ChainNode =>
385
- options.denoiseEnabled ? denoised(denoise(node, depth, normal(), view)) : node;
483
+ options.denoiseEnabled ? denoised(denoise(node, depth(), normal(), view)) : node;
386
484
 
485
+ let releaseBloom = (): void => {};
387
486
  const stages: ChainStage[] = [
388
487
  stage({
389
488
  name: "ssgi",
390
489
  build: (input) => {
391
- const gi = ssgi(input, depth, normal(), view);
490
+ const gi = ssgi(input, depth(), normal(), view);
392
491
  const tier = SSGI_QUALITY[options.ssgiQuality];
393
492
  gi.sliceCount.value = tier.sliceCount;
394
493
  gi.stepCount.value = tier.stepCount;
395
494
  gi.radius.value = options.ssgiRadius;
495
+ // Gather at a fraction of the frame. See `ssgiResolutionScale` above for why this is a
496
+ // wrapper rather than a property: the node has no scale of its own, and `setSize` is the
497
+ // public seam the pass drives it through. `setSize` is present on the node and absent
498
+ // from its type declarations, so the seam is named here rather than cast away at the call
499
+ // site — if a future three release declares it, or gives the node a `resolutionScale`,
500
+ // this narrows to nothing and the wrapper can go. Guarded at one texel so a zero or a
501
+ // negative cannot ask for an empty target: a 0x0 gather returns black and reads as SSGI
502
+ // simply not working.
503
+ const ssgiScale = options.ssgiResolutionScale;
504
+ const sizedGi = gi as unknown as {
505
+ setSize?: (width: number, height: number) => void;
506
+ };
507
+ const fullGiSize = sizedGi.setSize?.bind(gi);
508
+ if (ssgiScale > 0 && ssgiScale < 1 && fullGiSize !== undefined) {
509
+ sizedGi.setSize = (width: number, height: number): void => {
510
+ fullGiSize(
511
+ Math.max(1, Math.round(width * ssgiScale)),
512
+ Math.max(1, Math.round(height * ssgiScale)),
513
+ );
514
+ };
515
+ }
396
516
 
397
517
  // SSGI writes two targets: AO in a single-channel `RedFormat` texture, and the GI
398
518
  // term in an RGB one. Multiplying the beauty pass by the whole AO vec4 therefore
@@ -412,7 +532,7 @@ export class WorldEnvironment {
412
532
  stage({
413
533
  name: "ambientOcclusion",
414
534
  build: (input) => {
415
- const contact = ao(depth, normal(), view);
535
+ const contact = ao(depth(), normal(), view);
416
536
  contact.radius.value = options.gtaoRadius;
417
537
  contact.scale.value = options.gtaoScale;
418
538
  contact.samples.value = options.gtaoSamples;
@@ -435,11 +555,19 @@ export class WorldEnvironment {
435
555
  if (light === undefined) return "godraysEnabled is true but no godraysLight was passed";
436
556
  if (light.castShadow !== true)
437
557
  return `light '${light.name || "sun"}' does not cast shadows`;
558
+ // `castShadow` is a request, not a result: three allocates the shadow map on the first
559
+ // render that needs it, and `GodraysNode` reads `shadow.map.depthTexture` while the
560
+ // graph is built. Without this check that read throws inside TSL, the chain build
561
+ // fails, and *every* stage is lost — the frame comes back ungraded with no SSGI, no
562
+ // SSR and no tonemap, which looks like a scene problem rather than a missing map.
563
+ // Refusing by name keeps the rest of the chain, which is this stage list's contract.
564
+ if (light.shadow?.map == null)
565
+ return `light '${light.name || "sun"}' has no shadow map yet: set renderer.shadowMap.enabled on the raw renderer (ctx.renderer.raw), and build the chain after the first frame has rendered`;
438
566
  return true;
439
567
  },
440
568
  build: (input) => {
441
569
  const light = target.godraysLight as DirectionalLight;
442
- const shafts = godrays(depth, view, light);
570
+ const shafts = godrays(depth(), view, light);
443
571
  shafts.density.value = options.godraysDensity;
444
572
  shafts.maxDensity.value = options.godraysMaxDensity;
445
573
  shafts.raymarchSteps.value = options.godraysSteps;
@@ -450,7 +578,7 @@ export class WorldEnvironment {
450
578
  // silhouettes the depth term owns. Denoise before the floor: the floor's
451
579
  // subtraction amplifies relative noise on near-floor values.
452
580
  let shaft: ChainNode = convertToTexture(shafts);
453
- if (options.denoiseEnabled) shaft = denoised(denoise(shaft, depth, normal(), view));
581
+ if (options.denoiseEnabled) shaft = denoised(denoise(shaft, depth(), normal(), view));
454
582
  // Floor, then scale, then tint. The floor is what turns this from a whole-frame
455
583
  // brightener into a shaft renderer; the tint by the light's own colour is what
456
584
  // stops a warm sun throwing a white beam.
@@ -476,7 +604,7 @@ export class WorldEnvironment {
476
604
  // reflections onto a second copy builds two parallel graphs, and the frame comes
477
605
  // out as the bare background colour.
478
606
  const base = convertToTexture(input);
479
- const reflections = ssr(base, depth, normal() as unknown as Parameters<typeof ssr>[2], {
607
+ const reflections = ssr(base, depth(), normal() as unknown as Parameters<typeof ssr>[2], {
480
608
  camera: view,
481
609
  metalnessNode: metal().r,
482
610
  roughnessNode: rough().g,
@@ -500,15 +628,33 @@ export class WorldEnvironment {
500
628
  }),
501
629
  stage({
502
630
  name: "bloom",
503
- build: (input) =>
504
- input.add(
505
- bloom(
506
- convertToTexture(input),
507
- options.bloomStrength,
508
- options.bloomRadius,
509
- options.bloomThreshold,
510
- ),
511
- ),
631
+ dispose: () => {
632
+ releaseBloom();
633
+ releaseBloom = () => {};
634
+ },
635
+ build: (input) => {
636
+ const texture = convertToTexture(input);
637
+ const effect = bloom(
638
+ texture,
639
+ options.bloomStrength,
640
+ options.bloomRadius,
641
+ options.bloomThreshold,
642
+ );
643
+ releaseBloom = () => {
644
+ effect.dispose();
645
+ // convertToTexture may return its input. Only the newly allocated RTT is ours.
646
+ const scratch = texture as unknown as {
647
+ isRTTNode?: boolean;
648
+ renderTarget: { dispose(): void };
649
+ _quadMesh: { material: { dispose(): void } };
650
+ };
651
+ if (texture !== input && scratch.isRTTNode === true) {
652
+ scratch.renderTarget.dispose();
653
+ scratch._quadMesh.material.dispose();
654
+ }
655
+ };
656
+ return input.add(effect);
657
+ },
512
658
  }),
513
659
  stage({
514
660
  name: "vignette",
@@ -524,6 +670,11 @@ export class WorldEnvironment {
524
670
  }),
525
671
  ];
526
672
 
673
+ // The kit's own stages, composed after the built-ins. The factory is called with the two
674
+ // things only this file can produce — the scene pass's depth texture and the resolved tier —
675
+ // and returns the complete authored graph plus the subset to run.
676
+ stages.push(...options.authoredStages({ depthNode: depth(), tier: options.renderChainTier }));
677
+
527
678
  // A composed base colour with every stage off still has to reach the frame. The chain
528
679
  // installs nothing for an empty stage list, so this is the one path that goes direct.
529
680
  if (requested.length === 0) {
@@ -541,11 +692,19 @@ export class WorldEnvironment {
541
692
  if (renderer.createRenderChain === undefined) throw new Error("RenderChain is unavailable.");
542
693
  const chain = renderer.createRenderChain({
543
694
  input: exposed,
544
- request: { stages: requested, tier: "high" },
695
+ request: { stages: requested, tier: options.renderChainTier },
545
696
  stages,
697
+ worldPass: scenePass,
546
698
  });
547
699
  this.#reportApplied(chain.applied.stages, chain.applied.dropped);
548
- return { dropped: chain.applied.dropped, stages: chain.applied.stages };
700
+ return {
701
+ dropped: chain.applied.dropped,
702
+ stages: chain.applied.stages,
703
+ dispose: () => {
704
+ chain.dispose();
705
+ scenePass.dispose();
706
+ },
707
+ };
549
708
  }
550
709
 
551
710
  /**
@@ -562,7 +721,7 @@ export class WorldEnvironment {
562
721
  dropped: readonly { name: string; reason: string }[],
563
722
  ): void {
564
723
  const options = this.#options;
565
- const off: Record<ChainStage["name"], string> = {
724
+ const off: Record<string, string> = {
566
725
  ambientOcclusion: "gtaoEnabled is false",
567
726
  bloom: "bloomEnabled is false",
568
727
  godRays: "godraysEnabled is false",
@@ -570,12 +729,17 @@ export class WorldEnvironment {
570
729
  ssgi: "ssgiEnabled is false",
571
730
  ssr: "ssrEnabled is false",
572
731
  vignette: "vignetteAmount is 0",
732
+ kuwahara: "kuwaharaEnabled is false",
733
+ outline: "outlineEnabled is false",
734
+ watercolor: "watercolorEnabled is false",
573
735
  };
574
- const stages = (Object.keys(off) as ChainStage["name"][]).sort().map((name) => {
575
- if (applied.includes(name)) return { applied: true, name };
576
- const refused = dropped.find((entry) => entry.name === name);
577
- return { applied: false, name, reason: refused?.reason ?? off[name] };
578
- });
736
+ const stages = Object.keys(off)
737
+ .sort()
738
+ .map((name) => {
739
+ if (applied.includes(name)) return { applied: true, name };
740
+ const refused = dropped.find((entry) => entry.name === name);
741
+ return { applied: false, name, reason: refused?.reason ?? off[name] };
742
+ });
579
743
  console.info(
580
744
  `TN_WORLD_ENVIRONMENT:${JSON.stringify({
581
745
  denoise: options.denoiseEnabled,
@@ -588,3 +752,7 @@ export class WorldEnvironment {
588
752
  );
589
753
  }
590
754
  }
755
+
756
+ function isChainTier(value: unknown): value is ChainTier {
757
+ return value === "high" || value === "medium" || value === "low" || value === "off";
758
+ }
@@ -1,16 +1,23 @@
1
- import { type ICtx, Scene, type SceneFrame, WaveField, isMobile } from "@threenative/core";
1
+ import {
2
+ type ICtx,
3
+ Scene,
4
+ type SceneFrame,
5
+ isMobile,
6
+ isTouchscreenAvailable,
7
+ } from "@threenative/core";
2
8
  import type { IPhysicsContext } from "@threenative/physics";
3
- import { Fog, Mesh, type PerspectiveCamera, PlaneGeometry } from "three";
9
+ import { Fog, type PerspectiveCamera } from "three";
4
10
  import { Ship } from "../entities/Ship.js";
5
11
  import { followShip, setupCamera } from "../render/camera.js";
6
12
  import { setupLighting } from "../render/lighting.js";
7
13
  import { createLoadingScreen } from "../render/loading.js";
8
14
  import { createMaterials } from "../render/materials.js";
9
- import { SAILING_DOMAIN_WARP, SAILING_WAVES, palette } from "../render/palette.js";
15
+ import { createOcean, createWaterMesh } from "../render/ocean.js";
16
+ import { palette } from "../render/palette.js";
10
17
  import { setupPost } from "../render/postprocessing.js";
11
18
  import { createBuoy, createIsland } from "../render/props.js";
12
19
  import { setupSky } from "../render/sky.js";
13
- import { createWaterMaterial } from "../render/water-material.js";
20
+ import { TouchControls } from "../render/touch-controls.js";
14
21
  import type { GameState } from "../state.js";
15
22
 
16
23
  export type GameCtx = ICtx<GameState, IPhysicsContext>;
@@ -31,19 +38,25 @@ export class Sailing extends Scene<GameState, IPhysicsContext> {
31
38
 
32
39
  override enter(ctx: GameCtx): SceneFrame<GameState, IPhysicsContext> {
33
40
  setupSky(ctx.scene);
34
- ctx.scene.fog = new Fog(palette.skyLow, 30, 100);
41
+ // Fog to the horizon colour, and starting far enough out that the island is not eaten. At
42
+ // 30..100 against a dark navy the sea went to slate a boat-length away.
43
+ ctx.scene.fog = new Fog(palette.skyLow, 95, 330);
35
44
  const sun = setupLighting(ctx.scene, ctx.renderer.raw as Parameters<typeof setupLighting>[1]);
36
45
  setupPost(ctx.renderer, ctx.scene, ctx.camera, { godraysLight: sun, mobile: isMobile() });
37
46
  const loading = createLoadingScreen(ctx);
38
47
  const camera = ctx.camera as PerspectiveCamera;
39
48
  setupCamera(camera);
49
+ ctx.add(camera);
50
+ const showTouchControls = isMobile() && isTouchscreenAvailable();
51
+ const touchControls = showTouchControls
52
+ ? ctx.entities.add("touch-controls", new TouchControls(camera))
53
+ : undefined;
40
54
 
41
- const field = new WaveField({ waves: SAILING_WAVES, domainWarp: SAILING_DOMAIN_WARP });
42
- const water = new Mesh(new PlaneGeometry(80, 80, 96, 96), createWaterMaterial(field));
43
- water.geometry.rotateX(-Math.PI / 2);
44
- water.receiveShadow = true;
45
- water.frustumCulled = false;
46
- ctx.add(water);
55
+ // `SpectralOcean` is a compute-driven node: `ctx.add` hands it the renderer and puts its
56
+ // passes in the warmup set. It draws nothing — the mesh and its material are this game's, and
57
+ // both live in `src/render/ocean.ts`.
58
+ const ocean = ctx.add(createOcean());
59
+ ctx.add(createWaterMesh(ocean));
47
60
 
48
61
  const materials = createMaterials();
49
62
  ctx.add(createIsland(materials));
@@ -53,7 +66,7 @@ export class Sailing extends Scene<GameState, IPhysicsContext> {
53
66
  ctx.add(buoy);
54
67
  }
55
68
 
56
- const ship = new Ship(ctx, field);
69
+ const ship = new Ship(ctx, ocean);
57
70
  ctx.entities.add("player", ship);
58
71
  let elapsed = 0;
59
72
  let buoysRounded = 0;
@@ -64,7 +77,12 @@ export class Sailing extends Scene<GameState, IPhysicsContext> {
64
77
  status = "lost";
65
78
  return;
66
79
  }
67
- ship.update(frameCtx, deltaTime, wind);
80
+ ship.update(
81
+ frameCtx,
82
+ deltaTime,
83
+ wind,
84
+ touchControls?.update(frameCtx.input.raw.pointers, frameCtx.viewport.size),
85
+ );
68
86
  const nextBuoy = COURSE_BUOYS[buoysRounded];
69
87
  if (nextBuoy === undefined || ship.mesh.position.z > nextBuoy) {
70
88
  if (wind <= 0) status = "lost";
@@ -85,9 +103,13 @@ export class Sailing extends Scene<GameState, IPhysicsContext> {
85
103
  }
86
104
 
87
105
  elapsed += deltaTime;
88
- field.setTime(elapsed);
89
106
  const wind = Math.max(0, 1 - elapsed / 45);
107
+ ocean.advance(elapsed);
90
108
  if (status === "sailing") advanceSailing(frameCtx, deltaTime, wind);
109
+ // Outside the gameplay gate on purpose. Steering and buoy counting stop when the run ends;
110
+ // the hull still has to be placed on a sea that never stops moving, or the boat freezes
111
+ // mid-wave while the water rolls past underneath it.
112
+ ship.updateVisual(deltaTime);
91
113
 
92
114
  const state = frameCtx.state.getState();
93
115
  frameCtx.state.set({
@@ -96,11 +118,16 @@ export class Sailing extends Scene<GameState, IPhysicsContext> {
96
118
  paused: state.paused,
97
119
  shipZ: ship.mesh.position.z,
98
120
  status,
99
- submergedFraction: ship.buoyancy.submergedFraction,
121
+ submergedFraction: ship.immersion,
100
122
  uiReady: frameCtx.state.getState().uiReady,
101
123
  wind,
102
124
  });
103
- followShip(camera, ship.mesh.position);
125
+ // The **visual**, not the body. `Ship` draws the hull from `ship.visual`, whose y is the sea
126
+ // surface; `ship.mesh` is the physics body, whose y wanders on a throttled height copy and
127
+ // is no longer what anything is drawn at. Following the body pointed the camera somewhere
128
+ // the ship was not: the horizon slid up and down behind a hull that was itself steady, so
129
+ // the ship read as bobbing out of the water and back into it.
130
+ followShip(camera, ship.visual.position);
104
131
  };
105
132
  }
106
133
  }
@@ -27,6 +27,26 @@ body {
27
27
  background: #061b2b;
28
28
  }
29
29
 
30
+ /* Boot failures are a page state, so the generated game owns their presentation. */
31
+ [data-threenative-canvas-error="true"] {
32
+ position: fixed;
33
+ inset: 0;
34
+ z-index: 1000;
35
+ display: grid;
36
+ place-items: center;
37
+ box-sizing: border-box;
38
+ padding: clamp(1.5rem, 8vw, 6rem);
39
+ overflow: auto;
40
+ background: #fff7ed;
41
+ color: var(--color-ink);
42
+ font-family: inherit;
43
+ font-size: clamp(1rem, 2vw, 1.5rem);
44
+ line-height: 1.5;
45
+ text-align: center;
46
+ white-space: pre-wrap;
47
+ overflow-wrap: anywhere;
48
+ }
49
+
30
50
  /* The debug surface is framework plumbing; its default presentation is yours to change. */
31
51
  [data-threenative-debug-overlay="true"] {
32
52
  position: fixed;
@@ -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: { backgroundColor: "#061b2b" },
@@ -26,8 +27,13 @@ const config: IThreeNativeConfig = {
26
27
  renderer: {
27
28
  preferWebGPU: true,
28
29
  resolutionScale: "auto",
30
+ // Multisampling resolves triangle edges. A cutout silhouette — foliage, a fence, hair — is
31
+ // carved inside the triangle by an alpha test, so it resolves through the coverage mask or
32
+ // not at all, which is what this spends the samples above on. It costs no target and no
33
+ // extra pass; set it false for a deliberately hard-edged look. `TN_ALPHA_ANTIALIASING`
34
+ // reports what it did, and says so when a single-sampled surface leaves it nothing to do.
35
+ alphaAntialiasing: true,
29
36
  },
30
- assets: { models: "none", textures: "none" },
31
37
  ui: { renderer: "web" },
32
38
  };
33
39
 
@@ -13,3 +13,7 @@ args = ["./node_modules/@threenative/core/mcp/sculpt.mjs"]
13
13
  [mcp_servers.threenative-engine]
14
14
  command = "node"
15
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
+ }