create-threenative 0.2.14 → 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
@@ -0,0 +1,190 @@
1
+ // Generated user source: Unreal TSR's flicker-aware shading rejection (PRD-539 lever 4). A pixel whose
2
+ // output luma keeps changing direction against what plain ghosting would give is moire, not new
3
+ // shading, so its clip box widens by a bounded luma error and its history survives instead of resetting.
4
+ // UE 5.8.3: Engine/Shaders/Private/TemporalSuperResolution/TSRShadingAnalysis.ush:225-229,263-271,
5
+ // 381-455,477-490,586-593; the 2-frame period and the 0.95 decay come from
6
+ // Engine/Source/Runtime/Renderer/Private/PostProcess/TemporalSuperResolution.cpp:177-193,3005-3007.
7
+ import { HalfFloatType, NearestFilter, type Vector2 } from "three";
8
+ import {
9
+ Fn,
10
+ abs,
11
+ float,
12
+ int,
13
+ ivec2,
14
+ max,
15
+ min,
16
+ mix,
17
+ texture,
18
+ uv,
19
+ vec2,
20
+ vec3,
21
+ vec4,
22
+ } from "three/tsl";
23
+ import {
24
+ type Node,
25
+ NodeMaterial,
26
+ type QuadMesh,
27
+ RenderTarget,
28
+ type Renderer,
29
+ type TextureNode,
30
+ } from "three/webgpu";
31
+ import type { TemporalDepthRejection, TemporalResolveNode } from "./temporalResolveDepth.js";
32
+
33
+ const DECAY = 0.95;
34
+ const PERIOD = 2;
35
+ const MIN_GRADIENT = 1 / 127;
36
+ const LUMA_TO_CHANNEL = 3;
37
+ // Unreal's r.TSR.ShadingRejection.Flickering.MaxParallaxVelocity, in pixels of a 1920-wide output.
38
+ const MAX_PARALLAX_PX = 10;
39
+
40
+ /** Perceptual luma: the mean of the square-root channels (Unreal stores flicker luma in gamma space). */
41
+ const luma = (colour: Node<"vec4">) =>
42
+ colour.rgb
43
+ .max(0)
44
+ .sqrt()
45
+ .dot(vec3(1 / 3));
46
+
47
+ /** 1 where the pixel holds still, 0 where it moves. Unreal separates parallax from rotation; this
48
+ * counts every motion, so a rotating camera widens fewer boxes than Unreal does. */
49
+ function stillness(speedPx: Node<"float">, displayWidth: Node<"float">) {
50
+ const limit = displayWidth.mul(MAX_PARALLAX_PX / 1920);
51
+ return float(1).sub(speedPx.div(limit).sub(0.5).saturate());
52
+ }
53
+
54
+ export function createTemporalMoire(node: TemporalResolveNode) {
55
+ const targets = [0, 1, 2].map(() => {
56
+ const target = new RenderTarget(1, 1, { depthBuffer: false, type: HalfFloatType });
57
+ target.texture.minFilter = NearestFilter;
58
+ target.texture.magFilter = NearestFilter;
59
+ return target;
60
+ });
61
+ const [first, , scratch] = targets as [RenderTarget, RenderTarget, RenderTarget];
62
+ let read = 0;
63
+ // x: last luma gradient, y: total flicker variation, z: flicker count. Both decay by 0.95 a frame.
64
+ const previous: TextureNode = texture(first.texture);
65
+ let passes: { materials: NodeMaterial[]; equations: TemporalDepthRejection } | undefined;
66
+
67
+ /** The moire luma error the history has measured at this pixel. `speedPx` counts history pixels,
68
+ * so the parallax limit scales with the history raster. */
69
+ function error(historyUV: Node<"vec2">, speedPx: Node<"float">): Node<"float"> {
70
+ const state = previous.sample(historyUV);
71
+ const count = state.z;
72
+ const ramp = count
73
+ .mul(1 - DECAY ** PERIOD)
74
+ .sub(0.5)
75
+ .saturate();
76
+ return abs(state.y.div(max(count, 1e-4)))
77
+ .add(count.div(127))
78
+ .mul(ramp)
79
+ .mul(stillness(speedPx, vec2(previous.size(int(0)) as Node<"uvec2">).x))
80
+ .saturate();
81
+ }
82
+
83
+ /** The clip box widened by that error. */
84
+ function widen(
85
+ low: Node<"vec4">,
86
+ high: Node<"vec4">,
87
+ historyUV: Node<"vec2">,
88
+ speedPx: Node<"float">,
89
+ ) {
90
+ const size = vec4(vec3(error(historyUV, speedPx).mul(LUMA_TO_CHANNEL)), 0);
91
+ return { low: min(low, high.sub(size)), high: max(high, low.add(size)) };
92
+ }
93
+
94
+ /** Pass 1, per pixel: this frame's gradient, and whether it turned against the last one. */
95
+ function detect(equations: TemporalDepthRejection): NodeMaterial {
96
+ const resolved = texture(node._resolveRenderTarget.texture);
97
+ const history = texture(node._historyRenderTarget.texture);
98
+ const result = new NodeMaterial();
99
+ result.name = "Temporal AA moire detect";
100
+ result.fragmentNode = Fn(() => {
101
+ const pixel = uv();
102
+ const validity = equations.historyValidity(pixel);
103
+ const historyUV = validity.get("historyUV") as Node<"vec2">;
104
+ const last = previous.sample(historyUV).x;
105
+ // What the output did against pure ghosting (5% current), clamped like Unreal's gradient.
106
+ const ghost = mix(
107
+ luma(history.sample(historyUV)),
108
+ luma((node.beautyNode as TextureNode).sample(pixel)),
109
+ 0.05,
110
+ );
111
+ const gradient = luma(resolved.sample(pixel)).sub(ghost).clamp(-1, 1);
112
+ const turned = gradient.mul(last).lessThan(0);
113
+ const strong = min(abs(gradient), abs(last)).greaterThanEqual(MIN_GRADIENT);
114
+ const flicker = turned
115
+ .and(strong)
116
+ .select(float(1), float(0))
117
+ .mul(validity.get("hasValidHistory") as Node<"float">);
118
+ return vec4(gradient, min(abs(gradient), abs(last)).mul(flicker), flicker, 1);
119
+ })();
120
+ return result;
121
+ }
122
+
123
+ /** Pass 2: the flicker and its variation dilated over 5x5 (Unreal's max3x3 of max3x3), then
124
+ * accumulated into the decayed state of still, valid pixels. */
125
+ function accumulate(equations: TemporalDepthRejection): NodeMaterial {
126
+ const detected = texture(scratch.texture);
127
+ const result = new NodeMaterial();
128
+ result.name = "Temporal AA moire accumulate";
129
+ result.fragmentNode = Fn(() => {
130
+ const pixel = uv();
131
+ const validity = equations.historyValidity(pixel);
132
+ const historyUV = validity.get("historyUV") as Node<"vec2">;
133
+ const size = vec2(previous.size(int(0)) as Node<"uvec2">);
134
+ const centre = ivec2(pixel.mul(size));
135
+ let peak: Node<"vec4"> = detected.load(centre) as Node<"vec4">;
136
+ for (let y = -2; y <= 2; y++)
137
+ for (let x = -2; x <= 2; x++)
138
+ if (x !== 0 || y !== 0) {
139
+ const at = ivec2(vec2(centre.add(ivec2(x, y))).clamp(vec2(0), size.sub(1)));
140
+ peak = max(peak, detected.load(at) as Node<"vec4">);
141
+ }
142
+ const state = previous.sample(historyUV);
143
+ const speed = pixel.sub(historyUV).mul(size).length();
144
+ const valid = validity.get("hasValidHistory") as Node<"float">;
145
+ const keep = stillness(speed, size.x).mul(valid).mul(DECAY);
146
+ const own = detected.load(centre) as Node<"vec4">;
147
+ return vec4(own.x, state.y.mul(keep).add(peak.y), state.z.mul(keep).add(peak.z), 1);
148
+ })();
149
+ return result;
150
+ }
151
+
152
+ return {
153
+ error,
154
+ widen,
155
+ /** After the resolve, before the history copy: it reads last frame's history at this frame's UVs. */
156
+ update(
157
+ renderer: Renderer,
158
+ quadMesh: QuadMesh,
159
+ equations: TemporalDepthRejection,
160
+ history: Vector2,
161
+ ) {
162
+ for (const target of targets)
163
+ if (target.width !== history.x || target.height !== history.y) {
164
+ target.setSize(history.x, history.y);
165
+ renderer.initRenderTarget(target);
166
+ }
167
+ if (passes?.equations !== equations) {
168
+ for (const material of passes?.materials ?? []) material.dispose();
169
+ passes = { materials: [detect(equations), accumulate(equations)], equations };
170
+ }
171
+ const write = targets[1 - read];
172
+ const [detection, accumulation] = passes.materials;
173
+ if (write === undefined || detection === undefined || accumulation === undefined) return;
174
+ renderer.setRenderTarget(scratch);
175
+ quadMesh.material = detection;
176
+ quadMesh.render(renderer);
177
+ renderer.setRenderTarget(write);
178
+ quadMesh.material = accumulation;
179
+ quadMesh.render(renderer);
180
+ read = 1 - read;
181
+ previous.value = write.texture;
182
+ },
183
+ dispose() {
184
+ for (const target of targets) target.dispose();
185
+ for (const material of passes?.materials ?? []) material.dispose();
186
+ },
187
+ };
188
+ }
189
+
190
+ export type TemporalMoire = ReturnType<typeof createTemporalMoire>;
@@ -3,9 +3,11 @@
3
3
  // from this kernel; `temporalResolveMath.ts` and `temporalResolveDepth.ts` hold its equations.
