@threenative/core 0.3.12 → 0.3.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (150) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +746 -32
  3. package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
  4. package/dist/{canvas-layer-CWuFRT7G.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
  5. package/dist/{chunk-7UUT3TY5.js → chunk-4SRAQFTU.js} +1 -1
  6. package/dist/{chunk-GMHATRPW.js → chunk-DIPIJICH.js} +1590 -375
  7. package/dist/{chunk-OKXUCASC.js → chunk-EEABDLUC.js} +3 -4
  8. package/dist/{chunk-5O73CDMR.js → chunk-EFWZWLPY.js} +62 -16
  9. package/dist/{chunk-N5LRP4BR.js → chunk-GYUZJQ7U.js} +63 -3
  10. package/dist/{chunk-VAZM36TV.js → chunk-H4J6IAJE.js} +17 -10
  11. package/dist/{chunk-2Z44XSI2.js → chunk-SV4QVUTQ.js} +3 -7
  12. package/dist/{chunk-DBELTTTM.js → chunk-U4YHUKKL.js} +1 -1
  13. package/dist/chunk-VP43GIWW.js +18 -0
  14. package/dist/{chunk-6KLNISRJ.js → chunk-XDTZ4QMO.js} +11 -4
  15. package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
  16. package/dist/{game-D7pAzZUY.d.ts → game-k8K3hZai.d.ts} +72 -8
  17. package/dist/hot.d.ts +5 -4
  18. package/dist/hot.js +5 -8
  19. package/dist/index.d.ts +289 -1034
  20. package/dist/index.js +3096 -1305
  21. package/dist/{model-lod-B6BMqS1r.d.ts → model-lod-DPTzeCcD.d.ts} +4 -2
  22. package/dist/playtest.d.ts +5 -4
  23. package/dist/playtest.js +6 -5
  24. package/dist/quality-BYqKGAwo.d.ts +868 -0
  25. package/dist/react.d.ts +3 -2
  26. package/dist/render-environment.d.ts +170 -0
  27. package/dist/render-environment.js +352 -0
  28. package/dist/{renderer-DvFVoAgj.d.ts → renderer-BtOSseYf.d.ts} +29 -31
  29. package/dist/spells/index.js +1 -1
  30. package/dist/ui-layer.js +3 -2
  31. package/dist/worker.js +12 -5
  32. package/dist/world.d.ts +269 -15
  33. package/dist/world.js +1372 -628
  34. package/mcp/animation-server.mjs +1 -1
  35. package/mcp/engine-server.mjs +105 -7
  36. package/mcp/servers.mjs +4 -4
  37. package/package.json +10 -6
  38. package/src/animation-batch.ts +193 -0
  39. package/src/animation-layers.ts +7 -3
  40. package/src/animation.ts +209 -29
  41. package/src/asset-cache.ts +3 -3
  42. package/src/asset-memo.ts +202 -0
  43. package/src/assets.ts +436 -131
  44. package/src/auto-batch.ts +190 -44
  45. package/src/compute-driven.ts +1 -1
  46. package/src/config.ts +8 -0
  47. package/src/debug.ts +103 -22
  48. package/src/dev-global.ts +54 -0
  49. package/src/engine-hooks.ts +37 -0
  50. package/src/frame-budget.ts +19 -3
  51. package/src/game-boot-phase.ts +269 -0
  52. package/src/game-dev-tools.ts +7 -14
  53. package/src/game-frame-loop.ts +45 -82
  54. package/src/game-startup.ts +145 -70
  55. package/src/game-ui.ts +84 -0
  56. package/src/game.ts +168 -552
  57. package/src/gamepad-mappings.ts +269 -0
  58. package/src/generated/console-markers.ts +13 -0
  59. package/src/geometry-capture.ts +28 -4
  60. package/src/gpu-readings.ts +98 -0
  61. package/src/gpu-scene-bvh.ts +149 -36
  62. package/src/hot.ts +4 -7
  63. package/src/index.ts +115 -8
  64. package/src/input.ts +237 -25
  65. package/src/instanced-batch-lod.ts +3 -8
  66. package/src/interpolation.ts +171 -40
  67. package/src/look/ao-admission.ts +4 -3
  68. package/src/look/auto-exposure.ts +5 -16
  69. package/src/look/default-tone-mapping.ts +41 -5
  70. package/src/look/local-exposure.ts +2 -7
  71. package/src/look/quad-pass.ts +21 -0
  72. package/src/look/quality.ts +4 -0
  73. package/src/look/unreal-bloom.ts +4 -13
  74. package/src/look/world-environment.ts +58 -115
  75. package/src/merge-parts.ts +20 -24
  76. package/src/model-lod.ts +97 -14
  77. package/src/particle-significance.ts +12 -0
  78. package/src/particles.ts +19 -10
  79. package/src/platform.ts +23 -4
  80. package/src/profiling/FrameStages.ts +5 -6
  81. package/src/profiling/Spans.ts +3 -17
  82. package/src/profiling/debug-telemetry.ts +2 -6
  83. package/src/profiling/render-list-validate.ts +6 -15
  84. package/src/projection-marker.ts +2 -1
  85. package/src/quiet-markers.ts +3 -10
  86. package/src/render/cpu-bvh.ts +100 -0
  87. package/src/render/depth-pyramid.ts +6 -14
  88. package/src/render/environment/environmentContribution.ts +202 -0
  89. package/src/render/environment/environmentRadiance.ts +44 -0
  90. package/src/render/environment/environmentSampleCache.ts +56 -0
  91. package/src/render/environment/environmentSampling.ts +201 -0
  92. package/src/render/environment/environmentSnapshot.ts +71 -0
  93. package/src/render/environment/gate.ts +57 -0
  94. package/src/render/mesh-pool.ts +3 -19
  95. package/src/render/probe-trace.ts +872 -0
  96. package/src/render/probe-volume.ts +780 -34
  97. package/src/render/radiance-cache.ts +17 -0
  98. package/src/render/virtual-shadow-partial.ts +13 -0
  99. package/src/render/virtual-shadow.ts +18 -16
  100. package/src/render/world-impostor-surface.ts +109 -6
  101. package/src/render/world-impostor.ts +5 -2
  102. package/src/render-camera-cull.ts +98 -3
  103. package/src/render-environment.ts +41 -0
  104. package/src/renderer-config.ts +36 -0
  105. package/src/renderer-facts.ts +37 -0
  106. package/src/renderer.ts +52 -28
  107. package/src/resolution-scaler.ts +3 -2
  108. package/src/scene-entry-inspectors.ts +61 -0
  109. package/src/snow-field.ts +1 -0
  110. package/src/startup-offscreen-bytes.ts +78 -0
  111. package/src/static-transform.ts +25 -19
  112. package/src/streamed-textures.ts +112 -0
  113. package/src/streaming.ts +68 -4
  114. package/src/texture-streaming.ts +331 -0
  115. package/src/version.ts +1 -1
  116. package/src/worker.ts +12 -2
  117. package/src/world-bundle-safety.ts +55 -10
  118. package/src/world-cell-batches.ts +162 -200
  119. package/src/world-cell-chunks.ts +3 -7
  120. package/src/world-cell-impostors.ts +20 -8
  121. package/src/world-cell-options.ts +2 -14
  122. package/src/world-cell-placements.ts +194 -90
  123. package/src/world-cell-prewarm.ts +39 -4
  124. package/src/world-cell-records.ts +401 -0
  125. package/src/world-cell-render-bundles.ts +2 -2
  126. package/src/world-cell-render-gpu-dress.ts +13 -17
  127. package/src/world-cell-render-main-cull.ts +73 -17
  128. package/src/world-cell-render-util.ts +17 -4
  129. package/src/world-cell-render.ts +13 -5
  130. package/src/world-cell-residency.ts +15 -6
  131. package/src/world-cell-stale.ts +238 -0
  132. package/src/world-cells.ts +22 -5
  133. package/src/world-gpu-flags.ts +18 -50
  134. package/src/world-gpu-reference.ts +22 -8
  135. package/src/world-gpu-scene.ts +44 -24
  136. package/src/world-gpu-shadow.ts +21 -8
  137. package/src/world-gpu-types.ts +41 -13
  138. package/src/world-load-limiter.ts +5 -0
  139. package/src/world-model-sections.ts +80 -0
  140. package/src/world-river-ribbon.ts +282 -0
  141. package/src/world-root-frame.ts +39 -0
  142. package/src/world-shore-field.ts +91 -0
  143. package/src/world-static-pose.ts +163 -0
  144. package/src/world-surface-sampler.ts +48 -0
  145. package/src/world-terrain-splat.ts +10 -18
  146. package/src/world-tile-budget.ts +4 -11
  147. package/src/world-tiles.ts +79 -12
  148. package/src/world-validate.ts +6 -14
  149. package/src/world-warm.ts +51 -0
  150. package/src/world.ts +13 -0
@@ -0,0 +1,17 @@
1
+ import { type IProbeVolumeOptions, type IProbeVolumeTrace, ProbeVolume } from "./probe-volume.js";
2
+
3
+ export interface IRadianceCacheOptions extends Omit<IProbeVolumeOptions, "trace" | "update"> {
4
+ /** The packed scene a probe traces, the sun and the sky it reads. Every value is the game's. */
5
+ readonly trace: IProbeVolumeTrace;
6
+ }
7
+
8
+ /**
9
+ * A probe field that refreshes by tracing the packed scene, Unreal's radiance-cache update model: probes in view
10
+ * refresh first, the oldest first, a few hundred a frame at most, and the old values serve until replaced.
11
+ * It is a `ProbeVolume` whose update is always `trace`; sample it with `sampleNode`.
12
+ */
13
+ export class RadianceCache extends ProbeVolume {
14
+ constructor(options: IRadianceCacheOptions) {
15
+ super({ ...options, update: "trace" });
16
+ }
17
+ }
@@ -129,10 +129,23 @@ export function installPartialRender(
129
129
  current: () => IPartialPass | undefined,
130
130
  ): void {
131
131
  const stock = node.renderShadow.bind(node);
132
+ let quadBuilt = false;
132
133
  node.renderShadow = (frame) => {
133
134
  const pass = current();
134
135
  const pixels = pass?.pixels;
135
136
  if (pass === undefined || pixels === undefined) {
137
+ // The reset quad's pipeline is built on its first draw. Drawn once here, under the whole
138
+ // map's own clear, it is built with the first shadow render, behind a loading curtain, not on
139
+ // the first partial reset that a camera turn in play triggers (PRD-790).
140
+ if (!quadBuilt && frame.renderer !== null) {
141
+ quadBuilt = true;
142
+ const { scene, camera, object, material } = frame;
143
+ resetDepth(frame.renderer, node.shadow.camera.reversedDepth === true);
144
+ frame.scene = scene;
145
+ frame.camera = camera;
146
+ frame.object = object;
147
+ frame.material = material;
148
+ }
136
149
  stock(frame);
137
150
  return;
138
151
  }
@@ -4,7 +4,6 @@ import {
4
4
  type Camera,
5
5
  type DirectionalLight,
6
6
  FrontSide,
7
- Frustum,
8
7
  type InstancedMesh,
9
8
  type Material,
10
9
  Matrix4,
@@ -53,8 +52,10 @@ import {
53
52
  ShadowBaseNode,
54
53
  type UniformNode,
55
54
  } from "three/webgpu";
55
+ import { readLaunchFlag } from "../debug.js";
56
56
  import { shadowRedrawGpuMs } from "../render-pass-budget.js";
57
57
  import { DEFAULT_TARGET_FPS } from "../target-fps.js";
58
+ import { frustumPlanes } from "../world-gpu-types.js";
58
59
  import { isLeafReceiver } from "./soft-shadow.js";
59
60
  import {
60
61
  COST_SMOOTHING,
@@ -196,7 +197,6 @@ const _forward = new Vector3();
196
197
  /** A level's own light frustum, read once per level render and handed to its dispatch. */
197
198
  const _shadowProjection = new Matrix4();
198
199
  const _oldWorld = new Matrix4();
199
- const _shadowFrustum = new Frustum();
200
200
  const _shadowPlanes = new Float32Array(24);
201
201
  /** The depth row a level's map was drawn under, and the one this frame proposes: uploaded float32. */
202
202
  const _drawnDepth = new Float32Array(4);
@@ -214,8 +214,11 @@ interface IRenderingShadowNode {
214
214
 
215
215
  /** The slot the native bridge fills with its command sink on a core shadow node. */
216
216
  const COMMAND_KEY = Symbol.for("threenative.virtualShadowCommand");
217
+ /** The owned engine runs the clipmap and never calls updateBefore: it answers `settled` here each world render. */
218
+ const ENGINE_SETTLED_KEY = Symbol.for("threenative.virtualShadowSettled");
217
219
  interface ICommandSlot {
218
220
  [COMMAND_KEY]?: (value: object) => void;
221
+ [ENGINE_SETTLED_KEY]?: boolean;
219
222
  }
220
223
 
221
224
  /**
@@ -303,6 +306,8 @@ export class VirtualShadowNode extends ShadowBaseNode {
303
306
 
304
307
  /** Every map is present and no requested/delayed invalidation remains. */
305
308
  get settled(): boolean {
309
+ const engine = (this as ICommandSlot)[ENGINE_SETTLED_KEY];
310
+ if (engine !== undefined) return engine;
306
311
  return (
307
312
  this.#initialised &&
308
313
  this.#levels.length > 0 &&
@@ -1704,15 +1709,8 @@ export class VirtualShadowNode extends ShadowBaseNode {
1704
1709
  shadow.camera.projectionMatrix,
1705
1710
  shadow.camera.matrixWorldInverse,
1706
1711
  );
1707
- _shadowFrustum.setFromProjectionMatrix(_shadowProjection);
1708
1712
  const planes = _shadowPlanes;
1709
- for (const [at, plane] of _shadowFrustum.planes.entries()) {
1710
- const offset = at * 4;
1711
- planes[offset] = plane.normal.x;
1712
- planes[offset + 1] = plane.normal.y;
1713
- planes[offset + 2] = plane.normal.z;
1714
- planes[offset + 3] = plane.constant;
1715
- }
1713
+ frustumPlanes(_shadowProjection, planes);
1716
1714
  // Every compute leaves the one node frame every node shares with its fields at their bare
1717
1715
  // defaults — `scene` among them, which `Nodes.getNodeFrame()` sets with no arguments
1718
1716
  // (three.webgpu.js:56215, reached from `Renderer.compute` at 62235) and nothing puts back; the
@@ -2177,13 +2175,19 @@ export class VirtualShadowNode extends ShadowBaseNode {
2177
2175
  if (builder.renderer.shadowMap.enabled === false) return null;
2178
2176
  // Read once, like tnShadowStats. Build no diagnostic nodes unless the URL switch is on.
2179
2177
  if (this.#levelsRequested === undefined) {
2180
- const search = globalThis.location?.search ?? "";
2181
- this.#levelsRequested = /[?&]tnShadowLevels=(?!0(?:&|$))(?!false(?:&|$))[^&]/u.test(search);
2178
+ // One read of the URL for both switches: setup runs once, before the shader graph exists.
2179
+ const search = globalThis.location?.search;
2180
+ // Query only, as it always was: no environment variable and no global named these switches.
2181
+ this.#levelsRequested = readLaunchFlag(
2182
+ { environment: "", query: "tnShadowLevels" },
2183
+ "on",
2184
+ search,
2185
+ );
2182
2186
  // Counter runs: a fixed refreshStep, since the adaptive step follows measured render cost and
2183
2187
  // two runs of one route would move their windows at different ticks. Set once, before a frame.
2184
2188
  if (
2185
2189
  this.#adaptiveRefreshGiven === undefined &&
2186
- /[?&]tnAdaptiveRefresh=(?:0|false)(?:&|$)/u.test(search)
2190
+ readLaunchFlag({ environment: "", query: "tnAdaptiveRefresh" }, "off", search)
2187
2191
  ) {
2188
2192
  (this.options as { adaptiveRefresh: boolean }).adaptiveRefresh = false;
2189
2193
  }
@@ -2847,9 +2851,7 @@ export class VirtualShadowNode extends ShadowBaseNode {
2847
2851
 
2848
2852
  /** Whether `?tnShadowStats=1` is on this launch's URL, read once. */
2849
2853
  #statsWalkRequested(): boolean {
2850
- this.#statsRequested ??= /[?&]tnShadowStats=(?!0(?:&|$))(?!false(?:&|$))[^&]/u.test(
2851
- globalThis.location?.search ?? "",
2852
- );
2854
+ this.#statsRequested ??= readLaunchFlag({ environment: "", query: "tnShadowStats" });
2853
2855
  return this.#statsRequested;
2854
2856
  }
2855
2857
 
@@ -37,6 +37,7 @@ import {
37
37
  mat3,
38
38
  mat4,
39
39
  max,
40
+ min,
40
41
  modelWorldMatrix,
41
42
  normalize,
42
43
  positionGeometry,
@@ -146,6 +147,19 @@ const GEOMETRY_MAPS = [
146
147
  "transmissionMap",
147
148
  ] as const;
148
149
 
150
+ /**
151
+ * The node twins of those maps: a source's surface nodes describe its own mesh (a crown's ao and
152
+ * emissive sample its texture through `attribute("uv")`), which the quad does not have. Its scalar
153
+ * roughness and metalness stay; colour, normal, coverage and the cutout are the atlas's own nodes.
154
+ */
155
+ const SURFACE_NODES = [
156
+ "aoNode",
157
+ "emissiveNode",
158
+ "roughnessNode",
159
+ "metalnessNode",
160
+ "maskNode",
161
+ ] as const;
162
+
149
163
  /** One `mat4` node per CPU instance-matrix attribute, derived once and kept live with its source. */
150
164
  const INSTANCE_COLUMNS = new WeakMap<InstancedBufferAttribute, InstancedInterleavedBuffer>();
151
165
 
@@ -157,6 +171,13 @@ export interface IImpostorSurfaceOptions {
157
171
  readonly center: Vector3;
158
172
  /** The baked bounds' radius in asset-local space. */
159
173
  readonly radius: number;
174
+ /**
175
+ * The baked box's half size per asset-local axis (`impostorBounds`). With it the quad fits the
176
+ * box's projection instead of the bounding sphere: a spruce is a quarter of its sphere's square,
177
+ * and every fragment outside it ran the whole lit shader only to be discarded. Omitted, the quad
178
+ * is the sphere's square.
179
+ */
180
+ readonly halfExtents?: Vector3;
160
181
  /** The dominant source material; its class, roughness and metalness set the lit surface. */
161
182
  readonly source: Material;
162
183
  /** The source's own cutoff, or the scatter default. Kept positive for the shadow alpha caster. */
@@ -420,6 +441,7 @@ export class WorldImpostorSurface {
420
441
  throw new Error("WorldImpostorSurface requires a baked atlas.");
421
442
  const material = cloneLitMaterial(options.source);
422
443
  for (const key of GEOMETRY_MAPS) Reflect.set(material, key, null);
444
+ for (const key of SURFACE_NODES) Reflect.set(material, key, null);
423
445
  // Albedo and coverage are baked into the atlas; a vertex-colour attribute the quad does not
424
446
  // have, an opacity multiplier or an opacity node would apply the source's own colour and
425
447
  // coverage a second time on top of the baked one.
@@ -441,6 +463,8 @@ export class WorldImpostorSurface {
441
463
 
442
464
  const centerUniform = uniform(center);
443
465
  const radiusUniform = uniform(radius);
466
+ const halfUniform =
467
+ options.halfExtents === undefined ? undefined : uniform(options.halfExtents.clone());
444
468
  const cull = options.cull === true;
445
469
  const name = `WorldImpostorSurface${surfaceId}`;
446
470
  surfaceId += 1;
@@ -465,7 +489,22 @@ export class WorldImpostorSurface {
465
489
  const dAsset = normalize(asMat3(view).inverse().mul(eyeView));
466
490
  const basis = frameBasisNode(dAsset);
467
491
  const corner = positionGeometry.xy;
468
- const rel = basis.right.mul(corner.x).add(basis.up.mul(corner.y)).mul(radiusUniform);
492
+ // `impostorQuadExtents` on the GPU: the box's footprint circle across, its projection on `up`
493
+ // down, each with the slack a neighbouring frame's blend reaches, never past the sphere.
494
+ const extent = halfUniform
495
+ ? vec2(
496
+ min(radiusUniform, length(halfUniform.xz).mul(QUAD_ACROSS_SLACK)),
497
+ min(
498
+ radiusUniform,
499
+ abs(basis.up.x)
500
+ .mul(halfUniform.x)
501
+ .add(abs(basis.up.y).mul(halfUniform.y))
502
+ .add(abs(basis.up.z).mul(halfUniform.z))
503
+ .mul(QUAD_UP_SLACK),
504
+ ),
505
+ )
506
+ : vec2(radiusUniform, radiusUniform);
507
+ const rel = basis.right.mul(corner.x.mul(extent.x)).add(basis.up.mul(corner.y.mul(extent.y)));
469
508
  // A main-pass horizontal-distance gate: when the instance centre is past the asset's own cull
470
509
  // the quad collapses to a point, which the rasteriser drops. The cull is a per-instance
471
510
  // attribute, so one surface serves every canonical asset over this atlas each at its own
@@ -509,6 +548,9 @@ export class WorldImpostorSurface {
509
548
  transformNormal(fragment.normalAsset, instanceViewMatrixNode(builder)),
510
549
  )();
511
550
  material.positionNode = positionNode;
551
+ // A source's shadow position (a wind-swept crown casts its rest pose) would bypass the billboard
552
+ // above in the shadow draw: the quad must cast through its own positionNode.
553
+ material.castShadowPositionNode = null;
512
554
 
513
555
  const geometry = new BufferGeometry();
514
556
  geometry.setAttribute(
@@ -632,7 +674,17 @@ function buildFragmentNodes(
632
674
  const uvs: Node<"vec2">[] = [];
633
675
  const colors: Node<"vec4">[] = [];
634
676
  const normals: Node<"vec4">[] = [];
635
- for (let index = 0; index < 3; index += 1) {
677
+ // One march, on the frame the blend weighs most; the other two read the same surface point from
678
+ // their own view. Three marches were the far band's cost (PRD-866 AC-3).
679
+ const [wa, wb, wc] = weights as [Node<"float">, Node<"float">, Node<"float">];
680
+ const pickA = wa.greaterThanEqual(wb).and(wa.greaterThanEqual(wc));
681
+ const pickB = wb.greaterThanEqual(wc);
682
+ const [xa, xb, xc] = cellX as [Node<"float">, Node<"float">, Node<"float">];
683
+ const [ya, yb, yc] = cellY as [Node<"float">, Node<"float">, Node<"float">];
684
+ cellX.push(select(pickA, xa, select(pickB, xb, xc)));
685
+ cellY.push(select(pickA, ya, select(pickB, yb, yc)));
686
+ let marched: Node<"vec4"> | undefined;
687
+ for (let index = 3; index < 4; index += 1) {
636
688
  const direction = octahedralViewNode(
637
689
  cellX[index] as Node<"float">,
638
690
  cellY[index] as Node<"float">,
@@ -666,6 +718,7 @@ function buildFragmentNodes(
666
718
  const hit = Fn(() => {
667
719
  const found = float(0).toVar();
668
720
  const hitUv = vec2(2).toVar();
721
+ const hitT = float(0).toVar();
669
722
  const previousGap = float(0).toVar();
670
723
  const previousAlpha = float(0).toVar();
671
724
  const previousT = radiusUniform.toVar();
@@ -751,6 +804,7 @@ function buildFragmentNodes(
751
804
  ),
752
805
  () => {
753
806
  hitUv.assign(u);
807
+ hitT.assign(front.add(back).mul(0.5));
754
808
  found.assign(1);
755
809
  },
756
810
  );
@@ -764,11 +818,29 @@ function buildFragmentNodes(
764
818
  Break();
765
819
  });
766
820
  });
767
- return vec3(hitUv, found);
821
+ return vec4(hitUv, found, hitT);
768
822
  })();
769
- uvs.push(hit.xy);
770
- colors.push(colorMap.depth(layer).sample(hit.xy).mul(hit.z).toVar() as Node<"vec4">);
771
- normals.push(normalMap.depth(layer).sample(hit.xy).mul(hit.z).toVar() as Node<"vec4">);
823
+ marched = hit;
824
+ }
825
+
826
+ const surface = marched as Node<"vec4">;
827
+ const rayOut = normalize(select(orthographicNode(), dirVarying, dirVarying.sub(relVarying)));
828
+ const hitPoint = relVarying.add(rayOut.mul(surface.w));
829
+ for (let index = 0; index < 3; index += 1) {
830
+ const basis = frameBasisNode(
831
+ octahedralViewNode(cellX[index] as Node<"float">, cellY[index] as Node<"float">, grid),
832
+ );
833
+ const layer = (cellY[index] as Node<"float">)
834
+ .mul(grid)
835
+ .add(cellX[index] as Node<"float">)
836
+ .toInt();
837
+ const uv = vec2(dot(hitPoint, basis.right), dot(hitPoint, basis.up).negate())
838
+ .div(radiusUniform)
839
+ .mul(0.5)
840
+ .add(0.5);
841
+ uvs.push(uv);
842
+ colors.push(colorMap.depth(layer).sample(uv).mul(surface.z).toVar() as Node<"vec4">);
843
+ normals.push(normalMap.depth(layer).sample(uv).mul(surface.z).toVar() as Node<"vec4">);
772
844
  }
773
845
 
774
846
  const [w0, w1, w2] = weights as [Node<"float">, Node<"float">, Node<"float">];
@@ -787,6 +859,37 @@ function buildFragmentNodes(
787
859
  };
788
860
  }
789
861
 
862
+ /**
863
+ * Slack on the fitted quad. Across: a frame blended in from a neighbouring azimuth reprojects the
864
+ * footprint up to `1 / cos(45 deg)` wider, but its weight there is small, so a quarter covers it.
865
+ * Down: elevation neighbours shift the projection a little. Both stay inside the sphere's square.
866
+ */
867
+ const QUAD_ACROSS_SLACK = 1.25;
868
+ const QUAD_UP_SLACK = 1.1;
869
+
870
+ /**
871
+ * The quad's half width and half height for a view `direction` (asset space, toward the eye), as
872
+ * the surface's vertex shader computes them: the box footprint's circle across (any azimuth), the
873
+ * box's projection on the frame's `up` down, each with its slack and capped by the sphere radius.
874
+ */
875
+ export function impostorQuadExtents(
876
+ direction: Vector3,
877
+ halfExtents: Vector3,
878
+ radius: number,
879
+ ): { readonly across: number; readonly up: number } {
880
+ const { up } = impostorFrameBasis(direction);
881
+ return {
882
+ across: Math.min(radius, Math.hypot(halfExtents.x, halfExtents.z) * QUAD_ACROSS_SLACK),
883
+ up: Math.min(
884
+ radius,
885
+ (Math.abs(up.x) * halfExtents.x +
886
+ Math.abs(up.y) * halfExtents.y +
887
+ Math.abs(up.z) * halfExtents.z) *
888
+ QUAD_UP_SLACK,
889
+ ),
890
+ };
891
+ }
892
+
790
893
  /**
791
894
  * The frame basis the baker's orthographic camera actually built for `direction`: the three
792
895
  * endpoints of a view's own `lookAt`, so the sampler's projection and the bake share one basis.
@@ -152,6 +152,8 @@ export function impostorViewWeights(direction: Vector3): IViewBlend {
152
152
  export function impostorBounds(parts: readonly IImpostorPart[]): {
153
153
  readonly center: Vector3;
154
154
  readonly radius: number;
155
+ /** Half the baked box's size per asset-local axis, which fits the quad (`impostorQuadExtents`). */
156
+ readonly halfExtents: Vector3;
155
157
  } {
156
158
  const whole = new Box3();
157
159
  whole.makeEmpty();
@@ -168,10 +170,11 @@ export function impostorBounds(parts: readonly IImpostorPart[]): {
168
170
  whole.union(localBox);
169
171
  any = true;
170
172
  }
171
- if (!any) return { center: new Vector3(), radius: 0.5 };
173
+ if (!any) return { center: new Vector3(), radius: 0.5, halfExtents: new Vector3(0.5, 0.5, 0.5) };
172
174
  const center = whole.getCenter(new Vector3());
173
175
  const radius = whole.getBoundingSphere(new Sphere()).radius;
174
- return { center, radius: radius > 0 ? radius : 0.5 };
176
+ const halfExtents = whole.getSize(new Vector3()).multiplyScalar(0.5);
177
+ return { center, radius: radius > 0 ? radius : 0.5, halfExtents };
175
178
  }
176
179
 
177
180
  /** The exact byte cost of a mip chain of `levels` RGBA8 levels at `pixels` square and `depth` deep. */
@@ -112,6 +112,17 @@ const animationRateRootRefs = new WeakMap<Object3D, WeakRef<Object3D>>();
112
112
  /** The stand-ins named in {@link animationRateSources}, so the pass can reach them without a scene walk. */
113
113
  const animationRateCarriers = new Set<WeakRef<Object3D>>();
114
114
 
115
+ /** AnimationPlayer's disposal: the root stops carrying `state`, unless a newer player already took it. */
116
+ export function untrackAnimationRate(root: Object3D, state: IAnimationRateState): void {
117
+ if (animationRateStates.get(root) !== state) return;
118
+ animationRateStates.delete(root);
119
+ const id = engineRateIds.get(root);
120
+ if (id === undefined) return;
121
+ setEngineRateState(id, undefined);
122
+ const engineRig = root as Partial<IEngineRateRig>;
123
+ if (typeof engineRig.__trackAnimationRate === "function") engineRig.__trackAnimationRate(-1);
124
+ }
125
+
115
126
  /** A projection stand-in or skinned batch names the rigs it draws (see {@link animationRateSources}). */
116
127
  export function observeAnimationRates(
117
128
  carrier: Object3D,
@@ -121,9 +132,37 @@ export function observeAnimationRates(
121
132
  animationRateSources.set(carrier, sources);
122
133
  }
123
134
 
135
+ /**
136
+ * The engine's handle for each tracked root (PRD-878): the engine keeps the rigs and answers [handle, rate]
137
+ * pairs, so a frame finds each state by index instead of walking the roots in JS.
138
+ */
139
+ const engineRateIds = new WeakMap<Object3D, number>();
140
+ const engineRateStates: (IAnimationRateState | undefined)[] = [];
141
+ /** The live entries of {@link engineRateStates}: with none, a frame makes no band call at all. */
142
+ let engineRateRigs = 0;
143
+
144
+ function setEngineRateState(id: number, state: IAnimationRateState | undefined): void {
145
+ engineRateRigs += (state === undefined ? 0 : 1) - (engineRateStates[id] === undefined ? 0 : 1);
146
+ engineRateStates[id] = state;
147
+ }
148
+
149
+ interface IEngineRateRig {
150
+ __trackAnimationRate(id: number): void;
151
+ }
152
+
124
153
  /** AnimationPlayer's registration: the state the camera pass writes, and the root it is found on. */
125
154
  export function trackAnimationRate(root: Object3D, state: IAnimationRateState): void {
126
155
  animationRateStates.set(root, state);
156
+ const engineRig = root as Partial<IEngineRateRig>;
157
+ if (typeof engineRig.__trackAnimationRate === "function") {
158
+ let id = engineRateIds.get(root);
159
+ if (id === undefined) {
160
+ id = engineRateStates.length;
161
+ engineRateIds.set(root, id);
162
+ }
163
+ setEngineRateState(id, state);
164
+ engineRig.__trackAnimationRate(id);
165
+ }
127
166
  // One ref per root: a respawn's new player on the same root must not add a second walk of it.
128
167
  let ref = animationRateRootRefs.get(root);
129
168
  if (ref === undefined) {
@@ -236,6 +275,26 @@ function countEngineCost(name: string): void {
236
275
  host.__tnEngineCost[name] = (host.__tnEngineCost[name] ?? 0) + 1;
237
276
  }
238
277
 
278
+ /**
279
+ * A scene root whose engine runs the whole band pass (scene/projected_cull.h bandAnimation): [handle, rate]
280
+ * pairs, [handle, -1] for a freed rig, or undefined when a tracked rig sits inside another.
281
+ */
282
+ interface IEngineBandRoot {
283
+ __bandAnimation(
284
+ camera: Camera,
285
+ cameraResolved: boolean,
286
+ scale: number,
287
+ frame: number,
288
+ ): readonly number[] | undefined;
289
+ }
290
+
291
+ function engineBandRoot(root: unknown): IEngineBandRoot | undefined {
292
+ const candidate = root as Partial<IEngineBandRoot> | null;
293
+ return typeof candidate?.__bandAnimation === "function"
294
+ ? (candidate as IEngineBandRoot)
295
+ : undefined;
296
+ }
297
+
239
298
  function engineCullRoot(root: unknown): IEngineCullRoot | undefined {
240
299
  const candidate = root as Partial<IEngineCullRoot> | null;
241
300
  return typeof candidate?.__cullProjected === "function" &&
@@ -414,7 +473,7 @@ export class RenderCameraCull {
414
473
  this.#animationFrame += 1;
415
474
  this.#animationPrepared = true;
416
475
  this.#prepareCamera(camera, viewportHeight);
417
- if (!this.#prepareAnimated()) return;
476
+ if (this.#bandOnEngine(root, camera) || !this.#prepareAnimated()) return;
418
477
  // Start at each rig and each stand-in that observes one, never at the scene: the walk then visits
419
478
  // the same objects a scene walk would have acted on, and nothing else.
420
479
  const rootShown = this.#isVisibleInWorld(root as Object3D);
@@ -429,8 +488,8 @@ export class RenderCameraCull {
429
488
  const rig = ref.deref();
430
489
  if (rig === undefined || !this.#reaches(rig, root)) continue;
431
490
  turn += 1;
432
- if (!holds || turn % RATE_MEASURE_FRAMES === 0 || !this.#holdRate(rig))
433
- this.#visitRig(rig, rootShown);
491
+ if (holds && turn % RATE_MEASURE_FRAMES !== 0 && this.#holdRate(rig)) continue;
492
+ this.#visitRig(rig, rootShown);
434
493
  }
435
494
  for (const ref of animationRateCarriers) {
436
495
  const carrier = ref.deref();
@@ -447,6 +506,42 @@ export class RenderCameraCull {
447
506
  }
448
507
  }
449
508
 
509
+ /**
510
+ * On the engine, with no stand-in observing a rig, the whole pass is one call (PRD-878): the engine keeps the
511
+ * rigs, checks which reach the root, holds a crowd's rates and bands the rest. False sends the frame to the
512
+ * walk below: plain three, a stand-in, or a rig inside a rig.
513
+ */
514
+ #bandOnEngine(root: unknown, camera: Camera): boolean {
515
+ const engine = animationRateCarriers.size === 0 ? engineBandRoot(root) : undefined;
516
+ if (engine !== undefined && engineRateRigs === 0) return true;
517
+ const pairs = engine?.__bandAnimation(
518
+ camera,
519
+ this.#cameraResolved,
520
+ this.#scale,
521
+ this.#animationFrame,
522
+ );
523
+ if (pairs === undefined) return false;
524
+ this.#takeBands(pairs);
525
+ return true;
526
+ }
527
+
528
+ /** The engine's [handle, rate] pairs, written to each state as the JS walk writes it; -1 drops a freed rig. */
529
+ #takeBands(pairs: readonly number[]): void {
530
+ for (let index = 0; index + 1 < pairs.length; index += 2) {
531
+ const id = pairs[index] as number;
532
+ const rate = pairs[index + 1] as number;
533
+ if (rate < 0) {
534
+ setEngineRateState(id, undefined);
535
+ continue;
536
+ }
537
+ const state = engineRateStates[id];
538
+ if (state === undefined) continue;
539
+ state.rate = rate;
540
+ state.source = this;
541
+ state.frame = this.#animationFrame;
542
+ }
543
+ }
544
+
450
545
  /** Carries a rig's rate into this frame; false when last frame did not measure or hold it, as for a rig just shown. */
451
546
  #holdRate(rig: Object3D): boolean {
452
547
  const state = animationRateStates.get(rig);
@@ -0,0 +1,41 @@
1
+ /**
2
+ * The environment measure-and-sample mechanism every kit repeats: what the scene's environment
3
+ * actually contributes, a bounded GPU sample of it with a cache and a readback deadline, the
4
+ * provenance a stale readback is rejected by, and the gate that decides which renderer may run
5
+ * the material lane. The backlight itself is a shader with fixed constants, so it stays in each
6
+ * kit's `src/render/` (stamped from one source there) where the game can change how it looks.
7
+ *
8
+ * This is machinery, not a look: every colour, gain and threshold arrives as an argument, and a kit
9
+ * that wants a different bound passes a different one. It lives here because twelve kits held
10
+ * byte-identical copies — 9 084 lines — so a fix to one left eleven wrong with every gate green
11
+ * (`c93b427d0` touched 552 files for one look change).
12
+ *
13
+ * @situation measure what a scene's environment actually contributes
14
+ * @situation sample the environment on the GPU without stalling the frame
15
+ * @situation keep an environment readback from reaching a frame it does not belong to
16
+ */
17
+ export {
18
+ type IEnvironmentMeasurement,
19
+ measureEnvironment,
20
+ reportEnvironmentContribution,
21
+ } from "./render/environment/environmentContribution.js";
22
+ export { sampledRadiance } from "./render/environment/environmentRadiance.js";
23
+ export {
24
+ cacheEnvironmentSample,
25
+ cachedEnvironmentSample,
26
+ } from "./render/environment/environmentSampleCache.js";
27
+ export {
28
+ type IEnvironmentSample,
29
+ sampleEnvironment,
30
+ } from "./render/environment/environmentSampling.js";
31
+ export {
32
+ type IEnvironmentSourceSnapshot,
33
+ captureEnvironmentSnapshot,
34
+ environmentSnapshotCurrent,
35
+ samplingSourceSupported,
36
+ } from "./render/environment/environmentSnapshot.js";
37
+ export {
38
+ type IMaterialLightingEnvironment,
39
+ isWebGLFallbackRenderer,
40
+ materialLightingEnabled,
41
+ } from "./render/environment/gate.js";
@@ -1,10 +1,46 @@
1
1
  import type { IThreeNativeConfig } from "./config.js";
2
2
  import type { MatrixWorldMode } from "./matrix-world.js";
3
3
  import type { PlatformOS } from "./platform.js";
4
+ import type { IRendererOptions } from "./renderer.js";
4
5
  import { RESOLUTION_SCALER } from "./resolution-scaler.js";
5
6
 
6
7
  type RendererConfig = NonNullable<IThreeNativeConfig["renderer"]>;
7
8
 
9
+ /**
10
+ * What `defineGame({ renderer })` accepts: the project's portable renderer config (`threenative.config.ts`
11
+ * `renderer`, including its `android` block and `"auto"` scale) beside the live renderer options.
12
+ *
13
+ * One key for both. `defineGame` once took the portable config as `render` and the live options as
14
+ * `renderer`, so a game wrote `render: config.renderer` beside a second `renderer:` and the
15
+ * antialias and scale resolvers each fell back from one to the other. The scale is the one field
16
+ * the two disagreed on, and the portable form (a number or `"auto"`) is the superset.
17
+ */
18
+ export type GameRendererConfig = Omit<IRendererOptions, "resolutionScale" | "scaleSource"> &
19
+ RendererConfig;
20
+
21
+ const LEGACY_RENDER_KEY_MESSAGE =
22
+ 'TN_GAME_RENDER_KEY_RENAMED: defineGame({ render }) is now defineGame({ renderer }). Move the object to `renderer` with no other change: preferWebGPU, antialias, alphaAntialiasing, resolutionScale (a number in (0, 1] or "auto"), the android block, matrixWorld, projection and minimumProjectedPixels keep their names and meaning, and `config.renderer` from threenative.config.ts passes through unchanged. `scaleSource` is reported by the engine and is not an input. Where a game set both keys, `render` won, so merge them with the `render` values on top.';
23
+
24
+ /**
25
+ * Adopt the retired `render` key for one release, reporting the rename it names.
26
+ *
27
+ * Dropping the key silently would lose a game's scale, sampling and Android overrides; throwing on
28
+ * it refuses to boot every game written against 0.3.12, `config.renderer` and all. So the values are
29
+ * forwarded onto `renderer` — where a game set both, `render` won, so they go on top — and the
30
+ * rename is reported once with the guidance that names every field and its meaning.
31
+ */
32
+ export function adoptLegacyRenderKey<T extends object>(config: T): T {
33
+ const { render, ...rest } = config as T & { render?: unknown };
34
+ if (render === undefined) return config;
35
+ if (typeof render !== "object" || render === null)
36
+ throw new Error(
37
+ `TN_GAME_RENDER_KEY_INVALID: defineGame({ render }) must be an object, received ${typeof render}.`,
38
+ );
39
+ console.warn(LEGACY_RENDER_KEY_MESSAGE);
40
+ const renderer = (config as { renderer?: object }).renderer;
41
+ return { ...rest, renderer: { ...renderer, ...render } } as T;
42
+ }
43
+
8
44
  /** How the active drawing-buffer scale was arrived at, reported beside every fps number. */
9
45
  export type ScaleSource = "pinned" | "auto";
10
46
 
@@ -0,0 +1,37 @@
1
+ /**
2
+ * What a renderer is, asked in one place.
3
+ *
4
+ * The facade wraps either the owned C++ engine or upstream three, and four core subsystems used to
5
+ * answer that by probing the renderer's own `info` object with `"engine" in info` — a fact spelled
6
+ * in four files, so a rename in the engine's info table would have left them all reporting the wrong
7
+ * backend with nothing failing. This is the one reader.
8
+ *
9
+ * `kind` is the wrapper's own label (`"webgpu"` for either backend: three's WebGPU renderer can run
10
+ * a WebGL fallback behind it, which is `isWebGLFallbackRenderer`'s question, not this one).
11
+ */
12
+ export interface IRendererFacts {
13
+ /** The wrapper's backend label, as `OutputRenderer.kind` reports it. */
14
+ readonly kind: string;
15
+ /** Whether the owned engine is behind the facade, rather than upstream three. */
16
+ readonly ownedEngine: boolean;
17
+ }
18
+
19
+ /** The renderer shape these facts are read from: a `kind` label and the raw three renderer. */
20
+ export interface IRendererFactSource {
21
+ readonly kind?: string;
22
+ readonly raw?: unknown;
23
+ }
24
+
25
+ /**
26
+ * The facts about `renderer`, from its own `info` table.
27
+ *
28
+ * A renderer with no `info` at all, or one from upstream three, is not the owned engine. A test
29
+ * double may pass nothing, which is the same answer.
30
+ */
31
+ export function rendererFacts(renderer: IRendererFactSource | undefined): IRendererFacts {
32
+ const info = (renderer?.raw as { info?: { engine?: unknown } } | undefined)?.info;
33
+ return {
34
+ kind: renderer?.kind ?? "unknown",
35
+ ownedEngine: info !== undefined && info.engine !== undefined,
36
+ };
37
+ }