create-threenative 0.2.15 → 0.2.17

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 (251) 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/capability-reference.md +958 -30
  5. package/agent-docs/references/conventions.md +271 -0
  6. package/agent-docs/references/kit-action-rpg.md +40 -0
  7. package/agent-docs/references/kit-adventure.md +40 -0
  8. package/agent-docs/references/kit-collectathon.md +38 -0
  9. package/agent-docs/references/kit-kart.md +31 -0
  10. package/agent-docs/references/kit-minimal.md +29 -0
  11. package/agent-docs/references/kit-platformer.md +34 -0
  12. package/agent-docs/references/kit-puzzle.md +22 -0
  13. package/agent-docs/references/kit-racing.md +26 -0
  14. package/agent-docs/references/kit-rain.md +31 -0
  15. package/agent-docs/references/kit-rts.md +34 -0
  16. package/agent-docs/references/kit-runner.md +32 -0
  17. package/agent-docs/references/kit-sailing.md +41 -0
  18. package/agent-docs/references/kit-shooter.md +33 -0
  19. package/agent-docs/references/kit-snow.md +33 -0
  20. package/agent-docs/references/kit-starter.md +55 -0
  21. package/agent-docs/references/kit-tower-defense.md +27 -0
  22. package/agent-docs/references/terrain-authoring.md +2 -1
  23. package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
  24. package/agent-files/.agents/skills/prd-creator/SKILL.md +3 -2
  25. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +81 -59
  26. package/agent-files/.claude/hooks/discovery-gate.mjs +125 -0
  27. package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
  28. package/agent-files/.claude/settings.json +25 -0
  29. package/agent-files/.codex/hooks.json +18 -1
  30. package/dist/index.js +256 -120
  31. package/dist/terrain-kit.d.ts +7 -0
  32. package/dist/terrain-kit.js +82 -0
  33. package/dist/threenative.js +23 -4
  34. package/dist/web-engine-gltf-loader.js +20 -7
  35. package/dist/web-engine-post-effects.js +34 -4
  36. package/dist/web-engine-runtime.js +6119 -3311
  37. package/package.json +13 -8
  38. package/template-assets/patches/three@0.187.0.patch +2004 -407
  39. package/templates/action-rpg/AGENTS.md +99 -84
  40. package/templates/action-rpg/CLAUDE.md +99 -84
  41. package/templates/action-rpg/kit.json +1 -0
  42. package/templates/action-rpg/package.json +7 -7
  43. package/templates/action-rpg/playtests/spells.playtest.json +20 -0
  44. package/templates/action-rpg/src/game.ts +1 -0
  45. package/templates/action-rpg/src/render/atmosphere.ts +5 -16
  46. package/templates/action-rpg/src/render/gpuSky.ts +4 -7
  47. package/templates/action-rpg/src/render/quality.ts +3 -1
  48. package/templates/action-rpg/src/scenes/Play.ts +26 -0
  49. package/templates/action-rpg/src/ui/AbilityBar.tsx +1 -1
  50. package/templates/action-rpg/threenative.config.ts +0 -3
  51. package/templates/adventure/AGENTS.md +87 -44
  52. package/templates/adventure/CLAUDE.md +87 -44
  53. package/templates/adventure/package.json +7 -7
  54. package/templates/collectathon/AGENTS.md +88 -42
  55. package/templates/collectathon/CLAUDE.md +88 -42
  56. package/templates/collectathon/package.json +7 -7
  57. package/templates/kart/AGENTS.md +82 -42
  58. package/templates/kart/CLAUDE.md +82 -42
  59. package/templates/kart/package.json +6 -6
  60. package/templates/minimal/AGENTS.md +100 -84
  61. package/templates/minimal/CLAUDE.md +100 -84
  62. package/templates/minimal/package.json +6 -6
  63. package/templates/minimal/src/render/atmosphere.ts +5 -16
  64. package/templates/minimal/src/render/gpuSky.ts +4 -7
  65. package/templates/platformer/AGENTS.md +90 -46
  66. package/templates/platformer/CLAUDE.md +90 -46
  67. package/templates/platformer/package.json +7 -7
  68. package/templates/puzzle/AGENTS.md +92 -80
  69. package/templates/puzzle/CLAUDE.md +92 -80
  70. package/templates/puzzle/package.json +7 -7
  71. package/templates/racing/AGENTS.md +95 -82
  72. package/templates/racing/CLAUDE.md +95 -82
  73. package/templates/racing/package.json +7 -7
  74. package/templates/racing/src/render/atmosphere.ts +5 -16
  75. package/templates/racing/src/render/gpuSky.ts +4 -7
  76. package/templates/rain/AGENTS.md +92 -84
  77. package/templates/rain/CLAUDE.md +92 -84
  78. package/templates/rain/native-playtests/lightning.playtest.json +85 -10
  79. package/templates/rain/package.json +6 -6
  80. package/templates/rain/playtests/reduced-motion.playtest.json +6 -0
  81. package/templates/rain/src/scenes/Boot.ts +1 -0
  82. package/templates/rain/src/state.ts +7 -0
  83. package/templates/rain/src/ui/GameUi.tsx +7 -1
  84. package/templates/rts/AGENTS.md +96 -85
  85. package/templates/rts/CLAUDE.md +96 -85
  86. package/templates/rts/package.json +6 -6
  87. package/templates/runner/AGENTS.md +92 -80
  88. package/templates/runner/CLAUDE.md +92 -80
  89. package/templates/runner/package.json +7 -7
  90. package/templates/runner/playtests/performance.playtest.json +1 -1
  91. package/templates/runner/src/render/atmosphere.ts +5 -16
  92. package/templates/runner/src/render/gpuSky.ts +4 -7
  93. package/templates/runner/src/render/lighting.ts +53 -11
  94. package/templates/runner/src/scenes/Run.ts +4 -3
  95. package/templates/runner/threenative.config.ts +0 -3
  96. package/templates/sailing/AGENTS.md +91 -79
  97. package/templates/sailing/CLAUDE.md +91 -79
  98. package/templates/sailing/package.json +7 -7
  99. package/templates/sailing/playtests/sails.playtest.json +1 -0
  100. package/templates/sailing/src/render/sky.ts +4 -0
  101. package/templates/sailing/threenative.config.ts +0 -3
  102. package/templates/shooter/AGENTS.md +93 -68
  103. package/templates/shooter/CLAUDE.md +93 -68
  104. package/templates/shooter/package.json +7 -7
  105. package/templates/shooter/src/render/atmosphere.ts +5 -16
  106. package/templates/shooter/src/render/gpuSky.ts +4 -7
  107. package/templates/shooter/src/render/quality.ts +3 -1
  108. package/templates/snow/AGENTS.md +90 -76
  109. package/templates/snow/CLAUDE.md +90 -76
  110. package/templates/snow/package.json +7 -7
  111. package/templates/snow/threenative.config.ts +0 -3
  112. package/templates/starter/AGENTS.md +104 -88
  113. package/templates/starter/CLAUDE.md +104 -88
  114. package/templates/starter/native-playtests/render-chain.playtest.json +24 -24
  115. package/templates/starter/native-playtests/smooth-motion.playtest.json +3 -3
  116. package/templates/starter/package.json +7 -7
  117. package/templates/starter/src/entities/Player.ts +10 -22
  118. package/templates/starter/src/render/atmosphere.ts +5 -16
  119. package/templates/starter/src/render/gpuSky.ts +4 -7
  120. package/templates/starter/src/render/lighting.ts +54 -4
  121. package/templates/starter/src/render/temporalAA.ts +8 -7
  122. package/templates/starter/src/render/temporalAAFrame.ts +30 -9
  123. package/templates/starter/src/render/temporalAAResolve.ts +15 -1
  124. package/templates/starter/src/render/temporalClampRelease.ts +183 -0
  125. package/templates/starter/src/render/temporalHistoryResolve.ts +90 -0
  126. package/templates/starter/src/render/temporalMoire.ts +190 -0
  127. package/templates/starter/src/render/temporalResolve.ts +75 -16
  128. package/templates/starter/src/render/temporalResolveDepth.ts +2 -0
  129. package/templates/starter/src/scenes/Play.ts +41 -29
  130. package/templates/tower-defense/AGENTS.md +92 -81
  131. package/templates/tower-defense/CLAUDE.md +92 -81
  132. package/templates/tower-defense/package.json +7 -7
  133. package/capabilities.json +0 -9197
  134. package/templates/AGENTS.md +0 -21
  135. package/templates/CLAUDE.md +0 -23
  136. package/templates/action-rpg/.codex/config.toml +0 -23
  137. package/templates/action-rpg/.cursor/mcp.json +0 -38
  138. package/templates/action-rpg/.gemini/settings.json +0 -38
  139. package/templates/action-rpg/.mcp.json +0 -38
  140. package/templates/action-rpg/.vscode/mcp.json +0 -43
  141. package/templates/action-rpg/.zed/settings.json +0 -43
  142. package/templates/action-rpg/opencode.json +0 -49
  143. package/templates/adventure/.codex/config.toml +0 -23
  144. package/templates/adventure/.cursor/mcp.json +0 -38
  145. package/templates/adventure/.gemini/settings.json +0 -38
  146. package/templates/adventure/.mcp.json +0 -38
  147. package/templates/adventure/.vscode/mcp.json +0 -43
  148. package/templates/adventure/.zed/settings.json +0 -43
  149. package/templates/adventure/opencode.json +0 -49
  150. package/templates/collectathon/.codex/config.toml +0 -23
  151. package/templates/collectathon/.cursor/mcp.json +0 -38
  152. package/templates/collectathon/.gemini/settings.json +0 -38
  153. package/templates/collectathon/.mcp.json +0 -38
  154. package/templates/collectathon/.vscode/mcp.json +0 -43
  155. package/templates/collectathon/.zed/settings.json +0 -43
  156. package/templates/collectathon/opencode.json +0 -49
  157. package/templates/kart/.codex/config.toml +0 -23
  158. package/templates/kart/.cursor/mcp.json +0 -38
  159. package/templates/kart/.gemini/settings.json +0 -38
  160. package/templates/kart/.mcp.json +0 -38
  161. package/templates/kart/.vscode/mcp.json +0 -43
  162. package/templates/kart/.zed/settings.json +0 -43
  163. package/templates/kart/opencode.json +0 -49
  164. package/templates/minimal/.codex/config.toml +0 -23
  165. package/templates/minimal/.cursor/mcp.json +0 -38
  166. package/templates/minimal/.gemini/settings.json +0 -38
  167. package/templates/minimal/.mcp.json +0 -38
  168. package/templates/minimal/.vscode/mcp.json +0 -43
  169. package/templates/minimal/.zed/settings.json +0 -43
  170. package/templates/minimal/opencode.json +0 -49
  171. package/templates/platformer/.codex/config.toml +0 -23
  172. package/templates/platformer/.cursor/mcp.json +0 -38
  173. package/templates/platformer/.gemini/settings.json +0 -38
  174. package/templates/platformer/.mcp.json +0 -38
  175. package/templates/platformer/.vscode/mcp.json +0 -43
  176. package/templates/platformer/.zed/settings.json +0 -43
  177. package/templates/platformer/opencode.json +0 -49
  178. package/templates/puzzle/.codex/config.toml +0 -23
  179. package/templates/puzzle/.cursor/mcp.json +0 -38
  180. package/templates/puzzle/.gemini/settings.json +0 -38
  181. package/templates/puzzle/.mcp.json +0 -38
  182. package/templates/puzzle/.vscode/mcp.json +0 -43
  183. package/templates/puzzle/.zed/settings.json +0 -43
  184. package/templates/puzzle/opencode.json +0 -49
  185. package/templates/racing/.codex/config.toml +0 -23
  186. package/templates/racing/.cursor/mcp.json +0 -38
  187. package/templates/racing/.gemini/settings.json +0 -38
  188. package/templates/racing/.mcp.json +0 -38
  189. package/templates/racing/.vscode/mcp.json +0 -43
  190. package/templates/racing/.zed/settings.json +0 -43
  191. package/templates/racing/opencode.json +0 -49
  192. package/templates/rain/.codex/config.toml +0 -23
  193. package/templates/rain/.cursor/mcp.json +0 -38
  194. package/templates/rain/.gemini/settings.json +0 -38
  195. package/templates/rain/.mcp.json +0 -38
  196. package/templates/rain/.vscode/mcp.json +0 -43
  197. package/templates/rain/.zed/settings.json +0 -43
  198. package/templates/rain/opencode.json +0 -49
  199. package/templates/rts/.codex/config.toml +0 -23
  200. package/templates/rts/.cursor/mcp.json +0 -38
  201. package/templates/rts/.gemini/settings.json +0 -38
  202. package/templates/rts/.mcp.json +0 -38
  203. package/templates/rts/.vscode/mcp.json +0 -43
  204. package/templates/rts/.zed/settings.json +0 -43
  205. package/templates/rts/opencode.json +0 -49
  206. package/templates/runner/.codex/config.toml +0 -23
  207. package/templates/runner/.cursor/mcp.json +0 -38
  208. package/templates/runner/.gemini/settings.json +0 -38
  209. package/templates/runner/.mcp.json +0 -38
  210. package/templates/runner/.vscode/mcp.json +0 -43
  211. package/templates/runner/.zed/settings.json +0 -43
  212. package/templates/runner/README.md +0 -43
  213. package/templates/runner/opencode.json +0 -49
  214. package/templates/sailing/.codex/config.toml +0 -23
  215. package/templates/sailing/.cursor/mcp.json +0 -38
  216. package/templates/sailing/.gemini/settings.json +0 -38
  217. package/templates/sailing/.mcp.json +0 -38
  218. package/templates/sailing/.vscode/mcp.json +0 -43
  219. package/templates/sailing/.zed/settings.json +0 -43
  220. package/templates/sailing/README.md +0 -28
  221. package/templates/sailing/opencode.json +0 -49
  222. package/templates/shooter/.codex/config.toml +0 -23
  223. package/templates/shooter/.cursor/mcp.json +0 -38
  224. package/templates/shooter/.gemini/settings.json +0 -38
  225. package/templates/shooter/.mcp.json +0 -38
  226. package/templates/shooter/.vscode/mcp.json +0 -43
  227. package/templates/shooter/.zed/settings.json +0 -43
  228. package/templates/shooter/opencode.json +0 -49
  229. package/templates/snow/.codex/config.toml +0 -23
  230. package/templates/snow/.cursor/mcp.json +0 -38
  231. package/templates/snow/.gemini/settings.json +0 -38
  232. package/templates/snow/.mcp.json +0 -38
  233. package/templates/snow/.vscode/mcp.json +0 -43
  234. package/templates/snow/.zed/settings.json +0 -43
  235. package/templates/snow/README.md +0 -26
  236. package/templates/snow/opencode.json +0 -49
  237. package/templates/starter/.codex/config.toml +0 -23
  238. package/templates/starter/.cursor/mcp.json +0 -38
  239. package/templates/starter/.gemini/settings.json +0 -38
  240. package/templates/starter/.mcp.json +0 -38
  241. package/templates/starter/.vscode/mcp.json +0 -43
  242. package/templates/starter/.zed/settings.json +0 -43
  243. package/templates/starter/opencode.json +0 -49
  244. package/templates/tower-defense/.codex/config.toml +0 -23
  245. package/templates/tower-defense/.cursor/mcp.json +0 -38
  246. package/templates/tower-defense/.gemini/settings.json +0 -38
  247. package/templates/tower-defense/.mcp.json +0 -38
  248. package/templates/tower-defense/.vscode/mcp.json +0 -43
  249. package/templates/tower-defense/.zed/settings.json +0 -43
  250. package/templates/tower-defense/README.md +0 -16
  251. package/templates/tower-defense/opencode.json +0 -49
