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,199 @@
1
+ // Generated source. It extracts a closed field and owns no renderer or appearance choice.
2
+ type Point = [number, number, number];
3
+ type Triangle = [number, number, number];
4
+ type SurfaceOptions = Readonly<{
5
+ bounds: Record<"maxX" | "maxY" | "maxZ" | "minX" | "minY" | "minZ", number>;
6
+ cellSize: number;
7
+ latticeCap: number;
8
+ sample: (x: number, y: number, z: number) => number;
9
+ closed?: boolean;
10
+ protectBoundary?: boolean;
11
+ }>;
12
+ function createSurfaceFunctions() {
13
+ // biome-ignore format: compact generated helper keeps the render source under its smell budget.
14
+ function failSurface(name: string, message: string): never {
15
+ const error = new Error(`${name}: ${message}`);
16
+ error.name = name;
17
+ throw error;
18
+ }
19
+ // biome-ignore format: compact generated helper keeps the render source under its smell budget.
20
+ function readPoint(array: ArrayLike<number>, vertex: number): Point {
21
+ return [array[vertex * 3] as number, array[vertex * 3 + 1] as number, array[vertex * 3 + 2] as number];
22
+ }
23
+ // biome-ignore format: compact generated helper keeps the render source under its smell budget.
24
+ function triangleMetrics(a: Point, b: Point, c: Point): [number, number] {
25
+ const u: Point = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
26
+ const v: Point = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
27
+ const n: Point = [u[1] * v[2] - u[2] * v[1], u[2] * v[0] - u[0] * v[2], u[0] * v[1] - u[1] * v[0]];
28
+ return [n[0] * n[0] + n[1] * n[1] + n[2] * n[2], a[0] * (b[1] * c[2] - b[2] * c[1]) + a[1] * (b[2] * c[0] - b[0] * c[2]) + a[2] * (b[0] * c[1] - b[1] * c[0])];
29
+ }
30
+ // biome-ignore format: compact generated helper keeps the render source under its smell budget.
31
+ function touchSurfaceEdge(edges: Map<string, Point>, from: number, to: number): void {
32
+ const key = from < to ? `${from}|${to}` : `${to}|${from}`;
33
+ const edge = edges.get(key) ?? [0, 0, 0];
34
+ edge[0] += 1; edge[1] += from < to ? 1 : -1; edges.set(key, edge);
35
+ }
36
+ // biome-ignore format: compact generated helper keeps the render source under its smell budget.
37
+ function auditImplicitSurface(indices: Uint32Array, positions: Float32Array) {
38
+ const edges = new Map<string, Point>();
39
+ const counts = { boundaryEdges: 0, degenerateTriangles: 0, signedVolume: 0, windingConflicts: 0 };
40
+ for (let index = 0; index < indices.length; index += 3) {
41
+ const a = indices[index] as number; const b = indices[index + 1] as number; const c = indices[index + 2] as number;
42
+ if (a >= positions.length / 3 || b >= positions.length / 3 || c >= positions.length / 3)
43
+ failSurface("TN_IMPLICIT_SURFACE_INDEX_INVALID", `triangle ${index / 3} references a missing vertex.`);
44
+ touchSurfaceEdge(edges, a, b); touchSurfaceEdge(edges, b, c); touchSurfaceEdge(edges, c, a);
45
+ const [area, volume] = triangleMetrics(readPoint(positions, a), readPoint(positions, b), readPoint(positions, c));
46
+ if (area < 1e-14) counts.degenerateTriangles += 1;
47
+ counts.signedVolume += volume;
48
+ }
49
+ for (const [count, direction] of edges.values()) {
50
+ if (count !== 2) counts.boundaryEdges += 1;
51
+ if (count === 2 && direction !== 0) counts.windingConflicts += 1;
52
+ }
53
+ return { ...counts, signedVolume: counts.signedVolume / 6, triangles: indices.length / 3, vertices: positions.length / 3 };
54
+ }
55
+ // biome-ignore format: compact generated helper keeps the render source under its smell budget.
56
+ function addSurfaceTriangle(output: number[], positions: number[], sample: SurfaceOptions["sample"], dx: number, dy: number, dz: number, vertices: Triangle): void {
57
+ const [va, vb, vc] = vertices;
58
+ const [a, b, c] = [readPoint(positions, va), readPoint(positions, vb), readPoint(positions, vc)] as [Point, Point, Point];
59
+ const [area] = triangleMetrics(a, b, c);
60
+ if (area < 1e-14) return;
61
+ const center: Point = [(a[0] + b[0] + c[0]) / 3, (a[1] + b[1] + c[1]) / 3, (a[2] + b[2] + c[2]) / 3];
62
+ const gradient: Point = [
63
+ sample(center[0] + dx * 0.25, center[1], center[2]) - sample(center[0] - dx * 0.25, center[1], center[2]),
64
+ sample(center[0], center[1] + dy * 0.25, center[2]) - sample(center[0], center[1] - dy * 0.25, center[2]),
65
+ sample(center[0], center[1], center[2] + dz * 0.25) - sample(center[0], center[1], center[2] - dz * 0.25),
66
+ ];
67
+ const n: Point = [(b[1] - a[1]) * (c[2] - a[2]) - (b[2] - a[2]) * (c[1] - a[1]), (b[2] - a[2]) * (c[0] - a[0]) - (b[0] - a[0]) * (c[2] - a[2]), (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0])];
68
+ if (n[0] * gradient[0] + n[1] * gradient[1] + n[2] * gradient[2] >= 0) output.push(va, vb, vc); else output.push(va, vc, vb);
69
+ }
70
+ // biome-ignore format: compact generated helper keeps the render source under its smell budget.
71
+ // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the bounded adjacency walk orients the final closed mesh.
72
+ function orientSurface(indices: Uint32Array): void {
73
+ const links = new Map<string, Array<[number, number]>>();
74
+ for (let triangle = 0; triangle < indices.length; triangle += 3) for (let edge = 0; edge < 3; edge++) {
75
+ const from = indices[triangle + edge] as number; const to = indices[triangle + (edge + 1) % 3] as number;
76
+ const key = from < to ? `${from}|${to}` : `${to}|${from}`;
77
+ const linked = links.get(key) ?? []; linked.push([triangle, from < to ? 1 : -1]); links.set(key, linked);
78
+ }
79
+ const flips = new Map<number, boolean>();
80
+ for (let start = 0; start < indices.length; start += 3) if (!flips.has(start)) {
81
+ const queue = [start]; flips.set(start, false); while (queue.length > 0) {
82
+ const triangle = queue.pop() as number; const flip = flips.get(triangle) as boolean;
83
+ for (let edge = 0; edge < 3; edge++) {
84
+ const from = indices[triangle + edge] as number; const to = indices[triangle + (edge + 1) % 3] as number;
85
+ const key = from < to ? `${from}|${to}` : `${to}|${from}`;
86
+ for (const [other, otherDirection] of links.get(key) ?? []) if (other !== triangle && !flips.has(other)) {
87
+ flips.set(other, flip !== ((from < to ? 1 : -1) === otherDirection)); queue.push(other);
88
+ }
89
+ }
90
+ }
91
+ }
92
+ for (const [triangle, flip] of flips) if (flip) {
93
+ const swap = indices[triangle + 1] as number; indices[triangle + 1] = indices[triangle + 2] as number; indices[triangle + 2] = swap;
94
+ }
95
+ }
96
+ // biome-ignore format: compact generated helper keeps the render source under its smell budget.
97
+ // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the bounded lattice traversal is the extractor.
98
+ function buildImplicitSurface(options: SurfaceOptions) {
99
+ const started = Date.now();
100
+ const { bounds } = options;
101
+ if ([bounds.minX, bounds.maxX, bounds.minY, bounds.maxY, bounds.minZ, bounds.maxZ].some((value) => !Number.isFinite(value)))
102
+ failSurface("TN_IMPLICIT_SURFACE_BOUNDS_INVALID", "bounds must be finite.");
103
+ if (bounds.maxX <= bounds.minX || bounds.maxY <= bounds.minY || bounds.maxZ <= bounds.minZ)
104
+ failSurface("TN_IMPLICIT_SURFACE_BOUNDS_INVALID", "each maximum must exceed its minimum.");
105
+ if (!Number.isFinite(options.cellSize) || options.cellSize <= 0)
106
+ failSurface("TN_IMPLICIT_SURFACE_CELL_INVALID", "cellSize must be positive and finite.");
107
+ if (!Number.isSafeInteger(options.latticeCap) || options.latticeCap <= 0)
108
+ failSurface("TN_IMPLICIT_SURFACE_CAP_INVALID", "latticeCap must be a positive safe integer.");
109
+ const nx = Math.max(1, Math.ceil((bounds.maxX - bounds.minX) / options.cellSize));
110
+ const ny = Math.max(1, Math.ceil((bounds.maxY - bounds.minY) / options.cellSize));
111
+ const nz = Math.max(1, Math.ceil((bounds.maxZ - bounds.minZ) / options.cellSize));
112
+ const width = nx + 1;
113
+ const height = ny + 1;
114
+ const depth = nz + 1;
115
+ const latticeLength = width * height * depth;
116
+ if (!Number.isSafeInteger(latticeLength) || latticeLength > options.latticeCap)
117
+ failSurface("TN_IMPLICIT_SURFACE_LATTICE_OVERFLOW", `lattice requires ${latticeLength} samples.`);
118
+ const dx = (bounds.maxX - bounds.minX) / nx;
119
+ const dy = (bounds.maxY - bounds.minY) / ny;
120
+ const dz = (bounds.maxZ - bounds.minZ) / nz;
121
+ const cell = Math.max(dx, dy, dz);
122
+ const sample = (x: number, y: number, z: number): number => {
123
+ const value = options.sample(x, y, z);
124
+ if (!Number.isFinite(value)) failSurface("TN_IMPLICIT_SURFACE_SAMPLE_INVALID", `sample at ${x},${y},${z} is not finite.`);
125
+ return value === 0 ? 1e-8 : value;
126
+ };
127
+ const indexOf = (x: number, y: number, z: number): number => x + width * (y + height * z);
128
+ const values = new Float64Array(latticeLength);
129
+ for (let z = 0; z < depth; z += 1) for (let y = 0; y < height; y += 1) for (let x = 0; x < width; x += 1) {
130
+ let value = sample(bounds.minX + x * dx, bounds.minY + y * dy, bounds.minZ + z * dz);
131
+ if (options.protectBoundary !== false && (x === 0 || y === 0 || z === 0 || x === nx || y === ny || z === nz)) value = Math.max(value, cell * 0.5);
132
+ values[indexOf(x, y, z)] = value;
133
+ }
134
+ const corners = "000 100 110 010 001 101 111 011".split(" ").map((value) => [...value].map(Number)) as Array<[number, number, number]>;
135
+ const tetrahedra = "0516 0126 0236 0376 0746 0456".split(" ").map((value) => [...value].map(Number)) as Array<[number, number, number, number]>;
136
+ // biome-ignore format: compact generated lookup stays within the render-source smell budget.
137
+ const tetraCases: number[][][][] = [[], [[[0, 1], [0, 2], [0, 3]]], [[[0, 1], [1, 2], [1, 3]]], [[[0, 2], [1, 2], [1, 3]], [[0, 2], [1, 3], [0, 3]]], [[[0, 2], [1, 2], [2, 3]]], [[[0, 1], [1, 2], [2, 3]], [[0, 1], [2, 3], [0, 3]]], [[[0, 1], [1, 3], [2, 3]], [[0, 1], [2, 3], [0, 2]]], [[[0, 3], [1, 3], [2, 3]]], [[[0, 3], [1, 3], [2, 3]]], [[[0, 1], [1, 3], [2, 3]], [[0, 1], [2, 3], [0, 2]]], [[[0, 1], [1, 2], [2, 3]], [[0, 1], [2, 3], [0, 3]]], [[[0, 2], [1, 2], [2, 3]]], [[[0, 2], [1, 2], [1, 3]], [[0, 2], [1, 3], [0, 3]]], [[[0, 1], [1, 2], [1, 3]]], [[[0, 1], [0, 2], [0, 3]]], []];
138
+ const positions: number[] = [];
139
+ const rawIndices: number[] = [];
140
+ const edgeVertices = new Map<string, number>();
141
+ const point = (index: number): Point => [bounds.minX + (index % width) * dx, bounds.minY + (Math.floor(index / width) % height) * dy, bounds.minZ + Math.floor(index / (width * height)) * dz];
142
+ const edgePoint = (a: number, b: number): number => {
143
+ const key = a < b ? `${a}|${b}` : `${b}|${a}`;
144
+ const existing = edgeVertices.get(key);
145
+ if (existing !== undefined) return existing;
146
+ const fa = values[a] as number;
147
+ const fb = values[b] as number;
148
+ const t = Math.max(0.015, Math.min(0.985, fa / (fa - fb)));
149
+ const pa = point(a);
150
+ const pb = point(b);
151
+ const vertex = positions.length / 3;
152
+ positions.push(pa[0] + (pb[0] - pa[0]) * t, pa[1] + (pb[1] - pa[1]) * t, pa[2] + (pb[2] - pa[2]) * t);
153
+ edgeVertices.set(key, vertex);
154
+ return vertex;
155
+ };
156
+ for (let z = 0; z < nz; z += 1) for (let y = 0; y < ny; y += 1) for (let x = 0; x < nx; x += 1) {
157
+ const indexes: number[] = [];
158
+ const field: number[] = [];
159
+ for (const corner of corners) {
160
+ const index = indexOf(x + corner[0], y + corner[1], z + corner[2]);
161
+ indexes.push(index); field.push(values[index] as number);
162
+ }
163
+ for (const tetrahedron of tetrahedra) {
164
+ let code = 0;
165
+ for (let corner = 0; corner < 4; corner += 1)
166
+ if ((field[tetrahedron[corner] as number] as number) < 0) code |= 1 << corner;
167
+ const tetVertex = (crossing: number[]): number =>
168
+ edgePoint(indexes[tetrahedron[crossing[0] as number] as number] as number, indexes[tetrahedron[crossing[1] as number] as number] as number);
169
+ for (const triangle of tetraCases[code] ?? [])
170
+ addSurfaceTriangle(rawIndices, positions, sample, dx, dy, dz, [tetVertex(triangle[0] as number[]), tetVertex(triangle[1] as number[]), tetVertex(triangle[2] as number[])]);
171
+ }
172
+ }
173
+ if (rawIndices.length === 0) failSurface("TN_IMPLICIT_SURFACE_EMPTY", "the field contains no triangles.");
174
+ const outputPositions = Float32Array.from(positions);
175
+ const outputIndices = Uint32Array.from(rawIndices);
176
+ orientSurface(outputIndices);
177
+ let report = auditImplicitSurface(outputIndices, outputPositions);
178
+ if (report.signedVolume < 0) {
179
+ for (let index = 0; index < outputIndices.length; index += 3) {
180
+ const swap = outputIndices[index + 1] as number;
181
+ outputIndices[index + 1] = outputIndices[index + 2] as number;
182
+ outputIndices[index + 2] = swap;
183
+ }
184
+ report = auditImplicitSurface(outputIndices, outputPositions);
185
+ }
186
+ if (options.closed !== false && (report.boundaryEdges > 0 || report.degenerateTriangles > 0 || report.windingConflicts > 0))
187
+ failSurface("TN_IMPLICIT_SURFACE_TOPOLOGY_INVALID", `boundary=${report.boundaryEdges}, degenerate=${report.degenerateTriangles}, winding=${report.windingConflicts}.`);
188
+ if (options.closed !== false && report.signedVolume <= Math.max(cell ** 3 * 0.01, 1e-8))
189
+ failSurface("TN_IMPLICIT_SURFACE_VOLUME_INVALID", `signed volume ${report.signedVolume} is not non-trivial.`);
190
+ return { indices: outputIndices, positions: outputPositions, report: { ...report, buildMs: Math.max(0, Date.now() - started), cellSize: cell } };
191
+ }
192
+ return { auditImplicitSurface, buildImplicitSurface };
193
+ }
194
+ export const { auditImplicitSurface, buildImplicitSurface } = createSurfaceFunctions();
195
+
196
+ export function createImplicitSurfaceWorkerSource(): string {
197
+ // biome-ignore format: compact generated source list keeps this file under its smell budget.
198
+ return `const { auditImplicitSurface, buildImplicitSurface } = (${createSurfaceFunctions.toString()})();`;
199
+ }
@@ -0,0 +1,174 @@
1
+ // Generated source: the starter owns this painterly algorithm and may replace it freely.
2
+ import { HalfFloatType } from "three";
3
+ import * as tsl from "three/tsl";
4
+ import type { Node } from "three/webgpu";
5
+ import { createTextureScope } from "./textureLifetime.js";
6
+ export type KernelOffset = { readonly x: number; readonly y: number };
7
+ export interface IKuwaharaStageOptions {
8
+ readonly anisotropy?: number;
9
+ readonly radius?: number;
10
+ readonly resolutionScale?: number;
11
+ readonly strength?: number;
12
+ }
13
+ export interface IKuwaharaStage {
14
+ readonly after: "outline";
15
+ readonly build: (input: unknown) => unknown;
16
+ readonly dispose: () => void;
17
+ readonly minimumTier: "medium";
18
+ readonly name: "kuwahara";
19
+ }
20
+ function sectorSampleOffsets(radius: number): readonly KernelOffset[] {
21
+ const bounded = boundedRadius(radius);
22
+ const halfWidth = Math.floor(bounded / 2);
23
+ const offsets: KernelOffset[] = [];
24
+ for (let radial = 1; radial <= bounded; radial += 1)
25
+ for (let tangent = -halfWidth; tangent <= halfWidth; tangent += 1)
26
+ offsets.push({ x: radial, y: tangent });
27
+ return offsets;
28
+ }
29
+ export function createKuwaharaStage(options: IKuwaharaStageOptions = {}): IKuwaharaStage {
30
+ const anisotropy = finiteRange(options.anisotropy ?? 0.72, 0, 1, false, "kuwahara anisotropy");
31
+ const radius = boundedRadius(options.radius ?? 5);
32
+ const resolutionScale = finiteRange(
33
+ options.resolutionScale ?? 0.5,
34
+ 0,
35
+ 1,
36
+ true,
37
+ "kuwahara resolutionScale",
38
+ );
39
+ const strength = finiteRange(options.strength ?? 0.82, 0, 1, false, "kuwahara strength");
40
+ const textureScope = createTextureScope();
41
+ const dispose = textureScope.dispose;
42
+ return {
43
+ after: "outline",
44
+ build: (input) => {
45
+ if (!isNode(input)) throw new Error("kuwahara input is missing");
46
+ if (strength === 0) return input;
47
+ dispose();
48
+ const source = textureScope.texture(input) as unknown as ITextureNode;
49
+ const texel = tsl.screenSize.reciprocal();
50
+ const sampleUv = (x: Node<"float"> | number, y: Node<"float"> | number): Node<"vec2"> =>
51
+ tsl.screenUV.add(texel.mul(tsl.vec2(x, y))).clamp(0, 1) as Node<"vec2">;
52
+ const sampleColour = (x: number, y: number): Node<"float"> =>
53
+ tsl.luminance(source.sample(sampleUv(x, y)).rgb);
54
+ const gradientX = sampleColour(1, 0).sub(sampleColour(-1, 0)).mul(0.5);
55
+ const gradientY = sampleColour(0, 1).sub(sampleColour(0, -1)).mul(0.5);
56
+ const tensor = makeHalfFloatScratch(
57
+ textureScope,
58
+ tsl.vec4(gradientX.mul(gradientX), gradientX.mul(gradientY), gradientY.mul(gradientY), 1),
59
+ resolutionScale,
60
+ );
61
+ const tensorSample = tensor.sample(tsl.screenUV);
62
+ const orientation = tsl
63
+ .atan(tensorSample.y.mul(2), tensorSample.x.sub(tensorSample.z))
64
+ .mul(0.5);
65
+ const axis = tsl.vec2(tsl.cos(orientation), tsl.sin(orientation));
66
+ const sectorOffsets = sectorSampleOffsets(radius);
67
+ const sector = (sectorIndex: number) => {
68
+ let mean: Node<"vec3"> = tsl.vec3(0);
69
+ let secondMoment: Node<"vec3"> = tsl.vec3(0);
70
+ const angle = (sectorIndex / 8) * Math.PI * 2;
71
+ const sectorAxis = tsl.vec2(
72
+ axis.x.mul(Math.cos(angle)).sub(axis.y.mul(Math.sin(angle))),
73
+ axis.y.mul(Math.cos(angle)).add(axis.x.mul(Math.sin(angle))),
74
+ );
75
+ for (const localOffset of sectorOffsets) {
76
+ const offset = transformKernelOffsetNode(
77
+ tsl.vec2(localOffset.x, localOffset.y),
78
+ sectorAxis,
79
+ anisotropy,
80
+ );
81
+ const colour = source.sample(sampleUv(offset.x, offset.y)).rgb;
82
+ mean = mean.add(colour);
83
+ secondMoment = secondMoment.add(colour.mul(colour));
84
+ }
85
+ const average = mean.div(sectorOffsets.length);
86
+ const variance = secondMoment.div(sectorOffsets.length).sub(average.mul(average)).max(0);
87
+ return { mean: average, score: tsl.luminance(variance) };
88
+ };
89
+ let best = sector(0);
90
+ for (let sectorIndex = 1; sectorIndex < 8; sectorIndex += 1) {
91
+ const candidate = sector(sectorIndex);
92
+ const candidateWins = candidate.score.lessThan(best.score);
93
+ best = {
94
+ mean: tsl.select(candidateWins, candidate.mean, best.mean) as Node<"vec3">,
95
+ score: tsl.select(candidateWins, candidate.score, best.score) as Node<"float">,
96
+ };
97
+ }
98
+ const base = source.sample(tsl.screenUV);
99
+ const paint = makeHalfFloatScratch(
100
+ textureScope,
101
+ tsl.vec4(best.mean, base.a),
102
+ resolutionScale,
103
+ );
104
+ return mixColour(base, paint.sample(tsl.screenUV).rgb, strength);
105
+ },
106
+ dispose,
107
+ minimumTier: "medium",
108
+ name: "kuwahara",
109
+ };
110
+ }
111
+ interface ITextureNode extends Node<"vec4"> {
112
+ sample(uv: Node<"vec2">): Node<"vec4">;
113
+ }
114
+ function makeHalfFloatScratch(
115
+ scope: ReturnType<typeof createTextureScope>,
116
+ node: Node<"vec4">,
117
+ resolutionScale: number,
118
+ ): IRawScratch {
119
+ let scratch: IRawScratch | undefined;
120
+ try {
121
+ scratch = scope.own(
122
+ tsl.rtt(node, null, null, { type: HalfFloatType }) as unknown as IRawScratch,
123
+ );
124
+ scratch.setResolutionScale(resolutionScale);
125
+ } catch (error) {
126
+ scope.dispose();
127
+ throw new Error(
128
+ `kuwahara scratch allocation failed: ${error instanceof Error ? error.message : String(error)}`,
129
+ );
130
+ }
131
+ if (scratch.renderTarget.texture.type !== HalfFloatType) {
132
+ scope.dispose();
133
+ throw new Error("kuwahara scratch format is not half-float");
134
+ }
135
+ return scratch;
136
+ }
137
+ interface IRawScratch extends ITextureNode {
138
+ readonly renderTarget: { readonly texture: { readonly type: number }; dispose: () => void };
139
+ setResolutionScale(scale: number): void;
140
+ }
141
+ function transformKernelOffsetNode(
142
+ offset: Node<"vec2">,
143
+ axis: Node<"vec2">,
144
+ anisotropy: number,
145
+ ): Node<"vec2"> {
146
+ const scaled = tsl.vec2(offset.x.mul(1 + anisotropy), offset.y.mul(1 - anisotropy));
147
+ return tsl.vec2(
148
+ axis.x.mul(scaled.x).sub(axis.y.mul(scaled.y)),
149
+ axis.y.mul(scaled.x).add(axis.x.mul(scaled.y)),
150
+ );
151
+ }
152
+ function mixColour(base: Node<"vec4">, paint: Node<"vec3">, strength: number): Node<"vec4"> {
153
+ return tsl.mix(base, tsl.vec4(paint, base.a), strength) as Node<"vec4">;
154
+ }
155
+ function boundedRadius(value: number): number {
156
+ if (!Number.isInteger(value) || value < 1 || value > 9)
157
+ throw new Error("kuwahara radius must be an integer from 1 through 9");
158
+ return value;
159
+ }
160
+ function finiteRange(
161
+ value: number,
162
+ minimum: number,
163
+ maximum: number,
164
+ exclusiveMinimum: boolean,
165
+ name: string,
166
+ ): number {
167
+ const lower = exclusiveMinimum ? value <= minimum : value < minimum;
168
+ if (!Number.isFinite(value) || lower || value > maximum)
169
+ throw new Error(`${name} must be finite and in range`);
170
+ return value;
171
+ }
172
+ function isNode(value: unknown): value is Node {
173
+ return !!value && typeof value === "object" && (value as { isNode?: boolean }).isNode === true;
174
+ }
@@ -25,9 +25,9 @@ export function setupLighting(scene: Scene, renderer: ShadowRenderer): Direction
25
25
 
