create-threenative 0.2.3 → 0.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (447) hide show
  1. package/README.md +53 -2
  2. package/agent-docs/references/assertion-reference.md +173 -6
  3. package/agent-docs/references/capability-reference.md +1303 -99
  4. package/agent-docs/references/capture-the-frame.md +7 -0
  5. package/agent-docs/references/creating-creatures.md +215 -0
  6. package/agent-docs/references/ctx-cookbook.md +69 -0
  7. package/agent-docs/references/debug-surface.md +8 -3
  8. package/agent-docs/references/dream-loop.md +150 -0
  9. package/agent-docs/references/finding-assets.md +70 -2
  10. package/agent-docs/references/sculpt-from-a-reference.md +3 -2
  11. package/agent-docs/references/trace-a-slow-frame.md +99 -0
  12. package/agent-docs/references/visual-baseline.md +41 -0
  13. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
  14. package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
  15. package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
  16. package/agent-files/.agents/skills/threenative-builder/SKILL.md +1 -1
  17. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
  18. package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
  19. package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
  20. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
  21. package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
  22. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +1 -1
  23. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
  24. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
  25. package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
  26. package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
  27. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
  28. package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
  29. package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
  30. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
  31. package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
  32. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
  33. package/agent-files/scripts/reference.mjs +705 -0
  34. package/agent-files/scripts/visual-loop.mjs +382 -0
  35. package/capabilities.json +1881 -131
  36. package/dist/index.d.ts +39 -6
  37. package/dist/index.js +297 -32
  38. package/dist/threenative.js +822 -105
  39. package/package.json +30 -5
  40. package/template-assets/loading.ts +12 -2
  41. package/template-assets/patches/three@0.185.1.patch +249 -14
  42. package/template-assets/worldEnvironment.ts +758 -0
  43. package/templates/action-rpg/.codex/config.toml +4 -0
  44. package/templates/action-rpg/.cursor/mcp.json +32 -0
  45. package/templates/action-rpg/.gemini/settings.json +32 -0
  46. package/templates/action-rpg/.mcp.json +15 -3
  47. package/templates/action-rpg/.vscode/mcp.json +36 -0
  48. package/templates/action-rpg/.zed/settings.json +36 -0
  49. package/templates/action-rpg/AGENTS.md +69 -378
  50. package/templates/action-rpg/CLAUDE.md +69 -378
  51. package/templates/action-rpg/opencode.json +41 -0
  52. package/templates/action-rpg/package.json +7 -7
  53. package/templates/action-rpg/playtests/combat.playtest.json +9 -0
  54. package/templates/action-rpg/playtests/performance.playtest.json +24 -7
  55. package/templates/action-rpg/playtests/survives.playtest.json +27 -0
  56. package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
  57. package/templates/action-rpg/src/conventions.ts +35 -0
  58. package/templates/action-rpg/src/entities/Enemy.ts +2 -3
  59. package/templates/action-rpg/src/entities/Player.ts +20 -3
  60. package/templates/action-rpg/src/render/camera.ts +7 -2
  61. package/templates/action-rpg/src/render/lighting.ts +5 -3
  62. package/templates/action-rpg/src/render/loading.ts +12 -2
  63. package/templates/action-rpg/src/render/materials.ts +11 -0
  64. package/templates/action-rpg/src/render/palette.ts +10 -3
  65. package/templates/action-rpg/src/render/postprocessing.ts +21 -58
  66. package/templates/action-rpg/src/render/quality.ts +170 -0
  67. package/templates/action-rpg/src/render/shapes.ts +185 -26
  68. package/templates/action-rpg/src/render/touch-controls.ts +185 -0
  69. package/templates/action-rpg/src/render/vfx.ts +257 -0
  70. package/templates/action-rpg/src/render/worldEnvironment.ts +208 -33
  71. package/templates/action-rpg/src/scenes/Play.ts +43 -6
  72. package/templates/action-rpg/src/style.css +20 -0
  73. package/templates/action-rpg/threenative.config.ts +7 -0
  74. package/templates/defense/.codex/config.toml +4 -0
  75. package/templates/defense/.cursor/mcp.json +32 -0
  76. package/templates/defense/.gemini/settings.json +32 -0
  77. package/templates/defense/.mcp.json +15 -3
  78. package/templates/defense/.vscode/mcp.json +36 -0
  79. package/templates/defense/.zed/settings.json +36 -0
  80. package/templates/defense/AGENTS.md +62 -385
  81. package/templates/defense/CLAUDE.md +62 -385
  82. package/templates/defense/opencode.json +41 -0
  83. package/templates/defense/package.json +7 -7
  84. package/templates/defense/playtests/performance.playtest.json +24 -7
  85. package/templates/defense/playtests/pointer-placement.playtest.json +87 -20
  86. package/templates/defense/playtests/scan.playtest.json +1 -1
  87. package/templates/defense/playtests/survive.playtest.json +14 -0
  88. package/templates/defense/src/attackers/Attacker.ts +4 -4
  89. package/templates/defense/src/board/Route.ts +22 -8
  90. package/templates/defense/src/conventions.ts +18 -0
  91. package/templates/defense/src/entities/Player.ts +11 -3
  92. package/templates/defense/src/game.ts +2 -3
  93. package/templates/defense/src/physics.ts +9 -39
  94. package/templates/defense/src/placement/Buildable.ts +4 -4
  95. package/templates/defense/src/render/camera.ts +9 -3
  96. package/templates/defense/src/render/loading.ts +12 -2
  97. package/templates/defense/src/render/materials.ts +9 -0
  98. package/templates/defense/src/render/palette.ts +12 -5
  99. package/templates/defense/src/render/postprocessing.ts +21 -58
  100. package/templates/defense/src/render/quality.ts +170 -0
  101. package/templates/defense/src/render/shapes.ts +142 -23
  102. package/templates/defense/src/render/sky.ts +2 -2
  103. package/templates/defense/src/render/worldEnvironment.ts +208 -33
  104. package/templates/defense/src/scenes/Boot.ts +2 -2
  105. package/templates/defense/src/scenes/Defense.ts +13 -6
  106. package/templates/defense/src/style.css +20 -0
  107. package/templates/defense/src/towers/Tower.ts +11 -12
  108. package/templates/defense/src/towers/targeting.ts +1 -1
  109. package/templates/defense/src/ui/App.tsx +2 -2
  110. package/templates/defense/threenative.config.ts +7 -0
  111. package/templates/minimal/.codex/config.toml +4 -0
  112. package/templates/minimal/.cursor/mcp.json +32 -0
  113. package/templates/minimal/.gemini/settings.json +32 -0
  114. package/templates/minimal/.mcp.json +15 -3
  115. package/templates/minimal/.vscode/mcp.json +36 -0
  116. package/templates/minimal/.zed/settings.json +36 -0
  117. package/templates/minimal/AGENTS.md +76 -485
  118. package/templates/minimal/CLAUDE.md +76 -485
  119. package/templates/minimal/opencode.json +41 -0
  120. package/templates/minimal/package.json +6 -6
  121. package/templates/minimal/playtests/play.playtest.json +2 -1
  122. package/templates/minimal/playtests/survives.playtest.json +48 -4
  123. package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
  124. package/templates/minimal/src/conventions.ts +18 -0
  125. package/templates/minimal/src/entities/Player.ts +39 -6
  126. package/templates/minimal/src/main.ts +14 -4
  127. package/templates/minimal/src/render/materials.ts +7 -0
  128. package/templates/minimal/src/render/palette.ts +3 -3
  129. package/templates/minimal/src/render/postprocessing.ts +17 -56
  130. package/templates/minimal/src/render/quality.ts +162 -0
  131. package/templates/minimal/src/render/sky.ts +23 -9
  132. package/templates/minimal/src/render/touch-controls.ts +165 -0
  133. package/templates/minimal/src/render/worldEnvironment.ts +208 -33
  134. package/templates/minimal/src/scenes/Play.ts +47 -11
  135. package/templates/minimal/src/style.css +20 -0
  136. package/templates/minimal/threenative.config.ts +7 -0
  137. package/templates/platformer/.codex/config.toml +4 -0
  138. package/templates/platformer/.cursor/mcp.json +32 -0
  139. package/templates/platformer/.gemini/settings.json +32 -0
  140. package/templates/platformer/.mcp.json +15 -3
  141. package/templates/platformer/.vscode/mcp.json +36 -0
  142. package/templates/platformer/.zed/settings.json +36 -0
  143. package/templates/platformer/AGENTS.md +70 -430
  144. package/templates/platformer/CLAUDE.md +70 -430
  145. package/templates/platformer/opencode.json +41 -0
  146. package/templates/platformer/package.json +7 -7
  147. package/templates/platformer/playtests/oneway.playtest.json +29 -2
  148. package/templates/platformer/playtests/performance.playtest.json +2 -1
  149. package/templates/platformer/playtests/survives.playtest.json +31 -0
  150. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +3 -0
  151. package/templates/platformer/playtests/touch-controls-web.playtest.json +15 -4
  152. package/templates/platformer/src/conventions.ts +18 -0
  153. package/templates/platformer/src/entities/Character.ts +63 -1
  154. package/templates/platformer/src/game.ts +3 -1
  155. package/templates/platformer/src/level/Platform.ts +13 -1
  156. package/templates/platformer/src/render/lighting.ts +7 -4
  157. package/templates/platformer/src/render/loading.ts +12 -2
  158. package/templates/platformer/src/render/palette.ts +4 -1
  159. package/templates/platformer/src/render/postprocessing.ts +32 -57
  160. package/templates/platformer/src/render/quality.ts +170 -0
  161. package/templates/platformer/src/render/worldEnvironment.ts +208 -33
  162. package/templates/platformer/src/scenes/Level.ts +52 -12
  163. package/templates/platformer/src/style.css +20 -0
  164. package/templates/platformer/threenative.config.ts +7 -0
  165. package/templates/puzzle/.codex/config.toml +19 -0
  166. package/templates/puzzle/.cursor/mcp.json +32 -0
  167. package/templates/puzzle/.gemini/settings.json +32 -0
  168. package/templates/puzzle/.mcp.json +32 -0
  169. package/templates/puzzle/.vscode/mcp.json +36 -0
  170. package/templates/puzzle/.zed/settings.json +36 -0
  171. package/templates/puzzle/AGENTS.md +96 -0
  172. package/templates/puzzle/CLAUDE.md +98 -0
  173. package/templates/puzzle/README.md +43 -0
  174. package/templates/puzzle/index.html +12 -0
  175. package/templates/puzzle/kit.json +7 -0
  176. package/templates/puzzle/opencode.json +41 -0
  177. package/templates/puzzle/package.json +50 -0
  178. package/templates/puzzle/playtests/carry.playtest.json +71 -0
  179. package/templates/puzzle/playtests/performance.playtest.json +23 -0
  180. package/templates/puzzle/playtests/survives.playtest.json +51 -0
  181. package/templates/puzzle/playtests/swing.playtest.json +38 -0
  182. package/templates/puzzle/public/favicon.svg +5 -0
  183. package/templates/puzzle/src/conventions.ts +25 -0
  184. package/templates/puzzle/src/entities/Ball.ts +70 -0
  185. package/templates/puzzle/src/entities/Crate.ts +76 -0
  186. package/templates/puzzle/src/entities/Gripper.ts +69 -0
  187. package/templates/puzzle/src/entities/Pendulum.ts +89 -0
  188. package/templates/puzzle/src/game.ts +48 -0
  189. package/templates/puzzle/src/main.ts +15 -0
  190. package/templates/puzzle/src/physics.ts +19 -0
  191. package/templates/puzzle/src/render/camera.ts +37 -0
  192. package/templates/puzzle/src/render/lighting.ts +55 -0
  193. package/templates/puzzle/src/render/loading.ts +325 -0
  194. package/templates/puzzle/src/render/materials.ts +28 -0
  195. package/templates/puzzle/src/render/palette.ts +31 -0
  196. package/templates/puzzle/src/render/postprocessing.ts +34 -0
  197. package/templates/puzzle/src/render/quality.ts +170 -0
  198. package/templates/puzzle/src/render/shapes.ts +134 -0
  199. package/templates/puzzle/src/render/sky.ts +16 -0
  200. package/templates/puzzle/src/render/touch-controls.ts +185 -0
  201. package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
  202. package/templates/puzzle/src/room.ts +83 -0
  203. package/templates/puzzle/src/scenes/Boot.ts +12 -0
  204. package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
  205. package/templates/puzzle/src/state.ts +30 -0
  206. package/templates/puzzle/src/style.css +96 -0
  207. package/templates/puzzle/src/ui/App.tsx +22 -0
  208. package/templates/puzzle/src/ui/GameUi.tsx +20 -0
  209. package/templates/puzzle/src/ui/Hud.tsx +57 -0
  210. package/templates/puzzle/src/ui/Menu.tsx +7 -0
  211. package/templates/puzzle/src/ui/main.tsx +14 -0
  212. package/templates/puzzle/tailwind.config.ts +1 -0
  213. package/templates/puzzle/threenative.config.ts +49 -0
  214. package/templates/puzzle/tsconfig.json +17 -0
  215. package/templates/puzzle/vite.config.ts +38 -0
  216. package/templates/racing/.codex/config.toml +4 -0
  217. package/templates/racing/.cursor/mcp.json +32 -0
  218. package/templates/racing/.gemini/settings.json +32 -0
  219. package/templates/racing/.mcp.json +15 -3
  220. package/templates/racing/.vscode/mcp.json +36 -0
  221. package/templates/racing/.zed/settings.json +36 -0
  222. package/templates/racing/AGENTS.md +63 -379
  223. package/templates/racing/CLAUDE.md +63 -379
  224. package/templates/racing/native-playtests/survives.playtest.json +43 -0
  225. package/templates/racing/opencode.json +41 -0
  226. package/templates/racing/package.json +8 -7
  227. package/templates/racing/playtests/performance.playtest.json +24 -7
  228. package/templates/racing/playtests/survives.playtest.json +36 -4
  229. package/templates/racing/playtests/touch-controls.playtest.json +41 -0
  230. package/templates/racing/src/conventions.ts +6 -0
  231. package/templates/racing/src/entities/RacingCar.ts +16 -4
  232. package/templates/racing/src/entities/Rival.ts +5 -2
  233. package/templates/racing/src/render/camera.ts +7 -4
  234. package/templates/racing/src/render/lighting.ts +22 -13
  235. package/templates/racing/src/render/loading.ts +12 -2
  236. package/templates/racing/src/render/materials.ts +54 -4
  237. package/templates/racing/src/render/palette.ts +23 -6
  238. package/templates/racing/src/render/postprocessing.ts +21 -58
  239. package/templates/racing/src/render/quality.ts +170 -0
  240. package/templates/racing/src/render/shapes.ts +537 -26
  241. package/templates/racing/src/render/sky.ts +5 -2
  242. package/templates/racing/src/render/touch-controls.ts +185 -0
  243. package/templates/racing/src/render/worldEnvironment.ts +208 -33
  244. package/templates/racing/src/scenes/Race.ts +17 -2
  245. package/templates/racing/src/style.css +20 -0
  246. package/templates/racing/src/track/Track.ts +270 -31
  247. package/templates/racing/threenative.config.ts +7 -0
  248. package/templates/runner/.codex/config.toml +19 -0
  249. package/templates/runner/.cursor/mcp.json +32 -0
  250. package/templates/runner/.gemini/settings.json +32 -0
  251. package/templates/runner/.mcp.json +32 -0
  252. package/templates/runner/.vscode/mcp.json +36 -0
  253. package/templates/runner/.zed/settings.json +36 -0
  254. package/templates/runner/AGENTS.md +96 -0
  255. package/templates/runner/CLAUDE.md +98 -0
  256. package/templates/runner/README.md +43 -0
  257. package/templates/runner/index.html +12 -0
  258. package/templates/runner/kit.json +7 -0
  259. package/templates/runner/opencode.json +41 -0
  260. package/templates/runner/package.json +50 -0
  261. package/templates/runner/playtests/performance.playtest.json +23 -0
  262. package/templates/runner/playtests/streams.playtest.json +38 -0
  263. package/templates/runner/playtests/survives.playtest.json +51 -0
  264. package/templates/runner/public/favicon.svg +5 -0
  265. package/templates/runner/src/conventions.ts +24 -0
  266. package/templates/runner/src/entities/Runner.ts +135 -0
  267. package/templates/runner/src/game.ts +50 -0
  268. package/templates/runner/src/main.ts +15 -0
  269. package/templates/runner/src/physics.ts +13 -0
  270. package/templates/runner/src/render/camera.ts +39 -0
  271. package/templates/runner/src/render/dust.ts +131 -0
  272. package/templates/runner/src/render/lighting.ts +57 -0
  273. package/templates/runner/src/render/loading.ts +325 -0
  274. package/templates/runner/src/render/materials.ts +27 -0
  275. package/templates/runner/src/render/palette.ts +30 -0
  276. package/templates/runner/src/render/postprocessing.ts +34 -0
  277. package/templates/runner/src/render/quality.ts +170 -0
  278. package/templates/runner/src/render/shapes.ts +68 -0
  279. package/templates/runner/src/render/sky.ts +51 -0
  280. package/templates/runner/src/render/touch-controls.ts +185 -0
  281. package/templates/runner/src/render/worldEnvironment.ts +758 -0
  282. package/templates/runner/src/scenes/Boot.ts +12 -0
  283. package/templates/runner/src/scenes/Run.ts +142 -0
  284. package/templates/runner/src/state.ts +29 -0
  285. package/templates/runner/src/style.css +96 -0
  286. package/templates/runner/src/track.ts +176 -0
  287. package/templates/runner/src/ui/App.tsx +22 -0
  288. package/templates/runner/src/ui/GameUi.tsx +20 -0
  289. package/templates/runner/src/ui/Hud.tsx +55 -0
  290. package/templates/runner/src/ui/Menu.tsx +7 -0
  291. package/templates/runner/src/ui/main.tsx +14 -0
  292. package/templates/runner/tailwind.config.ts +1 -0
  293. package/templates/runner/threenative.config.ts +49 -0
  294. package/templates/runner/tsconfig.json +17 -0
  295. package/templates/runner/vite.config.ts +38 -0
  296. package/templates/sailing/.codex/config.toml +4 -0
  297. package/templates/sailing/.cursor/mcp.json +32 -0
  298. package/templates/sailing/.gemini/settings.json +32 -0
  299. package/templates/sailing/.mcp.json +15 -3
  300. package/templates/sailing/.vscode/mcp.json +36 -0
  301. package/templates/sailing/.zed/settings.json +36 -0
  302. package/templates/sailing/AGENTS.md +62 -355
  303. package/templates/sailing/CLAUDE.md +62 -355
  304. package/templates/sailing/README.md +12 -9
  305. package/templates/sailing/native-playtests/float.playtest.json +55 -0
  306. package/templates/sailing/native-playtests/survives.playtest.json +20 -3
  307. package/templates/sailing/opencode.json +41 -0
  308. package/templates/sailing/package.json +8 -8
  309. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
  310. package/templates/sailing/playtests/float.playtest.json +59 -0
  311. package/templates/sailing/playtests/performance.playtest.json +21 -6
  312. package/templates/sailing/playtests/survives.playtest.json +8 -0
  313. package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
  314. package/templates/sailing/src/conventions.ts +8 -0
  315. package/templates/sailing/src/entities/Ship.ts +150 -13
  316. package/templates/sailing/src/render/camera.ts +15 -8
  317. package/templates/sailing/src/render/lighting.ts +10 -5
  318. package/templates/sailing/src/render/loading.ts +12 -2
  319. package/templates/sailing/src/render/materials.ts +24 -8
  320. package/templates/sailing/src/render/ocean.ts +179 -0
  321. package/templates/sailing/src/render/palette.ts +14 -21
  322. package/templates/sailing/src/render/postprocessing.ts +23 -22
  323. package/templates/sailing/src/render/props.ts +584 -34
  324. package/templates/sailing/src/render/quality.ts +140 -0
  325. package/templates/sailing/src/render/sky.ts +8 -3
  326. package/templates/sailing/src/render/touch-controls.ts +142 -0
  327. package/templates/sailing/src/render/worldEnvironment.ts +206 -38
  328. package/templates/sailing/src/scenes/Sailing.ts +43 -16
  329. package/templates/sailing/src/style.css +20 -0
  330. package/templates/sailing/threenative.config.ts +7 -1
  331. package/templates/shooter/.codex/config.toml +4 -0
  332. package/templates/shooter/.cursor/mcp.json +32 -0
  333. package/templates/shooter/.gemini/settings.json +32 -0
  334. package/templates/shooter/.mcp.json +15 -3
  335. package/templates/shooter/.vscode/mcp.json +36 -0
  336. package/templates/shooter/.zed/settings.json +36 -0
  337. package/templates/shooter/AGENTS.md +76 -415
  338. package/templates/shooter/CLAUDE.md +76 -415
  339. package/templates/shooter/kit.json +2 -2
  340. package/templates/shooter/opencode.json +41 -0
  341. package/templates/shooter/package.json +7 -7
  342. package/templates/shooter/playtests/combat.playtest.json +48 -0
  343. package/templates/shooter/playtests/input-control.playtest.json +165 -35
  344. package/templates/shooter/playtests/per-item.playtest.json +3 -3
  345. package/templates/shooter/playtests/performance.playtest.json +24 -7
  346. package/templates/shooter/playtests/shooter.playtest.json +13 -7
  347. package/templates/shooter/playtests/survives.playtest.json +27 -0
  348. package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
  349. package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
  350. package/templates/shooter/src/combat/damage.ts +1 -2
  351. package/templates/shooter/src/conventions.ts +51 -0
  352. package/templates/shooter/src/entities/Player.ts +235 -18
  353. package/templates/shooter/src/entities/Target.ts +2 -2
  354. package/templates/shooter/src/game.ts +13 -4
  355. package/templates/shooter/src/render/camera.ts +49 -39
  356. package/templates/shooter/src/render/decals.ts +211 -0
  357. package/templates/shooter/src/render/lighting.ts +7 -3
  358. package/templates/shooter/src/render/loading.ts +12 -2
  359. package/templates/shooter/src/render/materials.ts +56 -3
  360. package/templates/shooter/src/render/palette.ts +6 -3
  361. package/templates/shooter/src/render/postprocessing.ts +21 -58
  362. package/templates/shooter/src/render/quality.ts +170 -0
  363. package/templates/shooter/src/render/scale.ts +22 -0
  364. package/templates/shooter/src/render/shapes.ts +343 -62
  365. package/templates/shooter/src/render/sky.ts +5 -1
  366. package/templates/shooter/src/render/touch-controls.ts +305 -0
  367. package/templates/shooter/src/render/ui.css +85 -0
  368. package/templates/shooter/src/render/ui.ts +19 -3
  369. package/templates/shooter/src/render/vfx.ts +215 -0
  370. package/templates/shooter/src/render/worldEnvironment.ts +208 -33
  371. package/templates/shooter/src/scenes/Play.ts +171 -56
  372. package/templates/shooter/src/state.ts +5 -0
  373. package/templates/shooter/src/style.css +20 -0
  374. package/templates/shooter/src/ui/Crosshair.tsx +25 -0
  375. package/templates/shooter/src/ui/GameUi.tsx +2 -0
  376. package/templates/shooter/src/ui/Hud.tsx +7 -1
  377. package/templates/shooter/src/weapons/Hitscan.ts +3 -4
  378. package/templates/shooter/src/weapons/Projectile.ts +8 -3
  379. package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
  380. package/templates/shooter/threenative.config.ts +7 -0
  381. package/templates/starter/.codex/config.toml +4 -0
  382. package/templates/starter/.cursor/mcp.json +32 -0
  383. package/templates/starter/.gemini/settings.json +32 -0
  384. package/templates/starter/.mcp.json +15 -3
  385. package/templates/starter/.vscode/mcp.json +36 -0
  386. package/templates/starter/.zed/settings.json +36 -0
  387. package/templates/starter/AGENTS.md +70 -527
  388. package/templates/starter/CLAUDE.md +70 -527
  389. package/templates/starter/native-playtests/render-chain.playtest.json +73 -4
  390. package/templates/starter/opencode.json +41 -0
  391. package/templates/starter/package.json +7 -7
  392. package/templates/starter/playtests/boot-failure.playtest.json +45 -0
  393. package/templates/starter/playtests/look.playtest.json +110 -6
  394. package/templates/starter/playtests/play.playtest.json +3 -2
  395. package/templates/starter/playtests/survives.playtest.json +21 -0
  396. package/templates/starter/playtests/touch-controls.playtest.json +42 -0
  397. package/templates/starter/src/conventions.ts +18 -0
  398. package/templates/starter/src/entities/Goal.ts +18 -3
  399. package/templates/starter/src/entities/Player.ts +72 -9
  400. package/templates/starter/src/game.ts +2 -0
  401. package/templates/starter/src/render/adaptiveQuality.ts +195 -0
  402. package/templates/starter/src/render/camera.ts +1 -1
  403. package/templates/starter/src/render/coast.ts +199 -0
  404. package/templates/starter/src/render/hero.ts +88 -0
  405. package/templates/starter/src/render/implicitSurface.ts +199 -0
  406. package/templates/starter/src/render/kuwahara.ts +174 -0
  407. package/templates/starter/src/render/lighting.ts +4 -4
  408. package/templates/starter/src/render/loading.ts +12 -2
  409. package/templates/starter/src/render/materials.ts +25 -6
  410. package/templates/starter/src/render/outline.ts +141 -0
  411. package/templates/starter/src/render/painterly.ts +86 -0
  412. package/templates/starter/src/render/palette.ts +15 -6
  413. package/templates/starter/src/render/postprocessing.ts +87 -36
  414. package/templates/starter/src/render/quality.ts +185 -0
  415. package/templates/starter/src/render/rockRidge.ts +198 -0
  416. package/templates/starter/src/render/rockRidge.worker.ts +77 -0
  417. package/templates/starter/src/render/scenery.ts +16 -59
  418. package/templates/starter/src/render/textureLifetime.ts +53 -0
  419. package/templates/starter/src/render/touch-controls.ts +165 -0
  420. package/templates/starter/src/render/water.ts +38 -0
  421. package/templates/starter/src/render/watercolor.ts +85 -0
  422. package/templates/starter/src/render/worldEnvironment.ts +208 -33
  423. package/templates/starter/src/scenes/Play.ts +103 -16
  424. package/templates/starter/src/style.css +27 -7
  425. package/templates/starter/threenative.config.ts +7 -7
  426. package/agent-docs/asset-mcp-loop.md +0 -33
  427. package/agent-docs/ctx-surface.md +0 -69
  428. package/agent-docs/engine-capabilities.md +0 -4
  429. package/agent-docs/framework-blocks-you.md +0 -60
  430. package/agent-docs/look-at-it-and-budget-the-look.md +0 -27
  431. package/agent-docs/performance-default.md +0 -42
  432. package/agent-docs/pixel-budget.md +0 -20
  433. package/agent-docs/playtest-fail-closed.md +0 -23
  434. package/agent-docs/sculpt-loop.md +0 -16
  435. package/templates/action-rpg/src/physics.ts +0 -40
  436. package/templates/defense/public/icon.png +0 -0
  437. package/templates/minimal/public/icon.png +0 -0
  438. package/templates/platformer/public/icon.png +0 -0
  439. package/templates/racing/public/icon.png +0 -0
  440. package/templates/sailing/public/icon.png +0 -0
  441. package/templates/sailing/src/render/water-material.ts +0 -14
  442. package/templates/sailing/src/render/water-shaders.ts +0 -12
  443. package/templates/sailing/src/render/wave-nodes.ts +0 -10
  444. package/templates/shooter/public/icon.png +0 -0
  445. package/templates/shooter/src/physics.ts +0 -49
  446. package/templates/starter/public/icon.png +0 -0
  447. /package/{templates/action-rpg/public → template-assets}/icon.png +0 -0