@@ -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
+ }
@@ -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;
@@ -0,0 +1,183 @@
1
+ // Generated user source: Unreal TSR's low-frequency clamp release (PRD-539 lever 6). The per-pixel clip
2
+ // to the input's 3x3 box erases detail finer than an input texel. Unreal compares input and history only
3
+ // after a 3x3 blur, and where they agree it lerps the clamped history back to the unclamped one, so
4
+ // sub-texel detail the history gathered survives; disocclusion still forces the clamp.
5
+ // UE 5.8.3: Engine/Shaders/Private/TemporalSuperResolution/TSRShadingAnalysis.ush:25,509-525,563-566,
6
+ // 589-620,632-636; TSRRejectShading.usf:863; TSRUpdateHistory.usf:1256-1257; TSRColorSpace.ush:244-248.
7
+ import { HalfFloatType, NearestFilter } from "three";
8
+ import { Fn, float, int, ivec2, max, min, mix, texture, uv, vec2, vec3, vec4 } from "three/tsl";
9
+ import {
10
+ type Node,
11
+ NodeMaterial,
12
+ type QuadMesh,
13
+ RenderTarget,
14
+ type Renderer,
15
+ type TextureNode,
16
+ } from "three/webgpu";
17
+ import type { TemporalMoire } from "./temporalMoire.js";
18
+ import type { TemporalDepthRejection, TemporalResolveNode } from "./temporalResolveDepth.js";
19
+
20
+ // Unreal's 3x3 blur: centre 1, edges 0.5, corners 0.25, normalised by their sum.
21
+ const FILTERING_WEIGHT = 1 / (1 + 4 * 0.5 + 4 * 0.25);
22
+ // A 10-bit backbuffer's half step.
23
+ const QUANTIZATION = 0.5 / 1024;
24
+ const TAPS = [-1, 0, 1].flatMap((y) => [-1, 0, 1].map((x) => [x, y] as const));
25
+
26
+ type Load = (at: Node<"ivec2">) => Node<"vec4">;
27
+
28
+ /** Clamped integer taps around this fragment's input pixel. */
29
+ function taps(size: Node<"vec2">, load: Load): Node<"vec4">[] {
30
+ const centre = ivec2(uv().mul(size));
31
+ return TAPS.map(([x, y]) =>
32
+ load(ivec2(vec2(centre.add(ivec2(x, y))).clamp(vec2(0), size.sub(1)))),
33
+ );
34
+ }
35
+
36
+ const blur = (values: Node<"vec4">[]) =>
37
+ values.reduce<Node<"vec4">>((sum, value, index) => {
38
+ const [x, y] = TAPS[index] ?? [0, 0];
39
+ return sum.add(value.mul(FILTERING_WEIGHT * 0.5 ** (Math.abs(x) + Math.abs(y))));
40
+ }, vec4(0));
41
+
42
+ /** Median of nine by the 19-exchange network; every step is a min/max pair. */
43
+ function median(values: Node<"float">[]): Node<"float"> {
44
+ const v = [...values];
45
+ const sort = (a: number, b: number) => {
46
+ const low = min(v[a] as Node<"float">, v[b] as Node<"float">);
47
+ v[b] = max(v[a] as Node<"float">, v[b] as Node<"float">);
48
+ v[a] = low;
49
+ };
50
+ for (const [a, b] of "12 45 78 01 34 67 12 45 78 03 58 47 36 14 25 47 42 64 42".split(" "))
51
+ sort(Number(a), Number(b));
52
+ return v[4] as Node<"float">;
53
+ }
54
+
55
+ function quad(name: string, fragment: () => Node<"vec4">): NodeMaterial {
56
+ const material = new NodeMaterial();
57
+ material.name = `Temporal AA clamp release ${name}`;
58
+ material.fragmentNode = Fn(fragment)();
59
+ return material;
60
+ }
61
+
62
+ /** With `moire` (lever 4), the moire error widens the comparison, as in Unreal (TSRShadingAnalysis.ush:569-613). */
63
+ export function createTemporalClampRelease(node: TemporalResolveNode, moire?: TemporalMoire) {
64
+ const [guide, filteredInput, filteredHistory, raw, filtered, release] = [0, 1, 2, 3, 4, 5].map(
65
+ () => {
66
+ const target = new RenderTarget(1, 1, { depthBuffer: false, type: HalfFloatType });
67
+ target.texture.minFilter = NearestFilter;
68
+ target.texture.magFilter = NearestFilter;
69
+ return target;
70
+ },
71
+ ) as [RenderTarget, RenderTarget, RenderTarget, RenderTarget, RenderTarget, RenderTarget];
72
+ const targets = [guide, filteredInput, filteredHistory, raw, filtered, release];
73
+ const released: TextureNode = texture(release.texture);
74
+ let passes:
75
+ | { materials: [RenderTarget, NodeMaterial][]; equations: TemporalDepthRejection }
76
+ | undefined;
77
+
78
+ function build(equations: TemporalDepthRejection): [RenderTarget, NodeMaterial][] {
79
+ const input = node.beautyNode as TextureNode;
80
+ const history = texture(node._historyRenderTarget.texture);
81
+ const size = () => vec2(input.size(int(0)) as Node<"uvec2">);
82
+ const loader = (target: RenderTarget): Load => {
83
+ const source = texture(target.texture);
84
+ return (at) => source.load(at) as Node<"vec4">;
85
+ };
86
+ return [
87
+ // Last frame's history at this frame's input pixels; alpha 0 where depth says disoccluded.
88
+ [
89
+ guide,
90
+ quad("guide", () => {
91
+ const validity = equations.historyValidity(uv());
92
+ const colour = history.sample(validity.get("historyUV") as Node<"vec2">);
93
+ return vec4(colour.rgb, validity.get("hasValidHistory") as Node<"float">);
94
+ }),
95
+ ],
96
+ [
97
+ filteredInput,
98
+ quad("input blur", () => blur(taps(size(), (at) => input.load(at) as Node<"vec4">))),
99
+ ],
100
+ [filteredHistory, quad("history blur", () => blur(taps(size(), loader(guide))))],
101
+ [
102
+ raw,
103
+ quad("rejection", () => {
104
+ const s = size();
105
+ const inputs = taps(s, (at) => input.load(at) as Node<"vec4">);
106
+ const box = inputs.reduce((a, b) => max(a, b)).sub(inputs.reduce((a, b) => min(a, b)));
107
+ const blurred = taps(s, loader(filteredInput));
108
+ const historyBlur = taps(s, loader(filteredHistory))[4] as Node<"vec4">;
109
+ const inputBlur = blurred[4] as Node<"vec4">;
110
+ // ponytail: Unreal also widens by the blurred total variation of the input; add it if edges flip.
111
+ const error = max(box.mul(FILTERING_WEIGHT * 0.25), QUANTIZATION).add(QUANTIZATION);
112
+ let low = blurred.reduce((a, b) => min(a, b)).sub(error);
113
+ let high = blurred.reduce((a, b) => max(a, b)).add(error);
114
+ let boxSize = box.mul(FILTERING_WEIGHT).add(QUANTIZATION * 2 * FILTERING_WEIGHT);
115
+ if (moire !== undefined) {
116
+ const historyUV = equations.historyValidity(uv()).get("historyUV") as Node<"vec2">;
117
+ const historySize = vec2(history.size(int(0)) as Node<"uvec2">);
118
+ const moireError = moire.error(
119
+ historyUV,
120
+ uv().sub(historyUV).mul(historySize).length(),
121
+ );
122
+ const size = vec4(vec3(moireError.mul(3)), 0);
123
+ [low, high] = [min(low, high.sub(size)), max(high, low.add(size))];
124
+ const energy = historyBlur.clamp(low, high).sub(historyBlur).abs();
125
+ const share = energy.div(max(energy.r.add(energy.g).add(energy.b), 1e-6));
126
+ boxSize = max(boxSize, share.mul(moireError.mul(FILTERING_WEIGHT * 3)));
127
+ }
128
+ const delta = max(inputBlur.sub(historyBlur).abs(), boxSize);
129
+ const factor = float(1)
130
+ .sub(historyBlur.clamp(low, high).sub(historyBlur).abs().div(delta))
131
+ .saturate();
132
+ return vec4(min(factor.r, factor.g, factor.b));
133
+ }),
134
+ ],
135
+ [filtered, quad("median", () => vec4(median(taps(size(), loader(raw)).map((v) => v.x))))],
136
+ // ponytail: no velocity-edge term (Unreal's InputUncertainty); add it if edges of movers ghost.
137
+ [
138
+ release,
139
+ quad("min", () => {
140
+ const guideValid = (texture(guide.texture).load(ivec2(uv().mul(size()))) as Node<"vec4">)
141
+ .a;
142
+ const lowest = taps(size(), loader(filtered)).reduce((a, b) => min(a, b)).x;
143
+ return vec4(lowest.mul(guideValid.greaterThan(0.5).select(float(1), float(0))));
144
+ }),
145
+ ],
146
+ ];
147
+ }
148
+
149
+ return {
150
+ /** The clipped history lerped back towards the unclipped one where input and history agree. */
151
+ apply(clipped: Node<"vec4">, history: Node<"vec4">, pixel: Node<"vec2">): Node<"vec4"> {
152
+ return mix(clipped, history, released.sample(pixel).x);
153
+ },
154
+ /** Before the resolve: it reads this frame's input against last frame's history. */
155
+ update(
156
+ renderer: Renderer,
157
+ quadMesh: QuadMesh,
158
+ equations: TemporalDepthRejection,
159
+ input: { x: number; y: number },
160
+ ) {
161
+ for (const target of targets)
162
+ if (target.width !== input.x || target.height !== input.y) {
163
+ target.setSize(input.x, input.y);
164
+ renderer.initRenderTarget(target);
165
+ }
166
+ if (passes?.equations !== equations) {
167
+ for (const [, material] of passes?.materials ?? []) material.dispose();
168
+ passes = { materials: build(equations), equations };
169
+ }
170
+ for (const [target, material] of passes.materials) {
171
+ renderer.setRenderTarget(target);
172
+ quadMesh.material = material;
173
+ quadMesh.render(renderer);
174
+ }
175
+ },
176
+ dispose() {
177
+ for (const target of targets) target.dispose();
178
+ for (const [, material] of passes?.materials ?? []) material.dispose();
179
+ },
180
+ };
181
+ }
182
+
183
+ export type TemporalClampRelease = ReturnType<typeof createTemporalClampRelease>;
@@ -0,0 +1,90 @@
1
+ // Generated user source: Unreal TSR's history resolve for a history stored above the display raster.
2
+ // The chain reads its display-sized output in place of the history, so later post stages pay
3
+ // display pixels, not history pixels.
4
+ import { HalfFloatType, type Vector2 } from "three";
5
+ import { Fn, float, int, ivec2, max, min, texture, uv, vec2, vec4 } from "three/tsl";
6
+ import {
7
+ type Node,
8
+ NodeMaterial,
9
+ type QuadMesh,
10
+ RenderTarget,
11
+ type Renderer,
12
+ type TextureNode,
13
+ } from "three/webgpu";
14
+ import type { ITemporalAANode } from "./temporalResolveDepth.js";
15
+
16
+ /** Mitchell–Netravali, B = C = 1/3, at distance x (UE 5.8.3: Engine/Shaders/Private/
17
+ * TemporalSuperResolution/TSRResolveHistory.usf:82-83). */
18
+ function mitchell(x: number): number {
19
+ const b = 1 / 3;
20
+ const c = 1 / 3;
21
+ const ax = Math.abs(x);
22
+ if (ax < 1)
23
+ return ((12 - 9 * b - 6 * c) * ax ** 3 + (-18 + 12 * b + 6 * c) * ax ** 2 + (6 - 2 * b)) / 6;
24
+ if (ax < 2)
25
+ return (
26
+ ((-b - 6 * c) * ax ** 3 +
27
+ (6 * b + 30 * c) * ax ** 2 +
28
+ (-12 * b - 48 * c) * ax +
29
+ (8 * b + 24 * c)) /
30
+ 6
31
+ );
32
+ return 0;
33
+ }
34
+
35
+ /**
36
+ * Unreal TSR's history resolve (UE 5.8.3: Engine/Shaders/Private/TemporalSuperResolution/
37
+ * TSRResolveHistory.usf:312-357): a display pixel takes the 4×4 history pixels around its centre,
38
+ * Mitchell-weighted by their distance in history pixels and by Unreal's HDR weight 1 / (R + 2G + B + 4)
39
+ * (TSRColorSpace.ush:167-195), then clamped to those samples' range. At a 2x history the centre sits
40
+ * between pixels, so the taps lie at ±0.5 and ±1.5 history pixels.
41
+ */
42
+ function createHistoryResolve(resolve: TextureNode): NodeMaterial {
43
+ const weights = [1.5, 0.5, 0.5, 1.5].map(mitchell);
44
+ const material = new NodeMaterial();
45
+ material.name = "Temporal AA history resolve";
46
+ material.fragmentNode = Fn(() => {
47
+ const size = vec2(resolve.size(int(0)) as Node<"uvec2">);
48
+ const base = ivec2(uv().mul(size).sub(1.5).floor());
49
+ const sum = vec4(0).toVar();
50
+ const weightSum = float(0).toVar();
51
+ const samples: Node<"vec4">[] = [];
52
+ for (let y = 0; y < 4; y++)
53
+ for (let x = 0; x < 4; x++) {
54
+ const at = ivec2(vec2(base.add(ivec2(x, y))).clamp(vec2(0), size.sub(1)));
55
+ const colour = (resolve.load(at).max(0) as Node<"vec4">).toVar();
56
+ const hdr = float(1).div(colour.r.add(colour.g.mul(2)).add(colour.b).add(4));
57
+ const weight = hdr.mul((weights[x] ?? 0) * (weights[y] ?? 0));
58
+ sum.addAssign(colour.mul(weight));
59
+ weightSum.addAssign(weight);
60
+ samples.push(colour);
61
+ }
62
+ // The range starts from a real sample: WGSL has no infinity literal.
63
+ const low = samples.reduce((a, b) => min(a, b));
64
+ const high = samples.reduce((a, b) => max(a, b));
65
+ return sum.div(weightSum).clamp(low, high);
66
+ })();
67
+ return material;
68
+ }
69
+
70
+ /** The display-sized target the chain reads in place of a 2x history, and its resolve draw. */
71
+ export function createHistoryPresent(internals: ITemporalAANode, quadMesh: QuadMesh) {
72
+ const target = new RenderTarget(1, 1, { depthBuffer: false, type: HalfFloatType });
73
+ const material = createHistoryResolve(texture(internals._resolveRenderTarget.texture));
74
+ return {
75
+ draw(renderer: Renderer, display: Vector2): void {
76
+ if (target.width !== display.x || target.height !== display.y) {
77
+ target.setSize(display.x, display.y);
78
+ renderer.initRenderTarget(target);
79
+ }
80
+ internals._textureNode.value = target.texture;
81
+ renderer.setRenderTarget(target);
82
+ quadMesh.material = material;
83
+ quadMesh.render(renderer);
84
+ },
85
+ dispose(): void {
86
+ target.dispose();
87
+ material.dispose();
88
+ },
89
+ };
90
+ }