create-threenative 0.2.15 → 0.2.18

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 (488) hide show
  1. package/agent-docs/kit-mcp.md +10 -0
  2. package/agent-docs/kit-router.md +14 -0
  3. package/agent-docs/kit-stuck.md +7 -0
  4. package/agent-docs/references/assertion-reference.md +54 -110
  5. package/agent-docs/references/capability-reference.md +1740 -254
  6. package/agent-docs/references/conventions.md +299 -0
  7. package/agent-docs/references/kit-action-rpg.md +40 -0
  8. package/agent-docs/references/kit-adventure.md +40 -0
  9. package/agent-docs/references/kit-collectathon.md +38 -0
  10. package/agent-docs/references/kit-kart.md +31 -0
  11. package/agent-docs/references/kit-minimal.md +29 -0
  12. package/agent-docs/references/kit-platformer.md +34 -0
  13. package/agent-docs/references/kit-puzzle.md +22 -0
  14. package/agent-docs/references/kit-racing.md +26 -0
  15. package/agent-docs/references/kit-rain.md +31 -0
  16. package/agent-docs/references/kit-rts.md +34 -0
  17. package/agent-docs/references/kit-runner.md +32 -0
  18. package/agent-docs/references/kit-sailing.md +41 -0
  19. package/agent-docs/references/kit-shooter.md +33 -0
  20. package/agent-docs/references/kit-snow.md +33 -0
  21. package/agent-docs/references/kit-starter.md +55 -0
  22. package/agent-docs/references/kit-tower-defense.md +27 -0
  23. package/agent-docs/references/performance-basics.md +8 -4
  24. package/agent-docs/references/terrain-authoring.md +2 -1
  25. package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
  26. package/agent-files/.agents/skills/prd-creator/SKILL.md +3 -2
  27. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +84 -59
  28. package/agent-files/.claude/hooks/discovery-gate.mjs +125 -0
  29. package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
  30. package/agent-files/.claude/settings.json +25 -0
  31. package/agent-files/.codex/hooks.json +18 -1
  32. package/dist/index.d.ts +97 -6
  33. package/dist/index.js +899 -271
  34. package/dist/terrain-kit.d.ts +7 -0
  35. package/dist/terrain-kit.js +82 -0
  36. package/dist/threenative.js +114 -16
  37. package/dist/web-engine-ccd-ik-solver.js +127 -0
  38. package/dist/web-engine-gltf-loader.js +71 -20
  39. package/dist/web-engine-post-effects.js +39 -14
  40. package/dist/web-engine-runtime.js +10011 -4101
  41. package/package.json +15 -9
  42. package/template-assets/clearwater/README.md +1 -1
  43. package/template-assets/patches/manifest.json +18 -0
  44. package/template-assets/patches/three@0.187.0.patch +2004 -407
  45. package/template-assets/terrain/alpine/assets.json +12 -0
  46. package/template-assets/terrain/alpine/bake.mjs +6 -0
  47. package/template-assets/terrain/alpine/credits.json +164 -0
  48. package/template-assets/terrain/alpine/heightmap.r16 +0 -0
  49. package/template-assets/terrain/alpine/recipe.json +119 -0
  50. package/template-assets/terrain/alpine/surface.json +53 -0
  51. package/template-assets/terrain/coastal/assets.json +11 -0
  52. package/template-assets/terrain/coastal/bake.mjs +6 -0
  53. package/template-assets/terrain/coastal/credits.json +117 -0
  54. package/template-assets/terrain/coastal/heightmap.r16 +0 -0
  55. package/template-assets/terrain/coastal/recipe.json +113 -0
  56. package/template-assets/terrain/coastal/surface.json +41 -0
  57. package/template-assets/terrain/desert/assets.json +12 -0
  58. package/template-assets/terrain/desert/bake.mjs +6 -0
  59. package/template-assets/terrain/desert/credits.json +164 -0
  60. package/template-assets/terrain/desert/heightmap.r16 +0 -0
  61. package/template-assets/terrain/desert/recipe.json +108 -0
  62. package/template-assets/terrain/desert/surface.json +54 -0
  63. package/template-assets/terrain/forest/assets.json +65 -0
  64. package/template-assets/terrain/forest/bake.mjs +8 -0
  65. package/template-assets/terrain/forest/credits.json +225 -0
  66. package/template-assets/terrain/forest/heightmap.r16 +0 -0
  67. package/template-assets/terrain/forest/recipe.json +350 -0
  68. package/template-assets/terrain/forest/surface.json +79 -0
  69. package/template-assets/terrain/tundra/assets.json +12 -0
  70. package/template-assets/terrain/tundra/bake.mjs +6 -0
  71. package/template-assets/terrain/tundra/credits.json +164 -0
  72. package/template-assets/terrain/tundra/heightmap.r16 +0 -0
  73. package/template-assets/terrain/tundra/recipe.json +277 -0
  74. package/template-assets/terrain/tundra/surface.json +54 -0
  75. package/templates/action-rpg/AGENTS.md +103 -84
  76. package/templates/action-rpg/CLAUDE.md +103 -84
  77. package/templates/action-rpg/kit.json +1 -0
  78. package/templates/action-rpg/package.json +7 -7
  79. package/templates/action-rpg/playtests/spells.playtest.json +20 -0
  80. package/templates/action-rpg/src/game.ts +2 -1
  81. package/templates/action-rpg/src/render/atmosphere.ts +11 -16
  82. package/templates/action-rpg/src/render/backlightControls.ts +10 -0
  83. package/templates/action-rpg/src/render/backlightMaterial.ts +4 -4
  84. package/templates/action-rpg/src/render/clouds.ts +13 -0
  85. package/templates/action-rpg/src/render/gpuSky.ts +4 -7
  86. package/templates/action-rpg/src/render/materialLighting.ts +5 -5
  87. package/templates/action-rpg/src/render/quality.ts +10 -33
  88. package/templates/action-rpg/src/scenes/Play.ts +30 -1
  89. package/templates/action-rpg/src/style.css +4 -0
  90. package/templates/action-rpg/src/ui/AbilityBar.tsx +1 -1
  91. package/templates/action-rpg/threenative.config.ts +0 -3
  92. package/templates/action-rpg/vite.config.ts +2 -0
  93. package/templates/adventure/AGENTS.md +92 -44
  94. package/templates/adventure/CLAUDE.md +92 -44
  95. package/templates/adventure/kit.json +5 -1
  96. package/templates/adventure/package.json +7 -7
  97. package/templates/adventure/src/game.ts +1 -1
  98. package/templates/adventure/src/style.css +4 -0
  99. package/templates/adventure/tsconfig.json +1 -1
  100. package/templates/adventure/vite.config.ts +2 -0
  101. package/templates/collectathon/AGENTS.md +93 -42
  102. package/templates/collectathon/CLAUDE.md +93 -42
  103. package/templates/collectathon/package.json +7 -7
  104. package/templates/collectathon/src/game.ts +1 -1
  105. package/templates/collectathon/src/level/Course.ts +55 -9
  106. package/templates/collectathon/src/level/terrain.ts +27 -6
  107. package/templates/collectathon/src/main.ts +1 -0
  108. package/templates/collectathon/src/render/foliage.ts +359 -98
  109. package/templates/collectathon/src/render/sky.ts +76 -12
  110. package/templates/collectathon/src/render/water.ts +32 -10
  111. package/templates/collectathon/src/scenes/Play.ts +18 -5
  112. package/templates/collectathon/src/style.css +4 -0
  113. package/templates/collectathon/tsconfig.json +1 -1
  114. package/templates/collectathon/vite.config.ts +2 -0
  115. package/templates/kart/AGENTS.md +87 -42
  116. package/templates/kart/CLAUDE.md +87 -42
  117. package/templates/kart/package.json +6 -6
  118. package/templates/kart/src/game.ts +1 -1
  119. package/templates/kart/src/main.ts +1 -0
  120. package/templates/kart/src/style.css +4 -0
  121. package/templates/kart/tsconfig.json +1 -1
  122. package/templates/kart/vite.config.ts +2 -0
  123. package/templates/minimal/AGENTS.md +105 -84
  124. package/templates/minimal/CLAUDE.md +105 -84
  125. package/templates/minimal/package.json +6 -6
  126. package/templates/minimal/playtests/stands-still.playtest.json +30 -0
  127. package/templates/minimal/src/game.ts +1 -1
  128. package/templates/minimal/src/render/atmosphere.ts +11 -16
  129. package/templates/minimal/src/render/backlightControls.ts +10 -0
  130. package/templates/minimal/src/render/backlightMaterial.ts +4 -4
  131. package/templates/minimal/src/render/camera.ts +13 -2
  132. package/templates/minimal/src/render/clouds.ts +13 -0
  133. package/templates/minimal/src/render/gpuSky.ts +4 -7
  134. package/templates/minimal/src/render/lighting.ts +4 -2
  135. package/templates/minimal/src/render/materialLighting.ts +5 -5
  136. package/templates/minimal/src/render/materials.ts +10 -0
  137. package/templates/minimal/src/render/quality.ts +7 -32
  138. package/templates/minimal/src/scenes/Play.ts +4 -1
  139. package/templates/minimal/vite.config.ts +7 -1
  140. package/templates/platformer/AGENTS.md +95 -46
  141. package/templates/platformer/CLAUDE.md +95 -46
  142. package/templates/platformer/index.html +1 -1
  143. package/templates/platformer/main.html +12 -0
  144. package/templates/platformer/package.json +7 -7
  145. package/templates/platformer/playtests/gamepad-idle.playtest.json +21 -0
  146. package/templates/platformer/playtests/gamepad.playtest.json +30 -0
  147. package/templates/platformer/src/entities/Fox.ts +21 -6
  148. package/templates/platformer/src/game.ts +1 -1
  149. package/templates/platformer/src/main.ts +1 -0
  150. package/templates/platformer/src/render/backlightControls.ts +10 -0
  151. package/templates/platformer/src/render/backlightMaterial.ts +4 -4
  152. package/templates/platformer/src/render/materialLighting.ts +5 -5
  153. package/templates/platformer/src/render/quality.ts +7 -32
  154. package/templates/platformer/src/scenes/Play.ts +2 -1
  155. package/templates/platformer/src/style.css +4 -0
  156. package/templates/platformer/src/worker-page.ts +29 -0
  157. package/templates/platformer/src/worker.ts +5 -0
  158. package/templates/platformer/tsconfig.json +1 -1
  159. package/templates/platformer/vite.config.ts +4 -0
  160. package/templates/puzzle/AGENTS.md +97 -80
  161. package/templates/puzzle/CLAUDE.md +97 -80
  162. package/templates/puzzle/package.json +7 -7
  163. package/templates/puzzle/src/game.ts +1 -1
  164. package/templates/puzzle/src/render/backlightControls.ts +10 -0
  165. package/templates/puzzle/src/render/backlightMaterial.ts +4 -4
  166. package/templates/puzzle/src/render/materialLighting.ts +5 -5
  167. package/templates/puzzle/src/render/quality.ts +7 -32
  168. package/templates/puzzle/src/scenes/Play.ts +1 -1
  169. package/templates/puzzle/src/style.css +4 -0
  170. package/templates/puzzle/tsconfig.json +1 -1
  171. package/templates/puzzle/vite.config.ts +2 -0
  172. package/templates/racing/AGENTS.md +100 -82
  173. package/templates/racing/CLAUDE.md +100 -82
  174. package/templates/racing/package.json +7 -7
  175. package/templates/racing/src/game.ts +1 -1
  176. package/templates/racing/src/render/atmosphere.ts +11 -16
  177. package/templates/racing/src/render/backlightControls.ts +10 -0
  178. package/templates/racing/src/render/backlightMaterial.ts +4 -4
  179. package/templates/racing/src/render/clouds.ts +13 -0
  180. package/templates/racing/src/render/gpuSky.ts +4 -7
  181. package/templates/racing/src/render/materialLighting.ts +5 -5
  182. package/templates/racing/src/render/quality.ts +7 -32
  183. package/templates/racing/src/scenes/Race.ts +4 -1
  184. package/templates/racing/src/style.css +4 -0
  185. package/templates/racing/tsconfig.json +1 -1
  186. package/templates/racing/vite.config.ts +2 -0
  187. package/templates/rain/AGENTS.md +96 -84
  188. package/templates/rain/CLAUDE.md +96 -84
  189. package/templates/rain/native-playtests/lightning.playtest.json +85 -10
  190. package/templates/rain/package.json +6 -6
  191. package/templates/rain/playtests/reduced-motion.playtest.json +6 -0
  192. package/templates/rain/src/game.ts +1 -1
  193. package/templates/rain/src/scenes/Boot.ts +1 -0
  194. package/templates/rain/src/state.ts +7 -0
  195. package/templates/rain/src/ui/GameUi.tsx +7 -1
  196. package/templates/rain/vite.config.ts +6 -0
  197. package/templates/rts/AGENTS.md +100 -85
  198. package/templates/rts/CLAUDE.md +100 -85
  199. package/templates/rts/package.json +6 -6
  200. package/templates/rts/src/game.ts +1 -1
  201. package/templates/rts/src/render/backlightControls.ts +10 -0
  202. package/templates/rts/src/render/backlightMaterial.ts +4 -4
  203. package/templates/rts/src/render/materialLighting.ts +5 -5
  204. package/templates/rts/src/render/quality.ts +7 -31
  205. package/templates/rts/src/scenes/Play.ts +1 -1
  206. package/templates/rts/src/style.css +4 -0
  207. package/templates/rts/vite.config.ts +2 -0
  208. package/templates/runner/AGENTS.md +97 -80
  209. package/templates/runner/CLAUDE.md +97 -80
  210. package/templates/runner/package.json +7 -7
  211. package/templates/runner/playtests/performance.playtest.json +1 -1
  212. package/templates/runner/src/game.ts +1 -1
  213. package/templates/runner/src/render/atmosphere.ts +11 -16
  214. package/templates/runner/src/render/backlightControls.ts +10 -0
  215. package/templates/runner/src/render/backlightMaterial.ts +4 -4
  216. package/templates/runner/src/render/clouds.ts +13 -0
  217. package/templates/runner/src/render/gpuSky.ts +4 -7
  218. package/templates/runner/src/render/lighting.ts +53 -11
  219. package/templates/runner/src/render/materialLighting.ts +5 -5
  220. package/templates/runner/src/render/quality.ts +7 -32
  221. package/templates/runner/src/scenes/Run.ts +8 -4
  222. package/templates/runner/src/style.css +4 -0
  223. package/templates/runner/threenative.config.ts +0 -3
  224. package/templates/runner/tsconfig.json +1 -1
  225. package/templates/runner/vite.config.ts +2 -0
  226. package/templates/sailing/AGENTS.md +96 -79
  227. package/templates/sailing/CLAUDE.md +96 -79
  228. package/templates/sailing/package.json +7 -7
  229. package/templates/sailing/playtests/sails.playtest.json +1 -0
  230. package/templates/sailing/src/game.ts +1 -1
  231. package/templates/sailing/src/render/backlightControls.ts +10 -0
  232. package/templates/sailing/src/render/backlightMaterial.ts +4 -4
  233. package/templates/sailing/src/render/environmentSetup.ts +1 -1
  234. package/templates/sailing/src/render/materialLighting.ts +5 -5
  235. package/templates/sailing/src/render/quality.ts +7 -32
  236. package/templates/sailing/src/render/sky.ts +4 -0
  237. package/templates/sailing/src/style.css +5 -0
  238. package/templates/sailing/threenative.config.ts +0 -3
  239. package/templates/sailing/vite.config.ts +6 -0
  240. package/templates/shooter/AGENTS.md +97 -68
  241. package/templates/shooter/CLAUDE.md +97 -68
  242. package/templates/shooter/package.json +7 -7
  243. package/templates/shooter/src/game.ts +3 -2
  244. package/templates/shooter/src/render/atmosphere.ts +11 -16
  245. package/templates/shooter/src/render/backlightControls.ts +10 -0
  246. package/templates/shooter/src/render/backlightMaterial.ts +4 -4
  247. package/templates/shooter/src/render/clouds.ts +13 -0
  248. package/templates/shooter/src/render/gpuSky.ts +4 -7
  249. package/templates/shooter/src/render/materialLighting.ts +5 -5
  250. package/templates/shooter/src/render/quality.ts +10 -33
  251. package/templates/shooter/src/scenes/Play.ts +4 -1
  252. package/templates/shooter/src/style.css +4 -0
  253. package/templates/shooter/vite.config.ts +2 -0
  254. package/templates/snow/AGENTS.md +95 -76
  255. package/templates/snow/CLAUDE.md +95 -76
  256. package/templates/snow/package.json +7 -7
  257. package/templates/snow/src/game.ts +1 -1
  258. package/templates/snow/src/render/backlightControls.ts +10 -0
  259. package/templates/snow/src/render/backlightMaterial.ts +4 -4
  260. package/templates/snow/src/render/materialLighting.ts +5 -5
  261. package/templates/snow/src/render/quality.ts +7 -32
  262. package/templates/snow/src/style.css +5 -0
  263. package/templates/snow/threenative.config.ts +0 -3
  264. package/templates/snow/vite.config.ts +6 -0
  265. package/templates/starter/AGENTS.md +109 -88
  266. package/templates/starter/CLAUDE.md +109 -88
  267. package/templates/starter/native-playtests/render-chain.playtest.json +24 -24
  268. package/templates/starter/native-playtests/smooth-motion.playtest.json +3 -3
  269. package/templates/starter/package.json +7 -7
  270. package/templates/starter/src/entities/Crate.ts +5 -2
  271. package/templates/starter/src/entities/Player.ts +10 -22
  272. package/templates/starter/src/game.ts +4 -3
  273. package/templates/starter/src/render/adaptiveQuality.ts +17 -0
  274. package/templates/starter/src/render/atmosphere.ts +11 -16
  275. package/templates/starter/src/render/backlightControls.ts +10 -0
  276. package/templates/starter/src/render/backlightMaterial.ts +4 -4
  277. package/templates/starter/src/render/clouds.ts +13 -0
  278. package/templates/starter/src/render/contactShadow.ts +1 -1
  279. package/templates/starter/src/render/gpuSky.ts +4 -7
  280. package/templates/starter/src/render/lighting.ts +54 -4
  281. package/templates/starter/src/render/materialLighting.ts +5 -5
  282. package/templates/starter/src/render/postprocessing.ts +11 -10
  283. package/templates/starter/src/render/quality.ts +14 -1
  284. package/templates/starter/src/render/temporalAA.ts +8 -7
  285. package/templates/starter/src/render/temporalAAFrame.ts +30 -9
  286. package/templates/starter/src/render/temporalAAResolve.ts +15 -1
  287. package/templates/starter/src/render/temporalClampRelease.ts +183 -0
  288. package/templates/starter/src/render/temporalHistoryResolve.ts +90 -0
  289. package/templates/starter/src/render/temporalMoire.ts +190 -0
  290. package/templates/starter/src/render/temporalResolve.ts +75 -16
  291. package/templates/starter/src/render/temporalResolveDepth.ts +2 -0
  292. package/templates/starter/src/scenes/Play.ts +53 -32
  293. package/templates/starter/src/state.ts +2 -0
  294. package/templates/starter/src/style.css +4 -0
  295. package/templates/starter/src/ui/Menu.tsx +5 -1
  296. package/templates/starter/vite.config.ts +2 -0
  297. package/templates/tower-defense/AGENTS.md +97 -81
  298. package/templates/tower-defense/CLAUDE.md +97 -81
  299. package/templates/tower-defense/package.json +7 -7
  300. package/templates/tower-defense/src/game.ts +1 -1
  301. package/templates/tower-defense/src/render/backlightControls.ts +10 -0
  302. package/templates/tower-defense/src/render/backlightMaterial.ts +4 -4
  303. package/templates/tower-defense/src/render/materialLighting.ts +5 -5
  304. package/templates/tower-defense/src/render/quality.ts +7 -32
  305. package/templates/tower-defense/src/scenes/Battle.ts +1 -1
  306. package/templates/tower-defense/src/style.css +4 -0
  307. package/templates/tower-defense/tsconfig.json +1 -1
  308. package/templates/tower-defense/vite.config.ts +2 -0
  309. package/capabilities.json +0 -9197
  310. package/templates/AGENTS.md +0 -21
  311. package/templates/CLAUDE.md +0 -23
  312. package/templates/action-rpg/.codex/config.toml +0 -23
  313. package/templates/action-rpg/.cursor/mcp.json +0 -38
  314. package/templates/action-rpg/.gemini/settings.json +0 -38
  315. package/templates/action-rpg/.mcp.json +0 -38
  316. package/templates/action-rpg/.vscode/mcp.json +0 -43
  317. package/templates/action-rpg/.zed/settings.json +0 -43
  318. package/templates/action-rpg/opencode.json +0 -49
  319. package/templates/action-rpg/src/render/environmentContribution.ts +0 -188
  320. package/templates/action-rpg/src/render/environmentRadiance.ts +0 -36
  321. package/templates/action-rpg/src/render/environmentSampleCache.ts +0 -43
  322. package/templates/action-rpg/src/render/environmentSampling.ts +0 -193
  323. package/templates/action-rpg/src/render/environmentSnapshot.ts +0 -53
  324. package/templates/adventure/.codex/config.toml +0 -23
  325. package/templates/adventure/.cursor/mcp.json +0 -38
  326. package/templates/adventure/.gemini/settings.json +0 -38
  327. package/templates/adventure/.mcp.json +0 -38
  328. package/templates/adventure/.vscode/mcp.json +0 -43
  329. package/templates/adventure/.zed/settings.json +0 -43
  330. package/templates/adventure/opencode.json +0 -49
  331. package/templates/collectathon/.codex/config.toml +0 -23
  332. package/templates/collectathon/.cursor/mcp.json +0 -38
  333. package/templates/collectathon/.gemini/settings.json +0 -38
  334. package/templates/collectathon/.mcp.json +0 -38
  335. package/templates/collectathon/.vscode/mcp.json +0 -43
  336. package/templates/collectathon/.zed/settings.json +0 -43
  337. package/templates/collectathon/opencode.json +0 -49
  338. package/templates/kart/.codex/config.toml +0 -23
  339. package/templates/kart/.cursor/mcp.json +0 -38
  340. package/templates/kart/.gemini/settings.json +0 -38
  341. package/templates/kart/.mcp.json +0 -38
  342. package/templates/kart/.vscode/mcp.json +0 -43
  343. package/templates/kart/.zed/settings.json +0 -43
  344. package/templates/kart/opencode.json +0 -49
  345. package/templates/minimal/.codex/config.toml +0 -23
  346. package/templates/minimal/.cursor/mcp.json +0 -38
  347. package/templates/minimal/.gemini/settings.json +0 -38
  348. package/templates/minimal/.mcp.json +0 -38
  349. package/templates/minimal/.vscode/mcp.json +0 -43
  350. package/templates/minimal/.zed/settings.json +0 -43
  351. package/templates/minimal/opencode.json +0 -49
  352. package/templates/minimal/src/render/environmentContribution.ts +0 -188
  353. package/templates/minimal/src/render/environmentRadiance.ts +0 -36
  354. package/templates/minimal/src/render/environmentSampleCache.ts +0 -43
  355. package/templates/minimal/src/render/environmentSampling.ts +0 -193
  356. package/templates/minimal/src/render/environmentSnapshot.ts +0 -53
  357. package/templates/platformer/.codex/config.toml +0 -23
  358. package/templates/platformer/.cursor/mcp.json +0 -38
  359. package/templates/platformer/.gemini/settings.json +0 -38
  360. package/templates/platformer/.mcp.json +0 -38
  361. package/templates/platformer/.vscode/mcp.json +0 -43
  362. package/templates/platformer/.zed/settings.json +0 -43
  363. package/templates/platformer/opencode.json +0 -49
  364. package/templates/platformer/src/render/environmentContribution.ts +0 -188
  365. package/templates/platformer/src/render/environmentRadiance.ts +0 -36
  366. package/templates/platformer/src/render/environmentSampleCache.ts +0 -43
  367. package/templates/platformer/src/render/environmentSampling.ts +0 -193
  368. package/templates/platformer/src/render/environmentSnapshot.ts +0 -53
  369. package/templates/puzzle/.codex/config.toml +0 -23
  370. package/templates/puzzle/.cursor/mcp.json +0 -38
  371. package/templates/puzzle/.gemini/settings.json +0 -38
  372. package/templates/puzzle/.mcp.json +0 -38
  373. package/templates/puzzle/.vscode/mcp.json +0 -43
  374. package/templates/puzzle/.zed/settings.json +0 -43
  375. package/templates/puzzle/opencode.json +0 -49
  376. package/templates/puzzle/src/render/environmentContribution.ts +0 -188
  377. package/templates/puzzle/src/render/environmentRadiance.ts +0 -36
  378. package/templates/puzzle/src/render/environmentSampleCache.ts +0 -43
  379. package/templates/puzzle/src/render/environmentSampling.ts +0 -193
  380. package/templates/puzzle/src/render/environmentSnapshot.ts +0 -53
  381. package/templates/racing/.codex/config.toml +0 -23
  382. package/templates/racing/.cursor/mcp.json +0 -38
  383. package/templates/racing/.gemini/settings.json +0 -38
  384. package/templates/racing/.mcp.json +0 -38
  385. package/templates/racing/.vscode/mcp.json +0 -43
  386. package/templates/racing/.zed/settings.json +0 -43
  387. package/templates/racing/opencode.json +0 -49
  388. package/templates/racing/src/render/environmentContribution.ts +0 -188
  389. package/templates/racing/src/render/environmentRadiance.ts +0 -36
  390. package/templates/racing/src/render/environmentSampleCache.ts +0 -43
  391. package/templates/racing/src/render/environmentSampling.ts +0 -193
  392. package/templates/racing/src/render/environmentSnapshot.ts +0 -53
  393. package/templates/rain/.codex/config.toml +0 -23
  394. package/templates/rain/.cursor/mcp.json +0 -38
  395. package/templates/rain/.gemini/settings.json +0 -38
  396. package/templates/rain/.mcp.json +0 -38
  397. package/templates/rain/.vscode/mcp.json +0 -43
  398. package/templates/rain/.zed/settings.json +0 -43
  399. package/templates/rain/opencode.json +0 -49
  400. package/templates/rts/.codex/config.toml +0 -23
  401. package/templates/rts/.cursor/mcp.json +0 -38
  402. package/templates/rts/.gemini/settings.json +0 -38
  403. package/templates/rts/.mcp.json +0 -38
  404. package/templates/rts/.vscode/mcp.json +0 -43
  405. package/templates/rts/.zed/settings.json +0 -43
  406. package/templates/rts/opencode.json +0 -49
  407. package/templates/rts/src/render/environmentContribution.ts +0 -188
  408. package/templates/rts/src/render/environmentRadiance.ts +0 -36
  409. package/templates/rts/src/render/environmentSampleCache.ts +0 -43
  410. package/templates/rts/src/render/environmentSampling.ts +0 -193
  411. package/templates/rts/src/render/environmentSnapshot.ts +0 -53
  412. package/templates/runner/.codex/config.toml +0 -23
  413. package/templates/runner/.cursor/mcp.json +0 -38
  414. package/templates/runner/.gemini/settings.json +0 -38
  415. package/templates/runner/.mcp.json +0 -38
  416. package/templates/runner/.vscode/mcp.json +0 -43
  417. package/templates/runner/.zed/settings.json +0 -43
  418. package/templates/runner/README.md +0 -43
  419. package/templates/runner/opencode.json +0 -49
  420. package/templates/runner/src/render/environmentContribution.ts +0 -188
  421. package/templates/runner/src/render/environmentRadiance.ts +0 -36
  422. package/templates/runner/src/render/environmentSampleCache.ts +0 -43
  423. package/templates/runner/src/render/environmentSampling.ts +0 -193
  424. package/templates/runner/src/render/environmentSnapshot.ts +0 -53
  425. package/templates/sailing/.codex/config.toml +0 -23
  426. package/templates/sailing/.cursor/mcp.json +0 -38
  427. package/templates/sailing/.gemini/settings.json +0 -38
  428. package/templates/sailing/.mcp.json +0 -38
  429. package/templates/sailing/.vscode/mcp.json +0 -43
  430. package/templates/sailing/.zed/settings.json +0 -43
  431. package/templates/sailing/README.md +0 -28
  432. package/templates/sailing/opencode.json +0 -49
  433. package/templates/sailing/src/render/environmentContribution.ts +0 -188
  434. package/templates/sailing/src/render/environmentRadiance.ts +0 -36
  435. package/templates/sailing/src/render/environmentSampleCache.ts +0 -43
  436. package/templates/sailing/src/render/environmentSampling.ts +0 -193
  437. package/templates/sailing/src/render/environmentSnapshot.ts +0 -53
  438. package/templates/shooter/.codex/config.toml +0 -23
  439. package/templates/shooter/.cursor/mcp.json +0 -38
  440. package/templates/shooter/.gemini/settings.json +0 -38
  441. package/templates/shooter/.mcp.json +0 -38
  442. package/templates/shooter/.vscode/mcp.json +0 -43
  443. package/templates/shooter/.zed/settings.json +0 -43
  444. package/templates/shooter/opencode.json +0 -49
  445. package/templates/shooter/src/render/environmentContribution.ts +0 -188
  446. package/templates/shooter/src/render/environmentRadiance.ts +0 -36
  447. package/templates/shooter/src/render/environmentSampleCache.ts +0 -43
  448. package/templates/shooter/src/render/environmentSampling.ts +0 -193
  449. package/templates/shooter/src/render/environmentSnapshot.ts +0 -53
  450. package/templates/snow/.codex/config.toml +0 -23
  451. package/templates/snow/.cursor/mcp.json +0 -38
  452. package/templates/snow/.gemini/settings.json +0 -38
  453. package/templates/snow/.mcp.json +0 -38
  454. package/templates/snow/.vscode/mcp.json +0 -43
  455. package/templates/snow/.zed/settings.json +0 -43
  456. package/templates/snow/README.md +0 -26
  457. package/templates/snow/opencode.json +0 -49
  458. package/templates/snow/src/render/environmentContribution.ts +0 -188
  459. package/templates/snow/src/render/environmentRadiance.ts +0 -36
  460. package/templates/snow/src/render/environmentSampleCache.ts +0 -43
  461. package/templates/snow/src/render/environmentSampling.ts +0 -193
  462. package/templates/snow/src/render/environmentSnapshot.ts +0 -53
  463. package/templates/starter/.codex/config.toml +0 -23
  464. package/templates/starter/.cursor/mcp.json +0 -38
  465. package/templates/starter/.gemini/settings.json +0 -38
  466. package/templates/starter/.mcp.json +0 -38
  467. package/templates/starter/.vscode/mcp.json +0 -43
  468. package/templates/starter/.zed/settings.json +0 -43
  469. package/templates/starter/opencode.json +0 -49
  470. package/templates/starter/src/render/environmentContribution.ts +0 -188
  471. package/templates/starter/src/render/environmentRadiance.ts +0 -36
  472. package/templates/starter/src/render/environmentSampleCache.ts +0 -43
  473. package/templates/starter/src/render/environmentSampling.ts +0 -193
  474. package/templates/starter/src/render/environmentSnapshot.ts +0 -53
  475. package/templates/starter/src/render/rendererGate.ts +0 -36
  476. package/templates/tower-defense/.codex/config.toml +0 -23
  477. package/templates/tower-defense/.cursor/mcp.json +0 -38
  478. package/templates/tower-defense/.gemini/settings.json +0 -38
  479. package/templates/tower-defense/.mcp.json +0 -38
  480. package/templates/tower-defense/.vscode/mcp.json +0 -43
  481. package/templates/tower-defense/.zed/settings.json +0 -43
  482. package/templates/tower-defense/README.md +0 -16
  483. package/templates/tower-defense/opencode.json +0 -49
  484. package/templates/tower-defense/src/render/environmentContribution.ts +0 -188
  485. package/templates/tower-defense/src/render/environmentRadiance.ts +0 -36
  486. package/templates/tower-defense/src/render/environmentSampleCache.ts +0 -43
  487. package/templates/tower-defense/src/render/environmentSampling.ts +0 -193
  488. package/templates/tower-defense/src/render/environmentSnapshot.ts +0 -53
