create-threenative 0.2.3 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (447) hide show
  1. package/README.md +53 -2
  2. package/agent-docs/references/assertion-reference.md +173 -6
  3. package/agent-docs/references/capability-reference.md +1303 -99
  4. package/agent-docs/references/capture-the-frame.md +7 -0
  5. package/agent-docs/references/creating-creatures.md +215 -0
  6. package/agent-docs/references/ctx-cookbook.md +69 -0
  7. package/agent-docs/references/debug-surface.md +8 -3
  8. package/agent-docs/references/dream-loop.md +150 -0
  9. package/agent-docs/references/finding-assets.md +70 -2
  10. package/agent-docs/references/sculpt-from-a-reference.md +3 -2
  11. package/agent-docs/references/trace-a-slow-frame.md +99 -0
  12. package/agent-docs/references/visual-baseline.md +41 -0
  13. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
  14. package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
  15. package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
  16. package/agent-files/.agents/skills/threenative-builder/SKILL.md +1 -1
  17. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
  18. package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
  19. package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
  20. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
  21. package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
  22. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +1 -1
  23. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
  24. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
  25. package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
  26. package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
  27. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
  28. package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
  29. package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
  30. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
  31. package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
  32. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
  33. package/agent-files/scripts/reference.mjs +705 -0
  34. package/agent-files/scripts/visual-loop.mjs +382 -0
  35. package/capabilities.json +1881 -131
  36. package/dist/index.d.ts +39 -6
  37. package/dist/index.js +297 -32
  38. package/dist/threenative.js +822 -105
  39. package/package.json +30 -5
  40. package/template-assets/loading.ts +12 -2
  41. package/template-assets/patches/three@0.185.1.patch +249 -14
  42. package/template-assets/worldEnvironment.ts +758 -0
  43. package/templates/action-rpg/.codex/config.toml +4 -0
  44. package/templates/action-rpg/.cursor/mcp.json +32 -0
  45. package/templates/action-rpg/.gemini/settings.json +32 -0
  46. package/templates/action-rpg/.mcp.json +15 -3
  47. package/templates/action-rpg/.vscode/mcp.json +36 -0
  48. package/templates/action-rpg/.zed/settings.json +36 -0
  49. package/templates/action-rpg/AGENTS.md +69 -378
  50. package/templates/action-rpg/CLAUDE.md +69 -378
  51. package/templates/action-rpg/opencode.json +41 -0
  52. package/templates/action-rpg/package.json +7 -7
  53. package/templates/action-rpg/playtests/combat.playtest.json +9 -0
  54. package/templates/action-rpg/playtests/performance.playtest.json +24 -7
  55. package/templates/action-rpg/playtests/survives.playtest.json +27 -0
  56. package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
  57. package/templates/action-rpg/src/conventions.ts +35 -0
  58. package/templates/action-rpg/src/entities/Enemy.ts +2 -3
  59. package/templates/action-rpg/src/entities/Player.ts +20 -3
  60. package/templates/action-rpg/src/render/camera.ts +7 -2
  61. package/templates/action-rpg/src/render/lighting.ts +5 -3
  62. package/templates/action-rpg/src/render/loading.ts +12 -2
  63. package/templates/action-rpg/src/render/materials.ts +11 -0
  64. package/templates/action-rpg/src/render/palette.ts +10 -3
  65. package/templates/action-rpg/src/render/postprocessing.ts +21 -58
  66. package/templates/action-rpg/src/render/quality.ts +170 -0
  67. package/templates/action-rpg/src/render/shapes.ts +185 -26
  68. package/templates/action-rpg/src/render/touch-controls.ts +185 -0
  69. package/templates/action-rpg/src/render/vfx.ts +257 -0
  70. package/templates/action-rpg/src/render/worldEnvironment.ts +208 -33
  71. package/templates/action-rpg/src/scenes/Play.ts +43 -6
  72. package/templates/action-rpg/src/style.css +20 -0
  73. package/templates/action-rpg/threenative.config.ts +7 -0
  74. package/templates/defense/.codex/config.toml +4 -0
  75. package/templates/defense/.cursor/mcp.json +32 -0
  76. package/templates/defense/.gemini/settings.json +32 -0
  77. package/templates/defense/.mcp.json +15 -3
  78. package/templates/defense/.vscode/mcp.json +36 -0
  79. package/templates/defense/.zed/settings.json +36 -0
  80. package/templates/defense/AGENTS.md +62 -385
  81. package/templates/defense/CLAUDE.md +62 -385
  82. package/templates/defense/opencode.json +41 -0
  83. package/templates/defense/package.json +7 -7
  84. package/templates/defense/playtests/performance.playtest.json +24 -7
  85. package/templates/defense/playtests/pointer-placement.playtest.json +87 -20
  86. package/templates/defense/playtests/scan.playtest.json +1 -1
  87. package/templates/defense/playtests/survive.playtest.json +14 -0
  88. package/templates/defense/src/attackers/Attacker.ts +4 -4
  89. package/templates/defense/src/board/Route.ts +22 -8
  90. package/templates/defense/src/conventions.ts +18 -0
  91. package/templates/defense/src/entities/Player.ts +11 -3
  92. package/templates/defense/src/game.ts +2 -3
  93. package/templates/defense/src/physics.ts +9 -39
  94. package/templates/defense/src/placement/Buildable.ts +4 -4
  95. package/templates/defense/src/render/camera.ts +9 -3
  96. package/templates/defense/src/render/loading.ts +12 -2
  97. package/templates/defense/src/render/materials.ts +9 -0
  98. package/templates/defense/src/render/palette.ts +12 -5
  99. package/templates/defense/src/render/postprocessing.ts +21 -58
  100. package/templates/defense/src/render/quality.ts +170 -0
  101. package/templates/defense/src/render/shapes.ts +142 -23
  102. package/templates/defense/src/render/sky.ts +2 -2
  103. package/templates/defense/src/render/worldEnvironment.ts +208 -33
  104. package/templates/defense/src/scenes/Boot.ts +2 -2
  105. package/templates/defense/src/scenes/Defense.ts +13 -6
  106. package/templates/defense/src/style.css +20 -0
  107. package/templates/defense/src/towers/Tower.ts +11 -12
  108. package/templates/defense/src/towers/targeting.ts +1 -1
  109. package/templates/defense/src/ui/App.tsx +2 -2
  110. package/templates/defense/threenative.config.ts +7 -0
  111. package/templates/minimal/.codex/config.toml +4 -0
  112. package/templates/minimal/.cursor/mcp.json +32 -0
  113. package/templates/minimal/.gemini/settings.json +32 -0
  114. package/templates/minimal/.mcp.json +15 -3
  115. package/templates/minimal/.vscode/mcp.json +36 -0
  116. package/templates/minimal/.zed/settings.json +36 -0
  117. package/templates/minimal/AGENTS.md +76 -485
  118. package/templates/minimal/CLAUDE.md +76 -485
  119. package/templates/minimal/opencode.json +41 -0
  120. package/templates/minimal/package.json +6 -6
  121. package/templates/minimal/playtests/play.playtest.json +2 -1
  122. package/templates/minimal/playtests/survives.playtest.json +48 -4
  123. package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
  124. package/templates/minimal/src/conventions.ts +18 -0
  125. package/templates/minimal/src/entities/Player.ts +39 -6
  126. package/templates/minimal/src/main.ts +14 -4
  127. package/templates/minimal/src/render/materials.ts +7 -0
  128. package/templates/minimal/src/render/palette.ts +3 -3
  129. package/templates/minimal/src/render/postprocessing.ts +17 -56
  130. package/templates/minimal/src/render/quality.ts +162 -0
  131. package/templates/minimal/src/render/sky.ts +23 -9
  132. package/templates/minimal/src/render/touch-controls.ts +165 -0
  133. package/templates/minimal/src/render/worldEnvironment.ts +208 -33
  134. package/templates/minimal/src/scenes/Play.ts +47 -11
  135. package/templates/minimal/src/style.css +20 -0
  136. package/templates/minimal/threenative.config.ts +7 -0
  137. package/templates/platformer/.codex/config.toml +4 -0
  138. package/templates/platformer/.cursor/mcp.json +32 -0
  139. package/templates/platformer/.gemini/settings.json +32 -0
  140. package/templates/platformer/.mcp.json +15 -3
  141. package/templates/platformer/.vscode/mcp.json +36 -0
  142. package/templates/platformer/.zed/settings.json +36 -0
  143. package/templates/platformer/AGENTS.md +70 -430
  144. package/templates/platformer/CLAUDE.md +70 -430
  145. package/templates/platformer/opencode.json +41 -0
  146. package/templates/platformer/package.json +7 -7
  147. package/templates/platformer/playtests/oneway.playtest.json +29 -2
  148. package/templates/platformer/playtests/performance.playtest.json +2 -1
  149. package/templates/platformer/playtests/survives.playtest.json +31 -0
  150. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +3 -0
  151. package/templates/platformer/playtests/touch-controls-web.playtest.json +15 -4
  152. package/templates/platformer/src/conventions.ts +18 -0
  153. package/templates/platformer/src/entities/Character.ts +63 -1
  154. package/templates/platformer/src/game.ts +3 -1
  155. package/templates/platformer/src/level/Platform.ts +13 -1
  156. package/templates/platformer/src/render/lighting.ts +7 -4
  157. package/templates/platformer/src/render/loading.ts +12 -2
  158. package/templates/platformer/src/render/palette.ts +4 -1
  159. package/templates/platformer/src/render/postprocessing.ts +32 -57
  160. package/templates/platformer/src/render/quality.ts +170 -0
  161. package/templates/platformer/src/render/worldEnvironment.ts +208 -33
  162. package/templates/platformer/src/scenes/Level.ts +52 -12
  163. package/templates/platformer/src/style.css +20 -0
  164. package/templates/platformer/threenative.config.ts +7 -0
  165. package/templates/puzzle/.codex/config.toml +19 -0
  166. package/templates/puzzle/.cursor/mcp.json +32 -0
  167. package/templates/puzzle/.gemini/settings.json +32 -0
  168. package/templates/puzzle/.mcp.json +32 -0
  169. package/templates/puzzle/.vscode/mcp.json +36 -0
  170. package/templates/puzzle/.zed/settings.json +36 -0
  171. package/templates/puzzle/AGENTS.md +96 -0
  172. package/templates/puzzle/CLAUDE.md +98 -0
  173. package/templates/puzzle/README.md +43 -0
  174. package/templates/puzzle/index.html +12 -0
  175. package/templates/puzzle/kit.json +7 -0
  176. package/templates/puzzle/opencode.json +41 -0
  177. package/templates/puzzle/package.json +50 -0
  178. package/templates/puzzle/playtests/carry.playtest.json +71 -0
  179. package/templates/puzzle/playtests/performance.playtest.json +23 -0
  180. package/templates/puzzle/playtests/survives.playtest.json +51 -0
  181. package/templates/puzzle/playtests/swing.playtest.json +38 -0
  182. package/templates/puzzle/public/favicon.svg +5 -0
  183. package/templates/puzzle/src/conventions.ts +25 -0
  184. package/templates/puzzle/src/entities/Ball.ts +70 -0
  185. package/templates/puzzle/src/entities/Crate.ts +76 -0
  186. package/templates/puzzle/src/entities/Gripper.ts +69 -0
  187. package/templates/puzzle/src/entities/Pendulum.ts +89 -0
  188. package/templates/puzzle/src/game.ts +48 -0
  189. package/templates/puzzle/src/main.ts +15 -0
  190. package/templates/puzzle/src/physics.ts +19 -0
  191. package/templates/puzzle/src/render/camera.ts +37 -0
  192. package/templates/puzzle/src/render/lighting.ts +55 -0
  193. package/templates/puzzle/src/render/loading.ts +325 -0
  194. package/templates/puzzle/src/render/materials.ts +28 -0
  195. package/templates/puzzle/src/render/palette.ts +31 -0
  196. package/templates/puzzle/src/render/postprocessing.ts +34 -0
  197. package/templates/puzzle/src/render/quality.ts +170 -0
  198. package/templates/puzzle/src/render/shapes.ts +134 -0
  199. package/templates/puzzle/src/render/sky.ts +16 -0
  200. package/templates/puzzle/src/render/touch-controls.ts +185 -0
  201. package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
  202. package/templates/puzzle/src/room.ts +83 -0
  203. package/templates/puzzle/src/scenes/Boot.ts +12 -0
  204. package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
  205. package/templates/puzzle/src/state.ts +30 -0
  206. package/templates/puzzle/src/style.css +96 -0
  207. package/templates/puzzle/src/ui/App.tsx +22 -0
  208. package/templates/puzzle/src/ui/GameUi.tsx +20 -0
  209. package/templates/puzzle/src/ui/Hud.tsx +57 -0
  210. package/templates/puzzle/src/ui/Menu.tsx +7 -0
  211. package/templates/puzzle/src/ui/main.tsx +14 -0
  212. package/templates/puzzle/tailwind.config.ts +1 -0
  213. package/templates/puzzle/threenative.config.ts +49 -0
  214. package/templates/puzzle/tsconfig.json +17 -0
  215. package/templates/puzzle/vite.config.ts +38 -0
  216. package/templates/racing/.codex/config.toml +4 -0
  217. package/templates/racing/.cursor/mcp.json +32 -0
  218. package/templates/racing/.gemini/settings.json +32 -0
  219. package/templates/racing/.mcp.json +15 -3
  220. package/templates/racing/.vscode/mcp.json +36 -0
  221. package/templates/racing/.zed/settings.json +36 -0
  222. package/templates/racing/AGENTS.md +63 -379
  223. package/templates/racing/CLAUDE.md +63 -379
  224. package/templates/racing/native-playtests/survives.playtest.json +43 -0
  225. package/templates/racing/opencode.json +41 -0
  226. package/templates/racing/package.json +8 -7
  227. package/templates/racing/playtests/performance.playtest.json +24 -7
  228. package/templates/racing/playtests/survives.playtest.json +36 -4
  229. package/templates/racing/playtests/touch-controls.playtest.json +41 -0
  230. package/templates/racing/src/conventions.ts +6 -0
  231. package/templates/racing/src/entities/RacingCar.ts +16 -4
  232. package/templates/racing/src/entities/Rival.ts +5 -2
  233. package/templates/racing/src/render/camera.ts +7 -4
  234. package/templates/racing/src/render/lighting.ts +22 -13
  235. package/templates/racing/src/render/loading.ts +12 -2
  236. package/templates/racing/src/render/materials.ts +54 -4
  237. package/templates/racing/src/render/palette.ts +23 -6
  238. package/templates/racing/src/render/postprocessing.ts +21 -58
  239. package/templates/racing/src/render/quality.ts +170 -0
  240. package/templates/racing/src/render/shapes.ts +537 -26
  241. package/templates/racing/src/render/sky.ts +5 -2
  242. package/templates/racing/src/render/touch-controls.ts +185 -0
  243. package/templates/racing/src/render/worldEnvironment.ts +208 -33
  244. package/templates/racing/src/scenes/Race.ts +17 -2
  245. package/templates/racing/src/style.css +20 -0
  246. package/templates/racing/src/track/Track.ts +270 -31
  247. package/templates/racing/threenative.config.ts +7 -0
  248. package/templates/runner/.codex/config.toml +19 -0
  249. package/templates/runner/.cursor/mcp.json +32 -0
  250. package/templates/runner/.gemini/settings.json +32 -0
  251. package/templates/runner/.mcp.json +32 -0
  252. package/templates/runner/.vscode/mcp.json +36 -0
  253. package/templates/runner/.zed/settings.json +36 -0
  254. package/templates/runner/AGENTS.md +96 -0
  255. package/templates/runner/CLAUDE.md +98 -0
  256. package/templates/runner/README.md +43 -0
  257. package/templates/runner/index.html +12 -0
  258. package/templates/runner/kit.json +7 -0
  259. package/templates/runner/opencode.json +41 -0
  260. package/templates/runner/package.json +50 -0
  261. package/templates/runner/playtests/performance.playtest.json +23 -0
  262. package/templates/runner/playtests/streams.playtest.json +38 -0
  263. package/templates/runner/playtests/survives.playtest.json +51 -0
  264. package/templates/runner/public/favicon.svg +5 -0
  265. package/templates/runner/src/conventions.ts +24 -0
  266. package/templates/runner/src/entities/Runner.ts +135 -0
  267. package/templates/runner/src/game.ts +50 -0
  268. package/templates/runner/src/main.ts +15 -0
  269. package/templates/runner/src/physics.ts +13 -0
  270. package/templates/runner/src/render/camera.ts +39 -0
  271. package/templates/runner/src/render/dust.ts +131 -0
  272. package/templates/runner/src/render/lighting.ts +57 -0
  273. package/templates/runner/src/render/loading.ts +325 -0
  274. package/templates/runner/src/render/materials.ts +27 -0
  275. package/templates/runner/src/render/palette.ts +30 -0
  276. package/templates/runner/src/render/postprocessing.ts +34 -0
  277. package/templates/runner/src/render/quality.ts +170 -0
  278. package/templates/runner/src/render/shapes.ts +68 -0
  279. package/templates/runner/src/render/sky.ts +51 -0
  280. package/templates/runner/src/render/touch-controls.ts +185 -0
  281. package/templates/runner/src/render/worldEnvironment.ts +758 -0
  282. package/templates/runner/src/scenes/Boot.ts +12 -0
  283. package/templates/runner/src/scenes/Run.ts +142 -0
  284. package/templates/runner/src/state.ts +29 -0
  285. package/templates/runner/src/style.css +96 -0
  286. package/templates/runner/src/track.ts +176 -0
  287. package/templates/runner/src/ui/App.tsx +22 -0
  288. package/templates/runner/src/ui/GameUi.tsx +20 -0
  289. package/templates/runner/src/ui/Hud.tsx +55 -0
  290. package/templates/runner/src/ui/Menu.tsx +7 -0
  291. package/templates/runner/src/ui/main.tsx +14 -0
  292. package/templates/runner/tailwind.config.ts +1 -0
  293. package/templates/runner/threenative.config.ts +49 -0
  294. package/templates/runner/tsconfig.json +17 -0
  295. package/templates/runner/vite.config.ts +38 -0
  296. package/templates/sailing/.codex/config.toml +4 -0
  297. package/templates/sailing/.cursor/mcp.json +32 -0
  298. package/templates/sailing/.gemini/settings.json +32 -0
  299. package/templates/sailing/.mcp.json +15 -3
  300. package/templates/sailing/.vscode/mcp.json +36 -0
  301. package/templates/sailing/.zed/settings.json +36 -0
  302. package/templates/sailing/AGENTS.md +62 -355
  303. package/templates/sailing/CLAUDE.md +62 -355
  304. package/templates/sailing/README.md +12 -9
  305. package/templates/sailing/native-playtests/float.playtest.json +55 -0
  306. package/templates/sailing/native-playtests/survives.playtest.json +20 -3
  307. package/templates/sailing/opencode.json +41 -0
  308. package/templates/sailing/package.json +8 -8
  309. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
  310. package/templates/sailing/playtests/float.playtest.json +59 -0
  311. package/templates/sailing/playtests/performance.playtest.json +21 -6
  312. package/templates/sailing/playtests/survives.playtest.json +8 -0
  313. package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
  314. package/templates/sailing/src/conventions.ts +8 -0
  315. package/templates/sailing/src/entities/Ship.ts +150 -13
  316. package/templates/sailing/src/render/camera.ts +15 -8
  317. package/templates/sailing/src/render/lighting.ts +10 -5
  318. package/templates/sailing/src/render/loading.ts +12 -2
  319. package/templates/sailing/src/render/materials.ts +24 -8
  320. package/templates/sailing/src/render/ocean.ts +179 -0
  321. package/templates/sailing/src/render/palette.ts +14 -21
  322. package/templates/sailing/src/render/postprocessing.ts +23 -22
  323. package/templates/sailing/src/render/props.ts +584 -34
  324. package/templates/sailing/src/render/quality.ts +140 -0
  325. package/templates/sailing/src/render/sky.ts +8 -3
  326. package/templates/sailing/src/render/touch-controls.ts +142 -0
  327. package/templates/sailing/src/render/worldEnvironment.ts +206 -38
  328. package/templates/sailing/src/scenes/Sailing.ts +43 -16
  329. package/templates/sailing/src/style.css +20 -0
  330. package/templates/sailing/threenative.config.ts +7 -1
  331. package/templates/shooter/.codex/config.toml +4 -0
  332. package/templates/shooter/.cursor/mcp.json +32 -0
  333. package/templates/shooter/.gemini/settings.json +32 -0
  334. package/templates/shooter/.mcp.json +15 -3
  335. package/templates/shooter/.vscode/mcp.json +36 -0
  336. package/templates/shooter/.zed/settings.json +36 -0
  337. package/templates/shooter/AGENTS.md +76 -415
  338. package/templates/shooter/CLAUDE.md +76 -415
  339. package/templates/shooter/kit.json +2 -2
  340. package/templates/shooter/opencode.json +41 -0
  341. package/templates/shooter/package.json +7 -7
  342. package/templates/shooter/playtests/combat.playtest.json +48 -0
  343. package/templates/shooter/playtests/input-control.playtest.json +165 -35
  344. package/templates/shooter/playtests/per-item.playtest.json +3 -3
  345. package/templates/shooter/playtests/performance.playtest.json +24 -7
  346. package/templates/shooter/playtests/shooter.playtest.json +13 -7
  347. package/templates/shooter/playtests/survives.playtest.json +27 -0
  348. package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
  349. package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
  350. package/templates/shooter/src/combat/damage.ts +1 -2
  351. package/templates/shooter/src/conventions.ts +51 -0
  352. package/templates/shooter/src/entities/Player.ts +235 -18
  353. package/templates/shooter/src/entities/Target.ts +2 -2
  354. package/templates/shooter/src/game.ts +13 -4
  355. package/templates/shooter/src/render/camera.ts +49 -39
  356. package/templates/shooter/src/render/decals.ts +211 -0
  357. package/templates/shooter/src/render/lighting.ts +7 -3
  358. package/templates/shooter/src/render/loading.ts +12 -2
  359. package/templates/shooter/src/render/materials.ts +56 -3
  360. package/templates/shooter/src/render/palette.ts +6 -3
  361. package/templates/shooter/src/render/postprocessing.ts +21 -58
  362. package/templates/shooter/src/render/quality.ts +170 -0
  363. package/templates/shooter/src/render/scale.ts +22 -0
  364. package/templates/shooter/src/render/shapes.ts +343 -62
  365. package/templates/shooter/src/render/sky.ts +5 -1
  366. package/templates/shooter/src/render/touch-controls.ts +305 -0
  367. package/templates/shooter/src/render/ui.css +85 -0
  368. package/templates/shooter/src/render/ui.ts +19 -3
  369. package/templates/shooter/src/render/vfx.ts +215 -0
  370. package/templates/shooter/src/render/worldEnvironment.ts +208 -33
  371. package/templates/shooter/src/scenes/Play.ts +171 -56
  372. package/templates/shooter/src/state.ts +5 -0
  373. package/templates/shooter/src/style.css +20 -0
  374. package/templates/shooter/src/ui/Crosshair.tsx +25 -0
  375. package/templates/shooter/src/ui/GameUi.tsx +2 -0
  376. package/templates/shooter/src/ui/Hud.tsx +7 -1
  377. package/templates/shooter/src/weapons/Hitscan.ts +3 -4
  378. package/templates/shooter/src/weapons/Projectile.ts +8 -3
  379. package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
  380. package/templates/shooter/threenative.config.ts +7 -0
  381. package/templates/starter/.codex/config.toml +4 -0
  382. package/templates/starter/.cursor/mcp.json +32 -0
  383. package/templates/starter/.gemini/settings.json +32 -0
  384. package/templates/starter/.mcp.json +15 -3
  385. package/templates/starter/.vscode/mcp.json +36 -0
  386. package/templates/starter/.zed/settings.json +36 -0
  387. package/templates/starter/AGENTS.md +70 -527
  388. package/templates/starter/CLAUDE.md +70 -527
  389. package/templates/starter/native-playtests/render-chain.playtest.json +73 -4
  390. package/templates/starter/opencode.json +41 -0
  391. package/templates/starter/package.json +7 -7
  392. package/templates/starter/playtests/boot-failure.playtest.json +45 -0
  393. package/templates/starter/playtests/look.playtest.json +110 -6
  394. package/templates/starter/playtests/play.playtest.json +3 -2
  395. package/templates/starter/playtests/survives.playtest.json +21 -0
  396. package/templates/starter/playtests/touch-controls.playtest.json +42 -0
  397. package/templates/starter/src/conventions.ts +18 -0
  398. package/templates/starter/src/entities/Goal.ts +18 -3
  399. package/templates/starter/src/entities/Player.ts +72 -9
  400. package/templates/starter/src/game.ts +2 -0
  401. package/templates/starter/src/render/adaptiveQuality.ts +195 -0
  402. package/templates/starter/src/render/camera.ts +1 -1
  403. package/templates/starter/src/render/coast.ts +199 -0
  404. package/templates/starter/src/render/hero.ts +88 -0
  405. package/templates/starter/src/render/implicitSurface.ts +199 -0
  406. package/templates/starter/src/render/kuwahara.ts +174 -0
  407. package/templates/starter/src/render/lighting.ts +4 -4
  408. package/templates/starter/src/render/loading.ts +12 -2
  409. package/templates/starter/src/render/materials.ts +25 -6
  410. package/templates/starter/src/render/outline.ts +141 -0
  411. package/templates/starter/src/render/painterly.ts +86 -0
  412. package/templates/starter/src/render/palette.ts +15 -6
  413. package/templates/starter/src/render/postprocessing.ts +87 -36
  414. package/templates/starter/src/render/quality.ts +185 -0
  415. package/templates/starter/src/render/rockRidge.ts +198 -0
  416. package/templates/starter/src/render/rockRidge.worker.ts +77 -0
  417. package/templates/starter/src/render/scenery.ts +16 -59
  418. package/templates/starter/src/render/textureLifetime.ts +53 -0
  419. package/templates/starter/src/render/touch-controls.ts +165 -0
  420. package/templates/starter/src/render/water.ts +38 -0
  421. package/templates/starter/src/render/watercolor.ts +85 -0
  422. package/templates/starter/src/render/worldEnvironment.ts +208 -33
  423. package/templates/starter/src/scenes/Play.ts +103 -16
  424. package/templates/starter/src/style.css +27 -7
  425. package/templates/starter/threenative.config.ts +7 -7
  426. package/agent-docs/asset-mcp-loop.md +0 -33
  427. package/agent-docs/ctx-surface.md +0 -69
  428. package/agent-docs/engine-capabilities.md +0 -4
  429. package/agent-docs/framework-blocks-you.md +0 -60
  430. package/agent-docs/look-at-it-and-budget-the-look.md +0 -27
  431. package/agent-docs/performance-default.md +0 -42
  432. package/agent-docs/pixel-budget.md +0 -20
  433. package/agent-docs/playtest-fail-closed.md +0 -23
  434. package/agent-docs/sculpt-loop.md +0 -16
  435. package/templates/action-rpg/src/physics.ts +0 -40
  436. package/templates/defense/public/icon.png +0 -0
  437. package/templates/minimal/public/icon.png +0 -0
  438. package/templates/platformer/public/icon.png +0 -0
  439. package/templates/racing/public/icon.png +0 -0
  440. package/templates/sailing/public/icon.png +0 -0
  441. package/templates/sailing/src/render/water-material.ts +0 -14
  442. package/templates/sailing/src/render/water-shaders.ts +0 -12
  443. package/templates/sailing/src/render/wave-nodes.ts +0 -10
  444. package/templates/shooter/public/icon.png +0 -0
  445. package/templates/shooter/src/physics.ts +0 -49
  446. package/templates/starter/public/icon.png +0 -0
  447. /package/{templates/action-rpg/public → template-assets}/icon.png +0 -0
