@threenative/core 0.3.12 → 0.3.15

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 (165) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +1047 -44
  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-2GPHICV6.js} +1 -1
  6. package/dist/{chunk-GMHATRPW.js → chunk-GEMQJBY4.js} +1650 -383
  7. package/dist/{chunk-VAZM36TV.js → chunk-H4J6IAJE.js} +17 -10
  8. package/dist/{chunk-5O73CDMR.js → chunk-QAMSM3Z5.js} +415 -27
  9. package/dist/{chunk-2Z44XSI2.js → chunk-QAQHYOWY.js} +3 -7
  10. package/dist/{chunk-DBELTTTM.js → chunk-U4YHUKKL.js} +1 -1
  11. package/dist/{chunk-OKXUCASC.js → chunk-VBBYWGAT.js} +3 -4
  12. package/dist/chunk-VP43GIWW.js +18 -0
  13. package/dist/{chunk-N5LRP4BR.js → chunk-VQRPEOKY.js} +66 -3
  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 +871 -1018
  20. package/dist/index.js +4786 -1631
  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-BADStsTn.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 +280 -16
  33. package/dist/world.js +1529 -642
  34. package/mcp/animation-server.mjs +1 -1
  35. package/mcp/engine-server.mjs +135 -11
  36. package/mcp/servers.mjs +4 -4
  37. package/package.json +10 -6
  38. package/scripts/ensure-mcp.mjs +6 -1
  39. package/src/animation-batch.ts +193 -0
  40. package/src/animation-layers.ts +7 -3
  41. package/src/animation.ts +209 -29
  42. package/src/asset-cache.ts +3 -3
  43. package/src/asset-memo.ts +202 -0
  44. package/src/assets.ts +436 -131
  45. package/src/auto-batch.ts +190 -44
  46. package/src/clustered-batch.ts +146 -3
  47. package/src/clustered-mesh.ts +548 -20
  48. package/src/compute-driven.ts +1 -1
  49. package/src/config.ts +8 -0
  50. package/src/debug.ts +119 -22
  51. package/src/dev-global.ts +54 -0
  52. package/src/displaced-surface.ts +428 -0
  53. package/src/engine-hooks.ts +37 -0
  54. package/src/frame-budget.ts +35 -3
  55. package/src/game-boot-phase.ts +269 -0
  56. package/src/game-dev-tools.ts +7 -14
  57. package/src/game-frame-loop.ts +45 -82
  58. package/src/game-startup.ts +145 -70
  59. package/src/game-ui.ts +84 -0
  60. package/src/game.ts +168 -552
  61. package/src/gamepad-mappings.ts +269 -0
  62. package/src/generated/console-markers.ts +14 -0
  63. package/src/geometry-capture.ts +28 -4
  64. package/src/gpu-readings.ts +98 -0
  65. package/src/gpu-scene-bvh.ts +149 -36
  66. package/src/grass-field.ts +628 -0
  67. package/src/hot.ts +4 -7
  68. package/src/index.ts +227 -8
  69. package/src/input.ts +237 -25
  70. package/src/instanced-batch-lod.ts +3 -8
  71. package/src/interpolation.ts +171 -40
  72. package/src/look/ao-admission.ts +4 -3
  73. package/src/look/auto-exposure.ts +5 -16
  74. package/src/look/default-tone-mapping.ts +41 -5
  75. package/src/look/local-exposure.ts +2 -7
  76. package/src/look/quad-pass.ts +21 -0
  77. package/src/look/quality.ts +4 -0
  78. package/src/look/unreal-bloom.ts +4 -13
  79. package/src/look/world-environment.ts +58 -115
  80. package/src/merge-parts.ts +20 -24
  81. package/src/model-lod.ts +97 -14
  82. package/src/particle-significance.ts +12 -0
  83. package/src/particles.ts +19 -10
  84. package/src/platform.ts +23 -4
  85. package/src/profiling/FrameStages.ts +5 -6
  86. package/src/profiling/Spans.ts +3 -17
  87. package/src/profiling/debug-telemetry.ts +2 -6
  88. package/src/profiling/render-list-validate.ts +6 -15
  89. package/src/projection-marker.ts +2 -1
  90. package/src/quiet-markers.ts +3 -10
  91. package/src/render/cpu-bvh.ts +100 -0
  92. package/src/render/depth-pyramid.ts +6 -14
  93. package/src/render/environment/environmentContribution.ts +202 -0
  94. package/src/render/environment/environmentRadiance.ts +44 -0
  95. package/src/render/environment/environmentSampleCache.ts +56 -0
  96. package/src/render/environment/environmentSampling.ts +201 -0
  97. package/src/render/environment/environmentSnapshot.ts +71 -0
  98. package/src/render/environment/gate.ts +57 -0
  99. package/src/render/material-key.ts +21 -1
  100. package/src/render/mesh-pool.ts +3 -19
  101. package/src/render/probe-trace.ts +872 -0
  102. package/src/render/probe-volume.ts +780 -34
  103. package/src/render/radiance-cache.ts +17 -0
  104. package/src/render/screen-probe-gather.ts +303 -0
  105. package/src/render/short-range-ao.ts +274 -0
  106. package/src/render/virtual-shadow-partial.ts +13 -0
  107. package/src/render/virtual-shadow.ts +18 -16
  108. package/src/render/world-impostor-surface.ts +207 -9
  109. package/src/render/world-impostor.ts +5 -2
  110. package/src/render-camera-cull.ts +105 -4
  111. package/src/render-environment.ts +41 -0
  112. package/src/renderer-config.ts +36 -0
  113. package/src/renderer-facts.ts +37 -0
  114. package/src/renderer.ts +78 -32
  115. package/src/resolution-scaler.ts +3 -2
  116. package/src/scatter-field.ts +496 -0
  117. package/src/scene-entry-inspectors.ts +61 -0
  118. package/src/snow-field.ts +1 -0
  119. package/src/startup-offscreen-bytes.ts +84 -0
  120. package/src/state.ts +16 -3
  121. package/src/static-transform.ts +100 -25
  122. package/src/streamed-textures.ts +112 -0
  123. package/src/streaming.ts +68 -4
  124. package/src/texture-streaming.ts +331 -0
  125. package/src/tile-ring.ts +294 -0
  126. package/src/version.ts +1 -1
  127. package/src/warmup.ts +15 -2
  128. package/src/worker.ts +12 -2
  129. package/src/world-bundle-safety.ts +55 -10
  130. package/src/world-cell-batches.ts +166 -200
  131. package/src/world-cell-chunks.ts +3 -7
  132. package/src/world-cell-data.ts +7 -0
  133. package/src/world-cell-impostors.ts +20 -8
  134. package/src/world-cell-models.ts +36 -8
  135. package/src/world-cell-options.ts +2 -14
  136. package/src/world-cell-placements.ts +194 -90
  137. package/src/world-cell-prewarm.ts +39 -4
  138. package/src/world-cell-records.ts +401 -0
  139. package/src/world-cell-render-bundles.ts +2 -2
  140. package/src/world-cell-render-gpu-dress.ts +17 -19
  141. package/src/world-cell-render-main-cull.ts +73 -17
  142. package/src/world-cell-render-util.ts +18 -5
  143. package/src/world-cell-render.ts +13 -5
  144. package/src/world-cell-residency.ts +15 -6
  145. package/src/world-cell-stale.ts +238 -0
  146. package/src/world-cells.ts +23 -6
  147. package/src/world-gpu-flags.ts +18 -50
  148. package/src/world-gpu-reference.ts +22 -8
  149. package/src/world-gpu-scene.ts +44 -24
  150. package/src/world-gpu-shadow.ts +21 -8
  151. package/src/world-gpu-types.ts +41 -13
  152. package/src/world-load-limiter.ts +5 -0
  153. package/src/world-model-sections.ts +80 -0
  154. package/src/world-river-ribbon.ts +273 -0
  155. package/src/world-root-frame.ts +39 -0
  156. package/src/world-shore-field.ts +91 -0
  157. package/src/world-static-pose.ts +163 -0
  158. package/src/world-surface-sampler.ts +48 -0
  159. package/src/world-terrain-splat.ts +10 -18
  160. package/src/world-tile-budget.ts +4 -11
  161. package/src/world-tiles.ts +79 -12
  162. package/src/world-validate.ts +6 -14
  163. package/src/world-warm.ts +51 -0
  164. package/src/world-water-bodies.ts +113 -3
  165. package/src/world.ts +13 -0
