@threenative/core 0.3.11 → 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 (236) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +1988 -204
  3. package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
  4. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  5. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
  6. package/dist/chunk-4SRAQFTU.js +133 -0
  7. package/dist/chunk-CFGTPFUH.js +231 -0
  8. package/dist/chunk-DIPIJICH.js +8916 -0
  9. package/dist/chunk-EEABDLUC.js +2237 -0
  10. package/dist/chunk-EFWZWLPY.js +1895 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-GYUZJQ7U.js +280 -0
  13. package/dist/chunk-H4J6IAJE.js +504 -0
  14. package/dist/chunk-KIRUKTBQ.js +187 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-SV4QVUTQ.js +31 -0
  17. package/dist/chunk-U4YHUKKL.js +615 -0
  18. package/dist/chunk-VP43GIWW.js +18 -0
  19. package/dist/chunk-XDTZ4QMO.js +160 -0
  20. package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
  21. package/dist/{game-DzMcitDO.d.ts → game-k8K3hZai.d.ts} +85 -9
  22. package/dist/hot.d.ts +5 -4
  23. package/dist/hot.js +5 -52
  24. package/dist/index.d.ts +633 -1351
  25. package/dist/index.js +12873 -23068
  26. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-DPTzeCcD.d.ts} +35 -3
  27. package/dist/playtest.d.ts +5 -4
  28. package/dist/playtest.js +25 -75
  29. package/dist/quality-BYqKGAwo.d.ts +868 -0
  30. package/dist/react-css.js +1 -215
  31. package/dist/react.d.ts +3 -2
  32. package/dist/render-environment.d.ts +170 -0
  33. package/dist/render-environment.js +352 -0
  34. package/dist/{renderer-rZm0hVqq.d.ts → renderer-BtOSseYf.d.ts} +42 -35
  35. package/dist/spells/index.d.ts +643 -0
  36. package/dist/spells/index.js +1558 -0
  37. package/dist/spells/ultra/index.d.ts +1600 -0
  38. package/dist/spells/ultra/index.js +6804 -0
  39. package/dist/terrain-jobs-worker.js +1 -123
  40. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  41. package/dist/ui-layer.js +6 -384
  42. package/dist/worker.js +13 -43
  43. package/dist/world.d.ts +988 -268
  44. package/dist/world.js +17464 -18290
  45. package/mcp/animation-server.mjs +1 -1
  46. package/mcp/animation.mjs +2 -3
  47. package/mcp/engine-server.mjs +245 -52
  48. package/mcp/servers.mjs +10 -3
  49. package/mcp/terrain.mjs +8 -0
  50. package/package.json +19 -7
  51. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  52. package/patches/three@0.187.0.patch +2004 -407
  53. package/src/animation-batch.ts +193 -0
  54. package/src/animation-layers.ts +7 -3
  55. package/src/animation.ts +209 -29
  56. package/src/asset-cache.ts +3 -3
  57. package/src/asset-memo.ts +202 -0
  58. package/src/assets.ts +437 -125
  59. package/src/auto-batch.ts +190 -44
  60. package/src/card-lod.ts +152 -0
  61. package/src/compressed-texture-preparation.ts +1008 -0
  62. package/src/compute-driven.ts +1 -1
  63. package/src/config.ts +8 -0
  64. package/src/debug.ts +103 -22
  65. package/src/dev-global.ts +54 -0
  66. package/src/engine-hooks.ts +37 -0
  67. package/src/frame-budget.ts +50 -23
  68. package/src/game-boot-phase.ts +269 -0
  69. package/src/game-dev-tools.ts +86 -0
  70. package/src/game-frame-loop.ts +958 -0
  71. package/src/game-renderer-metrics.ts +77 -0
  72. package/src/game-startup.ts +1076 -0
  73. package/src/game-ui.ts +84 -0
  74. package/src/game-validate.ts +70 -0
  75. package/src/game.ts +198 -2264
  76. package/src/gamepad-mappings.ts +269 -0
  77. package/src/generated/console-markers.ts +13 -0
  78. package/src/geometry-capture.ts +28 -4
  79. package/src/gpu-readings.ts +98 -0
  80. package/src/gpu-scene-bvh.ts +149 -36
  81. package/src/hot.ts +4 -7
  82. package/src/index.ts +141 -9
  83. package/src/input.ts +237 -25
  84. package/src/instanced-batch-lod.ts +3 -8
  85. package/src/interpolation.ts +171 -40
  86. package/src/launch-diagnostics.ts +22 -12
  87. package/src/look/ao-admission.ts +25 -0
  88. package/src/look/auto-exposure.ts +5 -16
  89. package/src/look/default-tone-mapping.ts +41 -5
  90. package/src/look/filmic-tone-mapping.ts +15 -13
  91. package/src/look/local-exposure.ts +2 -7
  92. package/src/look/look-diagnostics.ts +3 -3
  93. package/src/look/quad-pass.ts +21 -0
  94. package/src/look/quality.ts +14 -5
  95. package/src/look/unreal-bloom.ts +4 -13
  96. package/src/look/world-environment.ts +113 -103
  97. package/src/loop.ts +29 -0
  98. package/src/merge-parts.ts +20 -24
  99. package/src/model-lod.ts +139 -17
  100. package/src/particle-kinds.ts +515 -0
  101. package/src/particle-significance.ts +12 -0
  102. package/src/particles.ts +19 -10
  103. package/src/picking.ts +17 -3
  104. package/src/platform.ts +23 -4
  105. package/src/playtest.ts +27 -1
  106. package/src/profiling/FrameStages.ts +5 -6
  107. package/src/profiling/Spans.ts +3 -17
  108. package/src/profiling/debug-telemetry.ts +2 -6
  109. package/src/profiling/render-list-validate.ts +6 -15
  110. package/src/projection-apply.ts +4 -1
  111. package/src/projection-marker.ts +2 -1
  112. package/src/projection-plan.ts +9 -6
  113. package/src/quiet-markers.ts +3 -10
  114. package/src/render/cpu-bvh.ts +100 -0
  115. package/src/render/depth-pyramid.ts +6 -14
  116. package/src/render/environment/environmentContribution.ts +202 -0
  117. package/src/render/environment/environmentRadiance.ts +44 -0
  118. package/src/render/environment/environmentSampleCache.ts +56 -0
  119. package/src/render/environment/environmentSampling.ts +201 -0
  120. package/src/render/environment/environmentSnapshot.ts +71 -0
  121. package/src/render/environment/gate.ts +57 -0
  122. package/src/render/mesh-pool.ts +4 -20
  123. package/src/render/probe-trace.ts +872 -0
  124. package/src/render/probe-volume.ts +780 -34
  125. package/src/render/radiance-cache.ts +17 -0
  126. package/src/render/resolution-subrect.ts +2 -0
  127. package/src/render/rough-diffuse.ts +46 -12
  128. package/src/render/soft-shadow.ts +27 -12
  129. package/src/render/virtual-shadow-adaptive.ts +55 -0
  130. package/src/render/virtual-shadow-casters.ts +175 -0
  131. package/src/render/virtual-shadow-layers.ts +76 -0
  132. package/src/render/virtual-shadow-level.ts +224 -0
  133. package/src/render/virtual-shadow-markers.ts +193 -0
  134. package/src/render/virtual-shadow-options.ts +370 -0
  135. package/src/render/virtual-shadow-pages.ts +5 -0
  136. package/src/render/virtual-shadow-partial.ts +13 -0
  137. package/src/render/virtual-shadow.ts +231 -1008
  138. package/src/render/world-impostor-surface.ts +402 -40
  139. package/src/render/world-impostor.ts +5 -2
  140. package/src/render-camera-cull.ts +98 -3
  141. package/src/render-environment.ts +41 -0
  142. package/src/render-pass-budget.ts +34 -7
  143. package/src/renderProjection.ts +22 -0
  144. package/src/renderer-config.ts +36 -0
  145. package/src/renderer-facts.ts +37 -0
  146. package/src/renderer.ts +144 -65
  147. package/src/resolution-scaler.ts +3 -2
  148. package/src/scene-entry-inspectors.ts +61 -0
  149. package/src/snow-field.ts +2 -1
  150. package/src/spells/cast-pool.ts +361 -0
  151. package/src/spells/index.ts +177 -0
  152. package/src/spells/mechanisms.ts +295 -0
  153. package/src/spells/reaction-field.ts +415 -0
  154. package/src/spells/spell-lights.ts +139 -0
  155. package/src/spells/spell-world.ts +187 -0
  156. package/src/spells/spell.ts +397 -0
  157. package/src/spells/spells.ts +283 -0
  158. package/src/spells/ultra/engine/camera.ts +184 -0
  159. package/src/spells/ultra/engine/quality.ts +96 -0
  160. package/src/spells/ultra/index.ts +52 -0
  161. package/src/spells/ultra/main.ts +305 -0
  162. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  163. package/src/spells/ultra/spells/cast.ts +233 -0
  164. package/src/spells/ultra/spells/fire.ts +1267 -0
  165. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  166. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  167. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  168. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  169. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  170. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  171. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  172. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  173. package/src/spells/ultra/vfx/common.ts +1195 -0
  174. package/src/spells/ultra/vfx/noise.ts +441 -0
  175. package/src/startup-offscreen-bytes.ts +78 -0
  176. package/src/startup-readiness.ts +128 -34
  177. package/src/static-transform.ts +25 -19
  178. package/src/streamed-textures.ts +112 -0
  179. package/src/streaming.ts +68 -4
  180. package/src/texture-streaming.ts +331 -0
  181. package/src/version.ts +1 -1
  182. package/src/warmup.ts +56 -8
  183. package/src/water-surface.ts +9 -3
  184. package/src/worker.ts +12 -2
  185. package/src/world-bundle-safety.ts +446 -0
  186. package/src/world-cell-batches.ts +1178 -0
  187. package/src/world-cell-chunks.ts +1128 -0
  188. package/src/world-cell-data.ts +995 -0
  189. package/src/world-cell-impostors.ts +1461 -0
  190. package/src/world-cell-lod-bias.ts +151 -0
  191. package/src/world-cell-models.ts +1074 -0
  192. package/src/world-cell-options.ts +177 -0
  193. package/src/world-cell-placements.ts +798 -0
  194. package/src/world-cell-prewarm.ts +592 -0
  195. package/src/world-cell-readiness.ts +357 -0
  196. package/src/world-cell-records.ts +401 -0
  197. package/src/world-cell-render-bundles.ts +459 -0
  198. package/src/world-cell-render-gpu-dress.ts +710 -0
  199. package/src/world-cell-render-main-cull.ts +540 -0
  200. package/src/world-cell-render-shadow-claims.ts +198 -0
  201. package/src/world-cell-render-util.ts +259 -0
  202. package/src/world-cell-render.ts +1501 -0
  203. package/src/world-cell-residency.ts +754 -0
  204. package/src/world-cell-stale.ts +238 -0
  205. package/src/world-cells.ts +1335 -10418
  206. package/src/world-chunk-shadow.ts +308 -0
  207. package/src/world-collar.ts +315 -0
  208. package/src/world-gpu-flags.ts +131 -0
  209. package/src/world-gpu-readback.ts +881 -0
  210. package/src/world-gpu-reference.ts +524 -0
  211. package/src/world-gpu-scene.ts +256 -2286
  212. package/src/world-gpu-shadow.ts +203 -0
  213. package/src/world-gpu-types.ts +409 -0
  214. package/src/world-gpu-validation.ts +518 -0
  215. package/src/world-heightfield.ts +802 -0
  216. package/src/world-load-limiter.ts +111 -0
  217. package/src/world-model-sections.ts +80 -0
  218. package/src/world-noise.ts +241 -0
  219. package/src/world-package.ts +42 -0
  220. package/src/world-region.ts +1 -1
  221. package/src/world-river-ribbon.ts +282 -0
  222. package/src/world-root-frame.ts +39 -0
  223. package/src/world-shore-field.ts +91 -0
  224. package/src/world-static-pose.ts +163 -0
  225. package/src/world-surface-sampler.ts +48 -0
  226. package/src/world-terrain-splat.ts +361 -153
  227. package/src/world-tile-budget.ts +249 -0
  228. package/src/world-tile-geometry.ts +469 -0
  229. package/src/world-tile-lod.ts +408 -0
  230. package/src/world-tile-observation.ts +566 -0
  231. package/src/world-tile-stitch.ts +166 -0
  232. package/src/world-tiles.ts +247 -1755
  233. package/src/world-validate.ts +6 -14
  234. package/src/world-warm.ts +51 -0
  235. package/src/world-water-bodies.ts +359 -0
  236. package/src/world.ts +48 -741
