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
@@ -0,0 +1,86 @@
1
+ // The starter's painterly look: an ink outline, a Kuwahara smear, and a watercolour wash.
2
+ //
3
+ // This file exists because `worldEnvironment.ts` may not contain it. That file is the render-chain
4
+ // plumbing every kit copies verbatim, and `shared-render-sources.spec.ts` fails when one kit's copy
5
+ // stops matching the others — which is exactly what happens when a kit's own art direction is
6
+ // written into it. Bloom and vignette live in there because they are grading primitives every kit
7
+ // wants; kuwahara, outline and watercolour are one kit's aesthetic, and an aesthetic shipped into
8
+ // ten kits so that one can use it is the preset system the charter closed with evidence.
9
+ //
10
+ // So the plumbing exposes a seam — `authoredStageNames` and `authoredStages` — and this is what the
11
+ // starter passes through it.
12
+
13
+ import { createKuwaharaStage } from "./kuwahara.js";
14
+ import { createOutlineStage } from "./outline.js";
15
+ import { createWatercolorStage } from "./watercolor.js";
16
+ import type { ChainStage, IWorldEnvironmentStageContext } from "./worldEnvironment.js";
17
+
18
+ /** The knobs the quality presets set. Every one is this kit's, not the framework's. */
19
+ export interface IPainterlyOptions {
20
+ readonly outlineEnabled?: boolean;
21
+ readonly outlineInkColor?: number;
22
+ readonly outlineStrength?: number;
23
+ readonly outlineThreshold?: number;
24
+ readonly outlineSoftness?: number;
25
+ readonly outlineDepthWeight?: number;
26
+ readonly kuwaharaEnabled?: boolean;
27
+ readonly kuwaharaRadius?: number;
28
+ readonly kuwaharaResolutionScale?: number;
29
+ readonly kuwaharaAnisotropy?: number;
30
+ readonly kuwaharaStrength?: number;
31
+ readonly watercolorEnabled?: boolean;
32
+ readonly watercolorLevels?: number;
33
+ readonly watercolorPaperStrength?: number;
34
+ readonly watercolorShadowStrength?: number;
35
+ readonly watercolorShadowTint?: number;
36
+ readonly watercolorStrength?: number;
37
+ }
38
+
39
+ /**
40
+ * Which stages run, in chain order.
41
+ *
42
+ * The chain reads this before the scene pass exists — with nothing requested it sets an exposure
43
+ * and never builds a pass at all — so it has to be answerable from the options alone.
44
+ */
45
+ export function painterlyStageNames(options: IPainterlyOptions): readonly string[] {
46
+ const names: string[] = [];
47
+ if (options.outlineEnabled === true) names.push("outline");
48
+ if (options.kuwaharaEnabled === true) names.push("kuwahara");
49
+ if (options.watercolorEnabled === true) names.push("watercolor");
50
+ return names;
51
+ }
52
+
53
+ /**
54
+ * The complete authored graph, dormant stages included.
55
+ *
56
+ * All three are always defined even when only one is requested, because `watercolor after
57
+ * kuwahara` and `kuwahara after outline` are anchors that must keep naming a stage that exists —
58
+ * otherwise enabling one stage on its own resolves against a name the chain never heard of.
59
+ */
60
+ export function painterlyStages(
61
+ options: IPainterlyOptions,
62
+ ): (context: IWorldEnvironmentStageContext) => readonly ChainStage[] {
63
+ return ({ depthNode }) => [
64
+ createOutlineStage({
65
+ depthNode,
66
+ depthWeight: options.outlineDepthWeight ?? 0.65,
67
+ inkColor: options.outlineInkColor ?? 0x142331,
68
+ softness: options.outlineSoftness ?? 0.16,
69
+ strength: options.outlineStrength ?? 0.8,
70
+ threshold: options.outlineThreshold ?? 0.12,
71
+ }),
72
+ createKuwaharaStage({
73
+ anisotropy: options.kuwaharaAnisotropy ?? 0.72,
74
+ radius: options.kuwaharaRadius ?? 5,
75
+ resolutionScale: options.kuwaharaResolutionScale ?? 0.5,
76
+ strength: options.kuwaharaStrength ?? 0.82,
77
+ }),
78
+ createWatercolorStage({
79
+ levels: options.watercolorLevels ?? 8,
80
+ paperStrength: options.watercolorPaperStrength ?? 0.2,
81
+ shadowStrength: options.watercolorShadowStrength ?? 0.16,
82
+ shadowTint: options.watercolorShadowTint ?? 0x6d5a52,
83
+ strength: options.watercolorStrength ?? 0.72,
84
+ }),
85
+ ];
86
+ }
@@ -1,9 +1,18 @@
1
1
  // Generated for you. Keep the six palette roles coherent when you change the look.