26
26
  // Sky above, ground bounce below. Tint the second colour toward whatever the
27
27
  // floor actually is — it is the cheapest realism in the whole rig.
28
- scene.add(new HemisphereLight(palette.skyHigh, palette.skyLow, 1.6));
28
+ scene.add(new HemisphereLight(palette.skyHigh, palette.skyLow, 1.8));
29
29
 
30
- const key = new DirectionalLight(palette.accent, 3);
30
+ const key = new DirectionalLight(palette.accent, 2.4);
31
31
  key.position.set(4, 7, 3);
32
32
  key.castShadow = true;
33
33
  // 1024² is one quarter of a 2048² map's texel storage and fill work while
@@ -50,11 +50,11 @@ export function setupLighting(scene: Scene, renderer: ShadowRenderer): Direction
50
50
  key.shadow.normalBias = 0.03;
51
51
  scene.add(key);
52
52
 
53
- const rim = new DirectionalLight(palette.player, 0.75);
53
+ const rim = new DirectionalLight(palette.skyHigh, 0.9);
54
54
  rim.position.set(-5, 3, -6);
55
55
  scene.add(rim);
56
56
 
57
- scene.add(new AmbientLight(palette.skyLow, 0.28));
57
+ scene.add(new AmbientLight(palette.skyLow, 0.38));
58
58
 
