@threenative/core 0.3.6 → 0.3.8

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 (137) hide show
  1. package/README.md +3 -5
  2. package/capabilities.json +739 -50
  3. package/dist/{assets-CqvE429w.d.ts → assets-YUbXa3-Y.d.ts} +101 -2
  4. package/dist/{canvas-layer-C1-5CviZ.d.ts → canvas-layer-vCtanIeB.d.ts} +1 -1
  5. package/dist/{game-Jz4Fdoeb.d.ts → game-cb99J-YE.d.ts} +100 -31
  6. package/dist/hot.d.ts +4 -4
  7. package/dist/hot.js +23 -5
  8. package/dist/index.d.ts +1742 -29
  9. package/dist/index.js +22443 -12423
  10. package/dist/{model-lod-BDAUYgsS.d.ts → model-lod-CTpZ6imz.d.ts} +1 -1
  11. package/dist/net.js +39 -12
  12. package/dist/playtest.d.ts +4 -4
  13. package/dist/playtest.js +48 -9
  14. package/dist/react-css.js +23 -0
  15. package/dist/react.d.ts +2 -2
  16. package/dist/{renderer-9yEo9hPa.d.ts → renderer-rZm0hVqq.d.ts} +178 -5
  17. package/dist/ui-layer.d.ts +11 -2
  18. package/dist/ui-layer.js +76 -4
  19. package/dist/worker.d.ts +36 -0
  20. package/dist/worker.js +1088 -0
  21. package/dist/world.d.ts +11 -3
  22. package/dist/world.js +1117 -197
  23. package/mcp/animation-server.mjs +265 -0
  24. package/mcp/animation.mjs +22 -0
  25. package/mcp/call.mjs +105 -0
  26. package/mcp/devtools.mjs +5 -0
  27. package/mcp/engine-server.mjs +713 -37
  28. package/mcp/launch.mjs +3 -2
  29. package/mcp/servers.d.mts +2 -0
  30. package/mcp/servers.mjs +33 -8
  31. package/package.json +12 -8
  32. package/patches/three@0.185.1-prd269-upgrade.patch +308 -0
  33. package/patches/three@0.185.1.patch +481 -272
  34. package/src/animation-packet-state.ts +88 -0
  35. package/src/animation-pose-packet.ts +537 -0
  36. package/src/animation.ts +779 -31
  37. package/src/asset-cache.ts +719 -0
  38. package/src/assets.ts +521 -152
  39. package/src/audio.ts +29 -3
  40. package/src/auto-batch.ts +792 -0
  41. package/src/config.ts +2 -0
  42. package/src/frame-budget.ts +268 -2
  43. package/src/game.ts +525 -105
  44. package/src/grounding.ts +7 -6
  45. package/src/hot.ts +19 -5
  46. package/src/index.ts +381 -6
  47. package/src/input.ts +21 -2
  48. package/src/interpolation.ts +19 -1
  49. package/src/launch-diagnostics.ts +7 -2
  50. package/src/look/ao-multibounce.ts +29 -0
  51. package/src/look/ao-reach.ts +39 -0
  52. package/src/look/auto-exposure.ts +264 -0
  53. package/src/look/default-tone-mapping.ts +44 -0
  54. package/src/look/exposure-graph.ts +208 -0
  55. package/src/look/exposure-readback.ts +97 -0
  56. package/src/look/exposure-settings.ts +132 -0
  57. package/src/look/filmic-tone-mapping.ts +852 -0
  58. package/src/look/gi-registry.ts +55 -0
  59. package/src/look/local-exposure.ts +507 -0
  60. package/src/look/look-diagnostics.ts +24 -0
  61. package/src/look/motion-blur.ts +42 -0
  62. package/src/look/quality.ts +309 -0
  63. package/src/look/reflection-trace.ts +344 -0
  64. package/src/look/unreal-bloom.ts +295 -0
  65. package/src/look/vignette.ts +14 -0
  66. package/src/look/world-environment.ts +2033 -0
  67. package/src/loop.ts +25 -1
  68. package/src/merge-parts.ts +25 -10
  69. package/src/model-lod.ts +14 -0
  70. package/src/net-session.ts +58 -14
  71. package/src/ocean/spectral.ts +41 -7
  72. package/src/picking.ts +72 -5
  73. package/src/platform.ts +29 -1
  74. package/src/playtest.ts +54 -8
  75. package/src/profiling/FrameCounters.ts +166 -5
  76. package/src/profiling/FrameStages.ts +289 -0
  77. package/src/profiling/Spans.ts +39 -25
  78. package/src/profiling/debug-telemetry.ts +312 -0
  79. package/src/profiling/scene-warning.ts +42 -6
  80. package/src/projection-apply.ts +11 -3
  81. package/src/projection-content.ts +189 -0
  82. package/src/projection-marker.ts +6 -2
  83. package/src/projection-plan.ts +279 -28
  84. package/src/projection-skinned.ts +620 -5
  85. package/src/projection-stability.ts +16 -0
  86. package/src/projection-uniform.ts +5 -1
  87. package/src/quiet-markers.ts +56 -0
  88. package/src/render/budget-ladder.ts +256 -0
  89. package/src/render/chain.ts +89 -7
  90. package/src/render/exposure-units.ts +59 -0
  91. package/src/render/frame-time-budget.ts +162 -0
  92. package/src/render/gi-budget.ts +231 -0
  93. package/src/render/gi-visualize.ts +49 -0
  94. package/src/render/material-key.ts +1 -0
  95. package/src/render/probe-volume.ts +196 -36
  96. package/src/render/rough-diffuse.ts +177 -0
  97. package/src/render/scene-trace.ts +532 -0
  98. package/src/render/shadow-filter-budget.ts +237 -0
  99. package/src/render/sky-capture.ts +194 -0
  100. package/src/render/soft-shadow.ts +607 -0
  101. package/src/render/surface-cache.ts +418 -0
  102. package/src/render/traced-reflections.ts +408 -0
  103. package/src/render/two-sided-foliage.ts +120 -0
  104. package/src/render/virtual-shadow-pages.ts +112 -12
  105. package/src/render/virtual-shadow.ts +386 -38
  106. package/src/render-camera-cull.ts +536 -31
  107. package/src/render-pass-budget.ts +140 -22
  108. package/src/renderProjection.ts +65 -9
  109. package/src/renderer-config.ts +3 -2
  110. package/src/renderer.ts +289 -14
  111. package/src/resolution-scaler.ts +65 -7
  112. package/src/skeletal-mesh.ts +4 -0
  113. package/src/snow-field.ts +46 -0
  114. package/src/softbody.ts +6 -5
  115. package/src/startup-offscreen-bytes.ts +168 -0
  116. package/src/startup-readiness.ts +137 -2
  117. package/src/ui-bridge.ts +38 -0
  118. package/src/ui-hit-regions.ts +6 -2
  119. package/src/ui-layer.ts +1 -0
  120. package/src/ui-state.ts +32 -3
  121. package/src/version.ts +1 -1
  122. package/src/viewport.ts +8 -5
  123. package/src/warmup.ts +76 -10
  124. package/src/worker-audio.ts +579 -0
  125. package/src/worker.ts +842 -0
  126. package/src/world-cells.ts +4 -1
  127. package/gpl/LICENSE.GPL +0 -117
  128. package/gpl/convert.py +0 -192
  129. package/gpl/fixtures/make_world_fixture.py +0 -184
  130. package/gpl/recipes/_common.py +0 -180
  131. package/gpl/recipes/bake_ao.py +0 -111
  132. package/gpl/recipes/decimate.py +0 -70
  133. package/gpl/recipes/export_world.py +0 -699
  134. package/gpl/recipes/retarget.py +0 -131
  135. package/gpl/recipes/unwrap.py +0 -71
  136. package/mcp/blender-server.mjs +0 -689
  137. package/mcp/blender.mjs +0 -26