@@ -16,15 +16,15 @@
16
16
  "typecheck": "tsc --noEmit -p tsconfig.json"
17
17
  },
18
18
  "dependencies": {
19
- "@threenative/core": "0.3.0",
20
- "@threenative/physics": "0.3.0",
19
+ "@threenative/core": "0.3.1",
20
+ "@threenative/physics": "0.3.1",
21
21
  "three": "0.185.1"
22
22
  },
23
23
  "devDependencies": {
24
- "@threenative/assets": "0.3.0",
25
- "@threenative/playtest": "0.3.0",
24
+ "@threenative/assets": "0.3.1",
25
+ "@threenative/playtest": "0.3.1",
26
26
  "@types/three": "0.185.3",
27
- "create-threenative": "0.2.3",
27
+ "create-threenative": "0.2.4",
28
28
  "esbuild": "0.27.0",
29
29
  "playwright": "1.62.1",
30
30
  "typescript": "5.9.3",
@@ -32,7 +32,7 @@
32
32
  "@gltf-transform/cli": "4.4.2"
33
33
  },
34
34
  "optionalDependencies": {
35
- "@threenative/runtime-native": "0.3.0"
35
+ "@threenative/runtime-native": "0.3.1"
36
36
  },
37
37
  "pnpm": {
38
38
  "onlyBuiltDependencies": ["@threenative/core", "@threenative/runtime-native"],
@@ -35,7 +35,8 @@
35
35
  "performance": {
36
36
  "maxDrawCalls": 48,
37
37
  "maxFrameMsP95": 33,
38
- "maxTriangles": 1223
38
+ "maxTriangles": 6200,
39
+ "minFps": 30
39
40
  },
40
41
  "renderChain": {
41
42
  "tier": "high"
@@ -2,12 +2,26 @@
2
2
  "name": "survives",
3
3
  "target": "web",
4
4
  "schemaVersion": 1,
5
- "viewport": { "width": 1280, "height": 720 },
5
+ "viewport": {
6
+ "width": 1280,
7
+ "height": 720
8
+ },
6
9
  "warmupFrames": 10,
7
10
  "subject": "player",
8
11
  "steps": [
9
- { "kind": "input", "label": "move", "press": "ArrowUp", "holdTicks": 60, "release": true },
10
- { "kind": "wait", "label": "settle", "waitTicks": 10, "release": true }
12
+ {
13
+ "kind": "input",
14
+ "label": "move",
15
+ "press": "ArrowUp",
16
+ "holdTicks": 60,
17
+ "release": true
18
+ },
19
+ {
20
+ "kind": "wait",
21
+ "label": "settle",
22
+ "waitTicks": 10,
23
+ "release": true
24
+ }
11
25
  ],
12
26
  "assert": {
13
27
  "diagnostics": {
@@ -16,7 +30,37 @@
16
30
  "noRuntimeDiagnostics": true,
17
31
  "runtimeReady": true
18
32
  },
19
- "movement": { "entity": "player", "minDistance": 0.5 },
33
+ "components": [
34
+ {
35
+ "entity": "player",
36
+ "component": "groundCorrectionEnabled",
37
+ "equals": false,
38
+ "allowTrivial": "The disabled correction is intentional while its measurement remains live."
39
+ },
40
+ {
41
+ "entity": "player",
42
+ "component": "groundClearance",
43
+ "lte": 0,
44
+ "allowTrivial": "The authored pose is intentionally below the floor so clearance stays observable."
45
+ },
46
+ {
47
+ "entity": "player",
48
+ "component": "normaliseFactor",
49
+ "allowTrivial": "The figure is authored taller than the template's 1.1 m convention and normalised down, so the retained factor is below one; either side of one proves normaliseToMetres ran in generated source.",
50
+ "lte": 0.99
51
+ }
52
+ ],
53
+ "movement": {
54
+ "entity": "player",
55
+ "minDistance": 0.5
56
+ },
57
+ "visibility": [
58
+ {
59
+ "entity": "touch-controls",
60
+ "present": false,
61
+ "allowTrivial": "Desktop keyboard lanes intentionally omit touch controls while movement proves the scene is active."
62
+ }
63
+ ],
20
64
  "visual": [
21
65
  {
22
66
  "region": {
@@ -0,0 +1,42 @@
1
+ {
2
+ "name": "minimal-touch-controls",
3
+ "schemaVersion": 1,
4
+ "target": "web",
5
+ "viewport": { "width": 1280, "height": 720 },
6
+ "warmupFrames": 10,
7
+ "subject": "player",
8
+ "steps": [
9
+ {
10
+ "kind": "input",
11
+ "label": "movement-anchor",
12
+ "pointers": [{ "id": 7, "x": 0.18, "y": 0.75 }],
13
+ "holdTicks": 2,
14
+ "release": false
15
+ },
16
+ {
17
+ "kind": "input",
18
+ "label": "move-right",
19
+ "pointers": [{ "id": 7, "x": 0.38, "y": 0.75 }],
20
+ "holdTicks": 45,
21
+ "release": true
22
+ },
23
+ { "kind": "wait", "label": "settled", "waitTicks": 10, "release": true }
24
+ ],
25
+ "assert": {
26
+ "diagnostics": {
27
+ "noConsoleErrors": true,
28
+ "noNetworkErrors": true,
29
+ "noRuntimeDiagnostics": true,
30
+ "runtimeReady": true
31
+ },
32
+ "movement": { "entity": "player", "minDistance": 0.1 },
33
+ "resources": [{ "id": "state", "path": "playerX", "changed": true }],
34
+ "visibility": [
35
+ {
36
+ "entity": "touch-controls",
37
+ "present": true,
38
+ "allowTrivial": "Touch-primary lanes keep the authored controls visible while state assertions prove they are live."
39
+ }
40
+ ]
41
+ }
42
+ }
@@ -0,0 +1,18 @@
1
+ import { GroundSnap, normaliseToMetres } from "@threenative/core";
2
+ import type { Mesh } from "three";
3
+
4
+ export interface IMinimalConventions {
5
+ readonly applyGrounding: (surfaceY: number, dt: number) => void;
6
+ readonly groundSnap: GroundSnap;
7
+ readonly normaliseFactor: number;
8
+ }
9
+
10
+ export function preparePlayerConventions(model: Mesh): IMinimalConventions {
11
+ const normaliseFactor = normaliseToMetres(model, { axis: "height", metres: 1.1 });
12
+ const groundSnap = new GroundSnap(model, { enabled: false });
13
+ return {
14
+ applyGrounding: (surfaceY, dt) => groundSnap.apply(model, surfaceY, dt),
15
+ groundSnap,
16
+ normaliseFactor,
17
+ };
18
+ }
@@ -1,7 +1,9 @@
1
1
  import type { ICtx } from "@threenative/core";
2
2
  import { CharacterBody3D, CollisionShape3D, type IPhysicsContext } from "@threenative/physics";
3
- import { BoxGeometry, Mesh } from "three";
4
- import { defaultMaterial } from "../render/materials.js";
3
+ import { BoxGeometry, Group, Mesh } from "three";
4
+ import { type IMinimalConventions, preparePlayerConventions } from "../conventions.js";
5
+ import { accentMaterial, defaultMaterial } from "../render/materials.js";
6
+ import type { ITouchInput } from "../render/touch-controls.js";
5
7
  import type { GameState } from "../state.js";
6
8
 
7
9
  type GameCtx = ICtx<GameState, IPhysicsContext>;
@@ -13,16 +15,37 @@ const MOVE_SPEED = 2;
13
15
  const SPAWN = { x: -2, y: 0.5, z: 0 } as const;
14
16
 
15
17
  export class Player {
16
- readonly mesh = new Mesh(new BoxGeometry(0.6, 1, 0.6), defaultMaterial);
18
+ readonly mesh: Group;
19
+ readonly visual: Mesh;
17
20
  readonly body: CharacterBody3D;
21
+ #conventions: IMinimalConventions;
18
22
  #coyoteTime = 0;
19
23
  #jumpBuffer = 0;
20
24
  #jumps = 0;
21
25
  #coyoteJumps = 0;
22
26
 
23
27
  constructor(ctx: GameCtx) {
28
+ this.mesh = new Group();
29
+ // A figure, not a cube. Three boxes is still minimal, and it gives the player a front — which
30
+ // is the whole difference between "a character" and "the scene's placeholder".
31
+ this.visual = new Mesh(new BoxGeometry(0.46, 0.56, 0.34), defaultMaterial);
32
+ this.visual.castShadow = true;
33
+ const head = new Mesh(new BoxGeometry(0.34, 0.3, 0.3), defaultMaterial);
34
+ head.position.y = 0.42;
35
+ head.castShadow = true;
36
+ this.visual.add(head);
37
+ const visor = new Mesh(new BoxGeometry(0.26, 0.08, 0.04), accentMaterial);
38
+ visor.position.set(0, 0.44, -0.16);
39
+ this.visual.add(visor);
40
+ for (const side of [-1, 1]) {
41
+ const leg = new Mesh(new BoxGeometry(0.15, 0.34, 0.2), accentMaterial);
42
+ leg.position.set(side * 0.12, -0.44, 0);
43
+ leg.castShadow = true;
44
+ this.visual.add(leg);
45
+ }
46
+ this.mesh.add(this.visual);
24
47
  this.mesh.position.set(SPAWN.x, SPAWN.y, SPAWN.z);
25
- this.mesh.castShadow = true;
48
+ this.#conventions = preparePlayerConventions(this.visual);
26
49
  ctx.add(this.mesh);
27
50
  this.body = new CharacterBody3D({
28
51
  autostep: { maxHeight: 0.4, minWidth: 0.2 },
@@ -32,11 +55,12 @@ export class Player {
32
55
  });
33
56
  }
34
57
 
35
- update(ctx: GameCtx, dt: number): void {
58
+ update(ctx: GameCtx, dt: number, touch?: ITouchInput): void {
36
59
  this.#coyoteTime = Math.max(0, this.#coyoteTime - dt);
37
60
  this.#jumpBuffer = Math.max(0, this.#jumpBuffer - dt);
38
61
  if (this.body.grounded) this.#coyoteTime = COYOTE_TIME;
39
- if (ctx.input.justPressed("jump")) this.#jumpBuffer = JUMP_BUFFER;
62
+ if (ctx.input.justPressed("jump") || touch?.jumpPressed === true)
63
+ this.#jumpBuffer = JUMP_BUFFER;
40
64
  if (this.#jumpBuffer > 0 && this.#coyoteTime > 0) {
41
65
  this.body.velocity.y = JUMP_SPEED;
42
66
  this.#jumpBuffer = 0;
@@ -45,16 +69,25 @@ export class Player {
45
69
  this.#coyoteJumps += 1;
46
70
  }
47
71
  const move = ctx.input.vector("move");
72
+ if (touch !== undefined) {
73
+ move.x += touch.move.x;
74
+ move.y += touch.move.y;
75
+ move.clampLength(0, 1);
76
+ }
48
77
  this.body.velocity.x = move.x * MOVE_SPEED;
49
78
  this.body.velocity.z = -move.y * MOVE_SPEED;
50
79
  this.body.moveAndSlide(dt);
80
+ this.#conventions.applyGrounding(0, dt);
51
81
  }
52
82
 
53
83
  debug(): Record<string, unknown> {
54
84
  return {
55
85
  coyoteJumps: this.#coyoteJumps,
56
86
  grounded: this.body.grounded,
87
+ groundClearance: this.#conventions.groundSnap.clearance,
88
+ groundCorrectionEnabled: this.#conventions.groundSnap.enabled,
57
89
  jumps: this.#jumps,
90
+ normaliseFactor: this.#conventions.normaliseFactor,
58
91
  position: this.mesh.position.toArray(),
59
92
  };
60
93
  }
@@ -11,7 +11,17 @@ if (app === null) throw new Error("Missing #app element.");
11
11
 
12
12
  import.meta.hot?.accept();
13
13
  acceptHotUpdate(game, import.meta.hot);
14
- void game.start().then(() => {
15
- const canvas = game.ctx?.renderer.domElement;
16
- if (canvas !== undefined) app.prepend(canvas);
17
- });
14
+ void game
15
+ .start()
16
+ .then(() => {
17
+ const canvas = game.ctx?.renderer.domElement;
18
+ if (canvas !== undefined) app.prepend(canvas);
19
+ })
20
+ .catch((error: unknown) => {
21
+ const failure = document.createElement("div");
22
+ failure.id = "threenative-canvas-error";
23
+ failure.dataset.threenativeCanvasError = "true";
24
+ failure.setAttribute("role", "alert");
25
+ failure.textContent = error instanceof Error ? error.message : String(error);
26
+ app.replaceChildren(failure);
27
+ });
@@ -9,6 +9,13 @@ export const floorMaterial = new MeshStandardMaterial({
9
9
  metalness: 0.12,
10
10
  });
11
11
 
12
+ /** The player's visor and boots: the one warm note against a cool morning. */
13
+ export const accentMaterial = new MeshStandardMaterial({
14
+ color: palette.accent,
15
+ roughness: 0.6,
16
+ metalness: 0.05,
17
+ });
18
+
12
19
  export const defaultMaterial = new MeshStandardMaterial({
13
20
  color: palette.player,
14
21
  roughness: 0.52,
@@ -1,9 +1,9 @@
1
1
  // Generated for you. Keep these six roles coherent when you change the look.
2
2
  export const palette = {
3
3
  skyHigh: 0x14516e,
4
- skyLow: 0x071018,
5
- floor: 0x12384a,
4
+ skyLow: 0x1b3a4e,
5
+ floor: 0x27566b,
6
6
  player: 0x6fe8ff,
7
7
  accent: 0xffd27a,
8
- shadow: 0x10232d,
8
+ shadow: 0x24414f,
9
9
  } as const;
@@ -1,20 +1,19 @@
1
- // Generated for you. This is ordinary Three.js — edit or delete it freely.
2
- // ThreeNative does not read this file.
1
+ // Generated for you: ordinary Three.js; ThreeNative does not read this file.
3
2
  //
4
- // `WorldEnvironment`, in this folder, builds the lighting chain: which stages run, in what
5
- // order, and an honest report of what happened. It prints `TN_WORLD_ENVIRONMENT` naming every
6
- // stage as applied or refused **with a reason**, so a stage that silently no-op'd is never
7
- // mistaken for one you turned off. It decides no colour and no strength — every value below is
8
- // an argument, and they are yours.
3
+ // This file wires two things together and decides nothing itself. `quality.ts`, in this folder,
4
+ // owns which stages run at which tier and records what each one measured. `WorldEnvironment`,
5
+ // also in this folder, builds them and prints `TN_WORLD_ENVIRONMENT` naming every stage as
6
+ // applied or refused **with a reason**, so a stage that silently no-op'd is never mistaken for
7
+ // one you turned off.
9
8
  //
10
- // SSGI and SSR are the expensive pair, so they ship on for desktop and off for mobile. That
11
- // split is the shipped default, not a ceiling: turn either on for mobile by adding it to
12
- // `mobilePreset` and read the frame cost back out of `TN_FRAME_BUDGET`. What each stage costs,
13
- // and the one-line enable for the ones that ship off everywhere (godrays, contact AO,
14
- // vignette), is in `agent-docs/visual-baseline.md`.
9
+ // To make the game cheaper or prettier everywhere, edit `quality.ts`. To force one tier for one
10
+ // run — a desktop that is dropping frames, a capture you want to compare — pass it:
11
+ // `setupPost(renderer, scene, camera, { tier: "low" })`. Overriding does not silence the report:
12
+ // `TN_QUALITY_TIER` names the tier that ran either way.
15
13
  import type { Camera, DirectionalLight, Scene } from "three";
16
14
  import { vec3 } from "three/tsl";
17
15
  import type { Node } from "three/webgpu";
16
+ import { type QualityTier, qualityPreset, resolveQualityTier } from "./quality.js";
18
17
  import type { OutputRenderer } from "./worldEnvironment.js";
19
18
  import { WorldEnvironment } from "./worldEnvironment.js";
20
19
 
@@ -23,49 +22,6 @@ type AtmosphereLike = {
23
22
  radiance(direction: unknown): unknown;
24
23
  };
25
24
 
26
- // Scene-referred exposure: multiplied into the pass before the tone curve, so the gather, the
27
- // reflections and the bloom threshold all see the same exposed image.
28
- const exposure = 1.15;
29
-
30
- // Unchanged from this template's previous chain — strength, radius and threshold are a look
31
- // decision that was already tuned to this scene's palette.
32
- const glow = {
33
- bloomEnabled: true,
34
- bloomRadius: 0.5,
35
- bloomStrength: 0.5,
36
- bloomThreshold: 0.2,
37
- } as const;
38
-
39
- // No SSGI here, and this is the one template where that is a measured decision rather than a
40
- // taste one: its sky, sun colour and depth haze are a volumetric `Atmosphere`, which already owns
41
- // most of the frame. With the gather on, `playtests/play.playtest.json` measured **34.2 ms p95
42
- // against the 33 ms ceiling**; without it the same scenario passes. Turn it on when you replace
43
- // the atmosphere with a flat sky, and read the p95 back out of `TN_FRAME_BUDGET`.
44
- const desktopPreset = {
45
- ...glow,
46
- exposure,
47
- ssrEnabled: true,
48
- // `SSRNode` defaults this to **1 world unit**, which on a scene this size reads as
49
- // "reflections are on and do nothing" — the ray dies a metre from where it started.
50
- ssrMaxDistance: 20,
51
- // A reflection carries almost no high-frequency detail, so half resolution costs a quarter
52
- // of the rays and is very hard to see in the result.
53
- ssrResolutionScale: 0.5,
54
- // RCAS puts back the micro-detail the half-resolution reflection and the denoiser take out.
55
- // The same cause everywhere, so the same value everywhere: **0 is maximum sharpening and 2
56
- // is none** — it is a radius, not a gain.
57
- sharpenEnabled: true,
58
- sharpenStrength: 0.3,
59
- tonemapMode: "aces",
60
- } as const;
61
-
62
- // No SSGI, no SSR, and therefore nothing for the sharpener to put back.
63
- const mobilePreset = {
64
- ...glow,
65
- exposure,
66
- tonemapMode: "aces",
67
- } as const;
68
-
69
25
  export function setupPost(
70
26
  renderer: OutputRenderer,
71
27
  scene: Scene,
@@ -74,9 +30,14 @@ export function setupPost(
74
30
  atmosphere?: AtmosphereLike;
75
31
  godraysLight?: DirectionalLight;
76
32
  mobile?: boolean;
33
+ /** Forces a tier, ignoring `mobile`. An unknown name throws rather than falling back. */
34
+ tier?: QualityTier;
77
35
  } = {},
78
36
  ): void {
79
- const world = new WorldEnvironment(environment.mobile === true ? mobilePreset : desktopPreset);
37
+ const tier = resolveQualityTier({ mobile: environment.mobile, tier: environment.tier });
38
+ const source = environment.tier === undefined ? "platform" : "override";
39
+ console.info(`TN_QUALITY_TIER ${tier} mobile=${environment.mobile === true} source=${source}`);
40
+ const world = new WorldEnvironment(qualityPreset(tier));
80
41
  const atmosphere = environment.atmosphere;
81
42
  world.apply(renderer, scene, camera, {
82
43
  // The chain builds the scene pass, so aerial perspective — which needs that pass and its
@@ -0,0 +1,162 @@
1
+ // Generated for you: ordinary Three.js; ThreeNative does not read this file. Delete or rewrite
2
+ // it freely — the tiers below are a starting point, not a framework look.
3
+ //
4
+ // This is the one place this game decides how expensive it looks. `postprocessing.ts` reads
5
+ // `qualityPreset(resolveQualityTier(...))` and nothing else, so "make it run on a phone" is one
6
+ // file to edit rather than a hunt through anonymous literals.
7
+ //
8
+ // **Where the numbers come from.** Every millisecond below is GPU time from the per-stage
9
+ // ablation recorded in the engine repository's `docs/verification/runtime-perf-state.md`: Chrome
10
+ // on an RTX 2080, 1600x900, static build, `gpuMs` read from three's `timestamp-query`. In that
11
+ // scene the whole five-stage chain costs **12.5 ms of a 14.7 ms GPU frame**, and the same frame
12
+ // with every stage off costs **2.2 ms**. The per-stage figures oversum — removing SSGI also
13
+ // removes the denoise passes the later stages sample — so read each as *what turning this one off
14
+ // gave back*, not as a share of a partition. A stage nobody has ablated on its own says
15
+ // `unmeasured` rather than guessing, and your scene is not that scene: read `TN_FRAME_BUDGET`
16
+ // back after you change a tier.
17
+ //
18
+ // One cost that is **not** a stage here and outweighs most of them: the prefiltered reflection
19
+ // probe on `scene.environment`, measured at **~6.3 ms of an 18-19 ms Pixel 8 frame**. It is set
20
+ // in `sky.ts`, not in this file.
21
+ //
22
+ // **This template runs no SSGI at any tier, and that is a measurement rather than a taste.** Its
23
+ // sky, sun colour and depth haze are a volumetric `Atmosphere`, which already owns most of the
24
+ // frame. With the gather on, `playtests/play.playtest.json` measured **34.2 ms p95 against the
25
+ // 33 ms ceiling**; without it the same scenario passes. Turn it on when you replace the
26
+ // atmosphere with a flat sky, and read the p95 back out of `TN_FRAME_BUDGET`.
27
+ import type { IWorldEnvironmentOptions } from "./worldEnvironment.js";
28
+
29
+ /**
30
+ * The three names this game's look comes in.
31
+ *
32
+ * `low` is what a phone gets and `high` what a desktop gets — those two are this template's
33
+ * shipped looks, unchanged. `medium` is the rung in between for a machine that is neither: a
34
+ * laptop iGPU, a handheld, a desktop that is dropping frames. Nothing outside this file decides
35
+ * what any of them mean.
36
+ */
37
+ export type QualityTier = "low" | "medium" | "high";
38
+
39
+ const QUALITY_TIERS: readonly QualityTier[] = ["low", "medium", "high"];
40
+
41
+ /**
42
+ * Narrows an arbitrary string — a URL parameter, a saved setting — to a tier name. Not exported:
43
+ * `resolveQualityTier` is the one door in, so an unknown name cannot be waved past the throw.
44
+ */
45
+ function isQualityTier(value: string): value is QualityTier {
46
+ return (QUALITY_TIERS as readonly string[]).includes(value);
47
+ }
48
+
49
+ /**
50
+ * Picks the tier: an explicit `tier` always wins, otherwise the platform decides.
51
+ *
52
+ * Fails closed. An unrecognised tier name throws with the value it was handed rather than
53
+ * quietly rendering the default, because a silent fallback here looks exactly like a tier that
54
+ * turned out to have no effect.
55
+ */
56
+ export function resolveQualityTier(
57
+ request: { readonly mobile?: boolean; readonly tier?: string } = {},
58
+ ): QualityTier {
59
+ const requested = request.tier;
60
+ if (requested !== undefined) {
61
+ if (!isQualityTier(requested)) {
62
+ throw new Error(
63
+ `Unknown quality tier ${JSON.stringify(requested)} — expected one of ${QUALITY_TIERS.join(", ")}.`,
64
+ );
65
+ }
66
+ return requested;
67
+ }
68
+ return request.mobile === true ? "low" : "high";
69
+ }
70
+
71
+ /**
72
+ * What a desktop gets: this template's shipped desktop look, unchanged.
73
+ *
74
+ * The whole chain measured 12.5 ms of a 14.7 ms GPU frame in the reference ablation, and SSGI
75
+ * with its denoiser is ~9.2 ms of that.
76
+ */
77
+ const high: IWorldEnvironmentOptions = {
78
+ // Strength, radius and threshold are a look decision already tuned to this scene's palette.
79
+ // Bloom: ~4.6 ms — the second most expensive stage in the chain, and the one nobody expects
80
+ // to be.
81
+ bloomEnabled: true,
82
+ bloomRadius: 0.5,
83
+ bloomStrength: 0.5,
84
+ bloomThreshold: 0.2,
85
+ exposure: 1.15,
86
+ // Screen-space reflections: ~4.1 ms.
87
+ ssrEnabled: true,
88
+ // `SSRNode` defaults this to **1 world unit**, which on a scene this size reads as "reflections
89
+ // are on and do nothing" — the ray dies a metre from where it started.
90
+ ssrMaxDistance: 20,
91
+ // A reflection carries almost no high-frequency detail, so half resolution costs a quarter of
92
+ // the rays and is very hard to see in the result.
93
+ ssrResolutionScale: 0.5,
94
+ // RCAS sharpen: unmeasured — never ablated on its own here. It puts back the micro-detail the
95
+ // denoiser and the half-resolution reflection take out, so it earns its cost only on a tier
96
+ // that runs one of them.
97
+ sharpenEnabled: true,
98
+ // **0 is maximum sharpening and 2 is none** — it is a radius, not a gain.
99
+ sharpenStrength: 0.3,
100
+ tonemapMode: "aces",
101
+ };
102
+
103
+ /**
104
+ * The rung in between. With no SSGI to drop, the reflection is the only stage large enough to be
105
+ * worth halving, so `medium` traces it at a quarter resolution instead of a half — a quarter of
106
+ * the rays. The saving is **unmeasured**: the ablation measured SSR on and off, not SSR at two
107
+ * scales.
108
+ */
109
+ const medium: IWorldEnvironmentOptions = {
110
+ // Strength, radius and threshold are a look decision already tuned to this scene's palette.
111
+ // Bloom: ~4.6 ms — the second most expensive stage in the chain, and the one nobody expects
112
+ // to be.
113
+ bloomEnabled: true,
114
+ bloomRadius: 0.5,
115
+ bloomStrength: 0.5,
116
+ bloomThreshold: 0.2,
117
+ exposure: 1.15,
118
+ // Screen-space reflections: ~4.1 ms.
119
+ ssrEnabled: true,
120
+ // `SSRNode` defaults this to **1 world unit**, which on a scene this size reads as "reflections
121
+ // are on and do nothing" — the ray dies a metre from where it started.
122
+ ssrMaxDistance: 20,
123
+ // A reflection carries almost no high-frequency detail, so half resolution costs a quarter of
124
+ // the rays and is very hard to see in the result.
125
+ ssrResolutionScale: 0.25,
126
+ // RCAS sharpen: unmeasured — never ablated on its own here. It puts back the micro-detail the
127
+ // denoiser and the half-resolution reflection take out, so it earns its cost only on a tier
128
+ // that runs one of them.
129
+ sharpenEnabled: true,
130
+ // **0 is maximum sharpening and 2 is none** — it is a radius, not a gain.
131
+ sharpenStrength: 0.3,
132
+ tonemapMode: "aces",
133
+ };
134
+
135
+ /**
136
+ * What a phone gets: this template's shipped mobile look, unchanged. Bloom and the tone curve,
137
+ * nothing screen-space. The ablation's floor — every stage off — was 2.2 ms.
138
+ */
139
+ const low: IWorldEnvironmentOptions = {
140
+ // Strength, radius and threshold are a look decision already tuned to this scene's palette.
141
+ // Bloom: ~4.6 ms — the second most expensive stage in the chain, and the one nobody expects
142
+ // to be.
143
+ bloomEnabled: true,
144
+ bloomRadius: 0.5,
145
+ bloomStrength: 0.5,
146
+ bloomThreshold: 0.2,
147
+ exposure: 1.15,
148
+ tonemapMode: "aces",
149
+ };
150
+
151
+ const QUALITY_PRESETS: Record<QualityTier, IWorldEnvironmentOptions> = { high, low, medium };
152
+
153
+ /** The stages and strengths a tier turns on. Throws on a name that is not a tier. */
154
+ export function qualityPreset(tier: string): IWorldEnvironmentOptions {
155
+ const preset = QUALITY_PRESETS[tier as QualityTier];
156
+ if (preset === undefined) {
157
+ throw new Error(
158
+ `Unknown quality tier ${JSON.stringify(tier)} — expected one of ${QUALITY_TIERS.join(", ")}.`,
159
+ );
160
+ }
161
+ return preset;
162
+ }
@@ -18,22 +18,36 @@ export function setupSky(scene: Scene, atmosphere?: AtmosphereLike): void {
18
18
  return;
19
19
  }
20
20
 
21
- // Keep the dome outside the deliberately kilometre-scale atmosphere probe in Play.ts. The
22
- // view-space depth remains metres, so the package can apply its supplied 1/km coefficients.
23
- const geometry = new SphereGeometry(20_000, 24, 12);
21
+ // Outside the deliberately kilometre-scale atmosphere probe in Play.ts, and **inside** the
22
+ // camera's far plane. The view-space depth remains metres, so the package can apply its
23
+ // supplied 1/km coefficients.
24
+ //
25
+ // The radius was 20 000 against `camera.far = 20_000`, which leaves the `BackSide` hemisphere
26
+ // sitting exactly on the far plane. Pulled in to 16 000 it has room; measured, this was not
27
+ // what was making the sky black — see the multiplier below — but a dome flush with the far
28
+ // plane is one renderer tolerance away from being clipped, so it stays pulled in.
29
+ const geometry = new SphereGeometry(16_000, 24, 12);
24
30
  const material = new MeshBasicNodeMaterial({
25
31
  fog: false,
26
32
  side: BackSide,
27
33
  toneMapped: false,
28
34
  });
29
35
  const viewDirection = normalize(positionWorld.sub(cameraPosition));
36
+ // Exposure for the dome alone.
37
+ //
30
38
  // 24 was authored when this template had no post chain, so the dome's radiance landed straight
31
- // in the frame. The chain now exposes the pass at 1.15 and tone-maps it with ACES, and the same
32
- // radiance is *also* fed to `aerialPerspective` as in-scattering in postprocessing.ts — so 24
33
- // was being applied twice over and then exposed again. Measured on a scaffolded minimal, median
34
- // frame luminance was 203 of 255 at 24 and is 25 at 1.5, against 22 for this template's last
35
- // good baseline. Both multipliers moved together; neither alone reaches it.
36
- material.colorNode = (atmosphere.radiance(viewDirection) as Node<"vec3">).mul(1.5);
39
+ // in the frame; the chain now exposes the pass at 1.15 and tone-maps it with ACES. A previous
40
+ // pass measured 203 of 255 at 24 and 25 at 1.5, and chose 1.5 because it matched "this
41
+ // template's last good baseline" of 22. That baseline was the problem: **22 of 255 is not a
42
+ // sky**, it is a black rectangle above the horizon, and it is what the smallest template showed
43
+ // a new project on its first frame with a sun fifty degrees up and a correctly-scattering
44
+ // atmosphere behind it.
45
+ //
46
+ // 8 lands the daytime sky around a hundred, which is a sky. Raising it further starts to blow
47
+ // the horizon out under ACES. This multiplier scales the dome and nothing else — the
48
+ // in-scattering `aerialPerspective` receives in postprocessing.ts comes from its own call and
49
+ // is unaffected, so this cannot double-count the way the old note feared.
50
+ material.colorNode = (atmosphere.radiance(viewDirection) as Node<"vec3">).mul(8);
37
51
  const dome = new Mesh(geometry, material);
38
52
  // The dome is authored at the origin and never moves; freeze only this known-static render
39
53
  // object, leaving gameplay transforms under user control.