@threenative/core 0.3.11 → 0.3.12

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 (157) hide show
  1. package/capabilities.json +1096 -26
  2. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  3. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-CWuFRT7G.d.ts} +1 -1
  4. package/dist/chunk-2Z44XSI2.js +35 -0
  5. package/dist/chunk-5O73CDMR.js +1849 -0
  6. package/dist/chunk-6KLNISRJ.js +153 -0
  7. package/dist/chunk-7UUT3TY5.js +133 -0
  8. package/dist/chunk-CFGTPFUH.js +231 -0
  9. package/dist/chunk-DBELTTTM.js +615 -0
  10. package/dist/chunk-GMHATRPW.js +7701 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-KIRUKTBQ.js +187 -0
  13. package/dist/chunk-N5LRP4BR.js +220 -0
  14. package/dist/chunk-OKXUCASC.js +2238 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-VAZM36TV.js +497 -0
  17. package/dist/{game-DzMcitDO.d.ts → game-D7pAzZUY.d.ts} +15 -3
  18. package/dist/hot.d.ts +3 -3
  19. package/dist/hot.js +2 -46
  20. package/dist/index.d.ts +329 -302
  21. package/dist/index.js +10566 -22552
  22. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-B6BMqS1r.d.ts} +33 -3
  23. package/dist/playtest.d.ts +3 -3
  24. package/dist/playtest.js +24 -75
  25. package/dist/react-css.js +1 -215
  26. package/dist/react.d.ts +2 -2
  27. package/dist/{renderer-rZm0hVqq.d.ts → renderer-DvFVoAgj.d.ts} +13 -4
  28. package/dist/spells/index.d.ts +643 -0
  29. package/dist/spells/index.js +1558 -0
  30. package/dist/spells/ultra/index.d.ts +1600 -0
  31. package/dist/spells/ultra/index.js +6804 -0
  32. package/dist/terrain-jobs-worker.js +1 -123
  33. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  34. package/dist/ui-layer.js +5 -384
  35. package/dist/worker.js +4 -41
  36. package/dist/world.d.ts +725 -259
  37. package/dist/world.js +16714 -18284
  38. package/mcp/animation-server.mjs +1 -1
  39. package/mcp/animation.mjs +2 -3
  40. package/mcp/engine-server.mjs +142 -47
  41. package/mcp/servers.mjs +9 -2
  42. package/mcp/terrain.mjs +8 -0
  43. package/package.json +14 -6
  44. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  45. package/patches/three@0.187.0.patch +2004 -407
  46. package/src/assets.ts +9 -2
  47. package/src/card-lod.ts +152 -0
  48. package/src/compressed-texture-preparation.ts +1008 -0
  49. package/src/frame-budget.ts +31 -20
  50. package/src/game-dev-tools.ts +93 -0
  51. package/src/game-frame-loop.ts +995 -0
  52. package/src/game-renderer-metrics.ts +77 -0
  53. package/src/game-startup.ts +1001 -0
  54. package/src/game-validate.ts +70 -0
  55. package/src/game.ts +253 -1935
  56. package/src/index.ts +27 -2
  57. package/src/launch-diagnostics.ts +22 -12
  58. package/src/look/ao-admission.ts +24 -0
  59. package/src/look/filmic-tone-mapping.ts +15 -13
  60. package/src/look/look-diagnostics.ts +3 -3
  61. package/src/look/quality.ts +10 -5
  62. package/src/look/world-environment.ts +76 -9
  63. package/src/loop.ts +29 -0
  64. package/src/model-lod.ts +42 -3
  65. package/src/particle-kinds.ts +515 -0
  66. package/src/picking.ts +17 -3
  67. package/src/playtest.ts +27 -1
  68. package/src/projection-apply.ts +4 -1
  69. package/src/projection-plan.ts +9 -6
  70. package/src/render/mesh-pool.ts +1 -1
  71. package/src/render/resolution-subrect.ts +2 -0
  72. package/src/render/rough-diffuse.ts +46 -12
  73. package/src/render/soft-shadow.ts +27 -12
  74. package/src/render/virtual-shadow-adaptive.ts +55 -0
  75. package/src/render/virtual-shadow-casters.ts +175 -0
  76. package/src/render/virtual-shadow-layers.ts +76 -0
  77. package/src/render/virtual-shadow-level.ts +224 -0
  78. package/src/render/virtual-shadow-markers.ts +193 -0
  79. package/src/render/virtual-shadow-options.ts +370 -0
  80. package/src/render/virtual-shadow-pages.ts +5 -0
  81. package/src/render/virtual-shadow.ts +213 -992
  82. package/src/render/world-impostor-surface.ts +293 -34
  83. package/src/render-pass-budget.ts +34 -7
  84. package/src/renderProjection.ts +22 -0
  85. package/src/renderer.ts +92 -37
  86. package/src/snow-field.ts +1 -1
  87. package/src/spells/cast-pool.ts +361 -0
  88. package/src/spells/index.ts +177 -0
  89. package/src/spells/mechanisms.ts +295 -0
  90. package/src/spells/reaction-field.ts +415 -0
  91. package/src/spells/spell-lights.ts +139 -0
  92. package/src/spells/spell-world.ts +187 -0
  93. package/src/spells/spell.ts +397 -0
  94. package/src/spells/spells.ts +283 -0
  95. package/src/spells/ultra/engine/camera.ts +184 -0
  96. package/src/spells/ultra/engine/quality.ts +96 -0
  97. package/src/spells/ultra/index.ts +52 -0
  98. package/src/spells/ultra/main.ts +305 -0
  99. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  100. package/src/spells/ultra/spells/cast.ts +233 -0
  101. package/src/spells/ultra/spells/fire.ts +1267 -0
  102. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  103. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  104. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  105. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  106. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  107. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  108. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  109. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  110. package/src/spells/ultra/vfx/common.ts +1195 -0
  111. package/src/spells/ultra/vfx/noise.ts +441 -0
  112. package/src/startup-readiness.ts +128 -34
  113. package/src/version.ts +1 -1
  114. package/src/warmup.ts +56 -8
  115. package/src/water-surface.ts +9 -3
  116. package/src/world-bundle-safety.ts +401 -0
  117. package/src/world-cell-batches.ts +1216 -0
  118. package/src/world-cell-chunks.ts +1132 -0
  119. package/src/world-cell-data.ts +995 -0
  120. package/src/world-cell-impostors.ts +1449 -0
  121. package/src/world-cell-lod-bias.ts +151 -0
  122. package/src/world-cell-models.ts +1074 -0
  123. package/src/world-cell-options.ts +189 -0
  124. package/src/world-cell-placements.ts +694 -0
  125. package/src/world-cell-prewarm.ts +557 -0
  126. package/src/world-cell-readiness.ts +357 -0
  127. package/src/world-cell-render-bundles.ts +459 -0
  128. package/src/world-cell-render-gpu-dress.ts +714 -0
  129. package/src/world-cell-render-main-cull.ts +484 -0
  130. package/src/world-cell-render-shadow-claims.ts +198 -0
  131. package/src/world-cell-render-util.ts +246 -0
  132. package/src/world-cell-render.ts +1493 -0
  133. package/src/world-cell-residency.ts +745 -0
  134. package/src/world-cells.ts +1318 -10418
  135. package/src/world-chunk-shadow.ts +308 -0
  136. package/src/world-collar.ts +315 -0
  137. package/src/world-gpu-flags.ts +163 -0
  138. package/src/world-gpu-readback.ts +881 -0
  139. package/src/world-gpu-reference.ts +510 -0
  140. package/src/world-gpu-scene.ts +214 -2264
  141. package/src/world-gpu-shadow.ts +190 -0
  142. package/src/world-gpu-types.ts +381 -0
  143. package/src/world-gpu-validation.ts +518 -0
  144. package/src/world-heightfield.ts +802 -0
  145. package/src/world-load-limiter.ts +106 -0
  146. package/src/world-noise.ts +241 -0
  147. package/src/world-package.ts +42 -0
  148. package/src/world-region.ts +1 -1
  149. package/src/world-terrain-splat.ts +365 -149
  150. package/src/world-tile-budget.ts +256 -0
  151. package/src/world-tile-geometry.ts +469 -0
  152. package/src/world-tile-lod.ts +408 -0
  153. package/src/world-tile-observation.ts +566 -0
  154. package/src/world-tile-stitch.ts +166 -0
  155. package/src/world-tiles.ts +170 -1745
  156. package/src/world-water-bodies.ts +359 -0
  157. package/src/world.ts +35 -741