2
2
  export const palette = {
3
- skyHigh: 0x12324a,
4
- skyLow: 0x071018,
5
- floor: 0x12384a,
6
- player: 0x6fe8ff,
7
- crate: 0xffb86b,
8
- accent: 0xffd27a,
3
+ skyHigh: 0x8fd5cf,
4
+ skyLow: 0x28556a,
5
+ floor: 0x67c878,
6
+ player: 0xfff0b0,
7
+ crate: 0xd86f55,
8
+ accent: 0xe6c58d,
9
9
  } as const;
10
+
11
+ export const COAST_WAVES = [
12
+ { amplitude: 0.12, direction: [1, 0.2] as const, speed: 0.52, wavelength: 7.2 },
13
+ { amplitude: 0.055, detail: true, direction: [-0.35, 1] as const, speed: 0.3, wavelength: 3.3 },
14
+ ] as const;
15
+
16
+ export const COAST_DOMAIN_WARP = [
17
+ { amplitude: 0.12, direction: [0.65, -0.35] as const, speed: 0.18, wavelength: 11 },
18
+ ] as const;
@@ -1,49 +1,100 @@
1
1
  // Generated for you: ordinary Three.js; ThreeNative does not read this file.
2
2
  //
3
- // `WorldEnvironment` (in this folder) builds the lighting chain: which stages run, in what
4
- // order, and an honest report of what happened — the chain prints `TN_RENDER_CHAIN` naming
5
- // every stage as applied or refused with a reason. It decides no colour and no strength;
6
- // the values below are arguments, and they are yours.
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.
7
8
  //
8
- // The two presets are the PRD-278 default: SSGI and SSR are interior-scale stages that the
9
- // starter's small outdoor scene does not need at mobile frame budgets, so they ship off
10
- // there; on desktop they are on. Every stage's cost and the one-line enable for the rest
11
- // (godrays, contact AO, vignette) is `agent-docs/visual-baseline.md`.
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.
12
13
  import type { Camera, DirectionalLight, Scene } from "three";
13
- import { WorldEnvironment } from "./worldEnvironment.js";
14
- import type { OutputRenderer } from "./worldEnvironment.js";
14
+ import {
15
+ type IAdaptiveQualityOptions,
16
+ type IQualityWindow,
17
+ createAdaptiveQuality,
18
+ formatQualityAdaptation,
19
+ } from "./adaptiveQuality.js";
20
+ import { painterlyStageNames, painterlyStages } from "./painterly.js";
21
+ import { type QualityTier, qualityPreset } from "./quality.js";
22
+ import { type OutputRenderer, WorldEnvironment } from "./worldEnvironment.js";
15
23
 
16
- const sharpenStrength = 0.28;
24
+ interface IPostController {
25
+ debug(): Record<string, unknown>;
26
+ observe(window: IQualityWindow): void;
27
+ dispose(): void;
28
+ }
17
29
 
18
- const desktopPreset = {
19
- ssgiEnabled: true,
20
- ssgiQuality: "medium",
21
- denoiseEnabled: true,
22
- ssrEnabled: true,
23
- ssrResolutionScale: 0.5,
24
- bloomEnabled: true,
25
- bloomStrength: 0.7,
26
- sharpenEnabled: true,
27
- sharpenStrength,
28
- tonemapMode: "aces",
29
- exposure: 1.15,
30
- } as const;
30
+ let active: IPostController | undefined;
31
31
 