@@ -1,11 +1,9 @@
1
1
  /**
2
2
  * Why a launch stopped, said where the player can read it.
3
3
  *
4
- * A launch has exactly two ways to go wrong quietly, and both were measured on a real game:
5
- * progress stops moving (a decode that never returns, an asset that never settles) and the GPU
6
- * device is lost (another process had taken 94% of VRAM). In both the loop keeps iterating, the
7
- * loading layer keeps painting, and the only account of what happened is a line on stdout — which
8
- * a player does not have, and which a bug report therefore never carries.
4
+ * A launch can fail when a scene load rejects, progress stops moving, or the GPU device is
5
+ * lost. Without a report, the player sees a loading layer while the actionable error stays
6
+ * on stdout or in a discarded scene-transition promise.
9
7
  *
10
8
  * So the failure is reported as text, once, through `onLaunchFailure` — and core stops there. Core
11
9
  * cannot draw it: on the native host `document` is a Three.js compatibility stub whose
@@ -14,16 +12,18 @@
14
12
  * asked for when they report a launch that hung); this owns the noticing and the wording.
15
13
  */
16
14
 
17
- /**
18
- * What failed. `stalled` is "no progress for a while"; `device-lost` is the GPU going away;
19
- * `scene-load-failed` is a scene's `load()` rejecting and `start-failed` is `start()` rejecting,
20
- * each of which otherwise reads as a stall.
21
- */
22
- export type LaunchFailureKind = "stalled" | "device-lost" | "scene-load-failed" | "start-failed";
15
+ /** What failed: startup progress, a rejected scene load/start, or a lost GPU device. */
16
+ export type LaunchFailureKind =
17
+ | "stalled"
18
+ | "device-lost"
19
+ | "load-failed"
20
+ | "scene-load-failed"
21
+ | "start-failed";
23
22
 