package/src/index.ts CHANGED
@@ -6,7 +6,7 @@
6
6
  * unavoidable here — core is bundled for browsers and cannot read `package.json` at runtime — so
7
7
  * the spec now asserts this equals the manifest instead of asserting a number somebody typed.
8
8
  */
9
- export const version = "0.3.11";
9
+ export const version = "0.3.12";
10
10
 
11
11
  /**
12
12
  * Play a skinned or sprite animation from game code.
@@ -536,6 +536,31 @@ export {
536
536
  * @example const geometry = baseGeometryOf(mesh);
537
537
  */
538
538
  export { baseGeometryOf } from "./model-lod.js";
539
+ /**
540
+ * The cooked automatic LOD chain (`TN_discrete_lod`) a loaded geometry carries, or `undefined`.
541
+ *
542
+ * Its levels share the base's vertex attributes and differ only in index, and `errors` are each
543
+ * level's world-unit error in the base's own space. A caller that draws one geometry many times
544
+ * (an instanced batch, a streamed world level) reads the reduced shapes here instead of re-cooking.
545
+ *
546
+ * @situation draw a cooked reduced level of a model in an instanced batch or streamed world level
547
+ * @constraint a geometry the loader built no chain for returns undefined
548
+ * @example const chain = lodChainOf(baseGeometryOf(mesh)); const far = chain?.levels.at(-1);
549
+ */
550
+ export { lodChainOf } from "./model-lod.js";
551
+ /**
552
+ * A far level for a card mesh (needle or leaf quads): keep a share of its cards and grow each kept
553
+ * card about its own centre, so the crown holds its total surface area, as Unreal's Nanite
554
+ * "Preserve Area" foliage does. A simplifier cannot reduce disconnected cards, so the cooked chain
555
+ * leaves them at full count.
556
+ *
557
+ * @situation far trees draw too many alpha-tested needle or leaf card triangles
558
+ * @constraint the geometry must be indexed and carry no material groups, else it throws
559
+ * @constraint keep is in (0, 1]; a share that drops nothing returns the same geometry
560
+ * @constraint the choice is deterministic, and the source geometry is left untouched
561
+ * @example const far = thinCards(needles.geometry, 0.4); // 40% of the cards, same area
562
+ */
563
+ export { thinCards } from "./card-lod.js";
539
564
  /**
540
565
  * The screen pixels one world unit covers at `depth` for this camera and viewport.
541
566
  *
@@ -1291,7 +1316,7 @@ export {
1291
1316
  } from "./render/exposure-units.js";
1292
1317
  export type { IVirtualShadowOptions, IVirtualShadowStats } from "./render/virtual-shadow.js";
1293
1318
  /**
1294
- * Attach hundreds of built objects to the scene in slices, presenting a frame between each.
1319
+ * Attach hundreds of built objects to the scene in slices with an 8 ms default budget, presenting a frame between each.
1295
1320
  * @situation add hundreds of built objects to the scene without one multi-second frame
1296
1321
  * @situation stream a detail tier in behind a loading curtain without the page looking hung
1297
1322
  * @constraint the objects, and where each one goes, stay the game's; this decides only when each joins the graph
@@ -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,24 @@
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. A frame with no baked world cache has none: the stage would multiply
6
+ // the sun as well, and the `engine: "threejs"` arm, which drops the stage outright (`TN_AO_REACH_UNSUPPORTED`
7
+ // in `world-environment.ts`), would not show the same picture. Fail closed and name what is missing, rather
8
+ // than shipping one engine a contact shadow the other cannot draw.
9
+
10
+ /** What the stage needs to know about the request and the frame it would run on. */
11
+ export interface IAoAdmission {
12
+ /** No authored `gtaoRadius`: the frame asks for Unreal's screen reach instead of a world radius. */
13
+ readonly reach: boolean;
14
+ /** The game asked for the indirect-only composite, which is the default. */
15
+ readonly indirectOnly: boolean;
16
+ /** A baked world cache exists, so the frame carries the indirect share the occlusion belongs on. */
17
+ readonly hasIndirect: boolean;
18
+ }
19
+
20
+ /** Why the contact occlusion cannot run on this frame, or `undefined` when it can. */
21
+ export function aoRefusal(request: IAoAdmission): string | undefined {
22
+ 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
+ }
@@ -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),
@@ -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
  };