32
- const mobilePreset = {
33
- bloomEnabled: true,
34
- bloomStrength: 0.7,
35
- sharpenEnabled: true,
36
- sharpenStrength,
37
- tonemapMode: "aces",
38
- exposure: 1.15,
39
- } as const;
32
+ /** The starter's game.ts connects its existing completed frame-window callback here. */
33
+ export function observeQualityWindow(window: IQualityWindow): void {
34
+ active?.observe(window);
35
+ }
40
36
 
41
37
  export function setupPost(
42
38
  renderer: OutputRenderer,
43
39
  scene: Scene,
44
40
  camera: Camera,
45
- environment: { godraysLight?: DirectionalLight; mobile?: boolean } = {},
46
- ): void {
47
- const world = new WorldEnvironment(environment.mobile === true ? mobilePreset : desktopPreset);
48
- world.apply(renderer, scene, camera, { godraysLight: environment.godraysLight });
41
+ environment: IAdaptiveQualityOptions & {
42
+ godraysLight?: DirectionalLight;
43
+ mobile?: boolean;
44
+ /** Forces a tier while keeping its costs observed. Unknown names throw. */
45
+ tier?: QualityTier;
46
+ } = {},
47
+ ): IPostController {
48
+ const policy = createAdaptiveQuality(environment, environment);
49
+ active?.dispose();
50
+ let disposed = false;
51
+ let disposeGraph: (() => void) | undefined;
52
+ let observation: Record<string, unknown> = {
53
+ tier: policy.tier,
54
+ source: policy.pinned ? "pinned" : "auto",
55
+ };
56
+ function apply(): void {
57
+ // Replacement is serialized: no old graph or subscription remains alive beside the new one.
58
+ disposeGraph?.();
59
+ const settings = qualityPreset(policy.tier);
60
+ const world = new WorldEnvironment({
61
+ ...settings,
62
+ authoredStageNames: painterlyStageNames(settings),
63
+ authoredStages: painterlyStages(settings),
64
+ });
65
+ const applied = world.apply(renderer, scene, camera, {
66
+ godraysLight: environment.godraysLight,
67
+ });
68
+ disposeGraph = applied.dispose;
69
+ observation = { ...observation, stages: applied.stages, dropped: applied.dropped };
70
+ }
71
+ apply();
72
+ const source = environment.tier === undefined ? "platform" : "override";
73
+ console.info(
74
+ `TN_QUALITY_TIER ${policy.tier} mobile=${environment.mobile === true} source=${source}`,
75
+ );
76
+ const controller = {
77
+ debug: () => observation,
78
+ observe(window: IQualityWindow): void {
79
+ if (disposed) return;
80
+ const decision = policy.observe(window);
81
+ if (decision.changed) apply();
82
+ observation = {
83
+ stages: observation.stages,
84
+ dropped: observation.dropped,
85
+ ...decision,
86
+ ...(Number.isInteger(window.window) ? { window: window.window } : {}),
87
+ };
88
+ console.info(formatQualityAdaptation(decision));
89
+ },
90
+ dispose(): void {
91
+ if (disposed) return;
92
+ disposed = true;
93
+ disposeGraph?.();
94
+ disposeGraph = undefined;
95
+ if (active === controller) active = undefined;
96
+ },
97
+ };
98
+ active = controller;
99
+ return controller;
49
100
  }