59
59
  return key;
60
60
  }
@@ -36,7 +36,11 @@ interface ILoadingHost {
36
36
  };
37
37
  readonly renderer: { compileAsync(scene: Scene, camera: Camera): Promise<void> };
38
38
  readonly scene: Scene;
39
- readonly startup: { readonly progress: number; whenReady(): Promise<void> };
39
+ readonly startup: {
40
+ readonly progress: number;
41
+ readonly warmup?: { readonly status: "complete" | "incomplete" | "unavailable" };
42
+ whenReady(): Promise<void>;
43
+ };
40
44
  readonly viewport?: {
41
45
  readonly safeArea: { height: number; width: number; x: number; y: number };
42
46
  };
@@ -231,7 +235,13 @@ export function createLoadingScreen(host: ILoadingHost): ILoadingController {
231
235
  };
232
236
 
233
237
  const updateProgress = (value: number): void => {
234
- progress = Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
238
+ const bounded = Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
239
+ // A missing or incomplete backend observation cannot prove that all first-use work is done.
240
+ // Keep the bar visibly indeterminate until readiness removes the cover; never turn unknown
241
+ // coverage into a false 100% claim.
242
+ const observationUnknown =
243
+ host.startup.warmup !== undefined && host.startup.warmup.status !== "complete";
244
+ progress = observationUnknown ? Math.min(0.9, bounded) : bounded;
235
245
  setFillUv(fill.geometry, progress, fillBaseU);
236
246
  status?.update(progress);
237
247
  layout();
@@ -6,19 +6,38 @@ import { palette } from "./palette.js";
6
6
 
7
7
  export function createMaterials() {
8
8
  return {
9
- floor: new MeshStandardMaterial({ color: palette.floor, roughness: 0.78, metalness: 0.12 }),
10
- player: new MeshStandardMaterial({ color: palette.player, roughness: 0.42, metalness: 0.22 }),
11
- crate: new MeshStandardMaterial({ color: palette.crate, roughness: 0.8, metalness: 0 }),
9
+ floor: new MeshStandardMaterial({ color: palette.floor, roughness: 0.9, metalness: 0 }),
10
+ player: new MeshStandardMaterial({ color: palette.player, roughness: 0.48, metalness: 0.04 }),
11
+ crate: new MeshStandardMaterial({ color: palette.crate, roughness: 0.76, metalness: 0 }),
12
+ /** The hero's hat, scarf and boots: the one warm accent on a cool coast. */
13
+ heroAccent: new MeshStandardMaterial({
14
+ color: palette.crate,
15
+ roughness: 0.6,
16
+ metalness: 0.02,
17
+ }),
18
+ /** The hero's pack, gloves, legs and visor. Reads as leather at this size. */
19
+ heroDark: new MeshStandardMaterial({ color: 0x4a4038, roughness: 0.8, metalness: 0.02 }),
12
20
  // The flagpole only. The island under it is `floor`, so the far side reads as more of
13
21
  // the same ground and the gap between them stays legible as a gap.
14
- goal: new MeshStandardMaterial({ color: palette.accent, roughness: 0.5, metalness: 0.1 }),
22
+ goal: new MeshStandardMaterial({ color: palette.accent, roughness: 0.45, metalness: 0.04 }),
15
23
  // The columns under the ledge: lit, matte, near-black, so the drop has a below.
16
- rock: new MeshStandardMaterial({ color: palette.skyLow, roughness: 0.95, metalness: 0 }),
24
+ rock: new MeshStandardMaterial({ color: palette.skyLow, roughness: 0.98, metalness: 0 }),
17
25
  // The ridge on the horizon is unlit on purpose. A standard material there takes the
18
26
  // warm key like everything else and the backdrop stops being a backdrop; a flat colour
19
27
  // between the two sky stops stays a silhouette from every light angle, and the scene's
20
28
  // fog still fades it with distance.
21
- ridge: new MeshBasicMaterial({ color: new Color(palette.skyHigh).multiplyScalar(0.9) }),
29
+ ridge: new MeshBasicMaterial({ color: new Color(palette.skyLow).multiplyScalar(0.72) }),
30
+ flower: new MeshStandardMaterial({ color: palette.crate, roughness: 0.6, metalness: 0 }),
31
+ grass: new MeshStandardMaterial({ color: palette.floor, roughness: 0.95, metalness: 0 }),
32
+ grassDark: new MeshStandardMaterial({
33
+ color: new Color(palette.floor).multiplyScalar(0.58),
34
+ roughness: 0.98,
35
+ metalness: 0,
36
+ }),
37
+ sand: new MeshStandardMaterial({ color: palette.accent, roughness: 0.96, metalness: 0 }),
38
+ /** The far sandbar's beach rim: the same sand as the main island's shore. */
39
+ shore: new MeshStandardMaterial({ color: palette.accent, roughness: 0.96, metalness: 0 }),
40
+ shoreline: new MeshStandardMaterial({ color: palette.player, roughness: 0.9, metalness: 0 }),
22
41
  };
23
42
  }
24
43
 
@@ -0,0 +1,141 @@
1
+ // Generated source. This stage is ordinary Three.js TSL; the engine only orders and measures it.
2
+
3
+ import {
4
+ cameraFar,
5
+ cameraNear,
6
+ color,
7
+ luminance,
8
+ mix,
9
+ perspectiveDepthToViewZ,
10
+ screenSize,
11
+ screenUV,
12
+ texture,
13
+ vec2,
14
+ vec4,
15
+ } from "three/tsl";
16
+ import type { Node } from "three/webgpu";
17
+ import { createTextureScope } from "./textureLifetime.js";
18
+
19
+ export interface IOutlineStageOptions {
20
+ /** The depth attachment written by the scene pass. */
21
+ readonly depthNode: Node;
22
+ /** Ink colour and thresholds are this game's look decisions. */
23
+ readonly inkColor?: number;
24
+ readonly strength?: number;
25
+ readonly threshold?: number;
26
+ readonly softness?: number;
27
+ readonly depthWeight?: number;
28
+ }
29
+
30
+ export interface IOutlineStage {
31
+ readonly after: "bloom";
32
+ readonly build: (input: unknown) => unknown;
33
+ readonly dispose: () => void;
34
+ readonly name: "outline";
35
+ }
36
+
37
+ /**
38
+ * Eight-tap Sobel edge ink, normalised to the physical framebuffer pixel size.
39
+ *
40
+ * Colour edges catch the painted prop boundaries while linearised depth catches silhouettes
41
+ * whose two sides happen to have similar colours. The stage samples the original chain input
42
+ * and never owns a material, palette or renderer fallback.
43
+ */
44
+ export function createOutlineStage(options: IOutlineStageOptions): IOutlineStage {
45
+ if (!isNode(options.depthNode)) throw new Error("outline depth source is missing");
46
+ const strength = finiteNonNegative(options.strength ?? 0.8, "outline strength");
47
+ const threshold = finiteNonNegative(options.threshold ?? 0.12, "outline threshold");
48
+ const softness = finitePositive(options.softness ?? 0.16, "outline softness");
49
+ const depthWeight = finiteUnit(options.depthWeight ?? 0.65, "outline depthWeight");
50
+ const colourWeight = 1 - depthWeight;
51
+ const ink = color(options.inkColor ?? 0x142331);
52
+ const textureScope = createTextureScope();
53
+
54
+ return {
55
+ after: "bloom",
56
+ build: (input) => {
57
+ textureScope.dispose();
58
+ if (!isNode(input)) throw new Error("outline input is missing");
59
+ if (strength === 0) return input;
60
+ const source = textureScope.texture(input) as unknown as ITextureNode;
61
+ const depthSource = texture(options.depthNode as never);
62
+ const texel = screenSize.reciprocal();
63
+ const sampleUv = (x: number, y: number): Node<"vec2"> =>
64
+ screenUV.add(texel.mul(vec2(x, y))).clamp(0, 1) as Node<"vec2">;
65
+ const sampleColour = (x: number, y: number): Node<"float"> =>
66
+ luminance(source.sample(sampleUv(x, y)).rgb);
67
+ const sampleDepth = (x: number, y: number): Node<"float"> =>
68
+ perspectiveDepthToViewZ(depthSource.sample(sampleUv(x, y)).r, cameraNear, cameraFar);
69
+
70
+ // Sobel's eight neighbours use physical-pixel offsets, so a resize does not change the
71
+ // apparent line width. This is the same eight-tap neighbourhood for colour and depth.
72
+ const colourX = sampleColour(-1, -1)
73
+ .negate()
74
+ .add(sampleColour(-1, 0).mul(-2))
75
+ .add(sampleColour(-1, 1).negate())
76
+ .add(sampleColour(1, -1))
77
+ .add(sampleColour(1, 0).mul(2))
78
+ .add(sampleColour(1, 1));
79
+ const colourY = sampleColour(-1, -1)
80
+ .negate()
81
+ .add(sampleColour(0, -1).mul(-2))
82
+ .add(sampleColour(1, -1).negate())
83
+ .add(sampleColour(-1, 1))
84
+ .add(sampleColour(0, 1).mul(2))
85
+ .add(sampleColour(1, 1));
86
+ const depthX = sampleDepth(-1, -1)
87
+ .negate()
88
+ .add(sampleDepth(-1, 0).mul(-2))
89
+ .add(sampleDepth(-1, 1).negate())
90
+ .add(sampleDepth(1, -1))
91
+ .add(sampleDepth(1, 0).mul(2))
92
+ .add(sampleDepth(1, 1));
93
+ const depthY = sampleDepth(-1, -1)
94
+ .negate()
95
+ .add(sampleDepth(0, -1).mul(-2))
96
+ .add(sampleDepth(1, -1).negate())
97
+ .add(sampleDepth(-1, 1))
98
+ .add(sampleDepth(0, 1).mul(2))
99
+ .add(sampleDepth(1, 1));
100
+ const centreDepth = sampleDepth(0, 0).abs().max(1);
101
+ const colourEdge = colourX.mul(colourX).add(colourY.mul(colourY)).sqrt();
102
+ const depthEdge = depthX.mul(depthX).add(depthY.mul(depthY)).sqrt().div(centreDepth);
103
+ const edge = colourEdge.mul(colourWeight).add(depthEdge.mul(depthWeight));
104
+ const mask = edge
105
+ .smoothstep(threshold, threshold + softness)
106
+ .mul(strength)
107
+ .clamp(0, 1);
108
+ const base = source.sample(screenUV);
109
+ return mix(base, vec4(ink, base.a), mask);
110
+ },
111
+ dispose: textureScope.dispose,
112
+ name: "outline",
113
+ };
114
+ }
115
+
116
+ interface ITextureNode extends Node<"vec4"> {
117
+ sample(uv: Node<"vec2">): Node<"vec4">;
118
+ }
119
+
120
+ function isNode(value: unknown): value is Node {
121
+ return (
122
+ typeof value === "object" && value !== null && (value as { isNode?: boolean }).isNode === true
123
+ );
124
+ }
125
+
126
+ function finiteNonNegative(value: number, name: string): number {
127
+ if (!Number.isFinite(value) || value < 0)
128
+ throw new Error(`${name} must be finite and non-negative`);
129
+ return value;
130
+ }
131
+
132
+ function finitePositive(value: number, name: string): number {
133
+ if (!Number.isFinite(value) || value <= 0) throw new Error(`${name} must be finite and positive`);
134
+ return value;
135
+ }
136
+
137
+ function finiteUnit(value: number, name: string): number {
138
+ if (!Number.isFinite(value) || value < 0 || value > 1)
139
+ throw new Error(`${name} must be finite and between 0 and 1`);
140
+ return value;
141
+ }