@@ -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,9 @@ const low: IWorldEnvironmentOptions = {
165
167
  finalGatherMethod: "none",
166
168
  localExposureEnabled: false,
167
169
  renderChainTier: "low",
170
+ // Single-sample, as medium: an unset count inherits the renderer's 4x MSAA, and the cheapest tier
171
+ // cost more than medium on a forest (Iris Xe 125 -> 158 ms at the switch, PRD-762).
172
+ samples: 0,
168
173
  };
169
174
 
170
175
  const QUALITY_PRESETS: Record<QualityTier, IWorldEnvironmentOptions> = { high, low, medium };
@@ -77,6 +77,7 @@ import {
77
77
  import { GIVisualize, type GIVisualizeMode } from "../render/gi-visualize.js";
78
78
  import type { TracedReflections } from "../render/traced-reflections.js";
79
79
  import { STARTUP_EXPOSURE } from "../renderer.js";
80
+ import { aoRefusal } from "./ao-admission.js";
80
81
  import { AO_MULTIBOUNCE_FIT, UNREAL_AO_MULTIBOUNCE_ALBEDO } from "./ao-multibounce.js";
81
82
  import { UNREAL_AO_REACH_PX } from "./ao-reach.js";
82
83
  import { AutoExposureNode, applyExposure } from "./auto-exposure.js";
@@ -85,7 +86,6 @@ import {
85
86
  type ColorGradeOptions,
86
87
  FILMIC_CURVE,
87
88
  type IFilmicCurve,
88
- LUT_CLIP,
89
89
  installFilmicToneMapping,
90
90
  resolveColorGrade,
91
91
  } from "./filmic-tone-mapping.js";
@@ -139,6 +139,29 @@ const TONEMAP: Record<TonemapMode, number> = {
139
139
  neutral: NeutralToneMapping,
140
140
  };
141
141
 
142
+ /**
143
+ * Whether this launch draws the transparent draws' own target (see `seesThrough` below).
144
+ *
145
+ * On unless a launch asks for it off: `TN_TRANSLUCENT=0`, `?tnTranslucent=0`, or the global
146
+ * `__tnTranslucent = false` a test sets. Only `0` and `false` count, so an old URL that never
147
+ * named the switch keeps the target. A frame without it takes the occlusion on its sheets, which
148
+ * is wrong to look at, so this is a measurement switch and not a look: a lane prices the pass by
149
+ * running the same pose both ways.
150
+ */
151
+ export function translucentTargetWanted(): boolean {
152
+ const host = globalThis as { process?: { env?: Record<string, unknown> } } & Record<
153
+ string,
154
+ unknown
155
+ >;
156
+ const fromEnv = host.process?.env?.TN_TRANSLUCENT;
157
+ if (fromEnv === "0" || fromEnv === "false") return false;
158
+ const query = globalThis.location?.search;
159
+ if (typeof query === "string" && /[?&]tnTranslucent=(?:0|false)(?:&|$)/u.test(query))
160
+ return false;
161
+ const set = host.__tnTranslucent;
162
+ return !(set === false || set === 0 || set === "0" || set === "false");
163
+ }
164
+
142
165
  /**
143
166
  * Publishes this install's exposure readiness for the startup's first visible frame
144
167
  * (`rendererFirstWorldFrame`): measured, settled, and within 3% of the meter's own target.
@@ -904,7 +927,7 @@ export class WorldEnvironment {
904
927
  {
905
928
  ...FILMIC_CURVE,
906
929
  ...options.filmicCurve,
907
- ...(lookDiagnostics.lutClipOn ? { lutClip: LUT_CLIP } : {}),
930
+ ...(lookDiagnostics.lutClipOff ? { lutClip: 0 } : {}),
908
931
  },
909
932
  resolveColorGrade(options.colorGrade),
910
933
  );
@@ -1028,6 +1051,19 @@ export class WorldEnvironment {
1028
1051
  // Unreal's AO (indirect light only) leaves it. Without a cache (the three.js engine) the whole frame is dimmed.
1029
1052
  const indirectOcclusion =
1030
1053
  ownedEngine && giCache.irradiance !== undefined && options.gtaoIndirectOnly;
1054
+ // Both screen-space stages below darken the frame with an occlusion gathered at the opaque surface's depth, so both
1055
+ // must leave the draws composited over it alone (see the MRT's `translucent` output and `translucentFrame`).
1056
+ // `TN_TRANSLUCENT=0` or `?tnTranslucent=0` keeps the target off the frame — the occlusion then darkens the sheets
1057
+ // over the opaque surface, as it did before the target existed — so one launch can price the pass; a diagnostic,
1058
+ // never a look.
1059
+ const seesThrough = (options.ssgiEnabled || options.gtaoEnabled) && translucentTargetWanted();
1060
+ // Upstream three has no scene-wide translucent target, so each material writes its own: its output, premultiplied
1061
+ // by its alpha, and nothing at all from an opaque material (whose alpha is 1). The owned engine draws the
1062
+ // transparent draws into the target itself (renderer.cpp, planAux), so it declares no output for it.
1063
+ const translucentMaterial = (): Node<"vec4"> =>
1064
+ vec4(output.rgb.mul(diffuseColor.a), diffuseColor.a).mul(
1065
+ diffuseColor.a.lessThan(0.999).select(float(1), float(0)),
1066
+ );
1031
1067
  const scenePass = pass(scene, camera, { samples: options.samples });
1032
1068
  const resolutionSubrect =
1033
1069
  requested.length === 0 || resolutionSubrectRefusal !== undefined
@@ -1056,8 +1092,16 @@ export class WorldEnvironment {
1056
1092
  : {}),
1057
1093
  // AO leaves emission alone: an emitter's underside stays its own radiance (Unreal's AO is indirect only).
1058
1094
  ...(options.gtaoEnabled || options.ssgiEnabled ? { emissive } : {}),
1095
+ // The occlusion and the gather belong to the opaque surface. A translucent draw composites over it after the
1096
+ // opaque pass, so a sheet over an occluded corner took the corner's occlusion with it (a waterfall showed the
1097
+ // cliff's stripes). This target carries what those draws composited, and the two composites below add it back
1098
+ // instead of darkening it, as they already do for `emissive`. Upstream three writes it from each material's
1099
+ // own output; the owned engine draws those draws into it while the graph reads it (renderer.cpp, planAux).
1100
+ ...(seesThrough && !ownedEngine ? { translucent: translucentMaterial() } : {}),
1059
1101
  });
1060
1102
  sceneMrt.setBlendMode("normal", new BlendMode(MaterialBlending));
1103
+ if (seesThrough && !ownedEngine)
1104
+ sceneMrt.setBlendMode("translucent", new BlendMode(MaterialBlending));
1061
1105
  scenePass.setMRT(sceneMrt);
1062
1106
  }
1063
1107
  // Requested lazily, and this is not a micro-optimisation. **Asking a pass for `normal`,
@@ -1102,6 +1146,12 @@ export class WorldEnvironment {
1102
1146
  const gain = exposure === undefined ? float(options.exposure) : exposure.exposureNode;
1103
1147
  const frameGain = localExposure === undefined ? gain : gain.mul(localExposure.gainNode);
1104
1148
  const exposed = applyExposure(colour, frameGain);
1149
+ // What the transparent draws composited over the frame, in the frame's own units: scene-referred, so it takes the
1150
+ // exposure multiplier the emitted radiance takes. The occlusion darkens the opaque surface only, and this part is
1151
+ // added back instead (the `emissive` restore's twin). A frame that runs neither stage never asks for it.
1152
+ const translucentFrame: Node<"vec3"> = seesThrough
1153
+ ? textureNode("translucent").rgb.mul(gain)
1154
+ : vec3(0);
1105
1155
  let released = false;
1106
1156
  const releaseGraph = (): void => {
1107
1157
  if (released) return;
@@ -1238,8 +1288,9 @@ export class WorldEnvironment {
1238
1288
  // The gathered light is incident radiance (E / pi). The surface returns it times its own
1239
1289
  // albedo, which the scene pass writes as the `diffuseColor` target, and a metal returns none
1240
1290
  // of it as diffuse. `ssgiIntensity` is the game's dial on that term.
1241
- // The owned engine's gather answers occlusion with a constant 1 (GTAO is its own stage): nothing to denoise.
1242
- const occlusion = wasmEngine ? gi.getAONode() : giDenoise(gi.getAONode());
1291
+ // Both engines answer the occlusion from their own gather, and both are denoised: the gather traces a few
1292
+ // rays a pixel, so an undenoised occlusion reads as a speckle rather than a shadowed corner.
1293
+ const occlusion = giDenoise(gi.getAONode());
1243
1294
  const indirect = giDenoise(gi.getGINode());
1244
1295
  if (options.denoiseEnabled && options.ssgiDenoiseRadius !== undefined)
1245
1296
  (indirect as typeof indirect & { radius: { value: number } }).radius.value =
@@ -1248,8 +1299,9 @@ export class WorldEnvironment {
1248
1299
  .rgb.mul(float(1).sub(metal().r))
1249
1300
  .mul(indirect.rgb)
1250
1301
  .mul(options.ssgiIntensity);
1251
- // The gather's own AO leaves emission alone too (see the GTAO stage).
1252
- const emitted = textureNode("emissive").rgb.mul(gain);
1302
+ // The gather's own AO leaves emission alone too (see the GTAO stage), and a translucent draw's own colour
1303
+ // is in the same position: the gather answered for the surface behind it.
1304
+ const emitted = textureNode("emissive").rgb.mul(gain).add(translucentFrame);
1253
1305
  // The contact term multiplied the frame before this stage ran, and the correction below is the one
1254
1306
  // part of the light that frame never carried: it takes the same factor, or a hit darker than the
1255
1307
  // cache subtracts more than the frame still holds and a lit floor under a sphere clips to black.
@@ -1283,6 +1335,16 @@ export class WorldEnvironment {
1283
1335
  releaseAo = () => {};
1284
1336
  },
1285
1337
  build: (input) => {
1338
+ // The reach form occludes indirect light only, so a frame without a baked world cache cannot run it:
1339
+ // the whole-frame multiply it would fall back to darkens the sun, and the threejs arm drops the stage.
1340
+ const refusal = aoRefusal({
1341
+ reach: options.gtaoRadius === undefined,
1342
+ indirectOnly: options.gtaoIndirectOnly,
1343
+ // The preset's own declaration covers the frame whose bake has not finished when the chain is built:
1344
+ // the gather's fallback reads the cache at render time, and the registration is the other signal.
1345
+ hasIndirect: options.finalGatherMethod !== "none" || giCache.irradiance !== undefined,
1346
+ });
1347
+ if (refusal !== undefined) throw new Error(refusal);
1286
1348
  // GTAO rebuilds the normal from the depth, so it agrees with the depth's facets. The pass's
1287
1349
  // smooth vertex normal against a faceted depth (a 32-sided capsule) read as one dark stripe per facet and a
1288
1350
  // stair-step band under the cap; the denoiser, GTAO scale and radius did not change them.
@@ -1441,9 +1503,10 @@ export class WorldEnvironment {
1441
1503
  indirectOcclusion && options.gtaoMultiBounceAlbedo > 0 ? bounce() : undefined;
1442
1504
  contactOcclusion = keeps ?? occlusion.r;
1443
1505
  // Emission is radiance a surface gives off, not light it receives: AO keeps it, as Unreal's AO darkens only
1444
- // indirect light. The emitted part passes at full weight; the rest takes the occlusion.
1506
+ // indirect light. The emitted part passes at full weight; the rest takes the occlusion. A translucent draw's
1507
+ // own colour is in the same position: the occlusion was gathered for the surface behind it.
1445
1508
  // The chain reads exposed light, so the emitted radiance takes the frame's gain too.
1446
- const emitted = textureNode("emissive").rgb.mul(gain);
1509
+ const emitted = textureNode("emissive").rgb.mul(gain).add(translucentFrame);
1447
1510
  // Scale the colour only: `input.mul(occlusion.r)` scales alpha too, which darkens the frame a second time.
1448
1511
  const composited = input
1449
1512
  .mul(vec4(occlusion.r, occlusion.r, occlusion.r, 1))
@@ -1488,9 +1551,13 @@ export class WorldEnvironment {
1488
1551
  .rgb.mul(float(1).sub(metal().r))
1489
1552
  .mul(cache(position, sceneNormal.normalize()))
1490
1553
  .mul(frameGain);
1554
+ // Only the opaque part of the frame carries that indirect light: a draw composited over it did not receive it.
1555
+ const opaque = input.rgb.sub(translucentFrame);
1491
1556
  result.assign(
1492
1557
  max(
1493
- input.rgb.sub(indirect.mul(float(1).sub(keeps ?? occlusion.r))),
1558
+ opaque
1559
+ .sub(indirect.mul(float(1).sub(keeps ?? occlusion.r)))
1560
+ .add(translucentFrame),
1494
1561
  composited.rgb,
1495
1562
  ),
1496
1563
  );
package/src/loop.ts CHANGED
@@ -356,6 +356,35 @@ export class FixedStepLoop {
356
356
  this.#settleSteps = settleSteps;
357
357
  this.#lastTime = Number.POSITIVE_INFINITY;
358
358
  }
359
+
360
+ /**
361
+ * Spend the settling pass now, from a caller that knows the world's scene is live.
362
+ *
363
+ * A freeze names the steps the world needs; the loop waits for the first live frame to spend
364
+ * them. On a game that boots through a loading scene that frame is often still the loading
365
+ * scene: the steps ran, the world's own clock never saw them, and how many were lost depended on
366
+ * how fast the machine booted. Measured on the sailing template's pose at the same anchor, the
367
+ * native engine was 60 steps (1.0 s) ahead of the legacy one for exactly this reason. A runner
368
+ * freezes with zero steps and calls this once the start scene has entered, so the settle lands
369
+ * on the world on every engine.
370
+ */
371
+ settleNow(steps = FROZEN_SETTLE_STEPS): void {
372
+ if (!Number.isInteger(steps) || steps < 0)
373
+ throw new Error("settleNow steps must be a non-negative integer.");
374
+ this.#primePending = false;
375
+ if (steps === 0) return;
376
+ // `advance()` freezes the clock, because a counted step is a statement that the run counts
377
+ // ticks. A settle asked of a loop that was live makes no such statement — a wall-clock run
378
+ // measures frames — so it hands the loop back the way it found it instead of leaving a profile
379
+ // of a game that stopped playing.
380
+ const wasFrozen = this.#clockFrozen;
381
+ this.advance(steps);
382
+ if (wasFrozen) return;
383
+ // The transition back banks no elapsed time, exactly as `_setClockMode("wall-clock")` does:
384
+ // the 60 steps are already on the tick count, and the next live frame owns the time after it.
385
+ this.#clockFrozen = false;
386
+ this.#lastTime = undefined;
387
+ }
359
388
  /** True once the live clock no longer drives the simulation. */
360
389
  get clockFrozen(): boolean {
361
390
  return this.#clockFrozen;
package/src/model-lod.ts CHANGED
@@ -4,6 +4,7 @@ import {
4
4
  BufferGeometry,
5
5
  type Camera,
6
6
  Group,
7
+ InstancedMesh,
7
8
  Matrix4,
8
9
  type Mesh,
9
10
  Object3D,
@@ -11,6 +12,7 @@ import {
11
12
  Vector3,
12
13
  } from "three";
13
14
  import { pixelsPerUnit } from "./clustered-mesh.js";
15
+ import type { attachInstancedLod } from "./instanced-batch-lod.js";
14
16
 
15
17
  /**
16
18
  * Engine-owned detail selection for automatic discrete LOD (`TN_discrete_lod`).
@@ -232,6 +234,7 @@ interface IParserLike {
232
234
  animations?: { channels?: { target?: { node?: number } }[] }[];
233
235
  extensions?: Record<string, unknown>;
234
236
  meshes?: { name?: string; primitives?: { extensions?: Record<string, unknown> }[] }[];
237
+ nodes?: { mesh?: number; extensions?: Record<string, unknown> }[];
235
238
  };
236
239
  }
237
240
 
@@ -913,6 +916,7 @@ export class DiscreteLodPlugin {
913
916
  readonly name = TN_DISCRETE_LOD;
914
917
  readonly #failClosed: boolean;
915
918
  #parser: IParserLike | undefined;
919
+ #associations: IParserLike["associations"] | undefined;
916
920
  readonly #pending = new Map<Mesh, IPendingLevels>();
917
921
  readonly #rungs: { readonly def: IJoinedRungDef; readonly prototype: Object3D }[] = [];
918
922
  /** A temporary holder for far-mesh prototypes, so widening reaches their joined geometry. */
@@ -930,6 +934,16 @@ export class DiscreteLodPlugin {
930
934
  this.#parser = parser;
931
935
  }
932
936
 
937
+ async beforeRoot(): Promise<void> {
938
+ const parser = this.#parser;
939
+ if (parser === undefined) return;
940
+ // Each glTF scene prunes parser.associations; retain the complete node map before that.
941
+ await Promise.all(
942
+ (parser.json.nodes ?? []).map((_, index) => parser.getDependency("node", index)),
943
+ );
944
+ this.#associations = parser.associations;
945
+ }
946
+
933
947
  #invalid(message: string): void {
934
948
  if (this.#failClosed) throw new Error(message);
935
949
  console.error(message);
@@ -938,7 +952,20 @@ export class DiscreteLodPlugin {
938
952
  async afterRoot(result: { scene?: Object3D }): Promise<void> {
939
953
  const parser = this.#parser;
940
954
  if (parser === undefined) return;
941
- for (const [object, association] of parser.associations) {
955
+ const associations = this.#associations ?? parser.associations;
956
+ // GLTFLoader's instancing extension replaces the primitive meshes without copying associations.
957
+ for (const [object, association] of associations) {
958
+ if (association?.primitives !== undefined) continue;
959
+ const node = parser.json.nodes?.[association?.nodes ?? -1];
960
+ if (node?.mesh === undefined || node.extensions?.EXT_mesh_gpu_instancing === undefined)
961
+ continue;
962
+ const parts = object instanceof InstancedMesh ? [object] : (object as Object3D).children;
963
+ for (const [primitives, mesh] of parts.entries()) {
964
+ if (!(mesh instanceof InstancedMesh)) continue;
965
+ associations.set(mesh, { ...association, meshes: node.mesh, primitives });
966
+ }
967
+ }
968
+ for (const [object, association] of associations) {
942
969
  const mesh = object as Mesh;
943
970
  if (mesh.isMesh !== true) continue;
944
971
  const { meshes, primitives } = association;
@@ -1001,7 +1028,11 @@ export class DiscreteLodPlugin {
1001
1028
  }
1002
1029
 
1003
1030
  /** Builds the derived geometries against the mesh's final (widened) attributes and registers. */
1004
- attach(_root: Object3D, policy: IModelLodPolicy | undefined): number {
1031
+ attach(
1032
+ _root: Object3D,
1033
+ policy: IModelLodPolicy | undefined,
1034
+ instancedLod?: typeof attachInstancedLod,
1035
+ ): number {
1005
1036
  const applied: IAppliedLod = {
1006
1037
  hysteresis: policy?.hysteresis ?? DISCRETE_LOD_DEFAULT_HYSTERESIS,
1007
1038
  maxPixelError: policy?.maxPixelError ?? DISCRETE_LOD_DEFAULT_ERROR_PIXELS,
@@ -1054,7 +1085,15 @@ export class DiscreteLodPlugin {
1054
1085
  for (const geometry of levels) chains.set(geometry, registered);
1055
1086
  bumpChains();
1056
1087
  preserveChainClones(registered);
1057
- controllers.set(mesh, new ModelLod(mesh, registered.chain, applied));
1088
+ if (mesh instanceof InstancedMesh) {
1089
+ if (instancedLod === undefined)
1090
+ throw new Error(
1091
+ "TN_discrete_lod requires the instanced LOD attachment for InstancedMesh.",
1092
+ );
1093
+ instancedLod(mesh, { autoLod: policy });
1094
+ } else {
1095
+ controllers.set(mesh, new ModelLod(mesh, registered.chain, applied));
1096
+ }
1058
1097
  appliedCount += 1;
1059
1098
  }
1060
1099
  this.#registerJoinedRungs(applied);