package/src/input.ts CHANGED
@@ -288,7 +288,10 @@ export class InputMap {
288
288
  const lockTargets = new Set<EventTarget>([this.#target, this.#pointerTarget]);
289
289
  if (lockDocument !== undefined) lockTargets.add(lockDocument);
290
290
  for (const target of lockTargets) {
291
- this.#listen(target, "pointerlockchange", () => this.#syncCaptured());
291
+ // A worker has no document to ask; its host forwards the page's verdict as `captured`.
292
+ this.#listen(target, "pointerlockchange", (event) =>
293
+ this.#syncCaptured((event as Event & { captured?: boolean }).captured),
294
+ );
292
295
  }
293
296
  }
294
297
 
@@ -559,6 +562,17 @@ export class InputMap {
559
562
  }
560
563
 
561
564
  #wheelEvent(event: Event): void {
565
+ // The game's wheel listener lives on the window so a game with no HUD still zooms anywhere.
566
+ // A wheel that landed on a DOM overlay (a scrollable settings list, say) belongs to that
567
+ // overlay: bubbling it into the game would zoom the camera while the player scrolls the HUD.
568
+ const eventTarget = event.target;
569
+ if (
570
+ eventTarget !== null &&
571
+ eventTarget !== undefined &&
572
+ eventTarget !== this.#target &&
573
+ eventTarget !== this.#pointerTarget
574
+ )
575
+ return;
562
576
  const wheel = event as Event & { deltaMode?: number; deltaY?: number };
563
577
  const deltaY = wheel.deltaY;
564
578
  if (deltaY === undefined || !Number.isFinite(deltaY)) return;
@@ -641,7 +655,12 @@ export class InputMap {
641
655
  } else if (edgeType === "up" || edgeType === "cancel") {
642
656
  this.#pointers.delete(id);
643
657
  } else if (tracked !== undefined) {
644
- tracked.buttons = buttons;
658
+ // Under pointer lock Chromium sends a move that presses or releases nothing (`button` -1)
659
+ // with `buttons` 0 while a button is held, about every fifth frame: it released a held block
660
+ // or lock button. Locked, the pointer cannot leave the page, so its pointerup still arrives.
661
+ // Unlocked, the same move is what clears a button released outside the window.
662
+ const phantomRelease = this.raw.pointer.captured && buttons === 0 && pointer.button === -1;
663
+ if (!phantomRelease) tracked.buttons = buttons;
645
664
  tracked.position.set(x, y);
646
665
  }
647
666
  const primary = this.#pointers.values().next().value as IRawInputPointer | undefined;
@@ -11,6 +11,24 @@ interface ITransformHistory {
11
11
  references: number;
12
12
  }
13
13
 
14
+ /**
15
+ * Arming the object's world-matrix recompose. The engine composes a node's own matrix from
16
+ * `position`/`quaternion`/`scale` at its walk, whenever the world-matrix dirty flag is set — three's
17
+ * `updateMatrix` for a `matrixAutoUpdate` node, done again one instant later. Core's restore used to cross
18
+ * to request exactly that (one `Mesh.updateMatrix` a body a frame, 300 on the stress lab), so on the engine
19
+ * it sets the flag the walk reads instead. The bridge writes that byte in place (`bindings_scene.cpp`
20
+ * `matrixWorldNeedsUpdate`), so the whole restore crosses nothing. Plain three keeps the call, and so does
21
+ * a node the walk will not compose.
22
+ */
23
+ function recompose(object: Object3D): void {
24
+ const engine = object as Object3D & { __tnCopyMatrixWorld?: unknown };
25
+ if (object.matrixAutoUpdate && engine.__tnCopyMatrixWorld !== undefined) {
26
+ engine.matrixWorldNeedsUpdate = true;
27
+ return;
28
+ }
29
+ object.updateMatrix();
30
+ }
31
+
14
32
  /** Draw-only transforms: simulation and queries always retain the solved tick pose. */
15
33
  export class PhysicsInterpolation {
16
34
  readonly enabled: boolean;
@@ -122,7 +140,7 @@ export class PhysicsInterpolation {
122
140
  continue;
123
141
  history.object.position.copy(history.savedPosition);
124
142
  history.object.quaternion.copy(history.savedRotation);
125
- history.object.updateMatrix();
143
+ recompose(history.object);
126
144
  }
127
145
  }
128
146
  }