@@ -0,0 +1,185 @@
1
+ // Generated for you: ordinary Three.js; ThreeNative does not read this file. Delete or rewrite
2
+ // it freely — the tiers below are a starting point, not a framework look.
3
+ //
4
+ // This is the one place this game decides how expensive it looks. `postprocessing.ts` reads
5
+ // `qualityPreset(resolveQualityTier(...))` and nothing else, so "make it run on a phone" is one
6
+ // file to edit rather than a hunt through anonymous literals.
7
+ //
8
+ // **Where the numbers come from.** Every millisecond below is GPU time from the per-stage
9
+ // ablation recorded in the engine repository's `docs/verification/runtime-perf-state.md`: Chrome
10
+ // on an RTX 2080, 1600x900, static build, `gpuMs` read from three's `timestamp-query`. In that
11
+ // scene the whole five-stage chain costs **12.5 ms of a 14.7 ms GPU frame**, and the same frame
12
+ // with every stage off costs **2.2 ms**. The per-stage figures oversum — removing SSGI also
13
+ // removes the denoise passes the later stages sample — so read each as *what turning this one off
14
+ // gave back*, not as a share of a partition. A stage nobody has ablated on its own says
15
+ // `unmeasured` rather than guessing, and your scene is not that scene: read `TN_FRAME_BUDGET`
16
+ // back after you change a tier.
17
+ //
18
+ // One cost that is **not** a stage here and outweighs most of them: the prefiltered reflection
19
+ // probe on `scene.environment`, measured at **~6.3 ms of an 18-19 ms Pixel 8 frame**. It is set
20
+ // in `sky.ts`, not in this file.
21
+ //
22
+ import type { IPainterlyOptions } from "./painterly.js";
23
+ import type { IWorldEnvironmentOptions } from "./worldEnvironment.js";
24
+
25
+ /**
26
+ * A preset is the framework's chain options plus this kit's own painterly knobs. The two are
27
+ * separate types because they belong to different layers: `worldEnvironment.ts` is shared with
28
+ * every other kit and must not know what a watercolour is.
29
+ */
30
+ type QualitySettings = IWorldEnvironmentOptions & IPainterlyOptions;
31
+
32
+ /**
33
+ * The three names this game's look comes in.
34
+ *
35
+ * `low` is what a phone gets and `high` what a desktop gets — those two are this template's
36
+ * shipped looks, unchanged. `medium` is the rung in between for a machine that is neither: a
37
+ * laptop iGPU, a handheld, a desktop that is dropping frames. Nothing outside this file decides
38
+ * what any of them mean.
39
+ */
40
+ export type QualityTier = "low" | "medium" | "high";
41
+
42
+ const QUALITY_TIERS: readonly QualityTier[] = ["low", "medium", "high"];
43
+
44
+ /**
45
+ * Narrows an arbitrary string — a URL parameter, a saved setting — to a tier name. Not exported:
46
+ * `resolveQualityTier` is the one door in, so an unknown name cannot be waved past the throw.
47
+ */
48
+ function isQualityTier(value: string): value is QualityTier {
49
+ return (QUALITY_TIERS as readonly string[]).includes(value);
50
+ }
51
+
52
+ /**
53
+ * Picks the tier: an explicit `tier` always wins, otherwise the platform decides.
54
+ *
55
+ * Fails closed. An unrecognised tier name throws with the value it was handed rather than
56
+ * quietly rendering the default, because a silent fallback here looks exactly like a tier that
57
+ * turned out to have no effect.
58
+ */
59
+ export function resolveQualityTier(
60
+ request: { readonly mobile?: boolean; readonly tier?: string } = {},
61
+ ): QualityTier {
62
+ const requested = request.tier;
63
+ if (requested !== undefined) {
64
+ if (!isQualityTier(requested)) {
65
+ throw new Error(
66
+ `Unknown quality tier ${JSON.stringify(requested)} — expected one of ${QUALITY_TIERS.join(", ")}.`,
67
+ );
68
+ }
69
+ return requested;
70
+ }
71
+ return request.mobile === true ? "low" : "high";
72
+ }
73
+
74
+ /**
75
+ * What a desktop gets: a clean coastal look with restrained painterly treatment. The expensive
76
+ * screen-space gathers are deliberately off here: on a small water scene they muddy the grass and
77
+ * turn the water glint into a halo instead of adding useful depth.
78
+ */
79
+ const high: QualitySettings = {
80
+ // Bloom cost: unmeasured for this authored scene; the low strength keeps water glints alive
81
+ // without washing the scene in orange.
82
+ bloomEnabled: true,
83
+ bloomRadius: 0.34,
84
+ bloomStrength: 0.26,
85
+ bloomThreshold: 0.64,
86
+ denoiseEnabled: false,
87
+ exposure: 1.04,
88
+ ssgiEnabled: false,
89
+ ssrEnabled: false,
90
+ sharpenEnabled: false,
91
+ // Outline cost: unmeasured; it is intentionally a soft blue-green edge, not a black
92
+ // comic-book stroke.
93
+ outlineEnabled: true,
94
+ outlineDepthWeight: 0.32,
95
+ outlineInkColor: 0x173c4a,
96
+ outlineSoftness: 0.08,
97
+ outlineStrength: 0.3,
98
+ outlineThreshold: 0.2,
99
+ // Kuwahara cost: unmeasured; the half-resolution scratch and restrained strength preserve
100
+ // readable grass silhouettes.
101
+ kuwaharaEnabled: true,
102
+ kuwaharaRadius: 5,
103
+ kuwaharaResolutionScale: 0.5,
104
+ kuwaharaStrength: 0.2,
105
+ // Watercolour cost: unmeasured; the low mix keeps the paper grouping from flattening the coast.
106
+ watercolorEnabled: true,
107
+ watercolorPaperStrength: 0.05,
108
+ watercolorShadowStrength: 0.04,
109
+ watercolorShadowTint: 0x7d6b62,
110
+ watercolorStrength: 0.26,
111
+ renderChainTier: "high",
112
+ tonemapMode: "aces",
113
+ };
114
+
115
+ /**
116
+ * Medium keeps the same readable coast, with a smaller paint radius and a little less colour
117
+ * grouping for machines that need a cheaper frame.
118
+ */
119
+ const medium: QualitySettings = {
120
+ // Bloom cost: unmeasured for this authored scene; keep only a small highlight lift.
121
+ bloomEnabled: true,
122
+ bloomRadius: 0.3,
123
+ bloomStrength: 0.22,
124
+ bloomThreshold: 0.68,
125
+ denoiseEnabled: false,
126
+ exposure: 1.03,
127
+ ssgiEnabled: false,
128
+ ssrEnabled: false,
129
+ sharpenEnabled: false,
130
+ // Outline cost: unmeasured; keep its edge narrow on the cheaper tier.
131
+ outlineEnabled: true,
132
+ outlineDepthWeight: 0.28,
133
+ outlineInkColor: 0x173c4a,
134
+ outlineSoftness: 0.08,
135
+ outlineStrength: 0.26,
136
+ outlineThreshold: 0.22,
137
+ // Kuwahara cost: unmeasured; radius three keeps the water and grass readable.
138
+ kuwaharaEnabled: true,
139
+ kuwaharaRadius: 3,
140
+ kuwaharaResolutionScale: 0.5,
141
+ kuwaharaStrength: 0.16,
142
+ // Watercolour cost: unmeasured; fewer bands and a low mix preserve the coast's value steps.
143
+ watercolorEnabled: true,
144
+ watercolorLevels: 6,
145
+ watercolorPaperStrength: 0.04,
146
+ watercolorShadowStrength: 0.03,
147
+ watercolorShadowTint: 0x7d6b62,
148
+ watercolorStrength: 0.22,
149
+ renderChainTier: "medium",
150
+ tonemapMode: "aces",
151
+ };
152
+
153
+ /**
154
+ * What a phone gets: the cleanest version of the coastal look. Authored paint is omitted to keep
155
+ * the water mesh and touch controls responsive.
156
+ */
157
+ const low: QualitySettings = {
158
+ // Bloom cost: unmeasured for this authored scene; this is the phone-safe highlight lift.
159
+ bloomEnabled: true,
160
+ bloomRadius: 0.28,
161
+ bloomStrength: 0.18,
162
+ bloomThreshold: 0.72,
163
+ exposure: 1.02,
164
+ sharpenEnabled: false,
165
+ // The low tier omits authored paint by name: no outline, scratch target, or paper graph is
166
+ // built on the phone path.
167
+ outlineEnabled: false,
168
+ kuwaharaEnabled: false,
169
+ watercolorEnabled: false,
170
+ renderChainTier: "low",
171
+ tonemapMode: "aces",
172
+ };
173
+
174
+ const QUALITY_PRESETS: Record<QualityTier, QualitySettings> = { high, low, medium };
175
+
176
+ /** The stages and strengths a tier turns on. Throws on a name that is not a tier. */
177
+ export function qualityPreset(tier: string): QualitySettings {
178
+ const preset = QUALITY_PRESETS[tier as QualityTier];
179
+ if (preset === undefined) {
180
+ throw new Error(
181
+ `Unknown quality tier ${JSON.stringify(tier)} — expected one of ${QUALITY_TIERS.join(", ")}.`,
182
+ );
183
+ }
184
+ return preset;
185
+ }
@@ -0,0 +1,198 @@
1
+ // Generated source. The field, seed and refinement quality belong to this game.
2
+ import { BufferAttribute, BufferGeometry, Group, type Material, Mesh } from "three";
3
+ import { auditImplicitSurface, buildImplicitSurface } from "./implicitSurface.js";
4
+ import {
5
+ type IRockRidgeWorkerInput,
6
+ type IRockRidgeWorkerMessage,
7
+ createRockRidgeWorkerSource,
8
+ } from "./rockRidge.worker.js";
9
+ // biome-ignore format: compact generated bounds keep the render source under its smell budget.
10
+ const ROCK_RIDGE_BOUNDS = { maxX: 54, maxY: 18, maxZ: -42, minX: -54, minY: -32, minZ: -74 } as const;
11
+ const PREVIEW_SETTINGS = { cellSize: 10, latticeCap: 30_000, protectBoundary: true } as const;
12
+ const REFINED_SETTINGS = { cellSize: 8, latticeCap: 100_000, protectBoundary: true } as const;
13
+ // biome-ignore format: the generated field stays within the render-source smell budget.
14
+ export function sampleGraniteField(x: number, y: number, z: number, seed: number, bounds: IRockRidgeWorkerInput["bounds"]): number {
15
+ const phase = ((seed >>> 0) % 4096) * 0.0015;
16
+ const noise = (index: number): number => {
17
+ let value = Math.imul((index | 0) ^ (seed | 0), 0x45d9f3b);
18
+ value = Math.imul(value ^ (value >>> 16), 0x45d9f3b);
19
+ return ((value ^ (value >>> 16)) >>> 0) / 4_294_967_295;
20
+ };
21
+ const smoothMin = (a: number, b: number, radius: number): number => {
22
+ const h = Math.max(radius - Math.abs(a - b), 0) / radius;
23
+ return Math.min(a, b) - h * h * h * radius / 6;
24
+ };
25
+ const centerZ = -58 + Math.sin(x * 0.08 + phase) * 1.2 + Math.cos(x * 0.17 - phase) * 0.7;
26
+ const top = -5 + Math.sin(x * 0.13 + phase * 2) * 0.8;
27
+ const contactY = -20;
28
+ const bottom = contactY - 2 + Math.cos(x * 0.07 - phase) * 0.45;
29
+ let field = Math.hypot(x / 50, (y - (top + bottom) * 0.5) / ((top - bottom) * 0.5), (z - centerZ) / 12) - 1;
30
+ for (let index = -4; index <= 4; index += 1) {
31
+ const jitter = noise(index + 31);
32
+ const lobeX = index * 11 + (jitter - 0.5) * 3;
33
+ const lobeZ = centerZ + (noise(index + 61) - 0.5) * 3;
34
+ const lobeY = -5 + (noise(index + 91) - 0.5) * 2;
35
+ const lobe = Math.hypot((x - lobeX) / (6.4 + noise(index + 121) * 2.2), (y - lobeY) / (8.5 + noise(index + 151) * 3), (z - lobeZ) / (6.5 + noise(index + 181) * 2)) - 1;
36
+ field = smoothMin(field, lobe, 0.22);
37
+ }
38
+ const edge = Math.min(x - bounds.minX, bounds.maxX - x, y - bounds.minY, bounds.maxY - y, z - bounds.minZ, bounds.maxZ - z);
39
+ return Math.max(field, 0.06 - edge / 4);
40
+ }
41
+ function hashArray(array: Float32Array | Uint32Array): string {
42
+ const bytes = new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
43
+ let hash = 2_166_136_261;
44
+ for (const byte of bytes) hash = Math.imul(hash ^ byte, 16_777_619);
45
+ return (hash >>> 0).toString(16).padStart(8, "0");
46
+ }
47
+ // biome-ignore format: compact generated validation keeps the render source under its smell budget.
48
+ function topologyError(report: ReturnType<typeof auditImplicitSurface>): Error | undefined {
49
+ if (report.boundaryEdges === 0 && report.degenerateTriangles === 0 && report.windingConflicts === 0 && report.signedVolume > 0)
50
+ return undefined;
51
+ const error = new Error(`boundary=${report.boundaryEdges}, degenerate=${report.degenerateTriangles}, winding=${report.windingConflicts}, volume=${report.signedVolume}`);
52
+ error.name = "TN_ROCK_RIDGE_TOPOLOGY_INVALID";
53
+ return error;
54
+ }
55
+ // biome-ignore format: compact generated mesh attachment keeps the render source under its smell budget.
56
+ function makeMesh(result: ReturnType<typeof buildImplicitSurface>, material: Material, generation: number): { mesh: Mesh; report: ReturnType<typeof auditImplicitSurface> } {
57
+ const report = auditImplicitSurface(result.indices, result.positions);
58
+ const error = topologyError(report);
59
+ if (error !== undefined) throw error;
60
+ const geometry = new BufferGeometry();
61
+ geometry.setAttribute("position", new BufferAttribute(result.positions, 3));
62
+ geometry.setIndex(new BufferAttribute(result.indices, 1));
63
+ geometry.computeVertexNormals();
64
+ geometry.computeBoundingBox();
65
+ geometry.computeBoundingSphere();
66
+ const mesh = new Mesh(geometry, material);
67
+ mesh.name = `granite-ridge-${generation === 0 ? "preview" : "refined"}`;
68
+ mesh.castShadow = false;
69
+ mesh.receiveShadow = false;
70
+ return { mesh, report };
71
+ }
72
+ // biome-ignore format: compact generated controller contract keeps the render source under budget.
73
+ export interface IRockRidgeController { readonly object: Group; readonly state: "preview" | "refined" | "error" | "disposed"; debug(): Record<string, unknown>; dispose(): void; rebuild(seed?: number): void; }
74
+ // biome-ignore format: the controller is a single generated render source with a fixed budget.
75
+ export function createRockRidge(ridgeMaterial: Material, initialSeed: number, options: { deferRefinement?: boolean } = {}): IRockRidgeController {
76
+ const object = new Group();
77
+ object.name = "granite-ridge";
78
+ const preview = buildImplicitSurface({
79
+ ...PREVIEW_SETTINGS, bounds: ROCK_RIDGE_BOUNDS, closed: true,
80
+ sample: (x, y, z) => sampleGraniteField(x, y, z, initialSeed, ROCK_RIDGE_BOUNDS),
81
+ });
82
+ let visible = makeMesh(preview, ridgeMaterial, 0);
83
+ object.add(visible.mesh);
84
+ const state = {
85
+ phase: "preview" as IRockRidgeController["state"],
86
+ visibleGeneration: 0,
87
+ requestedGeneration: 0,
88
+ lastError: undefined as string | undefined,
89
+ report: { ...visible.report, buildMs: preview.report.buildMs, cellSize: preview.report.cellSize },
90
+ };
91
+ const workers = new Set<Worker>();
92
+ const workerSource = createRockRidgeWorkerSource(sampleGraniteField);
93
+ const stop = (worker: Worker): void => {
94
+ if (!workers.delete(worker)) return;
95
+ worker.terminate();
96
+ };
97
+ const fail = (error: unknown): void => {
98
+ state.phase = "error";
99
+ state.lastError = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
100
+ for (const worker of [...workers]) stop(worker);
101
+ };
102
+ const swap = (result: ReturnType<typeof buildImplicitSurface>, generation: number, buildMs: number, cellSize: number): void => {
103
+ const next = makeMesh(result, ridgeMaterial, generation);
104
+ const previous = visible.mesh;
105
+ object.add(next.mesh);
106
+ visible = next;
107
+ state.visibleGeneration = generation;
108
+ state.report = { ...next.report, buildMs, cellSize };
109
+ object.remove(previous);
110
+ previous.geometry.dispose();
111
+ };
112
+ const dispatch = (seed: number, settings: typeof REFINED_SETTINGS): void => {
113
+ const generation = state.requestedGeneration + 1;
114
+ state.requestedGeneration = generation;
115
+ if (typeof Worker === "undefined" || typeof URL.createObjectURL !== "function") {
116
+ const error = new Error("TN_ROCK_RIDGE_WORKER_FAILED: classic Worker support is required.");
117
+ fail(error);
118
+ throw error;
119
+ }
120
+ const url = URL.createObjectURL(new Blob([workerSource], { type: "text/javascript" }));
121
+ let worker: Worker;
122
+ try {
123
+ worker = new Worker(url);
124
+ } catch (error) {
125
+ URL.revokeObjectURL(url);
126
+ fail(error);
127
+ throw error;
128
+ }
129
+ URL.revokeObjectURL(url);
130
+ workers.add(worker);
131
+ // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: stale-result and error guards stay atomic.
132
+ worker.onmessage = (event: MessageEvent<IRockRidgeWorkerMessage>) => {
133
+ stop(worker);
134
+ const message = event.data;
135
+ if (state.phase === "disposed" || message.generation !== state.requestedGeneration) return;
136
+ if (message.error !== undefined || message.positions === undefined || message.indices === undefined || message.report === undefined) {
137
+ fail(new Error(`${message.name ?? "TN_ROCK_RIDGE_WORKER_FAILED"}: ${message.error ?? "missing result"}`));
138
+ return;
139
+ }
140
+ try {
141
+ const result = { positions: message.positions, indices: message.indices, report: message.report } as ReturnType<typeof buildImplicitSurface>;
142
+ const report = auditImplicitSurface(result.indices, result.positions);
143
+ const error = topologyError(report);
144
+ if (error !== undefined) throw error;
145
+ if (report.boundaryEdges !== message.report.boundaryEdges || report.degenerateTriangles !== message.report.degenerateTriangles || report.windingConflicts !== message.report.windingConflicts)
146
+ throw new Error("TN_ROCK_RIDGE_WORKER_FAILED: report does not match final arrays.");
147
+ swap(result, message.generation, message.report.buildMs, message.report.cellSize);
148
+ state.phase = "refined";
149
+ } catch (error) {
150
+ fail(error);
151
+ }
152
+ };
153
+ worker.onerror = (event) => {
154
+ stop(worker);
155
+ if (state.phase !== "disposed" && generation === state.requestedGeneration)
156
+ fail(new Error(`TN_ROCK_RIDGE_WORKER_FAILED: ${event.message || "worker error"}`));
157
+ };
158
+ try {
159
+ const input: IRockRidgeWorkerInput = {
160
+ bounds: ROCK_RIDGE_BOUNDS, cellSize: settings.cellSize, generation,
161
+ latticeCap: settings.latticeCap, protectBoundary: settings.protectBoundary, seed,
162
+ };
163
+ worker.postMessage(input);
164
+ } catch (error) {
165
+ stop(worker);
166
+ fail(error);
167
+ throw error;
168
+ }
169
+ };
170
+ if (options.deferRefinement !== true) dispatch(initialSeed, REFINED_SETTINGS);
171
+ return {
172
+ object,
173
+ get state() {
174
+ return state.phase;
175
+ },
176
+ debug: () => ({
177
+ state: state.phase,
178
+ generation: state.visibleGeneration,
179
+ requestedGeneration: state.requestedGeneration,
180
+ positionHash: hashArray(visible.mesh.geometry.getAttribute("position").array as Float32Array),
181
+ indexHash: hashArray(visible.mesh.geometry.index?.array as Uint32Array),
182
+ topology: state.report,
183
+ ...(state.lastError === undefined ? {} : { error: state.lastError }),
184
+ }),
185
+ dispose: () => {
186
+ if (state.phase === "disposed") return;
187
+ state.phase = "disposed";
188
+ state.requestedGeneration += 1;
189
+ for (const worker of [...workers]) stop(worker);
190
+ object.remove(visible.mesh);
191
+ visible.mesh.geometry.dispose();
192
+ },
193
+ rebuild: (seed = initialSeed) => {
194
+ if (state.phase === "disposed") return;
195
+ dispatch(seed, REFINED_SETTINGS);
196
+ },
197
+ };
198
+ }