4
4
  // Derived resolve source: three/examples/jsm/tsl/display/TRAANode.js (pinned 0.185.1).
5
5
  import type TRAANode from "three/addons/tsl/display/TRAANode.js";
6
- import { Fn, add, float, int, luminance, max, mix, texture, uv } from "three/tsl";
6
+ import { Fn, add, float, int, luminance, max, mix, texture, uv, uvec2, vec2 } from "three/tsl";
7
7
  import type { Node } from "three/webgpu";
8
+ import type { TemporalClampRelease } from "./temporalClampRelease.js";
8
9
  import type { TemporalCurrentFootprint } from "./temporalCurrentFootprint.js";
10
+ import type { TemporalMoire } from "./temporalMoire.js";
9
11
  import {
10
12
  type TemporalDepthRejection,
11
13
  type TemporalResolveNode,
@@ -19,6 +21,37 @@ import {
19
21
 
20
22
  export { CATMULL_ROM_BASIS } from "./temporalResolveMath.js";
21
23
 
24
+ /** PRD-539 gate arms, ported from Unreal TSR. `historyScale` stores history and resolve at that
25
+ * multiple of the display raster (Unreal's `r.TSR.History.ScreenPercentage` / 100, 1 or 2); the
26
+ * next stage samples the resolve bilinearly at display pixel centres, a 2x2 box down-resolve.
27
+ * `velocityWeightClamp` caps the accumulated history sample count under motion. */
28
+ export interface ITemporalHistoryWeighting {
29
+ historyScale: number;
30
+ velocityWeightClamp: boolean;
31
+ /** Unreal TSR lever 4: widen the clip box where output luma flickers (`temporalMoire.ts`). */
32
+ flickerRejection?: boolean;
33
+ /** Lever 6: release the clip where input and history agree at low frequency. */
34
+ clampRelease?: boolean;
35
+ }
36
+
37
+ /**
38
+ * Unreal TSR at the Epic tier (PRD-539): history at 200% of the display (UE 5.8.3:
39
+ * Engine/Config/BaseScalability.ini:89, r.TSR.History.ScreenPercentage; Low to High keep 100) and a
40
+ * history weight clamped by velocity. The raw4 current-footprint path was measured at 100% only, so
41
+ * it keeps that history. Name `{ historyScale: 1, velocityWeightClamp: false }` to opt out.
42
+ */
43
+ export function historyWeighting(
44
+ requested: ITemporalHistoryWeighting | undefined,
45
+ raw4: boolean,
46
+ ): ITemporalHistoryWeighting {
47
+ if (requested !== undefined && requested.historyScale !== 1 && requested.historyScale !== 2)
48
+ throw new Error("Temporal AA historyScale must be 1 or 2.");
49
+ if (requested !== undefined) return requested;
50
+ return raw4
51
+ ? { historyScale: 1, velocityWeightClamp: false }
52
+ : { historyScale: 2, velocityWeightClamp: true };
53
+ }
54
+
22
55
  /** Returns the amount of subpixel (expressed within [0, 1]) in the velocity. */
23
56
  const subpixelCorrection = Fn(([velocityUV, textureSize]: [Node<"vec2">, Node<"uvec2">]) => {
24
57
  const velocityTexel = velocityUV.mul(textureSize);
@@ -73,7 +106,10 @@ export function createExperimentalTemporalResolve(
73
106
  renderer,
74
107
  ),
75
108
  current?: TemporalCurrentFootprint,
109
+ weighting: ITemporalHistoryWeighting = { historyScale: 1, velocityWeightClamp: false },
110
+ levers: { moire?: TemporalMoire; release?: TemporalClampRelease } = {},
76
111
  ) {
112
+ const { historyScale, velocityWeightClamp } = weighting;
77
113
  const node = source as TemporalResolveNode;
78
114
  const { historyValidity } = rejection;
79
115
  const { clipAABB } = createTemporalResolveMath(node);
@@ -93,9 +129,16 @@ export function createExperimentalTemporalResolve(
93
129
  // Reconstruction: gather the current frame's 3×3 input neighbourhood around the jittered sample
94
130
  // the scene pass drew, and read its moments for the variance clip from the same taps. At a 1:1
95
131
  // raster the plain current sample is exact; retain it instead of adding Gaussian blur.
132
+ // A full-resolution input under a 2x history keeps its owned point (the closest jittered tap)
133
+ // rather than the Gaussian gather: native axes are judged against the output raster, so the
134
+ // history scale is the only variable that changes.
135
+ const outputSize =
136
+ historyScale === 1
137
+ ? displaySize
138
+ : (uvec2(vec2(displaySize).div(historyScale).round()) as Node<"uvec2">);
96
139
  const reconstruction =
97
140
  current?.reconstruct(uvNode, displaySize) ??
98
- reconstructNeighbourhood(node.beautyNode, uvNode, inputSize, jitterOffset, displaySize);
141
+ reconstructNeighbourhood(node.beautyNode, uvNode, inputSize, jitterOffset, outputSize);
99
142
  const upsampled = inputSize.x.lessThan(displaySize.x).or(inputSize.y.lessThan(displaySize.y));
100
143
  const currentColor = upsampled.select(
101
144
  reconstruction.get("color") as Node<"vec4">,
@@ -106,29 +149,45 @@ export function createExperimentalTemporalResolve(
106
149
  interpolation === "linear"
107
150
  ? historyNode.sample(historyUV)
108
151
  : sampleCatmullRom(historyNode, historyUV).max(0);
109
- const motionFactor = uvNode
110
- .sub(historyUV)
111
- .mul(displaySize)
112
- .length()
113
- .div(node.maxVelocityLength)
114
- .saturate();
152
+ // Motion counts output pixels whatever the history raster, so a 2x history changes only the
153
+ // raster the history is stored at. Subpixel correction measures history-texel resampling and
154
+ // stays in history texels.
155
+ const outputPixelSpeed = uvNode.sub(historyUV).mul(displaySize).length().div(historyScale);
156
+ const motionFactor = outputPixelSpeed.div(node.maxVelocityLength).saturate();
115
157
  const currentWeight = float(0.05).toVar(); // A minimum weight
116
158
  if (node.useSubpixelCorrection) {
117
159
  // Increase the minimum weight towards the current frame when the velocity is more subpixel.
118
160
  currentWeight.addAssign(subpixelCorrection(offsetUV, displaySize).mul(0.25));
119
161
  }
162
+ if (velocityWeightClamp) {
163
+ // Unreal TSR's velocity clamp (UE 5.8.3: Engine/Source/Runtime/Renderer/Private/PostProcess/
164
+ // TemporalSuperResolution.cpp:3219-3224, Engine/Shaders/Private/TemporalSuperResolution/
165
+ // TSRUpdateHistory.usf:1262-1276): a history pixel holds 16 / scale² samples; at 1 output
166
+ // px/frame its accumulated count clamps to 4, lerped by speed, unless the luma change between
167
+ // history and current is larger (stability on high-contrast edges). A history clamped to N
168
+ // samples blends the current frame at 1 / (N + 1).
169
+ const historySamples = 16 / (historyScale * historyScale);
170
+ const amplitude = Math.min(1, Math.max(0, 1 - 4 / historySamples));
171
+ const historyLuma = luminance(historyColor.rgb);
172
+ const currentLuma = luminance(currentColor.rgb);
173
+ const stability = historyLuma
174
+ .sub(currentLuma)
175
+ .abs()
176
+ .div(max(historyLuma, currentLuma, 0.00001));
177
+ const maxValidity = max(float(1).sub(outputPixelSpeed.saturate().mul(amplitude)), stability);
178
+ currentWeight.assign(
179
+ max(currentWeight, float(1).div(maxValidity.mul(historySamples).add(1))),
180
+ );
181
+ }
120
182
  currentWeight.assign(hasValidHistory.select(currentWeight.add(motionFactor).saturate(), 1));
121
183
  // Reasonable gamma range is [0.75, 2]
122
184
  const varianceGamma = mix(0.5, 1, motionFactor.oneMinus().pow2());
123
185
  const variance = (reconstruction.get("variance") as Node<"vec4">).mul(varianceGamma);
124
- const minColor = mean.sub(variance);
125
- const maxColor = mean.add(variance);
126
- const clippedHistoryColor = clipAABB(
127
- mean.clamp(minColor, maxColor),
128
- historyColor,
129
- minColor,
130
- maxColor,
131
- );
186
+ const box = { low: mean.sub(variance), high: mean.add(variance) };
187
+ const { low: minColor, high: maxColor } =
188
+ levers.moire?.widen(box.low, box.high, historyUV, outputPixelSpeed.mul(historyScale)) ?? box;
189
+ const clipped = clipAABB(mean.clamp(minColor, maxColor), historyColor, minColor, maxColor);
190
+ const clippedHistoryColor = levers.release?.apply(clipped, historyColor, uvNode) ?? clipped;
132
191
  // Every accepted history colour still passes the raw current-tap variance box.
133
192
  // Diagnostic only: ordinary blending isolates luminance reweighting at the same weight.
134
193
  return blend === "ordinary"
@@ -75,6 +75,8 @@ export interface ITemporalResolvePinned {
75
75
  /** Actual input jitter, in input-raster UVs, captured beside the matching depth matrices. */
76
76
  _currentJitterUV?: Node<"vec2"> & ITemporalUniform<Vector2>;
77
77
  _previousJitterUV?: Node<"vec2"> & ITemporalUniform<Vector2>;
78
+ /** The node the chain reads: Three's pass texture over the resolve target. */
79
+ _textureNode: TextureNode;
78
80
  }
79
81
 
80
82
  export type TemporalResolveNode = TRAANode & ITemporalResolvePinned;
@@ -26,7 +26,7 @@ import { createArena, platform } from "../render/arena.js";
26
26
  import { createSpringArm } from "../render/camera.js";
27
27
  import { pickupRiseEase } from "../render/easing.js";
28
28
  import { type IEnvironmentSample, sampleEnvironment } from "../render/environmentSampling.js";
29
- import { setupLighting } from "../render/lighting.js";
29
+ import { setupLighting, shadeLikeSubstrate } from "../render/lighting.js";
30
30
  import { createLoadingScreen } from "../render/loading.js";
31
31
  import { createMaterialLighting } from "../render/materialLighting.js";
32
32
  import { createPennantMaterial, propMaterial } from "../render/materials.js";
@@ -43,8 +43,7 @@ export type GameCtx = ICtx<GameState, IPhysicsContext>;
43
43
  const KILL_PLANE = -4;
44
44
  const STARTING_LIVES = 3;
45
45
  const FLOOR_SURFACE_Y = 0;
46
- const FLOOR_BOUNDS = { maxX: 5, minX: -5, maxZ: 2, minZ: -2 } as const;
47
- /** The near platform's own footprint, which the support surface below answers for. */
46
+ /** The near platform's own footprint. */
48
47
  const FLOOR_SIZE = { depth: 4.2, width: 10 } as const;
49
48
 
50
49
  export class Play extends Scene<GameState, IPhysicsContext> {
@@ -150,15 +149,30 @@ export class Play extends Scene<GameState, IPhysicsContext> {
150
149
  // Observation is armed by playtest's first sample; ordinary games retain no frame series.
151
150
  let observeMotion = false;
152
151
  let wasMovingRight = false;
152
+ let simulatedMs = 0;
153
+ // Presented frames: one per drawn frame. That is the display's cadence on the web engine and
154
+ // the tick's own cadence on the native one, whose frame clock is the host's frame duration.
153
155
  const presented: Array<[number, number, number]> = [];
154
- this.#observeMotion = () => {
155
- if (!observeMotion) return;
156
+ // World updates: one per fixed step, timed by the steps themselves. A distance over those is
157
+ // the player's speed; the same distance over the frame clock would be the host's.
158
+ const ticks: Array<[number, number, number]> = [];
159
+ const sampleMotion = (series: Array<[number, number, number]>, time: number): void => {
156
160
  const movingRight = ctx.input.vector("move").x > 0;
157
- if (movingRight && !wasMovingRight) presented.length = 0;
161
+ if (movingRight && !wasMovingRight) {
162
+ presented.length = 0;
163
+ ticks.length = 0;
164
+ }
158
165
  wasMovingRight = movingRight;
159
166
  if (!movingRight) return;
160
- presented.push([ctx.frameTime, player.body.object.position.x, ctx.camera.position.x]);
161
- if (presented.length > 31) presented.shift();
167
+ series.push([time, player.body.object.position.x, ctx.camera.position.x]);
168
+ if (series.length > 31) series.shift();
169
+ };
170
+ this.#observeMotion = () => {
171
+ if (observeMotion) sampleMotion(presented, ctx.frameTime);
172
+ };
173
+ const recordMotionTick = (dt: number): void => {
174
+ simulatedMs += dt * 1000;
175
+ if (observeMotion) sampleMotion(ticks, simulatedMs);
162
176
  };
163
177
  ctx.entities.add("smooth-motion", {
164
178
  debug: () => {
@@ -169,6 +183,12 @@ export class Play extends Scene<GameState, IPhysicsContext> {
169
183
  if (previous === undefined) throw new Error("Missing presented motion sample.");
170
184
  return (frame[axis] - previous[axis]) / ((frame[0] - previous[0]) / 1000);
171
185
  });
186
+ const tickSpeeds = (axis: 1 | 2): number[] =>
187
+ ticks.slice(1).map((frame, index) => {
188
+ const previous = ticks[index];
189
+ if (previous === undefined) throw new Error("Missing tick motion sample.");
190
+ return (frame[axis] - previous[axis]) / ((frame[0] - previous[0]) / 1000);
191
+ });
172
192
  const cv = (values: number[]): number | null => {
173
193
  if (values.length < 20) return null;
174
194
  const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
@@ -182,7 +202,11 @@ export class Play extends Scene<GameState, IPhysicsContext> {
182
202
  samples: presented.length,
183
203
  playerCv: cv(speeds(1)),
184
204
  cameraCv: cv(speeds(2)),
205
+ tickSamples: ticks.length,
206
+ tickPlayerCv: cv(tickSpeeds(1)),
207
+ tickCameraCv: cv(tickSpeeds(2)),
185
208
  presented,
209
+ ticks,
186
210
  };
187
211
  },
188
212
  });
@@ -192,11 +216,12 @@ export class Play extends Scene<GameState, IPhysicsContext> {
192
216
  setupSky(ctx.scene, this.#sky, ctx.renderer.softwareAdapter !== undefined);
193
217
  // isMobile() arrives as an argument because src/render/ imports no framework package:
194
218
  // the platform decision is made here, in portable game code, exactly like createRandom.
195
- const { key } = setupLighting(
219
+ const { key, dispose: disposeLighting } = setupLighting(
196
220
  ctx.scene,
197
221
  ctx.renderer.raw as Parameters<typeof setupLighting>[1],
198
222
  isMobile(),
199
223
  );
224
+ this.#disposeLighting = disposeLighting;
200
225
  const materialEnvironment = {
201
226
  web: getPlatform().runtime === "web",
202
227
  rendererKind: ctx.renderer.kind,
@@ -296,6 +321,7 @@ export class Play extends Scene<GameState, IPhysicsContext> {
296
321
  // `load()` above, which is what the native asset gate greps for.
297
322
  const goal = ctx.entities.add("goal", new Goal(ctx, this.#assetProof));
298
323
  // All borrowed materials, including the cloned skinned mannequin and arena, now exist.
324
+ shadeLikeSubstrate(ctx.scene);
299
325
  this.#materialLighting = ctx.entities.add(
300
326
  "material-lighting",
301
327
  createMaterialLighting(ctx.scene, ctx.camera, key, {
@@ -312,25 +338,6 @@ export class Play extends Scene<GameState, IPhysicsContext> {
312
338
  this.#environmentSample,
313
339
  );
314
340
  }
315
- const supportSurfaceY = (position: { readonly x: number; readonly z: number }):
316
- | number
317
- | undefined => {
318
- if (
319
- position.x >= FLOOR_BOUNDS.minX &&
320
- position.x <= FLOOR_BOUNDS.maxX &&
321
- position.z >= FLOOR_BOUNDS.minZ &&
322
- position.z <= FLOOR_BOUNDS.maxZ
323
- )
324
- return FLOOR_SURFACE_Y;
325
- if (
326
- position.x >= ISLAND.x - ISLAND.width / 2 &&
327
- position.x <= ISLAND.x + ISLAND.width / 2 &&
328
- position.z >= ISLAND.z - ISLAND.depth / 2 &&
329
- position.z <= ISLAND.z + ISLAND.depth / 2
330
- )
331
- return ISLAND.top;
332
- return undefined;
333
- };
334
341
  // The area says the character is over the island; the run is only won once it is also
335
342
  // standing on it. Ending on the overlap alone freezes the character in mid-air at the
336
343
  // lip of the island, half a metre short of a landing, which is what it looks like.
@@ -377,6 +384,7 @@ export class Play extends Scene<GameState, IPhysicsContext> {
377
384
  const frameState: Partial<GameState> = {};
378
385
  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: starter frame coordinates existing gameplay state transitions.
379
386
  return (frameCtx, dt) => {
387
+ recordMotionTick(dt);
380
388
  loading.update();
381
389
  // Restart resets the store before clearing entities and scheduled callbacks.
382
390
  if (frameCtx.input.justPressed("restart")) {
@@ -394,7 +402,7 @@ export class Play extends Scene<GameState, IPhysicsContext> {
394
402
  frameCtx.state.set((state) => ({ flagGusts: state.flagGusts + 1 }));
395
403
  }
396
404
  const touch = touchControls?.update(frameCtx.input.raw.pointers, frameCtx.viewport.size);
397
- player.update(frameCtx, dt, supportSurfaceY, touch);
405
+ player.update(frameCtx, dt, touch);
398
406
  let respawned = false;
399
407
  let lives = previous.lives;
400
408
  if (player.mesh.position.y < KILL_PLANE) {
@@ -453,6 +461,7 @@ export class Play extends Scene<GameState, IPhysicsContext> {
453
461
  }
454
462
 
455
463
  #post: ReturnType<typeof setupPost> | undefined;
464
+ #disposeLighting: (() => void) | undefined;
456
465
  #materialLighting: ReturnType<typeof createMaterialLighting> | undefined;
457
466
 
458
467
  override render(): void {
@@ -466,6 +475,9 @@ export class Play extends Scene<GameState, IPhysicsContext> {
466
475
  // Also releases the medium `setupPost` built, with the graph it composed into.
467
476
  this.#post?.dispose();
468
477
  this.#post = undefined;
478
+ // After the post graph, whose godrays stage reads the sun's shadow map.
479
+ this.#disposeLighting?.();
480
+ this.#disposeLighting = undefined;
469
481
  super.exit(ctx);
470
482
  }
471
483
  }