@@ -0,0 +1,77 @@
1
+ // Generated source. The worker is a classic Blob worker so browser and native use one path.
2
+ import { createImplicitSurfaceWorkerSource } from "./implicitSurface.js";
3
+
4
+ export interface IRockRidgeWorkerInput {
5
+ readonly bounds: Readonly<Record<"maxX" | "maxY" | "maxZ" | "minX" | "minY" | "minZ", number>>;
6
+ readonly cellSize: number;
7
+ readonly generation: number;
8
+ readonly latticeCap: number;
9
+ readonly protectBoundary: boolean;
10
+ readonly seed: number;
11
+ }
12
+
13
+ export interface IRockRidgeWorkerReport {
14
+ readonly boundaryEdges: number;
15
+ readonly buildMs: number;
16
+ readonly cellSize: number;
17
+ readonly degenerateTriangles: number;
18
+ readonly signedVolume: number;
19
+ readonly triangles: number;
20
+ readonly vertices: number;
21
+ readonly windingConflicts: number;
22
+ }
23
+
24
+ export interface IRockRidgeWorkerMessage {
25
+ readonly error?: string;
26
+ readonly generation: number;
27
+ readonly indices?: Uint32Array;
28
+ readonly name?: string;
29
+ readonly positions?: Float32Array;
30
+ readonly report?: IRockRidgeWorkerReport;
31
+ }
32
+
33
+ export function createRockRidgeWorkerSource(
34
+ sampleField: (
35
+ x: number,
36
+ y: number,
37
+ z: number,
38
+ seed: number,
39
+ bounds: IRockRidgeWorkerInput["bounds"],
40
+ ) => number,
41
+ ): string {
42
+ const extractor = createImplicitSurfaceWorkerSource();
43
+ const field = sampleField.toString();
44
+ return `${extractor}
45
+ const sampleGraniteField = ${field};
46
+ self.onmessage = function (event) {
47
+ const input = event.data;
48
+ try {
49
+ const result = buildImplicitSurface({
50
+ bounds: input.bounds,
51
+ cellSize: input.cellSize,
52
+ closed: true,
53
+ latticeCap: input.latticeCap,
54
+ protectBoundary: input.protectBoundary,
55
+ sample: function (x, y, z) {
56
+ return sampleGraniteField(x, y, z, input.seed, input.bounds);
57
+ },
58
+ });
59
+ self.postMessage(
60
+ {
61
+ generation: input.generation,
62
+ indices: result.indices,
63
+ positions: result.positions,
64
+ report: result.report,
65
+ },
66
+ [result.indices.buffer, result.positions.buffer],
67
+ );
68
+ } catch (error) {
69
+ self.postMessage({
70
+ error: error instanceof Error ? error.message : String(error),
71
+ generation: input.generation,
72
+ name: error instanceof Error ? error.name : "TN_ROCK_RIDGE_WORKER_FAILED",
73
+ });
74
+ }
75
+ };
76
+ `;
77
+ }
@@ -1,32 +1,19 @@
1
- // Generated for you. This is ordinary Three.js — edit or delete it freely.
1
+ // Generated for you. This is ordinary Three.js — edit its visual choices freely.
2
2
  // ThreeNative does not read this file.