@@ -136,15 +136,20 @@ export function watchStartupStall(options: IStallWatchOptions): () => void {
136
136
  /**
137
137
  * Reports a lost GPU device. Every backend that can lose one exposes the same `device.lost`
138
138
  * promise; a renderer that has no device yet (or never will) is not an error here.
139
+ *
140
+ * `destroyedByGame` says whether the game itself shut the renderer down. Only then is a
141
+ * `destroyed` loss quiet: headless Chromium on SwiftShader destroys the device at the first canvas
142
+ * present while the game runs, and that read as a shutdown and was reported nowhere.
139
143
  */
140
144
  export function watchDeviceLoss(
141
145
  device: { lost?: Promise<{ reason?: string; message?: string }> } | undefined,
146
+ destroyedByGame: () => boolean = () => false,
142
147
  ): void {
143
148
  const lost = device?.lost;
144
149
  if (lost === undefined) return;
145
150
  void lost.then((info) => {
146
- // `reason: "destroyed"` is the shutdown path: the game asked for it, so it is not a failure.
147
- if (info?.reason === "destroyed") return;
151
+ // `reason: "destroyed"` after the game stopped is the shutdown path: it asked for it.
152
+ if (info?.reason === "destroyed" && destroyedByGame()) return;
148
153
  // A real loss always says something — WebGPU requires a reason, and Dawn fills in a message.
149
154
  // A resolution carrying neither is a host stub settling its own placeholder promise, which the
150
155
  // desktop host does at loop start; reporting that would cry wolf on every launch.
@@ -0,0 +1,29 @@
1
+ // Multi-bounce on the contact occlusion (PRD-635). Light that an occluder blocks bounces off other pale surfaces, so a
2
+ // pale surface loses less to its own occlusion than a dark one. Unreal passes the short-range AO through the
3
+ // Jimenez et al. 2016 fit ("Practical Realtime Strategies for Accurate Indirect Occlusion") per colour channel, with
4
+ // the albedo capped at 0.5 (UE 5.8.3: Engine/Shaders/Private/DiffuseIndirectComposite.usf:195,
5
+ // Engine/Shaders/Private/DeferredShadingCommon.ush:1364 and
6
+ // Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenSpaceBentNormal.cpp:56).
7
+
8
+ /** The albedo cap, `r.Lumen.ScreenProbeGather.ShortRangeAO.MaxMultibounceAlbedo`. 0 leaves the occlusion as it is. */
9
+ export const UNREAL_AO_MULTIBOUNCE_ALBEDO = 0.5;
10
+
11
+ /** The fit's coefficients as `[slope, offset]` of the albedo, for the cubic's three terms. */
12
+ export const AO_MULTIBOUNCE_FIT = {
13
+ a: [2.0404, -0.3324],
14
+ b: [-4.7951, 0.6417],
15
+ c: [2.7552, 0.6903],
16
+ } as const;
17
+
18
+ /** The occlusion one colour channel keeps after multi-bounce, for the albedo of that channel. */
19
+ export function aoMultiBounce(
20
+ albedo: number,
21
+ occlusion: number,
22
+ cap = UNREAL_AO_MULTIBOUNCE_ALBEDO,
23
+ ): number {
24
+ const base = Math.min(albedo, cap);
25
+ const [a, b, c] = [AO_MULTIBOUNCE_FIT.a, AO_MULTIBOUNCE_FIT.b, AO_MULTIBOUNCE_FIT.c].map(
26
+ ([slope, offset]) => slope * base + offset,
27
+ ) as [number, number, number];
28
+ return Math.max(occlusion, ((occlusion * a + b) * occlusion + c) * occlusion);
29
+ }
@@ -0,0 +1,39 @@
1
+ // The reach of the contact occlusion (PRD-635). Unreal's short-range AO searches a fixed distance on the screen,
2
+ // not in the world: the reach is twice the screen probe downsample factor, 2 x 16 = 32 px
3
+ // (UE 5.8.3: Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:2665), and each step lands at
4
+ // the squared step fraction of it (Engine/Shaders/Private/Lumen/LumenScreenSpaceBentNormal.usf:355-358).
5
+ // The owned engine's GTAO takes it as the `reachPx` uniform (post_effects.cpp), in pixels of the occlusion target.
6
+
7
+ /** Unreal's screen reach in pixels at the display height. */
8
+ export const UNREAL_AO_REACH_PX = 32;
9
+
10
+ // Diagnosis: the contact occlusion's knobs by URL name on a calibration scene, every layer (PRD-635); Reference.ts.in
11
+ // keeps its own table, because a --baseline scaffold has no aoReach.ts. ?gtaoR=M (metres)
12
+ // and ?gtaoS=N are the short names of gtaoRadius and gtaoScale; ?gtaoReachPx=N sets the screen reach (Unreal's is 32);
13
+ // ?gtaoIndirectOnly=0 lets the whole frame take the occlusion.
14
+ const GTAO_KNOBS: Record<string, string> = {
15
+ gtaoR: "gtaoRadius",
16
+ gtaoS: "gtaoScale",
17
+ gtaoRadius: "gtaoRadius",
18
+ gtaoReachPx: "gtaoReachPx",
19
+ gtaoSamples: "gtaoSamples",
20
+ gtaoScale: "gtaoScale",
21
+ gtaoDistanceExponent: "gtaoDistanceExponent",
22
+ gtaoDistanceFalloff: "gtaoDistanceFalloff",
23
+ gtaoThickness: "gtaoThickness",
24
+ gtaoDenoiseRadius: "gtaoDenoiseRadius",
25
+ gtaoMultiBounceAlbedo: "gtaoMultiBounceAlbedo",
26
+ gtaoIndirectOnly: "gtaoIndirectOnly",
27
+ };
28
+
29
+ /** The `WorldEnvironment` options that the page URL sets through the knobs above. */
30
+ export function gtaoUrlKnobs(params: URLSearchParams): Record<string, number | boolean> {
31
+ return Object.fromEntries(
32
+ Object.entries(GTAO_KNOBS)
33
+ .filter(([name]) => params.get(name) !== null)
34
+ .map(([name, option]) => [
35
+ option,
36
+ option === "gtaoIndirectOnly" ? params.get(name) !== "0" : Number(params.get(name)),
37
+ ]),
38
+ );
39
+ }
@@ -0,0 +1,264 @@
1
+ // Auto exposure with Unreal 5.8.3's metering (owner exception to "never own the look", 2026-10-22): a histogram
2
+ // of log luminance, the darkest and brightest 10% ignored, adapted in log2 space. The settings are
3
+ // `exposure-settings.ts`; every field is an override.
4
+ import { type RenderTarget, Texture, Vector2 } from "three";
5
+ import { float, ivec2, nodeObject, texture, textureLoad, uniform, vec4 } from "three/tsl";
6
+ import {
7
+ type Node,
8
+ type NodeBuilder,
9
+ type NodeFrame,
10
+ NodeMaterial,
11
+ NodeUpdateType,
12
+ QuadMesh,
13
+ RendererUtils,
14
+ TempNode,
15
+ } from "three/webgpu";
16
+ import {
17
+ type IExposureSettings,
18
+ exposureLuminance,
19
+ exposureMeter,
20
+ exposureReductionSizes,
21
+ validateExposureSettings,
22
+ } from "./exposure-settings.js";
23
+
24
+ import { rendererEnvironmentBake, rendererFrameGateSkips } from "../renderer.js";
25
+ import {
26
+ type ColourTexture,
27
+ type Decode,
28
+ type Meter,
29
+ adaptExposure,
30
+ exposureBins,
31
+ exposureTarget,
32
+ exposureTiles,
33
+ histogramExposure,
34
+ histogramTiles,
35
+ reduceExposure,
36
+ } from "./exposure-graph.js";
37
+ import { ExposureReadback } from "./exposure-readback.js";
38
+
39
+ /** Scene-referred exposure changes light, never coverage/compositing alpha. */
40
+ export function applyExposure(colour: Node<"vec4">, exposure: Node<"float">): Node<"vec4"> {
41
+ return vec4(colour.rgb.mul(exposure), colour.a);
42
+ }
43
+
44
+ /** Owns scratch targets only. Never draws the world or installs another output transform. */
45
+ export class AutoExposureNode extends TempNode<"float"> {
46
+ static get type(): string {
47
+ return "AutoExposureNode";
48
+ }
49
+ readonly input: ColourTexture;
50
+ readonly settings: Readonly<IExposureSettings>;
51
+ readonly #constant: number;
52
+ readonly #size = new Vector2();
53
+ readonly #sourceSize = uniform(new Vector2(1, 1));
54
+ readonly #reduceSize = uniform(new Vector2(1, 1));
55
+ readonly #blockSize = uniform(new Vector2(1, 1));
56
+ readonly #delta = uniform(0);
57
+ // 0 = history, 1 = seed, 2 = next measured target. The first frame adopts its measured target,
58
+ // as Unreal forces the target on a view's first frame (UE 5.8.3: Engine/Source/Runtime/
59
+ // Renderer/Private/SceneVisibility.cpp:5495, PostProcess/PostProcessEyeAdaptation.cpp:723).
60
+ readonly #resetMode = uniform(2);
61
+ readonly #seed = uniform(0);
62
+ readonly #enabled = uniform(false);
63
+ readonly #bias = uniform(0);
64
+ readonly #quad = new QuadMesh();
65
+ readonly #meterMaterial = new NodeMaterial();
66
+ readonly #reduceMaterial = new NodeMaterial();
67
+ readonly #tilesMaterial = new NodeMaterial();
68
+ readonly #histogramMaterial = new NodeMaterial();
69
+ readonly #adaptMaterial = new NodeMaterial();
70
+ readonly #tilesTarget = exposureTarget();
71
+ readonly #histogramTarget = exposureTarget();
72
+ #readTarget = exposureTarget();
73
+ #writeTarget = exposureTarget();
74
+ #levels: RenderTarget[] = [];
75
+ readonly #reduced = texture(new Texture());
76
+ readonly #blocks = texture(new Texture());
77
+ readonly #previous = texture(this.#readTarget.texture);
78
+ readonly #result = texture(this.#writeTarget.texture);
79
+ #disposed = false;
80
+ readonly #observation: ExposureReadback;
81
+ #gateSkips: number | undefined;
82
+ // Three's runtime accepts undefined on first use, but its declaration requires a state.
83
+ #rendererState: Parameters<typeof RendererUtils.resetRendererState>[1] | undefined;
84
+
85
+ constructor(
86
+ input: ColourTexture,
87
+ settings: IExposureSettings,
88
+ constantExposure: number,
89
+ meter: Meter = (colour, uv) => exposureMeter(colour, uv),
90
+ decode: Decode = (mean) => exposureLuminance(mean),
91
+ ) {
92
+ super("float");
93
+ validateExposureSettings(settings);
94
+ if (!Number.isFinite(Math.fround(constantExposure)) || Math.fround(constantExposure) <= 0)
95
+ throw new Error("Exposure constant must be finite and positive.");
96
+ this.input = input;
97
+ this.settings = Object.freeze({ ...settings });
98
+ const policy = this.settings;
99
+ this.#constant = constantExposure;
100
+ this.#seed.value = Math.log2(settings.initialExposure);
101
+ this.#enabled.value = settings.enabled;
102
+ this.#observation = new ExposureReadback(constantExposure, () => this.#enabled.value);
103
+ this.updateBeforeType = NodeUpdateType.FRAME;
104
+ this.#meterMaterial.fragmentNode = reduceExposure(input, this.#sourceSize, meter);
105
+ this.#reduceMaterial.fragmentNode = reduceExposure(this.#reduced, this.#reduceSize);
106
+ this.#tilesTarget.setSize(exposureBins, exposureTiles);
107
+ this.#histogramTarget.setSize(exposureBins, 1);
108
+ this.#tilesMaterial.fragmentNode = histogramTiles(this.#blocks, this.#blockSize, policy);
109
+ this.#histogramMaterial.fragmentNode = histogramExposure(texture(this.#tilesTarget.texture));
110
+ this.#adaptMaterial.fragmentNode = adaptExposure(
111
+ texture(this.#histogramTarget.texture),
112
+ this.#previous,
113
+ this.#resetMode,
114
+ this.#seed,
115
+ this.#delta,
116
+ policy,
117
+ decode,
118
+ this.#bias,
119
+ );
120
+ }
121
+
122
+ override setup(builder: NodeBuilder): Node<"float"> {
123
+ // Force the existing pass dependency even in disabled mode; off never means unmeasured.
124
+ super.setup(builder);
125
+ return this.#enabled.select(
126
+ textureLoad(this.#result, ivec2(0)).r.exp2(),
127
+ float(this.#constant),
128
+ );
129
+ }
130
+
131
+ get exposureNode(): Node<"float"> {
132
+ return nodeObject(this);
133
+ }
134
+
135
+ reset(exposure?: number): void {
136
+ if (this.#disposed) throw new Error("Exposure node is disposed.");
137
+ if (
138
+ exposure !== undefined &&
139
+ (!Number.isFinite(Math.fround(exposure)) || Math.fround(exposure) <= 0)
140
+ )
141
+ throw new Error("Exposure reset must be finite and positive.");
142
+ this.#resetMode.value = exposure === undefined ? 2 : 1;
143
+ if (exposure !== undefined) this.#seed.value = Math.log2(exposure);
144
+ this.#observation.invalidate();
145
+ }
146
+
147
+ setEnabled(enabled: boolean): void {
148
+ if (typeof enabled !== "boolean") throw new Error("Exposure enabled must be boolean.");
149
+ if (this.#disposed) throw new Error("Exposure node is disposed.");
150
+ this.#enabled.value = enabled;
151
+ this.#observation.invalidate();
152
+ }
153
+
154
+ /**
155
+ * Exposure compensation in stops over the metered key, live: Unreal's AutoExposureBias
156
+ * (UE 5.8.3: Engine/Source/Runtime/Engine/Classes/Engine/Scene.h:1933), which post-process
157
+ * volumes blend at run time. Unreal applies 2^bias outside the smoothing
158
+ * (Engine/Shaders/Private/PostProcessEyeAdaptation.usf:179); here it moves the goal, so a change
159
+ * adapts at `rateUp`/`rateDown` and the reported exposure includes it.
160
+ */
161
+ setExposureBias(stops: number): void {
162
+ if (this.#disposed) throw new Error("Exposure node is disposed.");
163
+ if (!Number.isFinite(Math.fround(stops)))
164
+ throw new Error("Exposure bias must be a finite float32 number of stops.");
165
+ this.#bias.value = stops;
166
+ }
167
+
168
+ getObservation(): Record<string, unknown> {
169
+ return this.#observation.get();
170
+ }
171
+
172
+ override updateBefore(frame: NodeFrame): undefined {
173
+ if (this.#disposed) throw new Error("Exposure node is disposed.");
174
+ const renderer = frame.renderer;
175
+ if (renderer === null) throw new Error("Exposure requires a renderer.");
176
+ if (!Number.isFinite(frame.deltaTime) || frame.deltaTime < 0 || !Number.isFinite(frame.time))
177
+ throw new Error("Exposure frame time must be finite and nonnegative.");
178
+ // The owned engine draws the held scene under the loading cover while it bakes the
179
+ // environment, and that world is still unlit. Metering it clamps the target to maxStops and the
180
+ // first-frame adoption takes it, so the world opens several stops bright when the cover lifts
181
+ // and then adapts down at the authored rate. A bake draw presents nothing; the first presented
182
+ // frame adopts its measured target, as Unreal forces it on a view's first frame (UE 5.8.3:
183
+ // Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessEyeAdaptation.cpp:723).
184
+ if (rendererEnvironmentBake(renderer)) return;
185
+ renderer.getDrawingBufferSize(this.#size);
186
+ // Level 0 meters 4x4 pixels, level 1 averages 16x16. The histogram gathers level 1.
187
+ const sizes = exposureReductionSizes(this.#size.x, this.#size.y).slice(0, 2);
188
+ this.#sourceSize.value.copy(this.#size);
189
+ // The frame gate declines a draw while two frames are still on the GPU. The drawn frame's
190
+ // deltaTime already spans those declined calls (they never reach this node), so the decline is
191
+ // engine pacing, not a suspension: spend that time, up to maxDelta for each frame the call
192
+ // stands for. A frozen page banks no declined render and stays at one maxDelta.
193
+ const skips = rendererFrameGateSkips(renderer);
194
+ const declined =
195
+ skips !== undefined && this.#gateSkips !== undefined
196
+ ? Math.max(0, skips - this.#gateSkips)
197
+ : 0;
198
+ if (skips !== undefined) this.#gateSkips = skips;
199
+ this.#delta.value = Math.min(frame.deltaTime, this.settings.maxDelta * (1 + declined));
200
+ while (this.#levels.length > sizes.length) this.#levels.pop()?.dispose();
201
+ for (const [i, [width, height]] of sizes.entries()) {
202
+ const level = this.#levels[i] ?? exposureTarget();
203
+ this.#levels[i] = level;
204
+ level.setSize(width, height);
205
+ }
206
+ this.#rendererState ??= RendererUtils.saveRendererState(renderer);
207
+ this.#rendererState = RendererUtils.resetRendererState(renderer, this.#rendererState);
208
+ try {
209
+ for (const [i, level] of this.#levels.entries()) {
210
+ const previous = this.#levels[i - 1];
211
+ if (previous !== undefined) {
212
+ this.#reduced.value = previous.texture;
213
+ this.#reduceSize.value.set(previous.width, previous.height);
214
+ }
215
+ this.#quad.material = i === 0 ? this.#meterMaterial : this.#reduceMaterial;
216
+ renderer.setRenderTarget(level);
217
+ this.#quad.render(renderer);
218
+ }
219
+ const final = this.#levels.at(-1);
220
+ if (final === undefined) throw new Error("Exposure reduction is empty.");
221
+ this.#blocks.value = final.texture;
222
+ this.#blockSize.value.set(final.width, final.height);
223
+ this.#quad.material = this.#tilesMaterial;
224
+ renderer.setRenderTarget(this.#tilesTarget);
225
+ this.#quad.render(renderer);
226
+ this.#quad.material = this.#histogramMaterial;
227
+ renderer.setRenderTarget(this.#histogramTarget);
228
+ this.#quad.render(renderer);
229
+ const write = this.#writeTarget;
230
+ this.#previous.value = this.#readTarget.texture;
231
+ this.#quad.material = this.#adaptMaterial;
232
+ renderer.setRenderTarget(write);
233
+ this.#quad.render(renderer);
234
+ this.#result.value = write.texture;
235
+ this.#writeTarget = this.#readTarget;
236
+ this.#readTarget = write;
237
+ this.#resetMode.value = 0;
238
+ this.#observation.report(renderer, write, frame.time, this.settings.reportInterval);
239
+ } finally {
240
+ RendererUtils.restoreRendererState(renderer, this.#rendererState);
241
+ }
242
+ }
243
+
244
+ override dispose(): void {
245
+ if (this.#disposed) return;
246
+ this.#disposed = true;
247
+ this.#observation.dispose();
248
+ for (const level of [
249
+ ...this.#levels,
250
+ this.#tilesTarget,
251
+ this.#histogramTarget,
252
+ this.#readTarget,
253
+ this.#writeTarget,
254
+ ])
255
+ level.dispose();
256
+ this.#levels = [];
257
+ this.#meterMaterial.dispose();
258
+ this.#reduceMaterial.dispose();
259
+ this.#tilesMaterial.dispose();
260
+ this.#histogramMaterial.dispose();
261
+ this.#adaptMaterial.dispose();
262
+ super.dispose();
263
+ }
264
+ }
@@ -0,0 +1,44 @@
1
+ import { ACESFilmicToneMapping, AgXToneMapping, NeutralToneMapping, NoToneMapping } from "three";
2
+ import { installFilmicToneMapping } from "./filmic-tone-mapping.js";
3
+
4
+ /** `filmic` is a fresh Unreal 5.8.3 project's curve and the default; the rest are the named overrides. */
5
+ export type RendererToneMapping = "filmic" | "aces" | "agx" | "neutral" | "none";
6
+
7
+ const THREE_MODE: Record<Exclude<RendererToneMapping, "filmic">, number> = {
8
+ aces: ACESFilmicToneMapping,
9
+ agx: AgXToneMapping,
10
+ neutral: NeutralToneMapping,
11
+ none: NoToneMapping,
12
+ };
13
+
14
+ /**
15
+ * 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.
18
+ */
19
+ export function applyRendererToneMapping(
20
+ raw: unknown,
21
+ mode: RendererToneMapping,
22
+ report: (line: string) => void,
23
+ ): number {
24
+ const target = raw as { toneMapping?: number };
25
+ if (mode !== "filmic") {
26
+ const three = THREE_MODE[mode];
27
+ if (three === undefined)
28
+ throw new Error(
29
+ `Unknown toneMapping '${String(mode)}'. Use one of: filmic, ${Object.keys(THREE_MODE).join(", ")}.`,
30
+ );
31
+ target.toneMapping = three;
32
+ return three;
33
+ }
34
+ const installed = installFilmicToneMapping(raw);
35
+ if (installed !== undefined) {
36
+ target.toneMapping = installed;
37
+ return installed;
38
+ }
39
+ report(
40
+ `TN_TONEMAP ${JSON.stringify({ requested: "filmic", applied: "aces", reason: "renderer:no-node-library" })}`,
41
+ );
42
+ target.toneMapping = ACESFilmicToneMapping;
43
+ return ACESFilmicToneMapping;
44
+ }