@@ -11,9 +11,9 @@ import {
11
11
  DISCRETE_LOD_DEFAULT_HYSTERESIS,
12
12
  type IModelLodController,
13
13
  biasedLodDistance,
14
- conservativeViewDepth,
15
14
  lodChainOf,
16
15
  registerModelLodController,
16
+ selectLodFor,
17
17
  selectLodLevel,
18
18
  } from "./model-lod.js";
19
19
 
@@ -201,12 +201,7 @@ export function attachInstancedLod(mesh: InstancedMesh, options: IInstancedLodOp
201
201
  mesh.getMatrixAt(index, matrix);
202
202
  world.multiplyMatrices(mesh.matrixWorld, matrix);
203
203
  sphere.copy(local).applyMatrix4(world);
204
- const view = conservativeViewDepth(
205
- camera,
206
- sphere.center,
207
- sphere.radius,
208
- (camera as Camera & { near?: number }).near ?? 0,
209
- );
204
+ const view = selectLodFor(camera, sphere, (camera as Camera & { near?: number }).near ?? 0);
210
205
  let level = 0;
211
206
  if (options.lods !== undefined) {
212
207
  const distance = biasedLodDistance(cameraPosition.distanceTo(sphere.center));
@@ -224,7 +219,7 @@ export function attachInstancedLod(mesh: InstancedMesh, options: IInstancedLodOp
224
219
  {
225
220
  camera,
226
221
  viewportHeight,
227
- depth: biasedLodDistance(view.depth),
222
+ depth: view.biased,
228
223
  degenerate: view.degenerate,
229
224
  },
230
225
  ],
@@ -1,4 +1,34 @@
1
- import { type Object3D, Quaternion, Vector3 } from "three";
1
+ import { type Object3D, type Object3D as Object3DType, Quaternion, Vector3 } from "three";
2
+
3
+ import { hasCopyMatrixWorldHook } from "./engine-hooks.js";
4
+ import { debugRequested, measureDebug } from "./profiling/debug-telemetry.js";
5
+
6
+ /**
7
+ * The five engine-internal methods the owned engine puts on an `Object3D` for the C++ pose history
8
+ * (PRD-877). Plain three.js has none of them, and the JavaScript loops below stay the path there.
9
+ * `runtime-native/src/engine/abi/bindings_scene.cpp` defines these names; a rename on either side
10
+ * takes every caller down the slow path, which the spec beside this one fails on.
11
+ */
12
+ interface IPoseOwner {
13
+ __tnPoseWatch(objects: Object3DType[]): number;
14
+ __tnPoseReset(objects: Object3DType[]): void;
15
+ __tnPoseTick(phase: number): void;
16
+ __tnPoseBlend(alpha: number): void;
17
+ __tnPoseRestore(): void;
18
+ }
19
+
20
+ type PoseOwnerCarrier = Object3DType & Partial<IPoseOwner>;
21
+
22
+ function poseOwnerOf(object: Object3DType): IPoseOwner | undefined {
23
+ const candidate = object as PoseOwnerCarrier;
24
+ return typeof candidate.__tnPoseTick === "function" &&
25
+ typeof candidate.__tnPoseBlend === "function" &&
26
+ typeof candidate.__tnPoseRestore === "function" &&
27
+ typeof candidate.__tnPoseWatch === "function" &&
28
+ typeof candidate.__tnPoseReset === "function"
29
+ ? (candidate as IPoseOwner)
30
+ : undefined;
31
+ }
2
32
 
3
33
  interface ITransformHistory {
4
34
  readonly object: Object3D;
@@ -21,9 +51,8 @@ interface ITransformHistory {
21
51
  * a node the walk will not compose.
22
52
  */
23
53
  function recompose(object: Object3D): void {
24
- const engine = object as Object3D & { __tnCopyMatrixWorld?: unknown };
25
- if (object.matrixAutoUpdate && engine.__tnCopyMatrixWorld !== undefined) {
26
- engine.matrixWorldNeedsUpdate = true;
54
+ if (object.matrixAutoUpdate && hasCopyMatrixWorldHook(object)) {
55
+ object.matrixWorldNeedsUpdate = true;
27
56
  return;
28
57
  }
29
58
  object.updateMatrix();
@@ -33,14 +62,69 @@ function recompose(object: Object3D): void {
33
62
  export class PhysicsInterpolation {
34
63
  readonly enabled: boolean;
35
64
  readonly overrideSource: "default" | "defineGame";
36
- readonly #objects = new Map<Object3D, ITransformHistory>();
65
+ readonly #objects = new Map<Object3DType, ITransformHistory>();
66
+ readonly #debug = debugRequested();
37
67
  #lastReport = "";
68
+ /** The engine object the C++ history lives on: created lazily, never added to a scene. */
69
+ #ownerInjected: IPoseOwner | null = null;
70
+ #ownerResolved: IPoseOwner | null | undefined;
71
+ /** Bumped whenever the tracked set changes, so the engine is told only when it must be. */
72
+ #membership = 0;
73
+ #watchedMembership = -1;
38
74
 
39
- constructor(enabled?: boolean) {
75
+ constructor(enabled?: boolean, poseOwner?: Object3DType) {
40
76
  if (enabled !== undefined && typeof enabled !== "boolean")
41
77
  throw new Error("physicsInterpolation must be a boolean.");
42
78
  this.enabled = enabled ?? true;
43
79
  this.overrideSource = enabled === undefined ? "default" : "defineGame";
80
+ if (poseOwner !== undefined) {
81
+ const owner = poseOwnerOf(poseOwner);
82
+ if (owner === undefined)
83
+ throw new Error("The pose owner must carry the engine's five pose methods.");
84
+ this.#ownerInjected = owner;
85
+ }
86
+ }
87
+
88
+ /**
89
+ * The engine path, or null on plain three.js. Resolving it once and keeping the answer means a
90
+ * frame never probes for methods it already knows are absent.
91
+ */
92
+ get #owner(): IPoseOwner | null {
93
+ if (this.#ownerResolved === undefined) {
94
+ if (this.#ownerInjected !== null) this.#ownerResolved = this.#ownerInjected;
95
+ else {
96
+ // The tracked bodies are the objects the host demonstrably built: a game body carries the
97
+ // engine's methods when the host is the engine, and a detached `new Object3D()` created here
98
+ // may not be engine-backed at all. The first body that answers is the owner for all of them.
99
+ let found: IPoseOwner | null = null;
100
+ for (const object of this.#objects.keys()) {
101
+ const candidate = poseOwnerOf(object);
102
+ if (candidate !== undefined) {
103
+ found = candidate;
104
+ break;
105
+ }
106
+ }
107
+ this.#ownerResolved = found;
108
+ }
109
+ }
110
+ return this.#ownerResolved;
111
+ }
112
+
113
+ /** Which path this instance took, reported on every membership change. */
114
+ get path(): "engine" | "javascript" {
115
+ return this.#owner === null ? "javascript" : "engine";
116
+ }
117
+
118
+ /** Tells the engine the current tracked set, only when it changed since the last time. */
119
+ #watchIfDirty(owner: IPoseOwner): void {
120
+ if (this.#watchedMembership === this.#membership) return;
121
+ owner.__tnPoseWatch([...this.#objects.keys()]);
122
+ this.#watchedMembership = this.#membership;
123
+ }
124
+
125
+ /** One region of a frame step, timed only when this launch asked for debug telemetry. */
126
+ #measured<T>(name: string, caller: string, run: () => T): T {
127
+ return this.#debug ? measureDebug(name, "update", caller, run) : run();
44
128
  }
45
129
 
46
130
  track(object: Object3D): () => void {
@@ -58,6 +142,9 @@ export class PhysicsInterpolation {
58
142
  references: 0,
59
143
  };
60
144
  this.#objects.set(object, history);
145
+ this.#membership += 1;
146
+ // A body tracked after a plain one may be the first engine-backed object; ask again.
147
+ if (this.#ownerResolved === null) this.#ownerResolved = undefined;
61
148
  }
62
149
  history.references += 1;
63
150
  let active = true;
@@ -65,14 +152,17 @@ export class PhysicsInterpolation {
65
152
  if (!active) return;
66
153
  active = false;
67
154
  history.references -= 1;
68
- if (history.references === 0 && this.#objects.get(object) === history)
155
+ if (history.references === 0 && this.#objects.get(object) === history) {
69
156
  this.#objects.delete(object);
157
+ this.#membership += 1;
158
+ }
70
159
  };
71
160
  }
72
161
 
73
162
  reset(object: Object3D): void {
74
163
  const history = this.#objects.get(object);
75
164
  if (history === undefined) return;
165
+ this.#owner?.__tnPoseReset([object]);
76
166
  history.previousPosition.copy(object.position);
77
167
  history.previousRotation.copy(object.quaternion);
78
168
  history.currentPosition.copy(object.position);
@@ -81,28 +171,50 @@ export class PhysicsInterpolation {
81
171
 
82
172
  clear(): void {
83
173
  this.#objects.clear();
174
+ this.#membership += 1;
84
175
  }
85
176
 
86
177
  beginTick(): void {
87
- for (const history of this.#objects.values()) {
88
- history.previousPosition.copy(history.object.position);
89
- history.previousRotation.copy(history.object.quaternion);
178
+ const owner = this.#owner;
179
+ if (owner !== null) {
180
+ this.#watchIfDirty(owner);
181
+ this.#measured("interpolationTick", "PhysicsInterpolation.beginTick", () =>
182
+ owner.__tnPoseTick(0),
183
+ );
184
+ return;
90
185
  }
186
+ this.#measured("interpolationTick", "PhysicsInterpolation.beginTick", () => {
187
+ for (const history of this.#objects.values()) {
188
+ history.previousPosition.copy(history.object.position);
189
+ history.previousRotation.copy(history.object.quaternion);
190
+ }
191
+ });
91
192
  }
92
193
 
93
194
  endTick(): void {
94
- for (const history of this.#objects.values()) {
95
- history.currentPosition.copy(history.object.position);
96
- history.currentRotation.copy(history.object.quaternion);
195
+ const owner = this.#owner;
196
+ if (owner !== null) {
197
+ this.#measured("interpolationTick", "PhysicsInterpolation.endTick", () =>
198
+ owner.__tnPoseTick(1),
199
+ );
200
+ return;
97
201
  }
202
+ this.#measured("interpolationTick", "PhysicsInterpolation.endTick", () => {
203
+ for (const history of this.#objects.values()) {
204
+ history.currentPosition.copy(history.object.position);
205
+ history.currentRotation.copy(history.object.quaternion);
206
+ }
207
+ });
98
208
  }
99
209
 
100
210
  render<T>(alpha: number, draw: () => T): T {
101
211
  if (!Number.isFinite(alpha) || alpha < 0 || alpha > 1)
102
212
  throw new Error("Interpolation alpha must be in [0, 1].");
213
+ const owner = this.#owner;
103
214
  const report = JSON.stringify({
104
215
  enabled: this.enabled,
105
216
  overrideSource: this.overrideSource,
217
+ path: owner === null ? "javascript" : "engine",
106
218
  trackedObjects: this.#objects.size,
107
219
  });
108
220
  if (report !== this.#lastReport) {
@@ -110,38 +222,57 @@ export class PhysicsInterpolation {
110
222
  console.info(`TN_PHYSICS_INTERPOLATION:${report}`);
111
223
  }
112
224
  if (!this.enabled || alpha === 1) return draw();
225
+ if (owner !== null) {
226
+ // The reference counts, the early returns and the try/finally stay here; the poses move in C++.
227
+ // The watch crosses only when the tracked set changed since the engine last heard of it.
228
+ this.#watchIfDirty(owner);
229
+ this.#measured("interpolationBlend", "PhysicsInterpolation.render", () =>
230
+ owner.__tnPoseBlend(alpha),
231
+ );
232
+ try {
233
+ return draw();
234
+ } finally {
235
+ this.#measured("interpolationRestore", "PhysicsInterpolation.render", () =>
236
+ owner.__tnPoseRestore(),
237
+ );
238
+ }
239
+ }
113
240
  // Retain the exact participants even if Scene.render changes scenes or unregisters a body.
114
241
  const histories = [...this.#objects.values()];
115
242
  try {
116
- for (const history of histories) {
117
- const { object } = history;
118
- // An edit outside the fixed update is a discontinuity, never a new tick to blend across.
119
- if (
120
- !object.position.equals(history.currentPosition) ||
121
- !object.quaternion.equals(history.currentRotation)
122
- )
123
- this.reset(object);
124
- history.savedPosition.copy(object.position);
125
- history.savedRotation.copy(object.quaternion);
126
- object.position.lerpVectors(history.previousPosition, history.currentPosition, alpha);
127
- object.quaternion.slerpQuaternions(
128
- history.previousRotation,
129
- history.currentRotation,
130
- alpha,
131
- );
132
- }
243
+ this.#measured("interpolationBlend", "PhysicsInterpolation.render", () => {
244
+ for (const history of histories) {
245
+ const { object } = history;
246
+ // An edit outside the fixed update is a discontinuity, never a new tick to blend across.
247
+ if (
248
+ !object.position.equals(history.currentPosition) ||
249
+ !object.quaternion.equals(history.currentRotation)
250
+ )
251
+ this.reset(object);
252
+ history.savedPosition.copy(object.position);
253
+ history.savedRotation.copy(object.quaternion);
254
+ object.position.lerpVectors(history.previousPosition, history.currentPosition, alpha);
255
+ object.quaternion.slerpQuaternions(
256
+ history.previousRotation,
257
+ history.currentRotation,
258
+ alpha,
259
+ );
260
+ }
261
+ });
133
262
  return draw();
134
263
  } finally {
135
- for (const history of histories) {
136
- if (
137
- history.object.position.equals(history.savedPosition) &&
138
- history.object.quaternion.equals(history.savedRotation)
139
- )
140
- continue;
141
- history.object.position.copy(history.savedPosition);
142
- history.object.quaternion.copy(history.savedRotation);
143
- recompose(history.object);
144
- }
264
+ this.#measured("interpolationRestore", "PhysicsInterpolation.render", () => {
265
+ for (const history of histories) {
266
+ if (
267
+ history.object.position.equals(history.savedPosition) &&
268
+ history.object.quaternion.equals(history.savedRotation)
269
+ )
270
+ continue;
271
+ history.object.position.copy(history.savedPosition);
272
+ history.object.quaternion.copy(history.savedRotation);
273
+ recompose(history.object);
274
+ }
275
+ });
145
276
  }
146
277
  }
147
278
  }
@@ -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);