24
23
  const MARKERS: Readonly<Record<LaunchFailureKind, string>> = {
25
24
  stalled: "TN_STARTUP_STALLED",
26
25
  "device-lost": "TN_DEVICE_LOST",
26
+ "load-failed": "TN_STARTUP_FAILED",
27
27
  "scene-load-failed": "TN_SCENE_LOAD_FAILED",
28
28
  "start-failed": "TN_START_FAILED",
29
29
  };
@@ -60,7 +60,9 @@ export function reportLaunchFailure(failure: ILaunchFailure): void {
60
60
  // A launch that failed to start or load stops making progress too; that stall is not news.
61
61
  if (
62
62
  failure.kind === "stalled" &&
63
- (reported.has("scene-load-failed") || reported.has("start-failed"))
63
+ (reported.has("load-failed") ||
64
+ reported.has("scene-load-failed") ||
65
+ reported.has("start-failed"))
64
66
  )
65
67
  return;
66
68
  reported.add(failure.kind);
@@ -164,3 +166,11 @@ export function watchDeviceLoss(
164
166
  });
165
167
  });
166
168
  }
169
+
170
+ /** Preserve the actual loader error for the shell and playtest console diagnostics. */
171
+ export function reportSceneLoadFailure(error: unknown): void {
172
+ reportLaunchFailure({
173
+ kind: "load-failed",
174
+ message: error instanceof Error ? error.message : String(error),
175
+ });
176
+ }
@@ -0,0 +1,25 @@
1
+ // The admission of the contact occlusion (PRD-635, PRD-617). Unreal's short-range AO darkens the light that
2
+ // arrives from around a surface and leaves the sun alone (UE 5.8.3:
3
+ // Engine/Shaders/Private/PostProcessAmbientOcclusion.usf composites the term on indirect light). The reach form
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. The owned engine writes it to its `indirectDiffuse` target; upstream three
6
+ // with no baked world cache has none: the stage would multiply
7
+ // the sun as well, and the `engine: "threejs"` arm, which drops the stage outright (`TN_AO_REACH_UNSUPPORTED`
8
+ // in `world-environment.ts`), would not show the same picture. Fail closed and name what is missing, rather
9
+ // than shipping one engine a contact shadow the other cannot draw.
10
+
11
+ /** What the stage needs to know about the request and the frame it would run on. */
12
+ export interface IAoAdmission {
13
+ /** No authored `gtaoRadius`: the frame asks for Unreal's screen reach instead of a world radius. */
14
+ readonly reach: boolean;
15
+ /** The game asked for the indirect-only composite, which is the default. */
16
+ readonly indirectOnly: boolean;
17
+ /** The frame can tell its indirect share apart: the owned engine's `indirectDiffuse` target, or a baked world cache. */
18
+ readonly hasIndirect: boolean;
19
+ }
20
+
21
+ /** Why the contact occlusion cannot run on this frame, or `undefined` when it can. */
22
+ export function aoRefusal(request: IAoAdmission): string | undefined {
23
+ if (!request.reach || !request.indirectOnly || request.hasIndirect) return undefined;
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)";
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;
@@ -23,6 +23,7 @@ import {
23
23
  exp,
24
24
  exp2,
25
25
  float,
26
+ hash,
26
27
  log,
27
28
  max,
28
29
  min,
@@ -32,7 +33,6 @@ import {
32
33
  sign,
33
34
  sqrt,
34
35
  step,
35
- vec2,
36
36
  vec3,
37
37
  } from "three/tsl";
38
38
  import type { Node } from "three/webgpu";
@@ -71,13 +71,17 @@ export interface IFilmicCurve {
71
71
  * The largest scene-linear value, after exposure, that one channel can hold when the colour goes into Unreal's
72
72
  * colour LUT (the top of its 14-stop log shaper, `Engine/Shaders/Private/GammaCorrectionCommon.ush`: `LogToLin(1)`
73
73
  * minus `LogToLin(0)`). A channel above it is clipped there, so the sun disc and a hot emitter lose their hue
74
- * earlier than an unbounded curve would. 0, the default, leaves the channel unbounded; pass `LUT_CLIP` for Unreal's.
74
+ * earlier than an unbounded curve would. `LUT_CLIP` is the default, as in Unreal; 0 is the named override that leaves
75
+ * the channel unbounded.
75
76
  */
76
77
  readonly lutClip: number;
77
78
  }
78
79
 
79
80
  // Unreal's log shaper: 14 stops about mid grey 0.18, grey at code 444 of 1023.
80
- /** Unreal's LUT channel clip, 43.7. Off by default (it moves hot-emitter pixels); `filmicCurve: { lutClip: LUT_CLIP }` turns it on. */
81
+ /**
82
+ * Unreal's LUT channel clip, 43.7, on by default (PRD-632 GAP-4: on the L9 spheres cells, 5 runs per arm, no region moved
83
+ * and the judge read NEUTRAL). `filmicCurve: { lutClip: 0 }` turns it off.
84
+ */
81
85
  export const LUT_CLIP = 2 ** ((1 - 444 / 1023) * 14) * 0.18 - 2 ** ((-444 / 1023) * 14) * 0.18;
82
86
 
83
87
  /** Unreal 5.8.3 project defaults. Change these numbers to change the curve. */
@@ -92,7 +96,7 @@ export const FILMIC_CURVE: IFilmicCurve = {
92
96
  glow: 1,
93
97
  redModifier: 1,
94
98
  dither: 1,
95
- lutClip: 0,
99
+ lutClip: LUT_CLIP,
96
100
  };
97
101
 
98
102
  type Vec3 = readonly [number, number, number];
@@ -672,17 +676,15 @@ const toLinear = (v: Node<"vec3">) =>
672
676
  * (`Engine/Shaders/Private/PostProcessTonemap.usf`, scaled by `BackbufferQuantizationDithering` in
673
677
  * `Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessTonemap.cpp`). The pipeline applies the sRGB
674
678
  * transfer after this node, so the grain goes in on the display value and the result comes back to linear.
675
- * The shape is Unreal's triangle on [-1, 1]. The hash is white noise of the pixel position, with the sine
676
- * argument kept under pi. Unreal's grain moves every frame; this one stays on its pixel, so two captures of
677
- * one frame match bit for bit. The hash reads the pixel position: `screenUV` gave no grain in this stage on
678
- * the owned engine.
679
+ * The shape is Unreal's triangle on [-1, 1]. The noise is three's integer PCG `hash` of the pixel index, so
680
+ * every backend draws the same grain: the old `fract(sin(dot(p, k)) * 43758.5453)` hash multiplied float
681
+ * rounding by 43758, and Chrome and the desktop host drew uncorrelated grain (half the frame 1-2 levels
682
+ * apart). Unreal's grain moves every frame; this one stays on its pixel, so two captures of one frame match
683
+ * bit for bit. The hash reads the pixel position: `screenUV` gave no grain in this stage on the owned engine.
679
684
  */
680
685
  function dithered(linear: Node<"vec3">, steps: number): Node<"vec3"> {
681
- const uniform = dot(screenCoordinate, vec2(12.9898, 78.233))
682
- .mod(Math.PI)
683
- .sin()
684
- .mul(43758.5453)
685
- .fract();
686
+ // y * 4096 is exact, so the seed is one rounded add on every backend (FMA or not); hash truncates it to u32.
687
+ const uniform = hash(screenCoordinate.y.mul(4096).add(screenCoordinate.x));
686
688
  // The inverse of the triangular CDF: one root for each half of the unit interval.
687
689
  const grain = mix(
688
690
  uniform.mul(2).sqrt().sub(1),
@@ -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);
@@ -11,14 +11,14 @@ export const lookDiagnostics: {
11
11
  aaAlphaSqueezed: boolean;
12
12
  /** Runs N denoise passes over the SSGI gather at any layer, for an A/B against the tier's count. */
13
13
  denoisePasses: number | undefined;
14
- /** Turns on the film curve's 43.7 channel clip (off by default), the ON arm of a paired capture. */
15
- lutClipOn: boolean;
14
+ /** Turns off the film curve's 43.7 channel clip (on by default), the OFF arm of a paired capture. */
15
+ lutClipOff: boolean;
16
16
  /** Draws one GI term alone (PRD-646); needs the gather, so it applies at layer 7 and above. */
17
17
  giVisualize: GIVisualizeMode;
18
18
  } = {
19
19
  layer: 9,
20
20
  aaAlphaSqueezed: false,
21
21
  denoisePasses: undefined,
22
- lutClipOn: false,
22
+ lutClipOff: false,
23
23
  giVisualize: "off",
24
24
  };
@@ -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
+ }
@@ -1,6 +1,7 @@
1
1
  // The quality tiers of the Unreal 5.8.3 look (owner exception to "never own the look", 2026-10-22): what each tier
2
2
  // turns on, and the GI and shadow settings per tier named after Unreal's scalability levels. A `WorldEnvironment`
3
3
  // built with no options starts from the `high` tier; an explicit option always wins.
4
+ import { exposureSettings } from "./exposure-settings.js";
4
5
  import type { IWorldEnvironmentOptions } from "./world-environment.js";
5
6
 
6
7
  /**
@@ -94,11 +95,12 @@ const shared: IWorldEnvironmentOptions = {
94
95
  bloomRadius: 0.6,
95
96
  bloomStrength: 0.22,
96
97
  bloomThreshold: 1,
97
- // Unreal's fixed exposure scale is 1.0: its scene-linear EXR passed through the filmic curve alone
98
- // reproduces its PNG (mean error 0.4/255 over 72000 pixels, L1 and L2). Light units, not this
99
- // number, set the level: the sun is 6 lux (`atmosphere.ts`). With auto exposure on this is only
100
- // the value used while the meter is off.
101
- exposure: 1,
98
+ // Unreal's exposure with its meter off: the project setting pins the average luminance to mid grey
99
+ // under a 1 cd/m2 white point at a 1.2 saturation constant (SceneView.cpp:2060-2069), and the meter's
100
+ // rule key / average then gives 0.36 / (0.18 / 1.2) = 2.4 (PostProcessEyeAdaptation.cpp:810-821).
101
+ // The L1 cells, lit by the 6 lux sun (`atmosphere.ts`), match Unreal's at this value. With auto
102
+ // exposure on this is only the value used while the meter is off.
103
+ exposure: exposureSettings.key / (0.18 / 1.2),
102
104
  tonemapMode: "filmic",
103
105
  // Unreal's VignetteIntensity, cosine-fourth law (Scene.cpp, FPostProcessSettings constructor).
104
106
  vignetteAmount: 0.4,
@@ -165,6 +167,13 @@ const low: IWorldEnvironmentOptions = {
165
167
  finalGatherMethod: "none",
166
168
  localExposureEnabled: false,
167
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,
174
+ // Single-sample, as medium: an unset count inherits the renderer's 4x MSAA, and the cheapest tier
175
+ // cost more than medium on a forest (Iris Xe 125 -> 158 ms at the switch, PRD-762).
176
+ samples: 0,
168
177
  };
169
178
 
170
179
  const QUALITY_PRESETS: Record<QualityTier, IWorldEnvironmentOptions> = { high, low, medium };
@@ -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);