@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
@@ -2,7 +2,8 @@
2
2
  // arrives from around a surface and leaves the sun alone (UE 5.8.3:
3
3
  // Engine/Shaders/Private/PostProcessAmbientOcclusion.usf composites the term on indirect light). The reach form
4
4
  // of the stage has no world radius, so it cannot fall back to three's world-radius GTAO, which means it must
5
- // know the indirect share of the frame. A frame with no baked world cache has none: the stage would multiply
5
+ // know the indirect share of the frame. The owned engine writes it to its `indirectDiffuse` target; upstream three
6
+ // with no baked world cache has none: the stage would multiply
6
7
  // the sun as well, and the `engine: "threejs"` arm, which drops the stage outright (`TN_AO_REACH_UNSUPPORTED`
7
8
  // in `world-environment.ts`), would not show the same picture. Fail closed and name what is missing, rather
8
9
  // than shipping one engine a contact shadow the other cannot draw.
@@ -13,12 +14,12 @@ export interface IAoAdmission {
13
14
  readonly reach: boolean;
14
15
  /** The game asked for the indirect-only composite, which is the default. */
15
16
  readonly indirectOnly: boolean;
16
- /** A baked world cache exists, so the frame carries the indirect share the occlusion belongs on. */
17
+ /** The frame can tell its indirect share apart: the owned engine's `indirectDiffuse` target, or a baked world cache. */
17
18
  readonly hasIndirect: boolean;
18
19
  }
19
20
 
20
21
  /** Why the contact occlusion cannot run on this frame, or `undefined` when it can. */
21
22
  export function aoRefusal(request: IAoAdmission): string | undefined {
22
23
  if (!request.reach || !request.indirectOnly || request.hasIndirect) return undefined;
23
- return "TN_AO_INDIRECT_UNSUPPORTED: the screen-reach occlusion darkens indirect light only, and this frame has no baked world cache to read the indirect share from; set gtaoIndirectOnly false to darken the whole frame, or let the scene bake a cache (finalGatherMethod)";
24
+ return "TN_AO_INDIRECT_UNSUPPORTED: the screen-reach occlusion darkens indirect light only, and this frame cannot tell its indirect share apart (upstream three, no baked world cache); set gtaoIndirectOnly false to darken the whole frame, run the owned engine, or let the scene bake a cache (finalGatherMethod)";
24
25
  }
@@ -9,7 +9,6 @@ import {
9
9
  type NodeFrame,
10
10
  NodeMaterial,
11
11
  NodeUpdateType,
12
- QuadMesh,
13
12
  RendererUtils,
14
13
  } from "three/webgpu";
