@threenative/core 0.3.12 → 0.3.13

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 (150) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +746 -32
  3. package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
  4. package/dist/{canvas-layer-CWuFRT7G.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
  5. package/dist/{chunk-7UUT3TY5.js → chunk-4SRAQFTU.js} +1 -1
  6. package/dist/{chunk-GMHATRPW.js → chunk-DIPIJICH.js} +1590 -375
  7. package/dist/{chunk-OKXUCASC.js → chunk-EEABDLUC.js} +3 -4
  8. package/dist/{chunk-5O73CDMR.js → chunk-EFWZWLPY.js} +62 -16
  9. package/dist/{chunk-N5LRP4BR.js → chunk-GYUZJQ7U.js} +63 -3
  10. package/dist/{chunk-VAZM36TV.js → chunk-H4J6IAJE.js} +17 -10
  11. package/dist/{chunk-2Z44XSI2.js → chunk-SV4QVUTQ.js} +3 -7
  12. package/dist/{chunk-DBELTTTM.js → chunk-U4YHUKKL.js} +1 -1
  13. package/dist/chunk-VP43GIWW.js +18 -0
  14. package/dist/{chunk-6KLNISRJ.js → chunk-XDTZ4QMO.js} +11 -4
  15. package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
  16. package/dist/{game-D7pAzZUY.d.ts → game-k8K3hZai.d.ts} +72 -8
  17. package/dist/hot.d.ts +5 -4
  18. package/dist/hot.js +5 -8
  19. package/dist/index.d.ts +289 -1034
  20. package/dist/index.js +3096 -1305
  21. package/dist/{model-lod-B6BMqS1r.d.ts → model-lod-DPTzeCcD.d.ts} +4 -2
  22. package/dist/playtest.d.ts +5 -4
  23. package/dist/playtest.js +6 -5
  24. package/dist/quality-BYqKGAwo.d.ts +868 -0
  25. package/dist/react.d.ts +3 -2
  26. package/dist/render-environment.d.ts +170 -0
  27. package/dist/render-environment.js +352 -0
  28. package/dist/{renderer-DvFVoAgj.d.ts → renderer-BtOSseYf.d.ts} +29 -31
  29. package/dist/spells/index.js +1 -1
  30. package/dist/ui-layer.js +3 -2
  31. package/dist/worker.js +12 -5
  32. package/dist/world.d.ts +269 -15
  33. package/dist/world.js +1372 -628
  34. package/mcp/animation-server.mjs +1 -1
  35. package/mcp/engine-server.mjs +105 -7
  36. package/mcp/servers.mjs +4 -4
  37. package/package.json +10 -6
  38. package/src/animation-batch.ts +193 -0
  39. package/src/animation-layers.ts +7 -3
  40. package/src/animation.ts +209 -29
  41. package/src/asset-cache.ts +3 -3
  42. package/src/asset-memo.ts +202 -0
  43. package/src/assets.ts +436 -131
  44. package/src/auto-batch.ts +190 -44
  45. package/src/compute-driven.ts +1 -1
  46. package/src/config.ts +8 -0
  47. package/src/debug.ts +103 -22
  48. package/src/dev-global.ts +54 -0
  49. package/src/engine-hooks.ts +37 -0
  50. package/src/frame-budget.ts +19 -3
  51. package/src/game-boot-phase.ts +269 -0
  52. package/src/game-dev-tools.ts +7 -14
  53. package/src/game-frame-loop.ts +45 -82
  54. package/src/game-startup.ts +145 -70
  55. package/src/game-ui.ts +84 -0
  56. package/src/game.ts +168 -552
  57. package/src/gamepad-mappings.ts +269 -0
  58. package/src/generated/console-markers.ts +13 -0
  59. package/src/geometry-capture.ts +28 -4
  60. package/src/gpu-readings.ts +98 -0
  61. package/src/gpu-scene-bvh.ts +149 -36
  62. package/src/hot.ts +4 -7
  63. package/src/index.ts +115 -8
  64. package/src/input.ts +237 -25
  65. package/src/instanced-batch-lod.ts +3 -8
  66. package/src/interpolation.ts +171 -40
  67. package/src/look/ao-admission.ts +4 -3
  68. package/src/look/auto-exposure.ts +5 -16
  69. package/src/look/default-tone-mapping.ts +41 -5
  70. package/src/look/local-exposure.ts +2 -7
  71. package/src/look/quad-pass.ts +21 -0
  72. package/src/look/quality.ts +4 -0
  73. package/src/look/unreal-bloom.ts +4 -13
  74. package/src/look/world-environment.ts +58 -115
  75. package/src/merge-parts.ts +20 -24
  76. package/src/model-lod.ts +97 -14
  77. package/src/particle-significance.ts +12 -0
  78. package/src/particles.ts +19 -10
  79. package/src/platform.ts +23 -4
  80. package/src/profiling/FrameStages.ts +5 -6
  81. package/src/profiling/Spans.ts +3 -17
  82. package/src/profiling/debug-telemetry.ts +2 -6
  83. package/src/profiling/render-list-validate.ts +6 -15
  84. package/src/projection-marker.ts +2 -1
  85. package/src/quiet-markers.ts +3 -10
  86. package/src/render/cpu-bvh.ts +100 -0
  87. package/src/render/depth-pyramid.ts +6 -14
  88. package/src/render/environment/environmentContribution.ts +202 -0
  89. package/src/render/environment/environmentRadiance.ts +44 -0
  90. package/src/render/environment/environmentSampleCache.ts +56 -0
  91. package/src/render/environment/environmentSampling.ts +201 -0
  92. package/src/render/environment/environmentSnapshot.ts +71 -0
  93. package/src/render/environment/gate.ts +57 -0
  94. package/src/render/mesh-pool.ts +3 -19
  95. package/src/render/probe-trace.ts +872 -0
  96. package/src/render/probe-volume.ts +780 -34
  97. package/src/render/radiance-cache.ts +17 -0
  98. package/src/render/virtual-shadow-partial.ts +13 -0
  99. package/src/render/virtual-shadow.ts +18 -16
  100. package/src/render/world-impostor-surface.ts +109 -6
  101. package/src/render/world-impostor.ts +5 -2
  102. package/src/render-camera-cull.ts +98 -3
  103. package/src/render-environment.ts +41 -0
  104. package/src/renderer-config.ts +36 -0
  105. package/src/renderer-facts.ts +37 -0
  106. package/src/renderer.ts +52 -28
  107. package/src/resolution-scaler.ts +3 -2
  108. package/src/scene-entry-inspectors.ts +61 -0
  109. package/src/snow-field.ts +1 -0
  110. package/src/startup-offscreen-bytes.ts +78 -0
  111. package/src/static-transform.ts +25 -19
  112. package/src/streamed-textures.ts +112 -0
  113. package/src/streaming.ts +68 -4
  114. package/src/texture-streaming.ts +331 -0
  115. package/src/version.ts +1 -1
  116. package/src/worker.ts +12 -2
  117. package/src/world-bundle-safety.ts +55 -10
  118. package/src/world-cell-batches.ts +162 -200
  119. package/src/world-cell-chunks.ts +3 -7
  120. package/src/world-cell-impostors.ts +20 -8
  121. package/src/world-cell-options.ts +2 -14
  122. package/src/world-cell-placements.ts +194 -90
  123. package/src/world-cell-prewarm.ts +39 -4
  124. package/src/world-cell-records.ts +401 -0
  125. package/src/world-cell-render-bundles.ts +2 -2
  126. package/src/world-cell-render-gpu-dress.ts +13 -17
  127. package/src/world-cell-render-main-cull.ts +73 -17
  128. package/src/world-cell-render-util.ts +17 -4
  129. package/src/world-cell-render.ts +13 -5
  130. package/src/world-cell-residency.ts +15 -6
  131. package/src/world-cell-stale.ts +238 -0
  132. package/src/world-cells.ts +22 -5
  133. package/src/world-gpu-flags.ts +18 -50
  134. package/src/world-gpu-reference.ts +22 -8
  135. package/src/world-gpu-scene.ts +44 -24
  136. package/src/world-gpu-shadow.ts +21 -8
  137. package/src/world-gpu-types.ts +41 -13
  138. package/src/world-load-limiter.ts +5 -0
  139. package/src/world-model-sections.ts +80 -0
  140. package/src/world-river-ribbon.ts +282 -0
  141. package/src/world-root-frame.ts +39 -0
  142. package/src/world-shore-field.ts +91 -0
  143. package/src/world-static-pose.ts +163 -0
  144. package/src/world-surface-sampler.ts +48 -0
  145. package/src/world-terrain-splat.ts +10 -18
  146. package/src/world-tile-budget.ts +4 -11
  147. package/src/world-tiles.ts +79 -12
  148. package/src/world-validate.ts +6 -14
  149. package/src/world-warm.ts +51 -0
  150. package/src/world.ts +13 -0
@@ -0,0 +1,868 @@
1
+ import { Box3, Material, DataTexture, Mesh, Object3D, Vector2, Camera, DirectionalLight, RenderTarget, Texture, Scene } from 'three';
2
+ import { pass } from 'three/tsl';
3
+ import { Node, TextureNode, NodeBuilder, NodeFrame } from 'three/webgpu';
4
+ import { R as RendererToneMapping } from './default-tone-mapping-GgKPTiBP.js';
5
+
6
+ interface IFilmicCurve {
7
+ readonly slope: number;
8
+ readonly toe: number;
9
+ readonly shoulder: number;
10
+ readonly blackClip: number;
11
+ readonly whiteClip: number;
12
+ readonly blueCorrection: number;
13
+ /**
14
+ * Unreal's "Expand Gamut" (1 in a fresh project, `Engine/Source/Runtime/Engine/Private/Scene.cpp:437`): bright,
15
+ * saturated colour is pushed toward a wider gamut before the blue correction and the curve. 0 turns it off.
16
+ * Unreal's linear EXR frames are taken after this step (`Engine/Shaders/Private/PostProcessCombineLUTs.usf`,
17
+ * the expansion runs before the output-device branches), so a curve applied to an Unreal EXR needs 0 here.
18
+ */
19
+ readonly expandGamut: number;
20
+ /**
21
+ * The ACES reference rendering's glow, which Unreal keeps in its filmic curve (`Engine/Shaders/Private/TonemapCommon.ush`):
22
+ * dark, saturated colour gets up to 5% brighter. 1 is Unreal's amount, 0 turns it off.
23
+ */
24
+ readonly glow: number;
25
+ /**
26
+ * The ACES reference rendering's red modifier, also in Unreal's filmic curve: the red of a saturated red is pulled
27
+ * toward a dark pivot, up to 18%. 1 is Unreal's amount, 0 turns it off.
28
+ */
29
+ readonly redModifier: number;
30
+ /**
31
+ * Output dither in 8-bit steps: triangular grain added to the display colour before the backbuffer rounds it.
32
+ * Unreal 5.8.3 uses one step for an 8-bit backbuffer, so a dim gradient reads as grain of one level instead of
33
+ * contour bands. 0 turns it off. Only the tone-mapping node dithers; `filmicToneMap()` stays noise-free.
34
+ */
35
+ readonly dither: number;
36
+ /**
37
+ * The largest scene-linear value, after exposure, that one channel can hold when the colour goes into Unreal's
38
+ * colour LUT (the top of its 14-stop log shaper, `Engine/Shaders/Private/GammaCorrectionCommon.ush`: `LogToLin(1)`
39
+ * minus `LogToLin(0)`). A channel above it is clipped there, so the sun disc and a hot emitter lose their hue
40
+ * earlier than an unbounded curve would. `LUT_CLIP` is the default, as in Unreal; 0 is the named override that leaves
41
+ * the channel unbounded.
42
+ */
43
+ readonly lutClip: number;
44
+ }
45
+ /** Red, green, blue and a master factor, as Unreal's colour grading panel shows each control. */
46
+ type Vec4 = readonly [number, number, number, number];
47
+ /** One set of Unreal's colour grading controls. */
48
+ interface IGradeControls {
49
+ readonly saturation: Vec4;
50
+ readonly contrast: Vec4;
51
+ readonly gamma: Vec4;
52
+ readonly gain: Vec4;
53
+ readonly offset: Vec4;
54
+ }
55
+ /**
56
+ * Unreal's colour grading and white balance, run in the combined LUT before the film curve
57
+ * (`Engine/Shaders/Private/PostProcessCombineLUTs.usf:88-140` and `:369-403`; defaults in
58
+ * `Engine/Source/Runtime/Engine/Private/Scene.cpp:405-433`). Every default below is Unreal's, and at the
59
+ * defaults none of it costs a shader instruction.
60
+ */
61
+ interface IColorGrade {
62
+ /** Kelvin, 1500 to 15000. 6500 with tint 0 is a no-op. */
63
+ readonly whiteTemp: number;
64
+ /** -1 to 1 along the isotherm. */
65
+ readonly whiteTint: number;
66
+ /**
67
+ * `"whiteBalance"`: the temperature is the light the scene was lit by, and it turns neutral.
68
+ * `"colorTemperature"`: neutral turns into that temperature.
69
+ */
70
+ readonly temperatureMode: "whiteBalance" | "colorTemperature";
71
+ /** 1 is the full film curve, 0 the graded colour with no curve. */
72
+ readonly toneCurveAmount: number;
73
+ /** Applied to every pixel, and combined with each range below. */
74
+ readonly global: IGradeControls;
75
+ readonly shadows: IGradeControls;
76
+ readonly midtones: IGradeControls;
77
+ readonly highlights: IGradeControls;
78
+ /** Luma (AP1) up to which the shadows range has full weight, fading out by here. */
79
+ readonly shadowsMax: number;
80
+ /** Luma where the highlights range starts and where it has full weight. */
81
+ readonly highlightsMin: number;
82
+ readonly highlightsMax: number;
83
+ }
84
+ type RangeName = "global" | "shadows" | "midtones" | "highlights";
85
+ /** What a game passes: any field, and any control of a range. */
86
+ type ColorGradeOptions = {
87
+ readonly [K in keyof IColorGrade]?: K extends RangeName ? Partial<IGradeControls> : IColorGrade[K];
88
+ };
89
+ /**
90
+ * Registers the curve with a WebGPU renderer and returns the tone-mapping constant to assign.
91
+ * A renderer without a node library (the WebGL fallback) keeps ACES and says so.
92
+ */
93
+ declare function installFilmicToneMapping(raw: unknown, c?: IFilmicCurve, grade?: IColorGrade): number | undefined;
94
+
95
+ interface ITraceSceneReport {
96
+ readonly triangles: number;
97
+ readonly nodes: number;
98
+ readonly materials: number;
99
+ /** Meshes left out because their triangles move (instanced, skinned, batched, morphing). */
100
+ readonly skippedMoving: number;
101
+ readonly milliseconds: number;
102
+ }
103
+ interface ITraceScene {
104
+ readonly report: ITraceSceneReport;
105
+ readonly bounds: Box3;
106
+ /** The material of every id, for what the table cannot hold (a map, a node). */
107
+ readonly materials: readonly Material[];
108
+ readonly nodes: DataTexture;
109
+ readonly triangles: DataTexture;
110
+ readonly materialTable: DataTexture;
111
+ readonly nodeData: Float32Array;
112
+ readonly triangleData: Float32Array;
113
+ readonly materialData: Float32Array;
114
+ dispose(): void;
115
+ }
116
+
117
+ interface ITracedReflectionsOptions {
118
+ /** Which meshes a ray can hit. Default: every mesh under a visible parent chain. */
119
+ readonly include?: (mesh: Mesh) => boolean;
120
+ /** Surfaces rougher than this take no traced reflection. Unreal's `LumenMaxRoughnessToTrace`: 0.4. */
121
+ readonly maxRoughnessToTrace?: number;
122
+ /** The weight falls from 1 to 0 over this much roughness, ending at `maxRoughnessToTrace`: 0.1. */
123
+ readonly roughnessFadeLength?: number;
124
+ /**
125
+ * Surfaces rougher than this take the diffuse GI for specular, not the radiance cache. Unreal's
126
+ * `MaxRoughnessToEvaluateRoughSpecular`: 0.8.
127
+ */
128
+ readonly maxRoughnessToEvaluateRoughSpecular?: number;
129
+ /** The share of diffuse GI rises from 0 to 1 over this much roughness, ending at the limit above: 0.2. */
130
+ readonly roughSpecularFadeLength?: number;
131
+ /**
132
+ * Most nodes one ray visits before it stops walking with the nearest surface found so far, which may be the
133
+ * wrong one. A walk visits each node at most once, so the default, the tree's node count up to 2048, never
134
+ * cuts a ray short in a scene of up to 2048 nodes.
135
+ */
136
+ readonly maxSteps?: number;
137
+ /** False silences the TN_TRACED_REFLECTIONS line, not the report. */
138
+ readonly marker?: boolean;
139
+ }
140
+ /**
141
+ * Where a surface's specular comes from, as shares that add to 1: the traced ray, the radiance cache read along the
142
+ * reflected direction (a rough lobe), or the diffuse GI (a surface too rough for a lobe).
143
+ */
144
+ interface IReflectionRoute<T> {
145
+ readonly traced: T;
146
+ readonly roughSpecular: T;
147
+ readonly diffuse: T;
148
+ }
149
+ /** One ray's answer, as nodes. Every field is meaningful only where `hit` is 1. */
150
+ interface ITracedHit {
151
+ /** 1 where the ray found a surface, else 0. */
152
+ readonly hit: Node<"float">;
153
+ /** Metres along the (unit) ray, or -1 on a miss. */
154
+ readonly distance: Node<"float">;
155
+ readonly position: Node<"vec3">;
156
+ /** The interpolated vertex normal, flipped to face the ray. */
157
+ readonly normal: Node<"vec3">;
158
+ /** The hit triangle's index in the pack's leaf order. */
159
+ readonly triangle: Node<"float">;
160
+ /** The hit material's colour, roughness, emissive (times intensity) and metalness, from the pack's table. */
161
+ readonly albedo: Node<"vec3">;
162
+ readonly roughness: Node<"float">;
163
+ readonly emissive: Node<"vec3">;
164
+ readonly metalness: Node<"float">;
165
+ /** The index into `TracedReflections.scene.materials`: a game that needs a map or a node looks the material up. */
166
+ readonly material: Node<"float">;
167
+ }
168
+ interface ITracedRay {
169
+ readonly origin: Node<"vec3">;
170
+ /** Unit length. */
171
+ readonly direction: Node<"vec3">;
172
+ /** Closest hit allowed, in metres. Default 0.001. */
173
+ readonly near?: Node<"float"> | number;
174
+ /** Farthest hit allowed, in metres. Default 1e4. */
175
+ readonly far?: Node<"float"> | number;
176
+ /**
177
+ * Stop at the first surface found, which need not be the nearest: the answer for a shadow ray, which only asks
178
+ * whether anything is in the way. `distance`, `position` and the material then describe that surface.
179
+ */
180
+ readonly anyHit?: boolean;
181
+ }
182
+ /**
183
+ * Ray queries against the scene's triangles for reflections, in the engine's own TSL: the pack is float
184
+ * textures and the walk is a loop, so the kernel needs no storage buffer and no WGSL of its own.
185
+ *
186
+ * Unreal's Lumen reflections trace what the screen cannot see through a software scene (mesh SDFs, or hardware
187
+ * rays) for surfaces smoother than a roughness cut-off, and fall back to a cached radiance below it. This is
188
+ * the scene half of that: `trace()` answers "what does this ray hit" and the material at the hit. How the hit
189
+ * is lit, what a miss sees and how the result joins the frame stay in the game's `src/render/` code.
190
+ */
191
+ declare class TracedReflections {
192
+ #private;
193
+ /** The packed triangles; `scene.materials[hit.material]` is the three material of a hit. */
194
+ readonly scene: ITraceScene;
195
+ readonly maxRoughnessToTrace: number;
196
+ readonly roughnessFadeLength: number;
197
+ readonly maxRoughnessToEvaluateRoughSpecular: number;
198
+ readonly roughSpecularFadeLength: number;
199
+ readonly maxSteps: number;
200
+ constructor(root: Object3D, options?: ITracedReflectionsOptions);
201
+ get report(): ITraceSceneReport & {
202
+ readonly bytes: number;
203
+ };
204
+ /**
205
+ * 1 for a surface at least as smooth as the cut-off minus the fade, falling to 0 at `maxRoughnessToTrace`.
206
+ * Multiply a traced reflection by it so a rough surface never shows a trace's noise.
207
+ */
208
+ weight(roughness: Node<"float">): Node<"float">;
209
+ /** `weight` for one roughness on the CPU: a surface rougher than `maxRoughnessToTrace` casts no ray. */
210
+ weightAt(roughness: number): number;
211
+ /**
212
+ * Where a surface's specular comes from (Unreal: `LumenCombineReflectionsAlpha` picks the ray, and
213
+ * `RoughReflectionsDiffuseLerp` in `LumenReflectionsCombine.ush` fades the rest from the gather's rough specular to
214
+ * the diffuse GI). The ray's share is `weight`; of the rest, the diffuse share rises from 0 at the limit minus the
215
+ * fade to 1 at the limit, and the radiance cache answers for what is left.
216
+ */
217
+ route(roughness: Node<"float">): IReflectionRoute<Node<"float">>;
218
+ /** `route` for one roughness on the CPU. */
219
+ routeAt(roughness: number): IReflectionRoute<number>;
220
+ /**
221
+ * The nearest surface along a ray, with its normal and material. The walk is the depth-first, skip-pointer one
222
+ * `traceScene` runs on the CPU: a node's box is tested, a miss jumps to the node after the subtree, a hit on an
223
+ * inner node steps to its left child, a leaf tests its triangles in a loop.
224
+ */
225
+ trace(ray: ITracedRay): ITracedHit;
226
+ dispose(): void;
227
+ }
228
+
229
+ /**
230
+ * What a visualize mode shows. `off` is the finished frame; `indirectDiffuse` is the bounce light alone, the
231
+ * counterpart of Unreal's `r.Lumen.Visualize.IndirectDiffuse`. Other GI work adds its modes here when its data exists.
232
+ */
233
+ declare const GI_VISUALIZE_MODES: readonly ["off", "indirectDiffuse"];
234
+ type GIVisualizeMode = (typeof GI_VISUALIZE_MODES)[number];
235
+ interface IGIVisualizeOptions {
236
+ readonly mode: GIVisualizeMode;
237
+ /** The finished frame, returned unchanged in `off` mode. */
238
+ readonly beauty: Node<"vec4">;
239
+ /**
240
+ * The indirect diffuse light as the surface returns it: the gathered and cached light times the surface's own
241
+ * albedo, in the frame's exposure. The game's chain builds it, because it owns what the chain gathers.
242
+ */
243
+ readonly indirectDiffuse?: Node<"vec3">;
244
+ }
245
+ /**
246
+ * Shows one lighting term of a frame by itself, so a lighting difference against a reference can be told apart from a
247
+ * scene difference. The game builds each term in its own chain and picks the mode; this class only selects, and it
248
+ * fails when the chain did not build the term the mode needs, so a frame never claims to show a term it does not hold.
249
+ */
250
+ declare class GIVisualize {
251
+ readonly mode: GIVisualizeMode;
252
+ /** The node to output: `beauty` for `off`, the chosen term with an opaque alpha otherwise. */
253
+ readonly node: Node<"vec4">;
254
+ constructor(options: IGIVisualizeOptions);
255
+ }
256
+
257
+ interface IExposureSettings {
258
+ enabled: boolean;
259
+ /** Middle-grey target; increase to brighten the metered subject. */
260
+ key: number;
261
+ /** Exposure limits in stops. Expand only if the scene needs more range. */
262
+ minStops: number;
263
+ maxStops: number;
264
+ /**
265
+ * Percent of metered weight, dark to bright, ignored at each end of the histogram.
266
+ * Raise highPercent's gap (lower it) when a large bright backdrop still sets the exposure.
267
+ */
268
+ lowPercent: number;
269
+ highPercent: number;
270
+ /** Exponential response per second in log2 space. Up opens the eye; down squints. */
271
+ rateUp: number;
272
+ rateDown: number;
273
+ /** Stop error where cut acceleration begins / reaches its authored maximum. */
274
+ snapLo: number;
275
+ snapHi: number;
276
+ snapGain: number;
277
+ /**
278
+ * Seed for reset(value). The first frame and reset() without a value adopt the measured target.
279
+ */
280
+ initialExposure: number;
281
+ settleStops: number;
282
+ /**
283
+ * Limit catch-up after a suspended frame, avoiding an unrequested cut. A frame the renderer's
284
+ * gate declined is not a suspension: the drawn frame already spans that time, so it is spent.
285
+ */
286
+ maxDelta: number;
287
+ /** Readback/marker cadence in seconds. Metering still runs on every drawn frame. */
288
+ reportInterval: number;
289
+ }
290
+ declare const exposureSettings: Readonly<IExposureSettings>;
291
+
292
+ type ColourTexture = TextureNode;
293
+ type Meter = (colour: Node<"vec4">, uv: Node<"vec2">) => Node<"vec2">;
294
+ type Decode = (mean: Node<"float">) => Node<"float">;
295
+
296
+ /** Owns scratch targets only. Never draws the world or installs another output transform. */
297
+ declare class AutoExposureNode extends Node<"float"> {
298
+ #private;
299
+ static get type(): string;
300
+ readonly input: ColourTexture;
301
+ readonly settings: Readonly<IExposureSettings>;
302
+ constructor(input: ColourTexture, settings: IExposureSettings, constantExposure: number, meter?: Meter, decode?: Decode);
303
+ setup(builder: NodeBuilder): Node<"float">;
304
+ get exposureNode(): Node<"float">;
305
+ reset(exposure?: number): void;
306
+ setEnabled(enabled: boolean): void;
307
+ /**
308
+ * Exposure compensation in stops over the metered key, live: Unreal's AutoExposureBias
309
+ * (UE 5.8.3: Engine/Source/Runtime/Engine/Classes/Engine/Scene.h:1933), which post-process
310
+ * volumes blend at run time. Unreal applies 2^bias outside the smoothing
311
+ * (Engine/Shaders/Private/PostProcessEyeAdaptation.usf:179); here it moves the goal, so a change
312
+ * adapts at `rateUp`/`rateDown` and the reported exposure includes it.
313
+ */
314
+ setExposureBias(stops: number): void;
315
+ getObservation(): Record<string, unknown>;
316
+ updateBefore(frame: NodeFrame): undefined;
317
+ dispose(): void;
318
+ }
319
+
320
+ /** Godot's `Viewport.screen_space_aa`: which post-process antialiasing smooths the frame's edges. */
321
+ type ScreenSpaceAA = "smaa" | "fxaa" | "disabled";
322
+ /**
323
+ * Godot's `Environment.tonemap_mode`: the modes Three.js ships, plus `filmic`, the Unreal 5
324
+ * default curve written in `tonemap.ts`. The list itself is `RendererToneMapping`'s, one owner
325
+ * beside `applyRendererToneMapping`, so a mode this accepts is a mode the renderer can install.
326
+ */
327
+ type TonemapMode = RendererToneMapping;
328
+ /**
329
+ * SSGI sample budget. The three tiers are the presets SSGINode's own documentation
330
+ * recommends for the temporally-filtered case, not numbers invented here. An unknown
331
+ * tier throws rather than quietly becoming the default.
332
+ */
333
+ type SsgiQuality = "low" | "medium" | "high" | "epic";
334
+ interface IWorldEnvironmentOptions {
335
+ /** World-pass MSAA samples. Omit to inherit the renderer; 0 leaves post AA in charge. */
336
+ readonly samples?: number;
337
+ /**
338
+ * How bounce light reaches a pixel, Unreal's `r.Lumen.FinalGatherMethod` by the quality tier's name
339
+ * (`giPreset`). The screen-space gather runs only for `screenProbeGather`; the world cache is
340
+ * installed by the scene (`giCache.ts`) for `irradianceField` and `screenProbeGather`. Omit it and
341
+ * the harness layer decides.
342
+ */
343
+ readonly finalGatherMethod?: "none" | "irradianceField" | "screenProbeGather";
344
+ /** Screen-space indirect diffuse light. Godot calls this `ssil_enabled`. */
345
+ readonly ssgiEnabled?: boolean;
346
+ readonly ssgiQuality?: SsgiQuality;
347
+ /** How much of the gathered indirect light reaches the frame. Godot's `ssil_intensity`. */
348
+ readonly ssgiIntensity?: number;
349
+ /** How far, in world units, indirect light is gathered from. Room scale, not contact scale. */
350
+ readonly ssgiRadius?: number;
351
+ /** Screen-space reflections. Godot's `ssr_enabled`. */
352
+ readonly ssrEnabled?: boolean;
353
+ /**
354
+ * How far, in world units, a reflection ray is traced.
355
+ *
356
+ * `SSRNode` defaults this to **1**, which is one metre. On any scene larger than a
357
+ * tabletop that reads as "screen-space reflections are on and do nothing" — the ray
358
+ * terminates before it reaches the thing that should be standing in the floor.
359
+ */
360
+ readonly ssrMaxDistance?: number;
361
+ /**
362
+ * Fraction of the display resolution the reflection is traced at.
363
+ *
364
+ * A reflection in a rough surface carries almost no high-frequency detail, so tracing it
365
+ * at half resolution costs a quarter of the rays and is very hard to see in the result.
366
+ */
367
+ readonly ssrResolutionScale?: number;
368
+ /**
369
+ * The most steps one reflection ray marches. Defaults to Unreal's count for the render chain
370
+ * tier (`RENDER_CHAIN_TIERS`: 32 on high, 16 on medium, 8 on low). Fewer steps cost less and
371
+ * step over thin objects sooner.
372
+ */
373
+ readonly ssrMaxSteps?: number;
374
+ /** Spatial denoise over the SSGI result. Off is noisier and cheaper. */
375
+ readonly denoiseEnabled?: boolean;
376
+ /** The SSGI denoise's reach in gather pixels; omit for DenoiseNode's 5. A half-resolution gather wants more. */
377
+ readonly ssgiDenoiseRadius?: number;
378
+ /**
379
+ * Gather the SSGI with screen probes (one per 16 x 16 pixels, an 8 x 8 octahedron of rays each) instead of per-pixel
380
+ * rays: Unreal's ScreenProbeGather at its Epic settings (PRD-640). Owned engine only; elsewhere the per-pixel gather runs.
381
+ */
382
+ readonly ssgiScreenProbes?: boolean;
383
+ /** Shows one lighting term alone (`GIVisualize`); `off` draws the finished frame. Needs the gather (`ssgiEnabled`). */
384
+ readonly giVisualize?: GIVisualizeMode;
385
+ /** Screen probes only: 0 keeps every probe's rays on the same octahedron, 1 (default) offsets them per probe. */
386
+ readonly ssgiProbeJitter?: number;
387
+ /** Screen probes only: rays on a side of each probe's octahedron. Omit for 8 (Unreal's real-time Epic; its cinematic setting is 16). */
388
+ readonly ssgiProbeRays?: number;
389
+ /** Screen probes only, diagnosis: 1 draws the probes' weight and trust, 2 the sign of the gathered delta. */
390
+ readonly ssgiProbeDebug?: number;
391
+ /**
392
+ * Diagnosis, owned engine only: label one pass group as the `SSGI` GPU stage and leave the others in the frame, so
393
+ * `info.engine.gpuStages.SSGI` times that group alone (`trace`, `filter`, `gather` of the screen probes, or the chain's
394
+ * `denoise`). Omit to time every GI pass.
395
+ */
396
+ readonly ssgiTimedPass?: "trace" | "filter" | "gather" | "denoise";
397
+ /**
398
+ * Denoise passes over the SSGI gather, each turning the tap pattern by its index. The default is the render chain
399
+ * tier's `denoiseIterations` (high 3, medium 2, low 1): one pass left the sunlit room's walls grainy at `high`.
400
+ */
401
+ readonly giDenoisePasses?: number;
402
+ /** Raymarched shafts. Needs `godraysLight`, and that light must cast shadows. */
403
+ readonly godraysEnabled?: boolean;
404
+ /** How dense the participating medium is. Higher is foggier — and the whole frame brighter. */
405
+ readonly godraysDensity?: number;
406
+ /**
407
+ * Haze below this value is discarded instead of added to the frame.
408
+ *
409
+ * Without it the pass is a uniform brightener rather than a shaft renderer: it returns a
410
+ * non-zero value for nearly every pixel, and that "something" is tiny in linear space and
411
+ * enormous after the tone curve, which lifts shadows hardest. Subtracting a floor keeps
412
+ * the air inside a real beam and discards the ambient lift.
413
+ */
414
+ readonly godraysFloor?: number;
415
+ /** Multiplier applied after the floor, so beams can be bright without the haze returning. */
416
+ readonly godraysIntensity?: number;
417
+ /**
418
+ * Raymarch steps per pixel. `GodraysNode` defaults to 60.
419
+ *
420
+ * Every step is a shadow-map sample, so this multiplies directly into the cost of the
421
+ * whole pass. The pass jitters its sample positions, so a lower count trades a hard shaft
422
+ * edge for a slightly noisier one rather than for banding — which the denoiser then
423
+ * largely absorbs.
424
+ */
425
+ readonly godraysSteps?: number;
426
+ /**
427
+ * Ceiling on shaft brightness.
428
+ *
429
+ * This is also the single strongest control over how bright the *whole* scene looks: the
430
+ * pass adds its accumulated illumination to every pixel, not only to the pixels inside a
431
+ * visible beam, so raising it raises the shadow floor of the entire frame.
432
+ */
433
+ readonly godraysMaxDensity?: number;
434
+ /**
435
+ * Ground-truth ambient occlusion, at contact scale. Godot's `ssao_enabled`.
436
+ *
437
+ * Deliberately a *second* occlusion term next to the one SSGI already produces. SSGI's AO
438
+ * is gathered over `ssgiRadius` — metres — the right scale for "this hall is enclosed"
439
+ * and the wrong one for "this foot is standing on this floor". This pass runs at a radius
440
+ * of centimetres and multiplies on top.
441
+ */
442
+ readonly gtaoEnabled?: boolean;
443
+ /**
444
+ * Occlusion gather radius in world units, a named override. Left out, the radius follows Unreal's rule
445
+ * instead: a fixed reach on the screen (`gtaoReachPx`), so a contact is as wide at any distance.
446
+ */
447
+ readonly gtaoRadius?: number;
448
+ /** Screen reach of the occlusion in pixels at the display height when `gtaoRadius` is not set. Unreal's is 32. */
449
+ readonly gtaoReachPx?: number;
450
+ /** Exponent on the occlusion term: higher is a darker, tighter contact. */
451
+ readonly gtaoScale?: number;
452
+ /** Directions sampled per pixel. Cost is linear in this. */
453
+ readonly gtaoSamples?: number;
454
+ /** Spacing of the samples along a direction: 1 is even, 2 packs them near the pixel, as Unreal's horizon search does. */
455
+ readonly gtaoDistanceExponent?: number;
456
+ /** 0 weighs every sample alike, 1 (the node's default) weighs far samples less. */
457
+ readonly gtaoDistanceFalloff?: number;
458
+ /** Depth difference in world units beyond which a sample is no occluder. */
459
+ readonly gtaoThickness?: number;
460
+ /** The occlusion denoise's reach in pixels (DenoiseNode's 5 when omitted); 0 leaves the occlusion raw. */
461
+ readonly gtaoDenoiseRadius?: number;
462
+ /**
463
+ * The albedo cap of the occlusion's multi-bounce: pale surfaces keep more of the light a crease blocks. Unreal's is
464
+ * 0.5 (`MaxMultibounceAlbedo`); 0 leaves the occlusion as GTAO computed it. Applies where the cache holds the
465
+ * indirect light.
466
+ */
467
+ readonly gtaoMultiBounceAlbedo?: number;
468
+ /**
469
+ * Where the cache holds the indirect light, only that share takes the occlusion (Unreal's AO darkens indirect light
470
+ * only). `false` is the named override: the whole frame takes the occlusion, as an engine without a cache does.
471
+ */
472
+ readonly gtaoIndirectOnly?: boolean;
473
+ /** Fraction of display resolution the occlusion is traced at. */
474
+ readonly gtaoResolutionScale?: number;
475
+ /**
476
+ * The fraction of the frame SSGI actually gathers at. Half by default.
477
+ *
478
+ * `GTAONode` and `SSRNode` both carry a `resolutionScale` of their own; **`SSGINode` does not**,
479
+ * and its `setSize` passes width and height straight into its render target with no factor. So
480
+ * screen-space GI — a low-frequency effect every production renderer gathers at half or quarter
481
+ * res — was the only stage in this chain running at full resolution, and it cost accordingly.
482
+ *
483
+ * Measured on a 46,190-instance forest at 1600x900 on an RTX 2080, with the resolution scaler
484
+ * left on auto so the engine's own verdict is part of the result:
485
+ *
486
+ * fps still/walk scale it settled on interior median dead shadow
487
+ * full res 38.0 / 47.2 0.44 704x396 0.0299 19.19%
488
+ * off 60.0 / 60.0 0.61 976x549 0.0987 4.54%
489
+ * half res 59.8 / 60.0 0.72 1152x648 0.0301 18.58%
490
+ *
491
+ * Half res is better than both: it holds the budget like switching SSGI off, keeps the look
492
+ * within noise of full res, and produces the *sharpest* frame of the three — because the budget
493
+ * it hands back is spent by the scaler on pixels rather than on a gather nobody can see at full
494
+ * rate. Full-res SSGI was not buying quality, it was trading it.
495
+ *
496
+ * Fixed without touching three: `setSize` is public and the pass drives the node through it with
497
+ * the full frame size, so the instance is wrapped to hand it a smaller one. The node's own maths
498
+ * reads the `_resolution` uniform that `setSize` writes, so it stays self-consistent, and the
499
+ * result is sampled by UV rather than by texel — which is what makes the upsample free and is
500
+ * exactly the mechanism `GTAONode` uses internally.
501
+ */
502
+ readonly ssgiResolutionScale?: number;
503
+ /**
504
+ * Contrast-adaptive sharpening (RCAS) over the finished frame.
505
+ *
506
+ * Everything upstream of it blurs: the GI gather is denoised, the reflection is traced at
507
+ * reduced resolution and roughness-blurred. Each is worth its softness on its own and the
508
+ * sum is a frame with no micro-detail left. RCAS is contrast-adaptive, so it puts the
509
+ * edges back without ringing the soft areas.
510
+ */
511
+ readonly sharpenEnabled?: boolean;
512
+ /** RCAS sharpness. **0 is maximum sharpening and 2 is none** — it is a radius, not a gain. */
513
+ readonly sharpenStrength?: number;
514
+ /** Unreal's VignetteIntensity (Scene.cpp default 0.4), the cosine-fourth law. Zero disables it. */
515
+ readonly vignetteAmount?: number;
516
+ /** Unreal's default motion blur on the velocity the render chain provisions (harness overlay). */
517
+ readonly motionBlurEnabled?: boolean;
518
+ /**
519
+ * Post-process antialiasing, run last. Godot's `Viewport.screen_space_aa`. Default `"smaa"`.
520
+ *
521
+ * Not optional in practice: the chain renders `pass(scene, camera)` single-sampled, so the moment
522
+ * any stage runs, the renderer's own multisampling no longer reaches the frame and every edge
523
+ * stairsteps — the single loudest "this is a prototype" signal in a frame. It is requested only
524
+ * when some other stage (or a `baseColour`) installs a chain; with nothing installed the renderer
525
+ * draws straight to the canvas with its own MSAA and this would be paying twice.
526
+ */
527
+ readonly screenSpaceAA?: ScreenSpaceAA;
528
+ /**
529
+ * Temporal antialiasing, Unreal's default method (`r.AntiAliasingMethod` 4, temporal super resolution). Default `false`
530
+ * here, and `true` in the `high` and `medium` tiers of `quality.ts`.
531
+ *
532
+ * The engine jitters the camera by a sub-pixel offset every frame, draws each pixel's motion, and blends the frames
533
+ * before it into this one. The `traa` stage resolves the finished frame, after the screen-space stages (occlusion,
534
+ * global illumination, reflections) and ahead of blur, bloom and the grade, so their edges are smoothed with the rest.
535
+ * It replaces `screenSpaceAA` while it runs: Unreal runs one method too. It runs on the owned engine only. On
536
+ * `engine: "threejs"` and on a fallback renderer this option is refused with a reason in the applied report and
537
+ * `screenSpaceAA` stays in charge. Read `debug().temporal` for the live frame, history and jitter.
538
+ */
539
+ readonly temporalAA?: boolean;
540
+ /** Godot's `glow_enabled`. */
541
+ readonly bloomEnabled?: boolean;
542
+ readonly bloomStrength?: number;
543
+ /** How far a bright pixel bleeds, as a fraction of the screen. */
544
+ readonly bloomRadius?: number;
545
+ /** Luminance a pixel must exceed before it blooms at all. */
546
+ readonly bloomThreshold?: number;
547
+ /**
548
+ * Which of this kit's authored stages to run.
549
+ *
550
+ * Separate from the graph below, and not for tidiness: the chain has to know whether anything
551
+ * was requested at all before the scene pass exists — with nothing requested it sets an
552
+ * exposure and returns, and no pass is ever built. So the request is a static decision the kit
553
+ * makes from its own config, and only the graph needs the pass.
554
+ */
555
+ readonly authoredStageNames?: readonly string[];
556
+ /**
557
+ * This kit's own stages, composed after the built-ins.
558
+ *
559
+ * A factory because an authored stage needs the two things only this file can produce: the
560
+ * scene pass's depth texture node, which does not exist until the pass is built, and the
561
+ * resolved tier. It returns the complete graph — including stages left dormant this frame — so
562
+ * that an anchor like `watercolor after kuwahara` keeps naming a stage that exists.
563
+ *
564
+ * Naming specific stages here instead — an `outlineEnabled`, a `kuwaharaRadius` — is what put
565
+ * one kit's look inside the plumbing every kit copies verbatim, which
566
+ * `shared-render-sources.spec.ts` exists to refuse.
567
+ */
568
+ readonly authoredStages?: (context: IWorldEnvironmentStageContext) => readonly ChainStage[];
569
+ /** Quality tier passed to the measured chain; the quality module owns this value. */
570
+ readonly renderChainTier?: ChainTier;
571
+ readonly tonemapMode?: TonemapMode;
572
+ /**
573
+ * The numbers of the `"filmic"` curve, any field of `IFilmicCurve` (slope, toe, shoulder, black clip, white
574
+ * clip, blue correction, expand gamut, glow, red modifier, dither, lutClip). Unreal 5.8.3's project defaults
575
+ * apply to every field left out. Only `tonemapMode: "filmic"` reads it; any other mode with this set throws.
576
+ */
577
+ readonly filmicCurve?: Partial<IFilmicCurve>;
578
+ /**
579
+ * Unreal's colour grade and white balance for `"filmic"`: saturation, contrast, gamma, gain and offset
580
+ * (`[red, green, blue, master]`) for the whole frame and for `shadows`, `midtones` and `highlights`, the
581
+ * luma limits, `whiteTemp` and `whiteTint` in Kelvin and -1 to 1, and `toneCurveAmount`. Left out, the grade
582
+ * is neutral and costs no shader instruction. Only `tonemapMode: "filmic"` reads it.
583
+ */
584
+ readonly colorGrade?: ColorGradeOptions;
585
+ /**
586
+ * Scene-referred exposure: multiplied into the scene pass **before** the tone curve, so
587
+ * the GI gather, reflections and bloom threshold all see the exposed image and the bloom
588
+ * threshold means the same thing at any exposure.
589
+ *
590
+ * `renderer.toneMappingExposure` is live too (measured on three@0.185.1 — see
591
+ * `docs/verification/exposure-ab-2026-08-30.md`), and applies at the same point in the
592
+ * graph, but only when no output node is installed. When every stage here is off, this
593
+ * class falls back to that scalar; when any stage runs, this multiply is the shutter.
594
+ */
595
+ readonly exposure?: number;
596
+ /** Cost opt-in. False retains the direct constant-exposure path. */
597
+ readonly autoExposureEnabled?: boolean;
598
+ /** Unreal's bilateral local exposure on top of the automatic exposure (harness overlay). */
599
+ readonly localExposureEnabled?: boolean;
600
+ /** Unreal's standard bloom in place of the stock bloom stage (harness overlay). */
601
+ readonly unrealBloomEnabled?: boolean;
602
+ /** Editable game policy; disabled application still measures when cost is opted in. */
603
+ readonly exposurePolicy?: Readonly<IExposureSettings>;
604
+ }
605
+ interface IWorldEnvironmentTarget {
606
+ /** The directional light godrays are raymarched against. Required only by `godraysEnabled`. */
607
+ readonly godraysLight?: DirectionalLight;
608
+ /**
609
+ * Composes the colour the chain starts from, given the scene pass it renders.
610
+ *
611
+ * The chain builds `pass(scene, camera)` itself, so a game that composes something onto the
612
+ * beauty pass before any stage runs — aerial perspective, read against that pass's own view-Z,
613
+ * is the one in these templates — has nowhere else to put it. The node returned here is the
614
+ * game's; the chain only decides where it is spliced in, which is first, ahead of exposure and
615
+ * every stage.
616
+ */
617
+ readonly baseColour?: (scenePass: ReturnType<typeof pass>) => Node<"vec4">;
618
+ /**
619
+ * The scene's static triangles, for the `ssr` stage: a smooth surface (roughness under the trace's
620
+ * `maxRoughnessToTrace`) then reflects what its ray hits in the scene, as Unreal's Lumen reflections do,
621
+ * not only what the screen drew. Build it after the static scene exists; omit it and the stage marches the screen.
622
+ * @alias Lumen reflections, hit lighting, reflection rays
623
+ */
624
+ readonly reflectionTrace?: TracedReflections;
625
+ }
626
+ type ResolutionSubrectView = {
627
+ readonly viewFraction: Vector2;
628
+ readonly halfTexel: Vector2;
629
+ };
630
+ /**
631
+ * The scene pass's depth texture, as the pass itself types it.
632
+ *
633
+ * Named through `pass()` rather than written out because the addon's return type is the only
634
+ * honest spelling of it, and a hand-written alias here would drift the first time three changes it.
635
+ */
636
+ type DepthTextureNode = ReturnType<ReturnType<typeof pass>["getTextureNode"]>;
637
+ type ChainTier = "high" | "medium" | "low" | "off";
638
+ type ChainContext = {
639
+ readonly tier: ChainTier;
640
+ readonly resolutionSubrect?: ResolutionSubrectView;
641
+ /**
642
+ * The sampled velocity texture, present only when this chain request provisioned one.
643
+ *
644
+ * Distinct from the accessor TRAANode wants: the chain passes the texture here and installs the
645
+ * accessor on the graph separately, so a stage that handed this node over as the accessor would
646
+ * sample a texture that no fragment stage writes.
647
+ */
648
+ readonly velocityNode?: Node;
649
+ };
650
+ /**
651
+ * What a kit's `authoredStages` factory is handed. The depth node is the scene pass's, so a
652
+ * stage that reads depth gets the same texture the built-in stages read rather than its own.
653
+ */
654
+ interface IWorldEnvironmentStageContext {
655
+ readonly depthNode: DepthTextureNode;
656
+ readonly tier: ChainTier;
657
+ /** The camera the scene pass renders with, which is the one a temporal stage must jitter. */
658
+ readonly camera: Camera;
659
+ }
660
+ type ChainStage = {
661
+ readonly name: string;
662
+ readonly supportsResolutionSubrect?: boolean;
663
+ readonly before?: string;
664
+ readonly after?: string;
665
+ /**
666
+ * This stage reads display-referred colour — tone-mapped and sRGB-encoded — so the chain
667
+ * installs the graph with the renderer's automatic output transform switched off and the stage
668
+ * applies that transform itself (`renderOutput` from `three/tsl`).
669
+ *
670
+ * For effects authored against the picture rather than against light: a `.cube` table, an
671
+ * sRGB-space edge filter. Such a stage runs last and may not declare an anchor, and the chain
672
+ * only hands the renderer its transform back when the stage was actually refused.
673
+ */
674
+ readonly afterOutputTransform?: boolean;
675
+ readonly available?: (context: ChainContext) => boolean | string;
676
+ readonly dispose?: () => void;
677
+ readonly minimumTier?: ChainTier;
678
+ /**
679
+ * A temporal stage's completed rejection measurement. Its shape is the engine's velocity
680
+ * contract, restated here so this file keeps importing nothing, and it is asked once per frame
681
+ * after rendering. A stage that has not built, or has nothing landed yet, answers `undefined` —
682
+ * which the chain reports as absent rather than as zero.
683
+ */
684
+ readonly rejectionMeasurement?: () => {
685
+ frame: number;
686
+ rejectionFraction: number;
687
+ } | undefined;
688
+ /** The chain plumbing is stage-agnostic, so it names the node it carries `unknown`. */
689
+ readonly build: (input: unknown, context: ChainContext) => unknown;
690
+ };
691
+ type OutputInstallation = {
692
+ isCurrent(): boolean;
693
+ dispose(): void;
694
+ };
695
+ type ResolutionSubrectTarget = {
696
+ setSize(width: number, height: number, depth?: number): void;
697
+ };
698
+ type ResolutionSubrectController = {
699
+ readonly active?: boolean;
700
+ readonly view?: ResolutionSubrectView;
701
+ retain(node: ResolutionSubrectTarget, targets: readonly RenderTarget[]): void;
702
+ release(node: ResolutionSubrectTarget): void;
703
+ textureView(texture: Texture): ResolutionSubrectView | undefined;
704
+ dispose(): void;
705
+ };
706
+ type OutputSetter = ((node: unknown, worldPass?: unknown) => void) | ((node: unknown, worldPass?: unknown) => OutputInstallation);
707
+ type OutputRenderer = {
708
+ kind: string;
709
+ raw: unknown;
710
+ createResolutionSubrect?: () => ResolutionSubrectController;
711
+ /**
712
+ * Installs a node graph directly. Only reached when a `baseColour` is composed and every
713
+ * stage is off: the chain installs nothing for an empty stage list, and dropping the game's
714
+ * own composition on the floor would be the silent no-op this class exists to prevent.
715
+ */
716
+ setOutputNode?: OutputSetter;
717
+ /** Legacy node-only clear. The returned receipt distinguishes same-node reinstalls. */
718
+ clearOutputNode?: (expectedNode?: unknown) => void;
719
+ createRenderChain?: (options: {
720
+ input?: unknown;
721
+ worldPass?: unknown;
722
+ request?: {
723
+ stages?: readonly string[];
724
+ tier?: ChainContext["tier"];
725
+ /**
726
+ * The scene pass that owns the shared velocity output, for a temporal stage to read. Its
727
+ * shape is the engine's velocity contract, restated here so this file keeps importing
728
+ * nothing: `pass(scene, camera)` returns exactly this.
729
+ */
730
+ velocity?: {
731
+ pass?: ReturnType<typeof pass>;
732
+ /** How a host whose scene pass owns the velocity output provides it; the chain's MRT route is the default. */
733
+ provision?: {
734
+ texture(scenePass: ReturnType<typeof pass>): Node;
735
+ attach<T>(node: T, source: unknown): T;
736
+ };
737
+ rejectionMeasurement?: () => {
738
+ frame: number;
739
+ rejectionFraction: number;
740
+ } | undefined;
741
+ };
742
+ };
743
+ stages?: readonly ChainStage[];
744
+ resolutionSubrect?: ResolutionSubrectController;
745
+ }) => {
746
+ applied: {
747
+ dropped: readonly {
748
+ name: string;
749
+ reason: string;
750
+ }[];
751
+ stages: readonly string[];
752
+ };
753
+ dispose(): void;
754
+ };
755
+ };
756
+ declare class WorldEnvironment {
757
+ #private;
758
+ /**
759
+ * A scene with no options starts from the `high` quality tier, a fresh Unreal 5.8.3 project's look; the tier named by
760
+ * `renderChainTier` ("medium" or "low") starts from that tier instead. An option you give always wins, and an
761
+ * `undefined` one does not count as given.
762
+ */
763
+ constructor(given?: IWorldEnvironmentOptions);
764
+ /**
765
+ * Installs the chain. Returns what actually ran — the same applied report the chain
766
+ * printed — so a scene can assert on it instead of scraping the console.
767
+ */
768
+ apply(renderer: OutputRenderer, scene: Scene, camera: Camera, target?: IWorldEnvironmentTarget): {
769
+ dropped: readonly {
770
+ name: string;
771
+ reason: string;
772
+ }[];
773
+ stages: readonly string[];
774
+ dispose?: () => void;
775
+ exposure?: AutoExposureNode;
776
+ /** The engine's live temporal state; present only while `temporalAA` runs. */
777
+ temporalReport?: () => Record<string, unknown>;
778
+ };
779
+ }
780
+
781
+ /**
782
+ * This game's authored looks. GPU family picks the start; measured frame budgets refine it.
783
+ * Edit these presets to change the look without changing the framework.
784
+ */
785
+ type QualityTier = "low" | "medium" | "high";
786
+ /**
787
+ * Picks the tier: an explicit `tier` always wins, otherwise the platform decides.
788
+ *
789
+ * Fails closed. An unrecognised tier name throws with the value it was handed rather than
790
+ * quietly rendering the default, because a silent fallback here looks exactly like a tier that
791
+ * turned out to have no effect.
792
+ */
793
+ declare function resolveQualityTier(request?: {
794
+ readonly gpuClass?: string;
795
+ readonly mobile?: boolean;
796
+ readonly software?: boolean;
797
+ readonly tier?: string;
798
+ }): QualityTier;
799
+ /**
800
+ * Harness: the screen-space gather Unreal's L7 (Epic) is judged against: 32 rays a pixel at half resolution, denoised
801
+ * over 16 gather pixels. A calibration tool, not a shipping tier (PRD-640 Phase 1: about 31 ms at 1080p). Every harness
802
+ * scene that renders global illumination spreads it, so no scene falls back to the `high` preset's 2-slice gather.
803
+ */
804
+ declare const EPIC_SSGI: IWorldEnvironmentOptions;
805
+ /** The stages and strengths a tier turns on. Throws on a name that is not a tier. */
806
+ declare function qualityPreset(tier: string): IWorldEnvironmentOptions;
807
+ /**
808
+ * Global illumination and shadow filtering per tier, named after Unreal's scalability levels
809
+ * (Engine/Config/BaseScalability.ini, `[GlobalIlluminationQuality@0..3]` and `[ShadowQuality@0..3]`).
810
+ * A fresh Unreal project runs Epic (3), so `high` is Epic; `medium` is level 1 and `low` is level 0.
811
+ * Unreal's own level 2 (High) is not a ThreeNative tier: the three tiers are the three levels a
812
+ * calibration scene is judged against (PRD-644, PRD-652).
813
+ */
814
+ type FinalGatherMethod = "none" | "irradianceField" | "screenProbeGather";
815
+ interface IGiTier {
816
+ /**
817
+ * How bounce light reaches a pixel. `none` is Unreal's Low: no diffuse GI, the sky light at 0.8.
818
+ * `irradianceField` is Medium: world-space probes only (the baked cache here). `screenProbeGather`
819
+ * is Epic: the screen-space gather over the same cache. The preset of the tier names it.
820
+ */
821
+ readonly finalGatherMethod: FinalGatherMethod;
822
+ /** Read-only report: the `sg.GlobalIlluminationQuality` this tier follows. */
823
+ readonly globalIlluminationQuality: 0 | 1 | 3;
824
+ /**
825
+ * `r.DistanceFieldAO`: whether the scene's distance fields shadow the sky light. Unreal's Low turns it off, so
826
+ * the sky light reaches the inside of a room unoccluded (measured on `sunlit-room`, PRD-644 `## Decisions`).
827
+ */
828
+ readonly distanceFieldAO: boolean;
829
+ /** `r.SkylightIntensityMultiplier`: Unreal suppresses the sky light to 0.8 at Low, where DFAO is off. */
830
+ readonly skylightIntensityMultiplier: number;
831
+ }
832
+ /** The GI method and Unreal level of a tier. Throws on a name that is not a tier. */
833
+ declare function giPreset(tier: string): IGiTier;
834
+ interface IShadowFilter {
835
+ readonly blockerSamples: number;
836
+ readonly filterSamples: number;
837
+ }
838
+ interface IShadowTier {
839
+ /** Read-only report: the `sg.ShadowQuality` this tier follows. */
840
+ readonly shadowQuality: 0 | 1 | 3;
841
+ /**
842
+ * Whether the sun and the lamps cast dynamic shadows. Unreal draws none at `sg.ShadowQuality` 0
843
+ * (`r.ShadowQuality=0`), measured on `penumbra-lab` (PRD-652 `## Decisions`), so `low` casts none.
844
+ */
845
+ readonly castShadows: boolean;
846
+ /**
847
+ * The receiver filter taps of the sun and of every lamp: Unreal's directional and local ray counts
848
+ * are equal at Medium and Epic, so one pair serves both.
849
+ */
850
+ readonly filter: IShadowFilter;
851
+ /** `r.Shadow.Virtual.ResolutionLodBiasDirectional`: -1 halves the finest sun level's texel. */
852
+ readonly resolutionLodBiasDirectional: number;
853
+ }
854
+ /** The shadow filter and resolution bias of a tier. Throws on a name that is not a tier. */
855
+ declare function shadowPreset(tier: string): IShadowTier;
856
+ /** The tier tables as one object: `resolve` a start tier from a GPU class, `gi` and `shadow` settings of a tier. */
857
+ declare const qualityTiers: {
858
+ readonly resolutionScale: {
859
+ readonly low: 1;
860
+ readonly medium: 0.72;
861
+ readonly high: 0.85;
862
+ };
863
+ readonly gi: typeof giPreset;
864
+ readonly resolve: typeof resolveQualityTier;
865
+ readonly shadow: typeof shadowPreset;
866
+ };
867
+
868
+ export { AutoExposureNode as A, type ChainStage as C, EPIC_SSGI as E, type FinalGatherMethod as F, type GIVisualizeMode as G, type IExposureSettings as I, type OutputRenderer as O, type QualityTier as Q, type ScreenSpaceAA as S, type TonemapMode as T, WorldEnvironment as W, GIVisualize as a, GI_VISUALIZE_MODES as b, type IGIVisualizeOptions as c, type IGiTier as d, type IReflectionRoute as e, type IShadowFilter as f, type IShadowTier as g, type ITracedHit as h, type ITracedRay as i, type ITracedReflectionsOptions as j, type IWorldEnvironmentOptions as k, type IWorldEnvironmentStageContext as l, type IWorldEnvironmentTarget as m, type SsgiQuality as n, TracedReflections as o, exposureSettings as p, installFilmicToneMapping as q, qualityPreset as r, qualityTiers as s };