@@ -235,7 +235,13 @@ function march(
235
235
  * approximation in RenderMultiScatteredLuminanceLutCS); the full sphere gather overestimated the
236
236
  * ground bounce against the Unreal frames by up to 1.6x, so this uses the same two rays.
237
237
  */
238
+ // The table depends on no input: build it once a run, not once a sky refresh.
239
+ let multipleScattering: Multi | undefined;
238
240
  function multipleScatteringTable(): Multi {
241
+ multipleScattering ??= buildMultipleScatteringTable();
242
+ return multipleScattering;
243
+ }
244
+ function buildMultipleScatteringTable(): Multi {
239
245
  const nh = 12;
240
246
  const nc = 16;
241
247
  const dirs: Vec3[] = [
@@ -396,23 +402,12 @@ const SUN_LUX = 6;
396
402
  export const SUN_KELVIN = 6500;
397
403
 
398
404
  /**
399
- * The sun in three's light units. Unreal renders a lit diffuse surface as albedo x lux x cos(theta);
400
- * three's Lambert BRDF carries a 1/pi, so the same lux is pi times as large here. Measured on the
401
- * Unreal L1 cells (no atmosphere, scene-linear EXR): a 0.18 floor under the 60 degree sun reads
402
- * 0.874 luminance, within 7% of 0.18 x 6 x sin(60 deg) = 0.935 (the residual is checked on the
403
- * engine's own L1 capture).
404
- */
405
- export const SUN_ILLUMINANCE = SUN_LUX * Math.PI;
406
-
407
- /**
408
- * Sky radiance relative to the sun, as Unreal renders it. TEMPORARY, measured and not derived: with
409
- * the sun at 6 lux the model above is 1.3x too bright against the Unreal L2 frames, flat across
410
- * channels and across the 15 and 4 degree suns (1.30 / 1.30 / 1.35 at 19 degrees elevation), so
411
- * the sky is scaled by 1/1.3. The lens attenuation constant 0.78 (PostProcessEyeAdaptation.cpp,
412
- * r.EyeAdaptation.LensAttenuation) has the right size but the path that would apply it to the
413
- * atmosphere and not to the sun is not found in the source yet.
405
+ * The sun in three's light units, which are Unreal's: both shade a diffuse surface as
406
+ * albedo / pi x lux x cos(theta) (Diffuse_Lambert, Engine/Shaders/Private/BRDF.ush:157), and the
407
+ * sky is radiance in the same units. The frame's brightness is the exposure's job, not the light's:
408
+ * with its meter off Unreal exposes by 2.4 (`qualityPreset`), and the L1 cells match at that value.
414
409
  */
415
- export const SKY_TO_SUN = 0.78;
410
+ export const SUN_ILLUMINANCE = SUN_LUX;
416
411
 
417
412
  /**
418
413
  * Colour of a black-body-like light at `kelvin` as linear sRGB with unit luminance: the Planckian
@@ -10,6 +10,11 @@ function finiteColor(color: Color) {
10
10
  color.b >= 0
11
11
  );
12
12
  }
13
+ /**
14
+ * Throws when a `IBacklightControls` is missing a light or names a non-finite gain.
15
+ *
16
+ * @situation fail loudly instead of drawing an unlit material when a backlight has no key light
17
+ */
13
18
  export function validateControls(controls: IBacklightControls) {
14
19
  if (
15
20
  !Number.isFinite(controls.rimGain) ||
@@ -30,6 +35,11 @@ export function validateControls(controls: IBacklightControls) {
30
35
  "Backlight controls require finite nonnegative gains, a direction and angular size in (0, 1.5].",
31
36
  );
32
37
  }
38
+ /**
39
+ * The light and camera a backlit material reads its key direction from.
40
+ *
41
+ * @situation point the backlight at the sun the scene actually has
42
+ */
33
43
  export function resolveKey(
34
44
  controls: IBacklightControls,
35
45
  direction: Vector3,
@@ -48,10 +48,10 @@ export interface IBacklightControls {
48
48
  const graphs = new WeakMap<IBacklightControls, ReturnType<typeof createGraph>>();
49
49
 
50
50
  /**
51
- * Preserve the upstream standard PBR/normal/skinning paths and original material emissive.
52
- * This is an additive artistic convention, not a physical subsurface model or IBL replacement.
53
- * Cache at the caller to preserve shared source-material relationships; dispose only conversions
54
- * it owns, never maps/source materials borrowed from a loaded model.
51
+ * The game's material, wrapped in a node twin that adds the backlit sheen it was given.
52
+ *
53
+ * @situation give a material a launcher's glow without editing its colour, texture or roughness
54
+ * @constraint every colour, gain and angular size is the caller's; this copies the game's material and adds light
55
55
  */
56
56
  export function backlightMaterial(source: MeshStandardMaterial, controls: IBacklightControls) {
57
57
  if (
@@ -282,6 +282,19 @@ export interface ICloudTextures {
282
282
  }
283
283
  const textureCache = new Map<number, ICloudTextures>();
284
284
 
285
+ /**
286
+ * Hand back the textures an earlier run generated, so `cloudTextures(seed)` skips ~0.6 s of noise
287
+ * on the main thread. The scene keeps them between runs with `ctx.assets.memo`.
288
+ */
289
+ export function primeCloudTextures(textures: ICloudTextures, seed = 631): void {
290
+ if (
291
+ textures.pattern.length !== PATTERN_SIZE ** 2 * 4 ||
292
+ textures.volume.length !== VOLUME_SIZE ** 3 * 2
293
+ )
294
+ throw new Error("cloud textures do not match PATTERN_SIZE and VOLUME_SIZE.");
295
+ textureCache.set(seed, textures);
296
+ }
297
+
285
298
  export function cloudTextures(seed = 631): ICloudTextures {
286
299
  const cached = textureCache.get(seed);
287
300
  if (cached) return cached;
@@ -1,7 +1,7 @@
1
1
  // Generated for you. This is ordinary Three.js — edit or delete it freely.
2
2
  // ThreeNative does not read this file.
3
3
  //
4
- // A baked blob under a prop: what makes a crate sit on the floor on every tier. Unreal grounds a
4
+ // A baked blob under a prop: what makes a crate sit on the floor on the `low` tier. Unreal grounds a
5
5
  // contact with ambient occlusion, which is on by default (UE 5.8.3: Engine/Source/Runtime/Engine/
6
6
  // Private/SceneView.cpp:168-173, Scene.cpp:567) and off at its Low scalability level
7
7
  // (Engine/Config/BaseScalability.ini:568-569); its lights add no contact shadow of their own
@@ -53,7 +53,6 @@ import {
53
53
  MIE_SCATTER,
54
54
  OZONE,
55
55
  RAYLEIGH,
56
- SKY_TO_SUN,
57
56
  SUN_ILLUMINANCE,
58
57
  SUN_KELVIN,
59
58
  TOP_KM,
@@ -273,7 +272,7 @@ class GpuSkyNode extends Node<"vec3"> {
273
272
  readonly #quad = new QuadMesh(new NodeMaterial());
274
273
  readonly #noise = cloudNoise();
275
274
  readonly #fog = uniform(new Color());
276
- readonly #scale = vec3(...temperatureColour(SUN_KELVIN)).mul(SUN_ILLUMINANCE * SKY_TO_SUN);
275
+ readonly #scale = vec3(...temperatureColour(SUN_KELVIN)).mul(SUN_ILLUMINANCE);
277
276
  readonly #light = uniform(new Vector3());
278
277
  readonly #ambient = uniform(new Vector3());
279
278
  #last = new Vector3(Number.NaN, 0, 0);
@@ -587,9 +586,7 @@ class GpuSkyNode extends Node<"vec3"> {
587
586
  .greaterThanEqual(Math.cos(SUN_RADIUS))
588
587
  .and(skyDisc.greaterThan(0.5))
589
588
  .select(
590
- this.#light
591
- .mul(this.clouds ? cloud.a : float(1))
592
- .div(PI * Math.sin(SUN_RADIUS) ** 2 * SKY_TO_SUN),
589
+ this.#light.mul(this.clouds ? cloud.a : float(1)).div(PI * Math.sin(SUN_RADIUS) ** 2),
593
590
  vec3(0),
594
591
  );
595
592
  const colour = sky.add(disc).mul(this.#scale);
@@ -665,7 +662,7 @@ function distantFogColour(sun: Vector3): Color {
665
662
  const tint = temperatureColour(SUN_KELVIN);
666
663
  const light = viewDistanceSkyLight(sun);
667
664
  return new Color(
668
- ...([0, 1, 2].map((c) => (light[c] ?? 0) * (tint[c] ?? 1) * SUN_ILLUMINANCE * SKY_TO_SUN) as [
665
+ ...([0, 1, 2].map((c) => (light[c] ?? 0) * (tint[c] ?? 1) * SUN_ILLUMINANCE) as [
669
666
  number,
670
667
  number,
671
668
  number,
@@ -720,7 +717,7 @@ export function createGpuSky(
720
717
  const refresh = () => {
721
718
  const start = performance.now();
722
719
  const data = bakedRadiance(sun, w, h, ground, clouds);
723
- const scale = temperatureColour(SUN_KELVIN).map((v) => v * SUN_ILLUMINANCE * SKY_TO_SUN) as [
720
+ const scale = temperatureColour(SUN_KELVIN).map((v) => v * SUN_ILLUMINANCE) as [
724
721
  number,
725
722
  number,
726
723
  number,
@@ -3,7 +3,16 @@
3
3
  //
4
4
  // One sun. The sky in `sky.ts` is the fill light — its environment reaches every face the sun
5
5
  // misses — so there is no hemisphere or ambient light stacked on top to flatten the frame.
6
- import { Color, DirectionalLight, PCFSoftShadowMap, type Scene, Vector3 } from "three";
6
+ import { useRoughDiffuse } from "@threenative/core";
7
+ import {
8
+ Color,
9
+ DirectionalLight,
10
+ type Object3D,
11
+ PCFSoftShadowMap,
12
+ type Scene,
13
+ Vector3,
14
+ } from "three";
15
+ import type { Node } from "three/webgpu";
7
16
  import { ARENA, GROUND_Y } from "./arena.js";
8
17
  import {
9
18
  SUN_ILLUMINANCE,
@@ -30,12 +39,17 @@ function atmosphereSun(): DirectionalLight {
30
39
  }
31
40
 
32
41
  type ShadowRenderer = { shadowMap: { enabled: boolean; type: number } };
42
+ // The engine's `VirtualShadowNode` class. The scene passes it in, because this folder imports no
43
+ // framework package.
44
+ type VirtualShadowClass<T> = new (light: DirectionalLight, options: { clipExtents: number[] }) => T;
33
45
 
34
- export function setupLighting(
46
+ export function setupLighting<T extends Node = never>(
35
47
  scene: Scene,
36
48
  renderer: ShadowRenderer,
37
49
  mobile = false,
38
- ): { key: DirectionalLight } {
50
+ shadowExtents?: readonly number[],
51
+ VirtualShadowNode?: VirtualShadowClass<T>,
52
+ ): { key: DirectionalLight; shadows?: T; dispose: () => void } {
39
53
  renderer.shadowMap.enabled = true;
40
54
  renderer.shadowMap.type = PCFSoftShadowMap;
41
55
 
@@ -64,10 +78,37 @@ export function setupLighting(
64
78
  // Small biases: a large normal bias is what lifted the mannequin's shadow off its own feet.
65
79
  key.shadow.bias = -0.0002;
66
80
  key.shadow.normalBias = 0.005;
81
+ // Named override for a world wider than the arena, such as a streamed forest. `shadowExtents`
82
+ // are the wider windows in metres that the caller measures from its terrain. The finest window
83
+ // stays the arena window above, so near shadows keep this map's texel and softness. Each level inherits the map
84
+ // size, radius and biases above, re-renders when its window moves, and redraws only the region
85
+ // an `invalidateRegion` names. Godrays need an ordinary shadow map and refuse this light by name.
86
+ let shadows: T | undefined;
87
+ if (shadowExtents !== undefined) {
88
+ if (VirtualShadowNode === undefined)
89
+ throw new Error("setupLighting: shadowExtents needs the VirtualShadowNode class.");
90
+ const clipExtents = [extent, ...shadowExtents];
91
+ if (
92
+ !clipExtents.every((value, i) => Number.isFinite(value) && value > (clipExtents[i - 1] ?? 0))
93
+ )
94
+ throw new RangeError(
95
+ `setupLighting: shadowExtents must increase past ${extent} m, got [${shadowExtents.join(", ")}].`,
96
+ );
97
+ shadows = new VirtualShadowNode(key, { clipExtents });
98
+ key.shadow.shadowNode = shadows;
99
+ }
67
100
  scene.add(key);
68
101
  // The key light is returned because `WorldEnvironment`'s godrays stage raymarches against its
69
102
  // shadow map, so `setupPost` needs the light itself.
70
- return { key };
103
+ return {
104
+ key,
105
+ shadows,
106
+ dispose: () => {
107
+ shadows?.dispose();
108
+ key.removeFromParent();
109
+ key.dispose();
110
+ },
111
+ };
71
112
  }
72
113
 
73
114
  /** Material conventions are game-owned; each scene gets independent mutable controls. */
@@ -94,3 +135,12 @@ export function createLightingConvention(
94
135
  ...overrides,
95
136
  };
96
137
  }
138
+
139
+ /**
140
+ * Rough surfaces take the sun the way a fresh Unreal project's Substrate shades them: the EON diffuse in place of
141
+ * Lambert, with no energy conservation. Call it once the scene's models are attached; delete the call for three's
142
+ * Lambert, or set `material.roughDiffuse = false` on one material.
143
+ */
144
+ export function shadeLikeSubstrate(root: Object3D): void {
145
+ useRoughDiffuse(root);
146
+ }
@@ -1,16 +1,16 @@
1
- // Generated for you. Scene-owned material assignments; no engine appearance hooks.
2
- import type { Camera, DirectionalLight, Object3D, Scene, Texture } from "three";
3
- import type { IBacklightControls } from "./backlightMaterial.js";
4
1
  import {
5
2
  type IEnvironmentMeasurement,
6
3
  measureEnvironment,
7
4
  reportEnvironmentContribution,
8
- } from "./environmentContribution.js";
5
+ } from "@threenative/core/render/environment";
9
6
  import {
10
7
  type IEnvironmentSourceSnapshot,
11
8
  captureEnvironmentSnapshot,
12
9
  environmentSnapshotCurrent,
13
- } from "./environmentSnapshot.js";
10
+ } from "@threenative/core/render/environment";
11
+ // Generated for you. Scene-owned material assignments; no engine appearance hooks.
12
+ import type { Camera, DirectionalLight, Object3D, Scene, Texture } from "three";
13
+ import type { IBacklightControls } from "./backlightMaterial.js";
14
14
  import { type ILightingConvention, createLightingConvention } from "./lighting.js";
15
15
  import { createMaterialAssignments } from "./materialAssignments.js";
16
16
  import { type IMaterialLightingEnvironment, materialLightingEnabled } from "./quality.js";
@@ -1,13 +1,10 @@
1
1
  import { type OutputRenderer, WorldEnvironment } from "@threenative/core";
2
2
  // Generated for you: ordinary Three.js; ThreeNative does not read this file.
3
- //
4
- // This file wires two things together and decides nothing itself. `quality.ts` owns which stages
5
- // run at which tier and records what each one measured. Core's `WorldEnvironment` builds them and
6
- // prints `TN_WORLD_ENVIRONMENT`, naming every stage as applied or refused **with a reason**.
7
- //
8
- // To make the game cheaper or prettier everywhere, edit `quality.ts`. To force one tier for one run
9
- // (a slow desktop, a capture to compare), pass `setupPost(renderer, scene, camera, { tier: "low" })`.
10
- // `TN_QUALITY_TIER` names the tier that ran either way.
3
+ // This file wires two things together and decides nothing itself. `quality.ts` owns which stages run at which
4
+ // tier and records what each one measured; core's `WorldEnvironment` builds them and prints `TN_WORLD_ENVIRONMENT`,
5
+ // naming every stage as applied or refused **with a reason**.
6
+ // To make the game cheaper or prettier everywhere, edit `quality.ts`. To force one tier for one run (a slow desktop,
7
+ // a capture to compare), pass `setupPost(renderer, scene, camera, { tier: "low" })`; `TN_QUALITY_TIER` names it.
11
8
  import { type Camera, type DirectionalLight, FloatType, type Scene } from "three";
12
9
  import { LUTCubeLoader } from "three/addons/loaders/LUTCubeLoader.js";
13
10
  import {
@@ -17,7 +14,7 @@ import {
17
14
  formatQualityAdaptation,
18
15
  } from "./adaptiveQuality.js";
19
16
  import { type IGradeTable, filterableTable, gradeStages } from "./grade.js";
20
- import { type QualityTier, gradePreset, qualityPreset } from "./quality.js";
17
+ import { type QualityTier, gradePreset, qualityPreset, tierShadows } from "./quality.js";
21
18
  import { type TemporalAAProvider, temporalAAStages } from "./temporalAAStage.js";
22
19
  import { temporalDetailRequested, temporalDetailStages } from "./temporalDetailStage.js";
23
20
  import type { FogMedium } from "./volumetricFog.js";
@@ -64,6 +61,7 @@ export function setupPost(
64
61
  tier?: QualityTier;
65
62
  /** Scene-owned material assignments follow the same resolved tier. */
66
63
  onTierChanged?: (tier: QualityTier) => void;
64
+ shadows?: boolean; // on or off at every tier; omitted, the tier decides (`tierShadows` in `quality.ts`)
67
65
  /**
68
66
  * The bounded participating medium from `volumetricFog.ts`, built once per graph: a tier change
69
67
  * replaces the graph, and a fog controller owns one graph, so it is released and rebuilt here
@@ -95,6 +93,8 @@ export function setupPost(
95
93
  medium?.dispose();
96
94
  medium = environment.fog?.();
97
95
  const composed = medium;
96
+ const shadows = tierShadows(policy.tier, environment.shadows, renderer.raw);
97
+ observation = { ...observation, shadows };
98
98
  const settings = qualityPreset(policy.tier);
99
99
  const detail = temporalDetailRequested(renderer, settings) ? temporalDetailStages() : [];
100
100
  const world = new WorldEnvironment({
@@ -157,7 +157,7 @@ export function setupPost(
157
157
  console.info(
158
158
  `TN_QUALITY_TIER ${policy.tier} mobile=${environment.mobile === true} software=${
159
159
  environment.software === true
160
- } source=${source}`,
160
+ } source=${source} shadows=${tierShadows(policy.tier, environment.shadows).label}`,
161
161
  );
162
162
  const controller = {
163
163
  get tier(): QualityTier {
@@ -174,6 +174,7 @@ export function setupPost(
174
174
  observation = {
175
175
  stages: observation.stages,
176
176
  dropped: observation.dropped,
177
+ shadows: observation.shadows,
177
178
  ...decision,
178
179
  ...(Number.isInteger(window.window) ? { window: window.window } : {}),
179
180
  };
@@ -52,6 +52,19 @@ export function qualityPreset(tier: string): IWorldEnvironmentOptions {
52
52
  return { ...coreQualityPreset(tier), exposurePolicy: exposureSettings };
53
53
  }
54
54
 
55
+ /**
56
+ * Whether a tier casts shadows: the game's `setupPost(..., { shadows })`, else the tier's. `low` casts none, as
57
+ * Unreal's `sg.ShadowQuality` 0: its shadow pass was an Iris Xe frame's largest GPU cost (PRD-871). Pass the raw
58
+ * renderer to apply it to `shadowMap.enabled`.
59
+ */
60
+ export function tierShadows(tier: QualityTier, override?: boolean, raw?: unknown) {
61
+ const enabled = override ?? qualityTiers.shadow(tier).castShadows;
62
+ const source = override === undefined ? "tier" : "override";
63
+ const shadowMap = (raw as { shadowMap?: { enabled: boolean } } | undefined)?.shadowMap;
64
+ if (shadowMap) shadowMap.enabled = enabled;
65
+ return { enabled, source, label: `${enabled ? "on" : "off"}(${source})` } as const;
66
+ }
67
+
55
68
  /** The grade and grain a tier runs. Throws on a name that is not a tier, for the same reason. */
56
69
  export function gradePreset(tier: string): IGradeSettings {
57
70
  const preset = GRADE_PRESETS[tier as QualityTier];
@@ -67,4 +80,4 @@ export {
67
80
  type IMaterialLightingEnvironment,
68
81
  isWebGLFallbackRenderer,
69
82
  materialLightingEnabled,
70
- } from "./rendererGate.js";
83
+ } from "@threenative/core/render/environment";
@@ -13,6 +13,7 @@ import { createTemporalCurrentProducer } from "./temporalCurrentProducer.js";
13
13
  import { ownsCurrentInput } from "./temporalCurrentSelection.js";
14
14
  export type { ITemporalAAReport, TemporalResetReason } from "./temporalAAStage.js";
15
15
  import { createTemporalAAResolve } from "./temporalAAResolve.js";
16
+ import { type ITemporalHistoryWeighting, historyWeighting } from "./temporalResolve.js";
16
17
  import type { TemporalResolveNode } from "./temporalResolveDepth.js";
17
18
 
18
19
  /** Reuse TRAANode's jitter, depth rejection and variance clipping. In a RenderChain `traa` factory
@@ -24,10 +25,11 @@ export function createTemporalAA(
24
25
  velocityInput: TextureNode,
25
26
  camera: PerspectiveCamera | OrthographicCamera,
26
27
  currentPass?: PassNode,
28
+ requested?: ITemporalHistoryWeighting,
27
29
  ) {
28
- const currentProducer = ownsCurrentInput(colour, depthInput, velocityInput, camera, currentPass)
29
- ? createTemporalCurrentProducer(currentPass)
30
- : undefined;
30
+ const raw4 = ownsCurrentInput(colour, depthInput, velocityInput, camera, currentPass);
31
+ const weighting = historyWeighting(requested, raw4);
32
+ const currentProducer = raw4 ? createTemporalCurrentProducer(currentPass) : undefined;
31
33
  const depth = currentProducer?.depth ?? depthInput;
32
34
  const velocity = currentProducer?.motion ?? velocityInput;
33
35
  const node = traa(colour, depth, velocity, camera);
@@ -46,6 +48,7 @@ export function createTemporalAA(
46
48
  node as TemporalResolveNode,
47
49
  jitterOffset,
48
50
  currentProducer,
51
+ weighting,
49
52
  );
50
53
  const frames = createTemporalAAFrame(
51
54
  internals,
@@ -54,6 +57,8 @@ export function createTemporalAA(
54
57
  historyValid,
55
58
  resolve.equations,
56
59
  currentProducer?.publishDepth,
60
+ weighting.historyScale,
61
+ resolve.levers,
57
62
  );
58
63
  const hooks = createTemporalAAHooks(frames.jitterInput, () => internals.clearViewOffset());
59
64
  let ownedViewOffset: { width: number; height: number } | null = null;
@@ -152,10 +157,6 @@ export function createTemporalAA(
152
157
  pending = "resize";
153
158
  const reason = pending;
154
159
  frames.draw(frame.renderer, reason !== null, report.frame + 1);
155
- if (reason !== null && width === frames.display.x && height === frames.display.y) {
156
- frame.renderer.copyTextureToTexture(source.texture, internals._resolveRenderTarget.texture);
157
- frame.renderer.copyTextureToTexture(source.texture, internals._historyRenderTarget.texture);
158
- }
159
160
  report = {
160
161
  frame: report.frame + 1,
161
162
  historyValid: reason === null,
@@ -11,6 +11,9 @@ import {
11
11
  type TextureNode,
12
12
  } from "three/webgpu";
13
13
  import { createTemporalAAInput } from "./temporalAAInput.js";
14
+ import type { TemporalClampRelease } from "./temporalClampRelease.js";
15
+ import { createHistoryPresent } from "./temporalHistoryResolve.js";
16
+ import type { TemporalMoire } from "./temporalMoire.js";
14
17
  import {
15
18
  type ITemporalRejectionCounter,
16
19
  type ITemporalRejectionMeasurement,
@@ -36,11 +39,16 @@ export function createTemporalAAFrame(
36
39
  historyValid: { value: number },
37
40
  rejection: () => TemporalDepthRejection | undefined,
38
41
  publishCurrentDepth?: (renderer: Renderer) => void,
42
+ historyScale = 1,
43
+ { moire, release }: { moire?: TemporalMoire; release?: TemporalClampRelease } = {},
39
44
  ) {
40
45
  // Three 0.187's QuadMesh takes a material in the constructor; the draw replaces it before rendering.
41
46
  const quadMesh = new QuadMesh(internals._resolveMaterial);
42
47
  quadMesh.name = "Temporal AA";
43
48
  const display = new Vector2();
49
+ const history = new Vector2();
50
+ // Above a 1x history the chain reads a display-sized resolve of it, never the history raster.
51
+ const present = historyScale === 1 ? undefined : createHistoryPresent(internals, quadMesh);
44
52
  let previousDepth: DepthTexture | null = null;
45
53
  let depthReady = false;
46
54
  let disposed = false;
@@ -55,8 +63,8 @@ export function createTemporalAAFrame(
55
63
  * from sampling the seed at shifted history UVs. */
56
64
  function draw(renderer: Renderer, reset: boolean, currentFrame: number): void {
57
65
  frame = currentFrame;
58
- if (measure(renderer) === undefined)
59
- throw new Error("Temporal AA requires a materialized colour input.");
66
+ const source = measure(renderer);
67
+ if (source === undefined) throw new Error("Temporal AA requires a materialized colour input.");
60
68
  guardTemporalAASeams(internals);
61
69
  if (display.x < input.x || display.y < input.y)
62
70
  throw new Error("Temporal AA cannot resolve to a display raster below its input raster.");
@@ -102,21 +110,24 @@ export function createTemporalAAFrame(
102
110
  renderer.copyTextureToTexture(depth.value, depthHistory);
103
111
  depthReady = true;
104
112
  }
105
- // Resolve and history hold the display raster whatever the input raster is.
113
+ // Resolve and history hold the display raster times historyScale, whatever the input raster is.
114
+ history.copy(display).multiplyScalar(historyScale);
106
115
  const restarted =
107
- internals._historyRenderTarget.width !== display.x ||
108
- internals._historyRenderTarget.height !== display.y;
109
- internals.setSize(display.x, display.y);
116
+ internals._historyRenderTarget.width !== history.x ||
117
+ internals._historyRenderTarget.height !== history.y;
118
+ internals.setSize(history.x, history.y);
110
119
  if (restarted) {
111
120
  // A resize disposes the targets, so they need fresh GPU storage before the draw.
112
121
  renderer.initRenderTarget(internals._historyRenderTarget);
113
122
  renderer.initRenderTarget(internals._resolveRenderTarget);
114
123
  }
115
124
  if (
116
- internals._historyRenderTarget.width !== display.x ||
117
- internals._historyRenderTarget.height !== display.y
125
+ internals._historyRenderTarget.width !== history.x ||
126
+ internals._historyRenderTarget.height !== history.y
118
127
  )
119
- throw new Error("Temporal AA history and resolve must share the display raster.");
128
+ throw new Error("Temporal AA history and resolve must share the history raster.");
129
+ const before = rejection();
130
+ if (before !== undefined) release?.update(renderer, quadMesh, before, input);
120
131
  renderer.setRenderTarget(internals._resolveRenderTarget);
121
132
  quadMesh.material = internals._resolveMaterial;
122
133
  quadMesh.render(renderer);
@@ -130,6 +141,7 @@ export function createTemporalAAFrame(
130
141
  }
131
142
  counter ??= createTemporalRejectionCounter(equations);
132
143
  counter.sample(renderer, frame, display.x, display.y);
144
+ moire?.update(renderer, quadMesh, equations, history);
133
145
  }
134
146
  publishCurrentDepth?.(renderer);
135
147
  // History is the resolve this frame produced, at the same size, so the copy never crosses rasters.
@@ -138,9 +150,15 @@ export function createTemporalAAFrame(
138
150
  internals._resolveRenderTarget.texture,
139
151
  internals._historyRenderTarget.texture,
140
152
  );
153
+ present?.draw(renderer, display);
141
154
  } finally {
142
155
  if (state !== undefined) RendererUtils.restoreRendererState(renderer, state);
143
156
  }
157
+ // A reset seeds a 100% history from a display-sized input; a 2x history cannot take it.
158
+ if (reset && historyScale === 1 && input.equals(display)) {
159
+ renderer.copyTextureToTexture(source.texture, internals._resolveRenderTarget.texture);
160
+ renderer.copyTextureToTexture(source.texture, internals._historyRenderTarget.texture);
161
+ }
144
162
  }
145
163
 
146
164
  /** Both rasters, from the real targets: the scene pass one, then the drawing buffer. */
@@ -171,6 +189,9 @@ export function createTemporalAAFrame(
171
189
  previousDepth?.dispose();
172
190
  previousDepth = null;
173
191
  depthReady = false;
192
+ present?.dispose();
193
+ moire?.dispose();
194
+ release?.dispose();
174
195
  },
175
196
  };
176
197
  }
@@ -2,12 +2,17 @@
2
2
  import { Fn, int, texture } from "three/tsl";
3
3
  import type { Node, Renderer } from "three/webgpu";
4
4
  import type { ITemporalAANode } from "./temporalAAFrame.js";
5
+ import { createTemporalClampRelease } from "./temporalClampRelease.js";
5
6
  import {
6
7
  type TemporalCurrentFootprint,
7
8
  createTemporalCurrentFootprint,
8
9
  } from "./temporalCurrentFootprint.js";
9
10
  import type { TemporalCurrentProducer } from "./temporalCurrentProducer.js";
10
- import { createExperimentalTemporalResolve } from "./temporalResolve.js";
11
+ import { createTemporalMoire } from "./temporalMoire.js";
12
+ import {
13
+ type ITemporalHistoryWeighting,
14
+ createExperimentalTemporalResolve,
15
+ } from "./temporalResolve.js";
11
16
  import {
12
17
  type TemporalDepthRejection,
13
18
  type TemporalResolveNode,
@@ -18,8 +23,14 @@ export function createTemporalAAResolve(
18
23
  node: TemporalResolveNode,
19
24
  jitterOffset: Node<"vec2">,
20
25
  currentProducer?: TemporalCurrentProducer,
26
+ weighting?: ITemporalHistoryWeighting,
21
27
  ) {
22
28
  const internals = node as unknown as ITemporalAANode;
29
+ const moire = weighting?.flickerRejection === true ? createTemporalMoire(node) : undefined;
30
+ const levers = {
31
+ moire,
32
+ release: weighting?.clampRelease === true ? createTemporalClampRelease(node, moire) : undefined,
33
+ };
23
34
  let rejection: TemporalDepthRejection | undefined;
24
35
  let currentFootprint: TemporalCurrentFootprint | undefined;
25
36
  function configure(renderer: Renderer): void {
@@ -51,11 +62,14 @@ export function createTemporalAAResolve(
51
62
  "ordinary",
52
63
  rejection,
53
64
  currentFootprint,
65
+ weighting,
66
+ levers,
54
67
  );
55
68
  internals._resolveMaterial.needsUpdate = true;
56
69
  }
57
70
  return {
58
71
  equations: () => rejection,
72
+ levers,
59
73
  configure,
60
74
  invalidate: (renderer: Renderer) => {
61
75
  rejection = undefined;