15
14
  import {
@@ -34,6 +33,7 @@ import {
34
33
  reduceExposure,
35
34
  } from "./exposure-graph.js";
36
35
  import { ExposureReadback } from "./exposure-readback.js";
36
+ import { drawQuadPass } from "./quad-pass.js";
37
37
 
38
38
  /** Scene-referred exposure changes light, never coverage/compositing alpha. */
39
39
  export function applyExposure(colour: Node<"vec4">, exposure: Node<"float">): Node<"vec4"> {
@@ -60,7 +60,6 @@ export class AutoExposureNode extends Node<"float"> {
60
60
  readonly #seed = uniform(0);
61
61
  readonly #enabled = uniform(false);
62
62
  readonly #bias = uniform(0);
63
- readonly #quad: QuadMesh;
64
63
  readonly #meterMaterial = new NodeMaterial();
65
64
  readonly #reduceMaterial = new NodeMaterial();
66
65
  readonly #tilesMaterial = new NodeMaterial();
@@ -116,8 +115,6 @@ export class AutoExposureNode extends Node<"float"> {
116
115
  decode,
117
116
  this.#bias,
118
117
  );
119
- // Three 0.187's QuadMesh takes its material in the constructor; each pass replaces it before drawing.
120
- this.#quad = new QuadMesh(this.#meterMaterial);
121
118
  }
122
119
 
123
120
  override setup(builder: NodeBuilder): Node<"float"> {
@@ -213,25 +210,17 @@ export class AutoExposureNode extends Node<"float"> {
213
210
  this.#reduced.value = previous.texture;
214
211
  this.#reduceSize.value.set(previous.width, previous.height);
215
212
  }
216
- this.#quad.material = i === 0 ? this.#meterMaterial : this.#reduceMaterial;
217
- renderer.setRenderTarget(level);
218
- this.#quad.render(renderer);
213
+ drawQuadPass(renderer, i === 0 ? this.#meterMaterial : this.#reduceMaterial, level);
219
214
  }
220
215
  const final = this.#levels.at(-1);
221
216
  if (final === undefined) throw new Error("Exposure reduction is empty.");
222
217
  this.#blocks.value = final.texture;
223
218
  this.#blockSize.value.set(final.width, final.height);
224
- this.#quad.material = this.#tilesMaterial;
225
- renderer.setRenderTarget(this.#tilesTarget);
226
- this.#quad.render(renderer);
227
- this.#quad.material = this.#histogramMaterial;
228
- renderer.setRenderTarget(this.#histogramTarget);
229
- this.#quad.render(renderer);
219
+ drawQuadPass(renderer, this.#tilesMaterial, this.#tilesTarget);
220
+ drawQuadPass(renderer, this.#histogramMaterial, this.#histogramTarget);
230
221
  const write = this.#writeTarget;
231
222
  this.#previous.value = this.#readTarget.texture;
232
- this.#quad.material = this.#adaptMaterial;
233
- renderer.setRenderTarget(write);
234
- this.#quad.render(renderer);
223
+ drawQuadPass(renderer, this.#adaptMaterial, write);
235
224
  this.#result.value = write.texture;
236
225
  this.#writeTarget = this.#readTarget;
237
226
  this.#readTarget = write;
@@ -1,9 +1,16 @@
1
1
  import { ACESFilmicToneMapping, AgXToneMapping, NeutralToneMapping, NoToneMapping } from "three";
2
- import { installFilmicToneMapping } from "./filmic-tone-mapping.js";
2
+ import {
3
+ COLOR_GRADE,
4
+ FILMIC_CURVE,
5
+ type IColorGrade,
6
+ type IFilmicCurve,
7
+ installFilmicToneMapping,
8
+ } from "./filmic-tone-mapping.js";
3
9
 
4
10
  /** `filmic` is a fresh Unreal 5.8.3 project's curve and the default; the rest are the named overrides. */
5
11
  export type RendererToneMapping = "filmic" | "aces" | "agx" | "neutral" | "none";
6
12
 
13
+ /** The named overrides, in the order an error message lists them. `filmic` is handled apart. */
7
14
  const THREE_MODE: Record<Exclude<RendererToneMapping, "filmic">, number> = {
8
15
  aces: ACESFilmicToneMapping,
9
16
  agx: AgXToneMapping,
@@ -11,27 +18,56 @@ const THREE_MODE: Record<Exclude<RendererToneMapping, "filmic">, number> = {
11
18
  none: NoToneMapping,
12
19
  };
13
20
 
21
+ /** One list of tone curves, so a caller's validation cannot disagree with what is installed. */
22
+ export const RENDERER_TONE_MAPPINGS: readonly RendererToneMapping[] = [
23
+ "filmic",
24
+ ...(Object.keys(THREE_MODE) as (keyof typeof THREE_MODE)[]),
25
+ ];
26
+
27
+ export function isRendererToneMapping(value: unknown): value is RendererToneMapping {
28
+ return RENDERER_TONE_MAPPINGS.includes(value as RendererToneMapping);
29
+ }
30
+
31
+ /**
32
+ * The game's own curve and grade, for the one mode that reads them. A game that supplies neither
33
+ * gets Unreal's defaults, which is what a fresh project ships.
34
+ */
35
+ export interface IFilmicToneMappingOptions {
36
+ readonly curve?: Partial<IFilmicCurve>;
37
+ readonly grade?: IColorGrade;
38
+ }
39
+
14
40
  /**
15
41
  * Puts `mode` on a WebGPU renderer. `filmic` registers Unreal's curve as three's custom tone
16
- * mapping; a renderer without a node library cannot run it, keeps ACES and says so
17
- * (`TN_TONEMAP`). An unknown mode throws rather than quietly becoming the default.
42
+ * mapping; a renderer without a node library cannot run it, keeps ACES and says so (`TN_TONEMAP`).
43
+ * An unknown mode throws rather than quietly becoming the default.
44
+ *
45
+ * Inside the framework this is the only writer of `renderer.toneMapping`: the renderer's own default
46
+ * and `WorldEnvironment` both call it, so a scene cannot pick a curve its renderer disagrees with.
47
+ * The Unreal-look capture harness under `scripts/unreal-look/scaffold/` keeps its own copy because
48
+ * it is a generated arm of that experiment, not framework code.
18
49
  */
19
50
  export function applyRendererToneMapping(
20
51
  raw: unknown,
21
52
  mode: RendererToneMapping,
22
53
  report: (line: string) => void,
54
+ filmic: IFilmicToneMappingOptions = {},
23
55
  ): number {
24
56
  const target = raw as { toneMapping?: number };
25
57
  if (mode !== "filmic") {
26
58
  const three = THREE_MODE[mode];
27
59
  if (three === undefined)
28
60
  throw new Error(
29
- `Unknown toneMapping '${String(mode)}'. Use one of: filmic, ${Object.keys(THREE_MODE).join(", ")}.`,
61
+ `Unknown toneMapping '${String(mode)}'. Use one of: ${RENDERER_TONE_MAPPINGS.join(", ")}.`,
30
62
  );
31
63
  target.toneMapping = three;
32
64
  return three;
33
65
  }
34
- const installed = installFilmicToneMapping(raw);
66
+ const installed = installFilmicToneMapping(
67
+ raw,
68
+ { ...FILMIC_CURVE, ...filmic.curve },
69
+ filmic.grade ?? COLOR_GRADE,
70
+ );
35
71
  if (installed !== undefined) {
36
72
  target.toneMapping = installed;
37
73
  return installed;
@@ -27,11 +27,11 @@ import {
27
27
  type NodeFrame,
28
28
  NodeMaterial,
29
29
  NodeUpdateType,
30
- QuadMesh,
31
30
  RendererUtils,
32
31
  type TextureNode,
33
32
  } from "three/webgpu";
34
33
  import { exposureMeter, exposureSettings } from "./exposure-settings.js";
34
+ import { drawQuadPass } from "./quad-pass.js";
35
35
 
36
36
  type ColourTexture = TextureNode;
37
37
 
@@ -139,7 +139,6 @@ export class LocalExposureNode extends Node<"float"> {
139
139
  readonly #blurSize = uniform(new Vector2(1, 1));
140
140
  readonly #blurRadius = uniform(BLUR_RADIUS);
141
141
  readonly #rangeStride = uniform(1);
142
- readonly #quad: QuadMesh;
143
142
  readonly #logMaterial = new NodeMaterial();
144
143
  readonly #lumMaterial = new NodeMaterial();
145
144
  readonly #blurXMaterial = new NodeMaterial();
@@ -362,8 +361,6 @@ export class LocalExposureNode extends Node<"float"> {
362
361
  });
363
362
  return sum;
364
363
  })();
365
- // Three 0.187's QuadMesh takes its material in the constructor; each pass replaces it before drawing.
366
- this.#quad = new QuadMesh(this.#logMaterial);
367
364
  }
368
365
 
369
366
  override setup(builder: NodeBuilder): Node<"float"> {
@@ -474,9 +471,7 @@ export class LocalExposureNode extends Node<"float"> {
474
471
  [this.#rowMaterial, this.#rowTarget],
475
472
  [this.#gridMaterial, this.#gridTarget],
476
473
  ] as const) {
477
- this.#quad.material = material;
478
- renderer.setRenderTarget(target);
479
- this.#quad.render(renderer);
474
+ drawQuadPass(renderer, material, target);
480
475
  }
481
476
  } finally {
482
477
  RendererUtils.restoreRendererState(renderer, this.#rendererState);
@@ -0,0 +1,21 @@
1
+ import type { RenderTarget } from "three";
2
+ import { type NodeMaterial, QuadMesh, type Renderer } from "three/webgpu";
3
+
4
+ // PRD-828: one QuadMesh per pass material, made on first use. Reassigning QuadMesh.material each
5
+ // pass is an engine crossing on the owned engine; a material dropped by its pass frees its quad.
6
+ const quads = new WeakMap<NodeMaterial, QuadMesh>();
7
+
8
+ /** Draws one full-screen pass of `material` into `target`. */
9
+ export function drawQuadPass(
10
+ renderer: Renderer,
11
+ material: NodeMaterial,
12
+ target: RenderTarget | null,
13
+ ): void {
14
+ let quad = quads.get(material);
15
+ if (quad === undefined) {
16
+ quad = new QuadMesh(material);
17
+ quads.set(material, quad);
18
+ }
19
+ renderer.setRenderTarget(target);
20
+ quad.render(renderer);
21
+ }
@@ -167,6 +167,10 @@ const low: IWorldEnvironmentOptions = {
167
167
  finalGatherMethod: "none",
168
168
  localExposureEnabled: false,
169
169
  renderChainTier: "low",
170
+ // No screen-space reflections: UE 5.8.3 BaseScalability.ini:514-515, [ReflectionQuality@0] r.SSR.Quality=0. Left unset,
171
+ // the default turned SSR on, and its normal and material reads redrew the scene into a second G-buffer pass (Iris Xe
172
+ // stress lab: 6.7 of 26.7 ms, PRD-871).
173
+ ssrEnabled: false,
170
174
  // Single-sample, as medium: an unset count inherits the renderer's 4x MSAA, and the cheapest tier
171
175
  // cost more than medium on a forest (Iris Xe 125 -> 158 ms at the switch, PRD-762).
172
176
  samples: 0,
@@ -6,10 +6,10 @@ import {
6
6
  type NodeFrame,
7
7
  NodeMaterial,
8
8
  NodeUpdateType,
9
- QuadMesh,
10
9
  RendererUtils,
11
10
  type TextureNode,
12
11
  } from "three/webgpu";
12
+ import { drawQuadPass } from "./quad-pass.js";
13
13
 
14
14
  type ColourTexture = TextureNode;
15
15
 
@@ -103,7 +103,6 @@ export class UnrealBloomNode extends Node<"vec3"> {
103
103
  static readonly schedule = bloomSchedule;
104
104
  readonly input: ColourTexture;
105
105
  readonly #size = new Vector2();
106
- readonly #quad: QuadMesh;
107
106
  readonly #downMaterials: NodeMaterial[] = [];
108
107
  readonly #downTargets: RenderTarget[] = [];
109
108
  readonly #downTextures: ColourTexture[] = [];
@@ -142,8 +141,6 @@ export class UnrealBloomNode extends Node<"vec3"> {
142
141
  })();
143
142
  this.#downMaterials.push(material);
144
143
  }
145
- // Three 0.187's QuadMesh takes its material in the constructor; each pass replaces it before drawing.
146
- this.#quad = new QuadMesh(this.#downMaterials[0] as NodeMaterial);
147
144
  // Stage 1 is Bloom1 (tightest, level 1); stage 6 is Bloom6 (widest, level 6). Unreal runs them
148
145
  // widest first, each adding the one before it.
149
146
  const { sizes, tints, intensity, gaussianIntensity } = unrealBloomSettings;
@@ -264,17 +261,11 @@ export class UnrealBloomNode extends Node<"vec3"> {
264
261
  this.#rendererState = RendererUtils.resetRendererState(renderer, this.#rendererState);
265
262
  try {
266
263
  for (const [i, target] of this.#downTargets.entries()) {
267
- this.#quad.material = this.#downMaterials[i] as NodeMaterial;
268
- renderer.setRenderTarget(target);
269
- this.#quad.render(renderer);
264
+ drawQuadPass(renderer, this.#downMaterials[i] as NodeMaterial, target);
270
265
  }
271
266
  for (const stage of this.#stages) {
272
- this.#quad.material = stage.acrossMaterial;
273
- renderer.setRenderTarget(stage.across);
274
- this.#quad.render(renderer);
275
- this.#quad.material = stage.outMaterial;
276
- renderer.setRenderTarget(stage.out);
277
- this.#quad.render(renderer);
267
+ drawQuadPass(renderer, stage.acrossMaterial, stage.across);
268
+ drawQuadPass(renderer, stage.outMaterial, stage.out);
278
269
  }
279
270
  } finally {
280
271
  RendererUtils.restoreRendererState(renderer, this.#rendererState);
@@ -1,3 +1,4 @@
1
+ import { readLaunchFlag } from "../debug.js";
1
2
  // Generated for you: ordinary Three.js; ThreeNative does not read this file. Delete or
2
3
  // rewrite it freely — every default in here is a starting point, not a framework look.
3
4
  //
@@ -14,13 +15,9 @@
14
15
  // tier. Those are arguments, supplied by `postprocessing.ts`, yours to change.
15
16
 
16
17
  import {
17
- ACESFilmicToneMapping,
18
- AgXToneMapping,
19
18
  type Camera,
20
- CustomToneMapping,
21
19
  type DirectionalLight,
22
20
  MaterialBlending,
23
- NeutralToneMapping,
24
21
  type PerspectiveCamera,
25
22
  type RenderTarget,
26
23
  type Scene,
@@ -39,7 +36,6 @@ import { sharpen } from "three/addons/tsl/display/SharpenNode.js";
39
36
  import { traa } from "three/addons/tsl/display/TRAANode.js";
40
37
  import {
41
38
  Fn,
42
- If,
43
39
  color,
44
40
  convertToTexture,
45
41
  cross,
@@ -76,17 +72,23 @@ import {
76
72
  } from "../render/chain.js";
77
73
  import { GIVisualize, type GIVisualizeMode } from "../render/gi-visualize.js";
78
74
  import type { TracedReflections } from "../render/traced-reflections.js";
75
+ import { rendererFacts } from "../renderer-facts.js";
79
76
  import { STARTUP_EXPOSURE } from "../renderer.js";
80
77
  import { aoRefusal } from "./ao-admission.js";
81
78
  import { AO_MULTIBOUNCE_FIT, UNREAL_AO_MULTIBOUNCE_ALBEDO } from "./ao-multibounce.js";
82
79
  import { UNREAL_AO_REACH_PX } from "./ao-reach.js";
83
80
  import { AutoExposureNode, applyExposure } from "./auto-exposure.js";
81
+ import {
82
+ RENDERER_TONE_MAPPINGS,
83
+ type RendererToneMapping,
84
+ applyRendererToneMapping,
85
+ isRendererToneMapping,
86
+ } from "./default-tone-mapping.js";
84
87
  import { type IExposureSettings, exposureSettings } from "./exposure-settings.js";
85
88
  import {
86
89
  type ColorGradeOptions,
87
90
  FILMIC_CURVE,
88
91
  type IFilmicCurve,
89
- installFilmicToneMapping,
90
92
  resolveColorGrade,
91
93
  } from "./filmic-tone-mapping.js";
92
94
  import { cacheFallback, giCache } from "./gi-registry.js";
@@ -111,9 +113,10 @@ export type ScreenSpaceAA = "smaa" | "fxaa" | "disabled";
111
113
 
112
114
  /**
113
115
  * Godot's `Environment.tonemap_mode`: the modes Three.js ships, plus `filmic`, the Unreal 5
114
- * default curve written in `tonemap.ts`.
116
+ * default curve written in `tonemap.ts`. The list itself is `RendererToneMapping`'s, one owner
117
+ * beside `applyRendererToneMapping`, so a mode this accepts is a mode the renderer can install.
115
118
  */
116
- export type TonemapMode = "aces" | "agx" | "filmic" | "neutral";
119
+ export type TonemapMode = RendererToneMapping;
117
120
 
118
121
  /**
119
122
  * SSGI sample budget. The three tiers are the presets SSGINode's own documentation
@@ -132,13 +135,6 @@ const SSGI_QUALITY: Record<SsgiQuality, { sliceCount: number; stepCount: number
132
135
  epic: { sliceCount: 8, stepCount: 16 },
133
136
  };
134
137
 
135
- const TONEMAP: Record<TonemapMode, number> = {
136
- aces: ACESFilmicToneMapping,
137
- agx: AgXToneMapping,
138
- filmic: CustomToneMapping,
139
- neutral: NeutralToneMapping,
140
- };
141
-
142
138
  /**
143
139
  * Whether this launch draws the transparent draws' own target (see `seesThrough` below).
144
140
  *
@@ -149,17 +145,10 @@ const TONEMAP: Record<TonemapMode, number> = {
149
145
  * running the same pose both ways.
150
146
  */
151
147
  export function translucentTargetWanted(): boolean {
152
- const host = globalThis as { process?: { env?: Record<string, unknown> } } & Record<
153
- string,
154
- unknown
155
- >;
156
- const fromEnv = host.process?.env?.TN_TRANSLUCENT;
157
- if (fromEnv === "0" || fromEnv === "false") return false;
158
- const query = globalThis.location?.search;
159
- if (typeof query === "string" && /[?&]tnTranslucent=(?:0|false)(?:&|$)/u.test(query))
160
- return false;
161
- const set = host.__tnTranslucent;
162
- return !(set === false || set === 0 || set === "0" || set === "false");
148
+ return !readLaunchFlag(
149
+ { environment: "TN_TRANSLUCENT", global: "__tnTranslucent", query: "tnTranslucent" },
150
+ "off",
151
+ );
163
152
  }
164
153
 
165
154
  /**
@@ -790,10 +779,10 @@ export class WorldEnvironment {
790
779
  `Unknown ssgiQuality '${String(quality)}'. Use one of: ${Object.keys(SSGI_QUALITY).join(", ")}.`,
791
780
  );
792
781
  }
793
- const tonemapMode = options.tonemapMode ?? "aces";
794
- if (TONEMAP[tonemapMode] === undefined) {
782
+ const tonemapMode = options.tonemapMode ?? "filmic";
783
+ if (!isRendererToneMapping(tonemapMode)) {
795
784
  throw new Error(
796
- `Unknown tonemapMode '${String(tonemapMode)}'. Use one of: ${Object.keys(TONEMAP).join(", ")}.`,
785
+ `Unknown tonemapMode '${String(tonemapMode)}'. Use one of: ${RENDERER_TONE_MAPPINGS.join(", ")}.`,
797
786
  );
798
787
  }
799
788
  resolveColorGrade(options.colorGrade);
@@ -918,31 +907,21 @@ export class WorldEnvironment {
918
907
  ? this.#options
919
908
  : { ...this.#options, autoExposureEnabled: false };
920
909
  const raw = renderer.raw as { toneMapping?: number; toneMappingExposure?: number };
921
- raw.toneMapping = TONEMAP[options.tonemapMode];
922
- if (options.tonemapMode === "filmic") {
923
- // The curve is this game's source, registered as three's custom tone mapping. A renderer
924
- // without a node library cannot run it; that frame keeps ACES and says so.
925
- const installed = installFilmicToneMapping(
926
- renderer.raw,
927
- {
928
- ...FILMIC_CURVE,
929
- ...options.filmicCurve,
930
- ...(lookDiagnostics.lutClipOff ? { lutClip: 0 } : {}),
931
- },
932
- resolveColorGrade(options.colorGrade),
933
- );
934
- if (installed === undefined) {
935
- raw.toneMapping = ACESFilmicToneMapping;
936
- console.warn(
937
- `TN_TONEMAP ${JSON.stringify({ requested: "filmic", applied: "aces", reason: `renderer:${renderer.kind}` })}`,
938
- );
939
- }
940
- }
910
+ // One writer of `toneMapping` for the whole engine: the curve this game supplies reaches the
911
+ // same library the renderer's own default uses, and a renderer without a node library keeps
912
+ // ACES and reports `TN_TONEMAP` once, here or in the renderer.
913
+ applyRendererToneMapping(raw, options.tonemapMode, (line) => console.warn(line), {
914
+ curve: {
915
+ ...FILMIC_CURVE,
916
+ ...options.filmicCurve,
917
+ ...(lookDiagnostics.lutClipOff ? { lutClip: 0 } : {}),
918
+ },
919
+ grade: resolveColorGrade(options.colorGrade),
920
+ });
941
921
 
942
922
  // Temporal AA is the owned engine's: it jitters the camera and blends the frames ahead of every stage. Any other
943
923
  // renderer keeps the spatial filter, and the report says why.
944
- const engineInfo = (renderer.raw as { info?: object }).info;
945
- const ownedEngine = engineInfo !== undefined && "engine" in engineInfo;
924
+ const { ownedEngine } = rendererFacts(renderer);
946
925
  const temporalRefusal = !options.temporalAA
947
926
  ? undefined
948
927
  : renderer.kind !== "webgpu"
@@ -1043,14 +1022,13 @@ export class WorldEnvironment {
1043
1022
  const temporalReport = temporal
1044
1023
  ? (): Record<string, unknown> => ({
1045
1024
  method: "traa",
1046
- ...(engineInfo as { engine?: { temporal?: object } }).engine?.temporal,
1025
+ ...(renderer.raw as { info?: { engine?: { temporal?: object } } }).info?.engine?.temporal,
1047
1026
  })
1048
1027
  : undefined;
1049
- // Contact occlusion dims the light that comes from around. With the world cache baked the frame's indirect
1050
- // diffuse is known per pixel, so only that share takes the occlusion and the sun keeps its light, as
1051
- // Unreal's AO (indirect light only) leaves it. Without a cache (the three.js engine) the whole frame is dimmed.
1052
- const indirectOcclusion =
1053
- ownedEngine && giCache.irradiance !== undefined && options.gtaoIndirectOnly;
1028
+ // Contact occlusion dims the light that comes from around. The owned engine writes each pixel's indirect diffuse
1029
+ // light to its own target, so only that share takes the occlusion and the sun keeps its light, as Unreal's AO
1030
+ // (indirect light only) leaves it. Upstream three has no such target, so there the whole frame is dimmed.
1031
+ const indirectOcclusion = ownedEngine && options.gtaoIndirectOnly;
1054
1032
  // Both screen-space stages below darken the frame with an occlusion gathered at the opaque surface's depth, so both
1055
1033
  // must leave the draws composited over it alone (see the MRT's `translucent` output and `translucentFrame`).
1056
1034
  // `TN_TRANSLUCENT=0` or `?tnTranslucent=0` keeps the target off the frame — the occlusion then darkens the sheets
@@ -1209,7 +1187,7 @@ export class WorldEnvironment {
1209
1187
  build: (input) => {
1210
1188
  // The gather reads the lit frame at each ray's hit, so the frame is materialised once and reused.
1211
1189
  const base = convertToTexture(input);
1212
- const wasmEngine = "engine" in (renderer.raw as { info: object }).info;
1190
+ const wasmEngine = rendererFacts(renderer).ownedEngine;
1213
1191
  // Harness: on the owned engine the gather also answers for the tier below it (the world-space cache), so
1214
1192
  // a ray that hits returns `hit - cache` and the two never add the same light twice (Lumen's tiering,
1215
1193
  // Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp).
@@ -1335,14 +1313,17 @@ export class WorldEnvironment {
1335
1313
  releaseAo = () => {};
1336
1314
  },
1337
1315
  build: (input) => {
1338
- // The reach form occludes indirect light only, so a frame without a baked world cache cannot run it:
1339
- // the whole-frame multiply it would fall back to darkens the sun, and the threejs arm drops the stage.
1316
+ // The reach form occludes indirect light only, so a frame that cannot tell its indirect share apart (upstream
1317
+ // three with no baked world cache) cannot run it: the whole-frame multiply it would fall back to darkens the sun.
1340
1318
  const refusal = aoRefusal({
1341
1319
  reach: options.gtaoRadius === undefined,
1342
1320
  indirectOnly: options.gtaoIndirectOnly,
1343
1321
  // The preset's own declaration covers the frame whose bake has not finished when the chain is built:
1344
1322
  // the gather's fallback reads the cache at render time, and the registration is the other signal.
1345
- hasIndirect: options.finalGatherMethod !== "none" || giCache.irradiance !== undefined,
1323
+ hasIndirect:
1324
+ ownedEngine ||
1325
+ options.finalGatherMethod !== "none" ||
1326
+ giCache.irradiance !== undefined,
1346
1327
  });
1347
1328
  if (refusal !== undefined) throw new Error(refusal);
1348
1329
  // GTAO rebuilds the normal from the depth, so it agrees with the depth's facets. The pass's
@@ -1511,60 +1492,22 @@ export class WorldEnvironment {
1511
1492
  const composited = input
1512
1493
  .mul(vec4(occlusion.r, occlusion.r, occlusion.r, 1))
1513
1494
  .add(vec4(emitted.mul(float(1).sub(occlusion.r)), 0));
1514
- const cache = indirectOcclusion ? cacheFallback(view) : undefined;
1515
- if (cache === undefined) return composited;
1516
- // The pixel's view-space position from its depth and the camera's projection terms, read live each
1517
- // render: the engine has no getViewPosition, and a post quad's own camera nodes are the quad's.
1518
- const term = (index: number) =>
1519
- uniform(view.projectionMatrix.elements[index] ?? 0).onRenderUpdate(
1520
- () => view.projectionMatrix.elements[index] ?? 0,
1521
- );
1522
- const [p0, p5, p8, p9, p10, p14] = [
1523
- term(0),
1524
- term(5),
1525
- term(8),
1526
- term(9),
1527
- term(10),
1528
- term(14),
1529
- ];
1530
- const compose = Fn(() => {
1531
- const coordinate = uv();
1532
- const result = vec3(composited.rgb).toVar();
1533
- const sceneDepth = depth().sample(coordinate).r;
1534
- const sceneNormal = normal().sample(coordinate).xyz;
1535
- // The sky and a draw the normal pass skips (an unlit material) keep the whole-frame multiply.
1536
- If(sceneDepth.lessThan(1).and(sceneNormal.dot(sceneNormal).greaterThan(0.25)), () => {
1537
- const viewZ = p14.negate().div(sceneDepth.add(p10));
1538
- const ndc = vec2(
1539
- coordinate.x.mul(2).sub(1),
1540
- float(1).sub(coordinate.y).mul(2).sub(1),
1541
- );
1542
- const position = vec3(
1543
- viewZ.negate().mul(ndc.x.add(p8)).div(p0),
1544
- viewZ.negate().mul(ndc.y.add(p9)).div(p5),
1545
- viewZ,
1546
- );
1547
- // The indirect diffuse the material added: the cache's irradiance times the albedo, in the frame's
1548
- // units (the gather's own fallback reads it the same way). Only it takes the occlusion, and the
1549
- // result is never darker than the whole-frame multiply.
1550
- const indirect = albedo()
1551
- .rgb.mul(float(1).sub(metal().r))
1552
- .mul(cache(position, sceneNormal.normalize()))
1553
- .mul(frameGain);
1554
- // Only the opaque part of the frame carries that indirect light: a draw composited over it did not receive it.
1555
- const opaque = input.rgb.sub(translucentFrame);
1556
- result.assign(
1557
- max(
1558
- opaque
1559
- .sub(indirect.mul(float(1).sub(keeps ?? occlusion.r)))
1560
- .add(translucentFrame),
1561
- composited.rgb,
1562
- ),
1563
- );
1564
- });
1565
- return vec4(result, input.a);
1566
- });
1567
- return compose();
1495
+ if (!indirectOcclusion) return composited;
1496
+ // The indirect diffuse light the materials added, from the engine's own target (hemisphere, ambient,
1497
+ // environment and baked irradiance, never a direct light), in the frame's units. Only it takes the
1498
+ // occlusion, as Unreal's composite multiplies only the indirect term by the AO (UE 5.8.3:
1499
+ // Engine/Shaders/Private/DiffuseIndirectComposite.usf:195). An unlit draw and the sky add none, so
1500
+ // they keep their colour. The result is never darker than the whole-frame multiply.
1501
+ const indirect = textureNode("indirectDiffuse").rgb.mul(frameGain);
1502
+ // Only the opaque part of the frame carries that indirect light: a draw composited over it did not receive it.
1503
+ const opaque = input.rgb.sub(translucentFrame);
1504
+ return vec4(
1505
+ max(
1506
+ opaque.sub(indirect.mul(float(1).sub(keeps ?? occlusion.r))).add(translucentFrame),
1507
+ composited.rgb,
1508
+ ),
1509
+ input.a,
1510
+ );
1568
1511
  },
1569
1512
  }),
1570
1513
  stage({