3
3
  //
4
4
  // The half of the world that has no collider. None of this is reachable and none of it
5
- // is simulated; it exists because a lit slab alone in black reads as a test fixture, and
6
- // because two thirds of a 16:9 frame is above the playable floor. Columns give the ledge
7
- // a below, the ridge gives the sky a behind, and the silhouette of both is what makes a
8
- // screenshot look composed rather than empty.
5
+ // is simulated; it is the distant silhouette behind the coastal play space.
9
6
  //
10
- // Delete this file and the game plays identically — which is the point of it living here
11
- // rather than anywhere a rule could grow around it.
12
- import { Group, type Material } from "three";
7
+ // Play.enter imports and invokes createScenery, so deleting this live source without updating
8
+ // that caller breaks the build. Editing the backdrop leaves gameplay rules and colliders unchanged.
9
+ import type { Material } from "three";
10
+ import { type IRockRidgeController, createRockRidge } from "./rockRidge.js";
13
11
  import { block } from "./shapes.js";
14
12
 
15
- /** Column tops, so each one meets the underside of the thing it is holding up. */
16
- const COLUMNS = [
17
- { depth: 1.3, top: -0.2, width: 1.7, x: -3.4, z: -0.5 },
18
- { depth: 1.6, top: -0.2, width: 2.1, x: 1.4, z: 0.4 },
19
- { depth: 1.4, top: -0.8, width: 1.5, x: 8.0, z: -0.2 },
13
+ const REEF_ROCKS = [
14
+ { depth: 1.4, height: 1.35, top: -0.35, width: 1.9, x: -3.4, z: -0.5 },
15
+ { depth: 1.6, height: 1.1, top: -0.32, width: 2.1, x: 1.4, z: 0.4 },
20
16
  ] as const;
21
- const COLUMN_HEIGHT = 16;
22
- /** Spires between the ledge and the horizon, as `[x, z, width]`. */
23
- const MIDGROUND = [
24
- [-13.5, -19, 3.6],
25
- [-6, -27, 2.8],
26
- [4.5, -23, 3.2],
27
- [15, -17, 3],
28
- ] as const;
29
-
30
17
  /**
31
18
  * @param random Seeded source for the ridge, handed in by the scene — see `src/scenes/Play.ts`,
32
19
  * which builds it with the framework's `createRandom`. It arrives as an argument rather than as
@@ -37,47 +24,17 @@ export function createScenery(
37
24
  rockMaterial: Material,
38
25
  ridgeMaterial: Material,
39
26
  random: () => number,
40
- ): Group {
41
- const scenery = new Group();
42
- for (const { depth, top, width, x, z } of COLUMNS) {
43
- const column = block(width, COLUMN_HEIGHT, depth, rockMaterial, {
27
+ ): IRockRidgeController {
28
+ const ridgeSeed = Math.floor(random() * 4_294_967_295) >>> 0;
29
+ const scenery = createRockRidge(ridgeMaterial, ridgeSeed, { deferRefinement: true });
30
+ for (const { depth, height, top, width, x, z } of REEF_ROCKS) {
31
+ const rock = block(width, height, depth, rockMaterial, {
44
32
  castShadow: false,
45
33
  radius: 0.3,
46
34
  receiveShadow: false,
47
35
  });
48
- column.position.set(x, top - COLUMN_HEIGHT / 2, z);
49
- scenery.add(column);
50
- }
51
-
52
- // Far enough back that the scene's own fog does the aerial perspective for free, and big
53
- // enough to still read at that range. Move them closer and they stop being a horizon and
54
- // start being props standing behind the level.
55
- // Seeded, never Math.random: the ridge has to be byte-identical on every reload or a
56
- // screenshot diff is comparing two different worlds. The source arrives from the scene.
57
- for (let index = 0; index < 9; index += 1) {
58
- const height = 12 + random() * 20;
59
- const width = 12 + random() * 14;
60
- const ridge = block(width, height, 8, ridgeMaterial, {
61
- castShadow: false,
62
- radius: 1.5,
63
- receiveShadow: false,
64
- });
65
- // Inside the sky dome's 90-unit radius. Push one past it and the dome, drawn on its
66
- // back faces, simply hides it — a ridge that exists, costs a draw, and never appears.
67
- ridge.position.set(-44 + index * 11 + random() * 5, height / 2 - 20, -56 - random() * 12);
68
- scenery.add(ridge);
69
- }
70
-
71
- // One band between the ledge and the horizon. Two depths read as a backdrop; three read
72
- // as distance, and the middle one is the cheapest of the three to add.
73
- for (const [x, z, size] of MIDGROUND) {
74
- const spire = block(size, size * 2.4, size * 0.9, rockMaterial, {
75
- castShadow: false,
76
- radius: 0.4,
77
- receiveShadow: false,
78
- });
79
- spire.position.set(x, size * 1.2 - 6, z);
80
- scenery.add(spire);
36
+ rock.position.set(x, top - height / 2, z);
37
+ scenery.object.add(rock);
81
38
  }
82
39
  return scenery;
83
40
  }
@@ -0,0 +1,53 @@
1
+ import { convertToTexture } from "three/tsl";
2
+ import type { Node } from "three/webgpu";
3
+
4
+ interface ITextureResource {
5
+ readonly isRTTNode: true;
6
+ readonly renderTarget: { dispose(): void };
7
+ readonly _quadMesh: { material: { dispose(): void } };
8
+ }
9
+
10
+ function hasRttMarker(value: unknown): value is { readonly isRTTNode: true } {
11
+ return (
12
+ typeof value === "object" &&
13
+ value !== null &&
14
+ (value as { isRTTNode?: unknown }).isRTTNode === true
15
+ );
16
+ }
17
+
18
+ function isTextureResource(value: unknown): value is ITextureResource {
19
+ if (!hasRttMarker(value)) return false;
20
+ const resource = value as {
21
+ renderTarget?: { dispose?: unknown } | null;
22
+ _quadMesh?: { material?: { dispose?: unknown } } | null;
23
+ };
24
+ return (
25
+ typeof resource.renderTarget?.dispose === "function" &&
26
+ typeof resource._quadMesh?.material?.dispose === "function"
27
+ );
28
+ }
29
+
30
+ /** Owns only RTT nodes created by this stage; ordinary and shared texture nodes remain external. */
31
+ export function createTextureScope() {
32
+ const owned = new Set<ITextureResource>();
33
+ return {
34
+ texture(input: Node): Node {
35
+ const output = convertToTexture(input);
36
+ if (output !== input && hasRttMarker(output)) this.own(output);
37
+ return output;
38
+ },
39
+ own<T>(newRtt: T): T {
40
+ if (!isTextureResource(newRtt))
41
+ throw new Error("texture scope requires a disposable RTTNode.");
42
+ owned.add(newRtt);
43
+ return newRtt;
44
+ },
45
+ dispose(): void {
46
+ for (const resource of owned) {
47
+ resource.renderTarget.dispose();
48
+ resource._quadMesh.material.dispose();
49
+ }
50
+ owned.clear();
51
+ },
52
+ };
53
+ }
@@ -0,0 +1,165 @@
1
+ import {
2
+ CircleGeometry,
3
+ type ColorRepresentation,
4
+ Group,
5
+ MathUtils,
6
+ Mesh,
7
+ MeshBasicMaterial,
8
+ type PerspectiveCamera,
9
+ RingGeometry,
10
+ Vector2,
11
+ } from "three";
12
+ import { palette } from "./palette.js";
13
+
14
+ const MOVE_RADIUS = 72;
15
+ const BUTTON_RADIUS = 62;
16
+ const EDGE = 36;
17
+
18
+ export interface ITouchPointer {
19
+ readonly position: Vector2;
20
+ }
21
+
22
+ export interface ITouchViewport {
23
+ readonly height: number;
24
+ readonly width: number;
25
+ }
26
+
27
+ export interface ITouchInput {
28
+ readonly jumpPressed: boolean;
29
+ readonly move: Vector2;
30
+ }
31
+
32
+ function overlayMaterial(color: ColorRepresentation, opacity: number): MeshBasicMaterial {
33
+ return new MeshBasicMaterial({
34
+ color,
35
+ depthTest: false,
36
+ depthWrite: false,
37
+ opacity,
38
+ transparent: true,
39
+ });
40
+ }
41
+
42
+ function ringMesh(radius: number, material: MeshBasicMaterial): Mesh {
43
+ return new Mesh(new RingGeometry(radius - 5, radius, 32), material);
44
+ }
45
+
46
+ function place(mesh: Mesh, point: Vector2): void {
47
+ mesh.position.set(point.x, point.y, 0);
48
+ }
49
+
50
+ function controlPoint(size: ITouchViewport, name: "jump" | "move"): Vector2 {
51
+ if (name === "move") return new Vector2(MOVE_RADIUS + EDGE, size.height - MOVE_RADIUS - EDGE);
52
+ return new Vector2(size.width - BUTTON_RADIUS - EDGE, size.height - BUTTON_RADIUS - EDGE);
53
+ }
54
+
55
+ export class TouchControls {
56
+ readonly root = new Group();
57
+ readonly object = this.root;
58
+ #camera: PerspectiveCamera;
59
+ #input: { jumpPressed: boolean; move: Vector2 } = {
60
+ jumpPressed: false,
61
+ move: new Vector2(),
62
+ };
63
+ #wasJump = false;
64
+ #moveAnchor = new Vector2();
65
+ #resting = new Vector2();
66
+ #jumpCenter = new Vector2();
67
+ #hasMoveAnchor = false;
68
+ #lastWidth = -1;
69
+ #lastHeight = -1;
70
+ #moveBase: Mesh;
71
+ #moveKnob: Mesh;
72
+ #jump: Mesh;
73
+ #idleMaterial: MeshBasicMaterial;
74
+ #activeMaterial: MeshBasicMaterial;
75
+
76
+ constructor(camera: PerspectiveCamera) {
77
+ this.#camera = camera;
78
+ this.#idleMaterial = overlayMaterial(palette.floor, 0.34);
79
+ this.#activeMaterial = overlayMaterial(palette.accent, 0.6);
80
+ this.#moveBase = ringMesh(MOVE_RADIUS, this.#idleMaterial);
81
+ this.#moveKnob = new Mesh(new CircleGeometry(28, 24), this.#activeMaterial);
82
+ this.#jump = ringMesh(BUTTON_RADIUS, this.#idleMaterial);
83
+ this.root.add(this.#moveBase, this.#moveKnob, this.#jump);
84
+ this.root.renderOrder = 10_001;
85
+ camera.add(this.root);
86
+ }
87
+
88
+ update(pointers: ReadonlyMap<number, ITouchPointer>, size: ITouchViewport): ITouchInput {
89
+ this.#ensureLayout(size);
90
+ const jump = this.#at(pointers, this.#jumpCenter, BUTTON_RADIUS);
91
+ let movement: ITouchPointer | undefined;
92
+ for (const pointer of pointers.values()) {
93
+ if (pointer.position.x < size.width * 0.5) {
94
+ movement = pointer;
95
+ break;
96
+ }
97
+ }
98
+
99
+ if (movement === undefined) {
100
+ this.#hasMoveAnchor = false;
101
+ this.#input.move.set(0, 0);
102
+ } else {
103
+ if (!this.#hasMoveAnchor) {
104
+ this.#moveAnchor.copy(movement.position);
105
+ this.#hasMoveAnchor = true;
106
+ }
107
+ this.#input.move.set(
108
+ MathUtils.clamp((movement.position.x - this.#moveAnchor.x) / MOVE_RADIUS, -1, 1),
109
+ MathUtils.clamp((this.#moveAnchor.y - movement.position.y) / MOVE_RADIUS, -1, 1),
110
+ );
111
+ }
112
+
113
+ const center = this.#hasMoveAnchor ? this.#moveAnchor : this.#resting;
114
+ place(
115
+ this.#moveKnob,
116
+ new Vector2(
117
+ center.x + this.#input.move.x * MOVE_RADIUS,
118
+ center.y - this.#input.move.y * MOVE_RADIUS,
119
+ ),
120
+ );
121
+ this.#jump.material = jump ? this.#activeMaterial : this.#idleMaterial;
122
+ this.#input.jumpPressed = jump && !this.#wasJump;
123
+ this.#wasJump = jump;
124
+ this.#layout(size);
125
+ return this.#input;
126
+ }
127
+
128
+ debug(): Record<string, unknown> {
129
+ return { jump: this.#wasJump, move: this.#input.move.toArray() };
130
+ }
131
+
132
+ dispose(): void {
133
+ this.root.removeFromParent();
134
+ for (const child of this.root.children) {
135
+ if (child instanceof Mesh) child.geometry.dispose();
136
+ }
137
+ this.#idleMaterial.dispose();
138
+ this.#activeMaterial.dispose();
139
+ }
140
+
141
+ #ensureLayout(size: ITouchViewport): void {
142
+ if (size.width === this.#lastWidth && size.height === this.#lastHeight) return;
143
+ this.#lastWidth = size.width;
144
+ this.#lastHeight = size.height;
145
+ this.#resting.copy(controlPoint(size, "move"));
146
+ this.#jumpCenter.copy(controlPoint(size, "jump"));
147
+ }
148
+
149
+ #layout(size: ITouchViewport): void {
150
+ const worldHeight = 2 * Math.tan(MathUtils.degToRad(this.#camera.fov / 2));
151
+ const pixels = worldHeight / Math.max(1, size.height);
152
+ this.root.position.set(-(size.width * pixels) / 2, worldHeight / 2, -1);
153
+ this.root.scale.set(pixels, -pixels, 1);
154
+ place(this.#moveBase, this.#hasMoveAnchor ? this.#moveAnchor : this.#resting);
155
+ place(this.#jump, this.#jumpCenter);
156
+ }
157
+
158
+ #at(pointers: ReadonlyMap<number, ITouchPointer>, center: Vector2, radius: number): boolean {
159
+ const radiusSquared = radius * radius;
160
+ for (const pointer of pointers.values()) {
161
+ if (pointer.position.distanceToSquared(center) <= radiusSquared) return true;
162
+ }
163
+ return false;
164
+ }
165
+ }
@@ -0,0 +1,38 @@
1
+ // Generated for you: this is the starter's game-owned water look.
2
+ // The WaveField itself is framework plumbing; these colours, highlights and opacity are yours.
3
+ import { DoubleSide } from "three";
4
+ import { color, float, mix, normalize, smoothstep, vec3 } from "three/tsl";
5
+ import { MeshBasicNodeMaterial } from "three/webgpu";
6
+ import type { Node } from "three/webgpu";
7
+ import { palette } from "./palette.js";
8
+
9
+ export interface IWaveDisplacementSource {
10
+ displacementNode(): Node;
11
+ heightNode(): Node<"float">;
12
+ normalNode(): Node<"vec3">;
13
+ }
14
+
15
+ const SUN = normalize(vec3(0.45, 0.82, 0.3));
16
+
17
+ /** Water with broad colour bands and a narrow sun glint that survives the painterly grade. */
18
+ export function createWaterMaterial(source: IWaveDisplacementSource): MeshBasicNodeMaterial {
19
+ const water = new MeshBasicNodeMaterial({
20
+ depthWrite: false,
21
+ opacity: 0.94,
22
+ side: DoubleSide,
23
+ transparent: true,
24
+ });
25
+ water.positionNode = source.displacementNode();
26
+
27
+ const height = source.heightNode();
28
+ const normal = source.normalNode();
29
+ const facing = normal.dot(SUN).clamp(0, 1);
30
+ const troughToCrest = smoothstep(-0.26, 0.26, height);
31
+ const waterMid = mix(color(palette.skyLow), color(palette.skyHigh), 0.35);
32
+ const body = mix(color(palette.skyLow), waterMid, troughToCrest.mul(0.16).add(0.42));
33
+ const litBody = body.mul(mix(float(0.92), float(1), facing));
34
+ const glint = color(palette.skyHigh).mul(facing.pow(48).mul(0.07));
35
+ const crestFoam = color(palette.player).mul(smoothstep(0.16, 0.26, height).mul(0.025));
36
+ water.colorNode = litBody.add(glint).add(crestFoam);
37
+ return water;
38
+ }
@@ -0,0 +1,85 @@
1
+ // Generated source: the starter owns this value treatment and paper field.
2
+
3
+ import { color, float, hash, luminance, mix, screenUV, vec4 } from "three/tsl";
4
+ import type { Node } from "three/webgpu";
5
+ import { createTextureScope } from "./textureLifetime.js";
6
+
7
+ export interface IWatercolorStageOptions {
8
+ readonly levels?: number;
9
+ readonly paperStrength?: number;
10
+ readonly shadowStrength?: number;
11
+ readonly shadowTint?: number;
12
+ readonly strength?: number;
13
+ }
14
+
15
+ export interface IWatercolorStage {
16
+ readonly after: "kuwahara";
17
+ readonly build: (input: unknown) => unknown;
18
+ readonly dispose: () => void;
19
+ readonly minimumTier: "medium";
20
+ readonly name: "watercolor";
21
+ }
22
+
23
+ /** Luminance grouping plus deterministic procedural paper tooth. */
24
+ export function createWatercolorStage(options: IWatercolorStageOptions = {}): IWatercolorStage {
25
+ const levels = boundedInteger(options.levels ?? 8, 2, 16, "watercolor levels");
26
+ const paperStrength = unit(options.paperStrength ?? 0.2, "watercolor paperStrength");
27
+ const shadowStrength = unit(options.shadowStrength ?? 0.16, "watercolor shadowStrength");
28
+ const strength = unit(options.strength ?? 0.72, "watercolor strength");
29
+ const shadowTint = color(options.shadowTint ?? 0x6d5a52);
30
+ const textureScope = createTextureScope();
31
+
32
+ return {
33
+ after: "kuwahara",
34
+ build: (input) => {
35
+ textureScope.dispose();
36
+ if (!isNode(input)) throw new Error("watercolor input is missing");
37
+ if (strength === 0) return input;
38
+ const source = textureScope.texture(input) as unknown as ITextureNode;
39
+ const base = source.sample(screenUV);
40
+ const sceneLuminance = luminance(base.rgb);
41
+ // Quantise one scalar and apply its ratio to the full colour vector; never quantise RGB
42
+ // channels independently, which would drift the hue at every value step.
43
+ const stepped = sceneLuminance.mul(levels).floor().add(0.5).div(levels).clamp(0, 1);
44
+ const grouped = base.rgb.mul(stepped.div(sceneLuminance.max(0.0001)));
45
+ const shadow = sceneLuminance.smoothstep(0.04, 0.56).oneMinus().mul(shadowStrength);
46
+ const shaded = mix(grouped, grouped.mul(shadowTint), shadow);
47
+ const paper = mix(float(1), paperField(), paperStrength);
48
+ const painted = shaded.mul(paper);
49
+ return mix(base, vec4(painted, base.a), strength) as Node<"vec4">;
50
+ },
51
+ dispose: textureScope.dispose,
52
+ minimumTier: "medium",
53
+ name: "watercolor",
54
+ };
55
+ }
56
+
57
+ interface ITextureNode extends Node<"vec4"> {
58
+ sample(uv: Node<"vec2">): Node<"vec4">;
59
+ }
60
+
61
+ function paperField(): Node<"float"> {
62
+ const fine = hash(screenUV.x.mul(173).add(screenUV.y.mul(271)));
63
+ const broad = hash(screenUV.x.mul(31).add(screenUV.y.mul(47)));
64
+ return fine.mul(0.65).add(broad.mul(0.35)).sub(0.5).mul(0.16).add(1);
65
+ }
66
+
67
+ function boundedInteger(value: number, minimum: number, maximum: number, name: string): number {
68
+ if (!Number.isInteger(value) || value < minimum || value > maximum)
69
+ throw new Error(
70
+ `${name} must be an integer from ${String(minimum)} through ${String(maximum)}`,
71
+ );
72
+ return value;
73
+ }
74
+
75
+ function unit(value: number, name: string): number {
76
+ if (!Number.isFinite(value) || value < 0 || value > 1)
77
+ throw new Error(`${name} must be finite and between 0 and 1`);
78
+ return value;
79
+ }
80
+
81
+ function isNode(value: unknown): value is Node {
82
+ return (
83
+ typeof value === "object" && value !== null && (value as { isNode?: boolean }).isNode === true
84
+ );
85
+ }