@threenative/core 0.3.6 → 0.3.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/README.md +3 -5
  2. package/capabilities.json +739 -50
  3. package/dist/{assets-CqvE429w.d.ts → assets-YUbXa3-Y.d.ts} +101 -2
  4. package/dist/{canvas-layer-C1-5CviZ.d.ts → canvas-layer-vCtanIeB.d.ts} +1 -1
  5. package/dist/{game-Jz4Fdoeb.d.ts → game-cb99J-YE.d.ts} +100 -31
  6. package/dist/hot.d.ts +4 -4
  7. package/dist/hot.js +23 -5
  8. package/dist/index.d.ts +1742 -29
  9. package/dist/index.js +22443 -12423
  10. package/dist/{model-lod-BDAUYgsS.d.ts → model-lod-CTpZ6imz.d.ts} +1 -1
  11. package/dist/net.js +39 -12
  12. package/dist/playtest.d.ts +4 -4
  13. package/dist/playtest.js +48 -9
  14. package/dist/react-css.js +23 -0
  15. package/dist/react.d.ts +2 -2
  16. package/dist/{renderer-9yEo9hPa.d.ts → renderer-rZm0hVqq.d.ts} +178 -5
  17. package/dist/ui-layer.d.ts +11 -2
  18. package/dist/ui-layer.js +76 -4
  19. package/dist/worker.d.ts +36 -0
  20. package/dist/worker.js +1088 -0
  21. package/dist/world.d.ts +11 -3
  22. package/dist/world.js +1117 -197
  23. package/mcp/animation-server.mjs +265 -0
  24. package/mcp/animation.mjs +22 -0
  25. package/mcp/call.mjs +105 -0
  26. package/mcp/devtools.mjs +5 -0
  27. package/mcp/engine-server.mjs +713 -37
  28. package/mcp/launch.mjs +3 -2
  29. package/mcp/servers.d.mts +2 -0
  30. package/mcp/servers.mjs +33 -8
  31. package/package.json +12 -8
  32. package/patches/three@0.185.1-prd269-upgrade.patch +308 -0
  33. package/patches/three@0.185.1.patch +481 -272
  34. package/src/animation-packet-state.ts +88 -0
  35. package/src/animation-pose-packet.ts +537 -0
  36. package/src/animation.ts +779 -31
  37. package/src/asset-cache.ts +719 -0
  38. package/src/assets.ts +521 -152
  39. package/src/audio.ts +29 -3
  40. package/src/auto-batch.ts +792 -0
  41. package/src/config.ts +2 -0
  42. package/src/frame-budget.ts +268 -2
  43. package/src/game.ts +525 -105
  44. package/src/grounding.ts +7 -6
  45. package/src/hot.ts +19 -5
  46. package/src/index.ts +381 -6
  47. package/src/input.ts +21 -2
  48. package/src/interpolation.ts +19 -1
  49. package/src/launch-diagnostics.ts +7 -2
  50. package/src/look/ao-multibounce.ts +29 -0
  51. package/src/look/ao-reach.ts +39 -0
  52. package/src/look/auto-exposure.ts +264 -0
  53. package/src/look/default-tone-mapping.ts +44 -0
  54. package/src/look/exposure-graph.ts +208 -0
  55. package/src/look/exposure-readback.ts +97 -0
  56. package/src/look/exposure-settings.ts +132 -0
  57. package/src/look/filmic-tone-mapping.ts +852 -0
  58. package/src/look/gi-registry.ts +55 -0
  59. package/src/look/local-exposure.ts +507 -0
  60. package/src/look/look-diagnostics.ts +24 -0
  61. package/src/look/motion-blur.ts +42 -0
  62. package/src/look/quality.ts +309 -0
  63. package/src/look/reflection-trace.ts +344 -0
  64. package/src/look/unreal-bloom.ts +295 -0
  65. package/src/look/vignette.ts +14 -0
  66. package/src/look/world-environment.ts +2033 -0
  67. package/src/loop.ts +25 -1
  68. package/src/merge-parts.ts +25 -10
  69. package/src/model-lod.ts +14 -0
  70. package/src/net-session.ts +58 -14
  71. package/src/ocean/spectral.ts +41 -7
  72. package/src/picking.ts +72 -5
  73. package/src/platform.ts +29 -1
  74. package/src/playtest.ts +54 -8
  75. package/src/profiling/FrameCounters.ts +166 -5
  76. package/src/profiling/FrameStages.ts +289 -0
  77. package/src/profiling/Spans.ts +39 -25
  78. package/src/profiling/debug-telemetry.ts +312 -0
  79. package/src/profiling/scene-warning.ts +42 -6
  80. package/src/projection-apply.ts +11 -3
  81. package/src/projection-content.ts +189 -0
  82. package/src/projection-marker.ts +6 -2
  83. package/src/projection-plan.ts +279 -28
  84. package/src/projection-skinned.ts +620 -5
  85. package/src/projection-stability.ts +16 -0
  86. package/src/projection-uniform.ts +5 -1
  87. package/src/quiet-markers.ts +56 -0
  88. package/src/render/budget-ladder.ts +256 -0
  89. package/src/render/chain.ts +89 -7
  90. package/src/render/exposure-units.ts +59 -0
  91. package/src/render/frame-time-budget.ts +162 -0
  92. package/src/render/gi-budget.ts +231 -0
  93. package/src/render/gi-visualize.ts +49 -0
  94. package/src/render/material-key.ts +1 -0
  95. package/src/render/probe-volume.ts +196 -36
  96. package/src/render/rough-diffuse.ts +177 -0
  97. package/src/render/scene-trace.ts +532 -0
  98. package/src/render/shadow-filter-budget.ts +237 -0
  99. package/src/render/sky-capture.ts +194 -0
  100. package/src/render/soft-shadow.ts +607 -0
  101. package/src/render/surface-cache.ts +418 -0
  102. package/src/render/traced-reflections.ts +408 -0
  103. package/src/render/two-sided-foliage.ts +120 -0
  104. package/src/render/virtual-shadow-pages.ts +112 -12
  105. package/src/render/virtual-shadow.ts +386 -38
  106. package/src/render-camera-cull.ts +536 -31
  107. package/src/render-pass-budget.ts +140 -22
  108. package/src/renderProjection.ts +65 -9
  109. package/src/renderer-config.ts +3 -2
  110. package/src/renderer.ts +289 -14
  111. package/src/resolution-scaler.ts +65 -7
  112. package/src/skeletal-mesh.ts +4 -0
  113. package/src/snow-field.ts +46 -0
  114. package/src/softbody.ts +6 -5
  115. package/src/startup-offscreen-bytes.ts +168 -0
  116. package/src/startup-readiness.ts +137 -2
  117. package/src/ui-bridge.ts +38 -0
  118. package/src/ui-hit-regions.ts +6 -2
  119. package/src/ui-layer.ts +1 -0
  120. package/src/ui-state.ts +32 -3
  121. package/src/version.ts +1 -1
  122. package/src/viewport.ts +8 -5
  123. package/src/warmup.ts +76 -10
  124. package/src/worker-audio.ts +579 -0
  125. package/src/worker.ts +842 -0
  126. package/src/world-cells.ts +4 -1
  127. package/gpl/LICENSE.GPL +0 -117
  128. package/gpl/convert.py +0 -192
  129. package/gpl/fixtures/make_world_fixture.py +0 -184
  130. package/gpl/recipes/_common.py +0 -180
  131. package/gpl/recipes/bake_ao.py +0 -111
  132. package/gpl/recipes/decimate.py +0 -70
  133. package/gpl/recipes/export_world.py +0 -699
  134. package/gpl/recipes/retarget.py +0 -131
  135. package/gpl/recipes/unwrap.py +0 -71
  136. package/mcp/blender-server.mjs +0 -689
  137. package/mcp/blender.mjs +0 -26
@@ -1,4 +1,4 @@
1
- import { type Camera, Frustum, Matrix4, type Object3D, Vector3 } from "three";
1
+ import { type Camera, Matrix4, type Object3D, Vector3 } from "three";
2
2
 
3
3
  import { isRenderable } from "./projection-plan.js";
4
4
 
@@ -63,6 +63,7 @@ const DYNAMIC_BOUNDS = Symbol("render-camera-cull-dynamic-bounds");
63
63
  /** What the gate remembers about a geometry's position buffer between consults. */
64
64
  interface IPositionVersion {
65
65
  version: number;
66
+ frame: number;
66
67
  /** True when the previous consult also saw a change, so this one is the second in a row. */
67
68
  changedLastConsult: boolean;
68
69
  /** True when a rewrite was exempted without a rescan, so the cached sphere is stale. */
@@ -72,6 +73,57 @@ interface IPositionVersion {
72
73
  /** A sphere nearer than this to the camera would divide by zero; treat it as this far away. */
73
74
  const MIN_DISTANCE = 1e-4;
74
75
 
76
+ /**
77
+ * Internal mirror metadata: a projection stand-in or a skinned batch observes the authored rigs it
78
+ * draws. A JS map, not `userData`: on the web engine every `userData` read crosses into Wasm, and the
79
+ * camera pass asked every object in the scene for it.
80
+ */
81
+ export const animationRateSources = new WeakMap<Object3D, ReadonlyMap<Object3D, unknown>>();
82
+
83
+ /** Internal observations shared with AnimationPlayer, owned by the root rather than the game. */
84
+ export interface IAnimationRateState {
85
+ rate: number;
86
+ /** Cadence actually selected by the player on its last update; absent metadata stays stock. */
87
+ effectiveRate?: number;
88
+ frame: number;
89
+ source: RenderCameraCull | undefined;
90
+ evaluated: boolean;
91
+ evaluation: number;
92
+ /** Set by the player from its `gpuPose` option; the skinned batch evaluates no other rig on the GPU. */
93
+ gpuPoseEnabled?: boolean;
94
+ /** Set by the skinned batch while the GPU evaluates this rig's pose from keyframes and time. */
95
+ gpuPose?: boolean;
96
+ /** Set by the player: brings the CPU bones to the current playhead now. */
97
+ syncBones?: () => void;
98
+ }
99
+ export const animationRateStates = new WeakMap<Object3D, IAnimationRateState>();
100
+ /** The roots that may hold a rate state, so the camera pass walks the rigs instead of the scene. */
101
+ const animationRateRoots = new Set<WeakRef<Object3D>>();
102
+ const animationRateRootRefs = new WeakMap<Object3D, WeakRef<Object3D>>();
103
+ /** The stand-ins named in {@link animationRateSources}, so the pass can reach them without a scene walk. */
104
+ const animationRateCarriers = new Set<WeakRef<Object3D>>();
105
+
106
+ /** A projection stand-in or skinned batch names the rigs it draws (see {@link animationRateSources}). */
107
+ export function observeAnimationRates(
108
+ carrier: Object3D,
109
+ sources: ReadonlyMap<Object3D, unknown>,
110
+ ): void {
111
+ if (!animationRateSources.has(carrier)) animationRateCarriers.add(new WeakRef(carrier));
112
+ animationRateSources.set(carrier, sources);
113
+ }
114
+
115
+ /** AnimationPlayer's registration: the state the camera pass writes, and the root it is found on. */
116
+ export function trackAnimationRate(root: Object3D, state: IAnimationRateState): void {
117
+ animationRateStates.set(root, state);
118
+ // One ref per root: a respawn's new player on the same root must not add a second walk of it.
119
+ let ref = animationRateRootRefs.get(root);
120
+ if (ref === undefined) {
121
+ ref = new WeakRef(root);
122
+ animationRateRootRefs.set(root, ref);
123
+ }
124
+ animationRateRoots.add(ref);
125
+ }
126
+
75
127
  export interface IRenderCameraCullOptions {
76
128
  /**
77
129
  * Projected diameter in pixels below which an object is skipped, or `false` to leave every
@@ -155,6 +207,26 @@ interface IEngineCullRoot {
155
207
  __restoreCull(): void;
156
208
  }
157
209
 
210
+ /**
211
+ * The native engine counts every add, remove, attach and destroy in the process (scene/object3d.h).
212
+ * While it holds still, no subtree changed, so a walk that only finds who is under whom can be kept.
213
+ * Plain three has no such count, and its walks run every frame as before.
214
+ */
215
+ function hierarchyRevision(object: Object3D): number | undefined {
216
+ const revision = (object as { __hierarchyRevision?: unknown }).__hierarchyRevision;
217
+ return typeof revision === "number" ? revision : undefined;
218
+ }
219
+
220
+ /**
221
+ * Counts one costly step by name in `globalThis.__tnEngineCost`, the bag a playtest reads per frame
222
+ * (core reports it per frame in TN_FRAME_BUDGET.counters.engine), so a kit that brings back a per-frame walk fails its bound.
223
+ */
224
+ function countEngineCost(name: string): void {
225
+ const host = globalThis as { __tnEngineCost?: Record<string, number> };
226
+ host.__tnEngineCost ??= {};
227
+ host.__tnEngineCost[name] = (host.__tnEngineCost[name] ?? 0) + 1;
228
+ }
229
+
158
230
  function engineCullRoot(root: unknown): IEngineCullRoot | undefined {
159
231
  const candidate = root as Partial<IEngineCullRoot> | null;
160
232
  return typeof candidate?.__cullProjected === "function" &&
@@ -172,13 +244,38 @@ function engineCullRoot(root: unknown): IEngineCullRoot | undefined {
172
244
  * all owned by the instance.
173
245
  */
174
246
  export class RenderCameraCull {
247
+ #animationFrame = 0;
248
+ #animationPrepared = false;
175
249
  readonly #enabled: boolean;
176
250
  readonly #minimumPixels: number;
177
251
  readonly #center = new Vector3();
178
- readonly #frustum = new Frustum();
252
+ /**
253
+ * The main camera's six frustum planes, [nx, ny, nz, constant] each, as three's
254
+ * `Frustum.setFromProjectionMatrix` makes them. Plain numbers, so a test against them never crosses
255
+ * into the engine (its Frustum, Ray and Sphere are engine objects: one call per test).
256
+ */
257
+ readonly #planes = new Float64Array(24);
179
258
  readonly #projectionScreen = new Matrix4();
180
259
  readonly #hidden: Object3D[] = [];
260
+ readonly #animationVisitor: (object: Object3D) => void;
181
261
  readonly #visitor: (object: Object3D) => void;
262
+ /**
263
+ * Every object under a live rate root this frame, with the states of the roots above it: only
264
+ * these can change a rate, and their states need no walk up the parents.
265
+ */
266
+ readonly #animated = new Map<Object3D, readonly IAnimationRateState[]>();
267
+ #collecting: readonly IAnimationRateState[] = [];
268
+ /** Each root, its state and the engine's hierarchy count read off it, as {@link #animated} was built. */
269
+ readonly #animatedFrom: (Object3D | IAnimationRateState | number | undefined)[] = [];
270
+ /** The renderables under each rate root, in walk order, from the same walk as {@link #animated}. */
271
+ readonly #rigParts = new Map<Object3D, Object3D[]>();
272
+ #collectingParts: Object3D[] = [];
273
+ readonly #collectAnimated: (object: Object3D) => void;
274
+ /** The camera's descendants this frame, so camera attachment needs no walk up the parents. */
275
+ readonly #cameraParts = new Set<Object3D>();
276
+ readonly #collectCameraPart: (object: Object3D) => void;
277
+ #cameraPartsOf: Camera | undefined;
278
+ #cameraPartsRevision: number | undefined;
182
279
  /** Last position-buffer version seen per geometry, so a rewritten dynamic bound is recomputed. */
183
280
  readonly #positionVersions = new WeakMap<object, IPositionVersion>();
184
281
  #hiddenCount = 0;
@@ -188,6 +285,10 @@ export class RenderCameraCull {
188
285
  #cameraZ = 0;
189
286
  #scale = 0;
190
287
  #cameraResolved = true;
288
+ /** The camera's forward centre ray, [ox, oy, oz, dx, dy, dz]: the camera position and unit direction. */
289
+ readonly #ray = new Float64Array([0, 0, 0, 0, 0, -1]);
290
+ /** Per rig: [frame, x, y, z, radius] of the union of its parts' spheres so far this frame. */
291
+ readonly #rigSpheres = new WeakMap<IAnimationRateState, Float64Array>();
191
292
  #considered = 0;
192
293
  #culled = 0;
193
294
  #exemptCameraAttached = 0;
@@ -208,7 +309,60 @@ export class RenderCameraCull {
208
309
  }
209
310
  this.#enabled = requested !== false;
210
311
  this.#minimumPixels = requested === false ? DEFAULT_MINIMUM_PROJECTED_PIXELS : requested;
312
+ this.#animationVisitor = (object) => this.#visitAnimation(object);
211
313
  this.#visitor = (object) => this.#visit(object);
314
+ this.#collectAnimated = (object) => {
315
+ if (isRenderable(object)) this.#collectingParts.push(object);
316
+ const outer = this.#animated.get(object);
317
+ // A rig nested in another rig answers to both roots.
318
+ this.#animated.set(
319
+ object,
320
+ outer === undefined ? this.#collecting : [...outer, ...this.#collecting],
321
+ );
322
+ };
323
+ this.#collectCameraPart = (object) => this.#cameraParts.add(object);
324
+ }
325
+
326
+ /**
327
+ * Rebuilds {@link #animated} from the live rate roots; false when no rig can take a rate. The
328
+ * roots and states are JS objects; only the walk under them crosses into the engine, so it is
329
+ * kept while the same roots hold the same states and the engine's hierarchy has not moved.
330
+ */
331
+ #prepareAnimated(): boolean {
332
+ let same = true;
333
+ let at = 0;
334
+ for (const ref of animationRateRoots) {
335
+ const root = ref.deref();
336
+ const state = root === undefined ? undefined : animationRateStates.get(root);
337
+ if (root === undefined || state === undefined) {
338
+ animationRateRoots.delete(ref);
339
+ continue;
340
+ }
341
+ if (same) {
342
+ const revision = hierarchyRevision(root);
343
+ same =
344
+ revision !== undefined &&
345
+ this.#animatedFrom[at] === root &&
346
+ this.#animatedFrom[at + 1] === state &&
347
+ this.#animatedFrom[at + 2] === revision;
348
+ }
349
+ at += 3;
350
+ }
351
+ if (same && at === this.#animatedFrom.length) return this.#animated.size > 0;
352
+ countEngineCost("cullRigRebuilds");
353
+ this.#animated.clear();
354
+ this.#animatedFrom.length = 0;
355
+ this.#rigParts.clear();
356
+ for (const ref of animationRateRoots) {
357
+ const root = ref.deref() as Object3D;
358
+ const state = animationRateStates.get(root) as IAnimationRateState;
359
+ this.#animatedFrom.push(root, state, hierarchyRevision(root));
360
+ this.#collecting = [state];
361
+ this.#collectingParts = [];
362
+ root.traverse(this.#collectAnimated);
363
+ this.#rigParts.set(root, this.#collectingParts);
364
+ }
365
+ return this.#animated.size > 0;
212
366
  }
213
367
 
214
368
  get report(): IRenderCameraCullReport {
@@ -228,6 +382,85 @@ export class RenderCameraCull {
228
382
  };
229
383
  }
230
384
 
385
+ get animationFrame(): number {
386
+ return this.#animationFrame;
387
+ }
388
+
389
+ /**
390
+ * Publishes camera-driven animation metadata without changing draw visibility.
391
+ *
392
+ * The game calls this before scene `beforeRender` callbacks and projection packing, then calls
393
+ * {@link apply} after those phases for the one visibility cull that feeds the draw.
394
+ */
395
+ prepareAnimation(
396
+ root: { traverseVisible(callback: (object: Object3D) => void): void },
397
+ camera: Camera,
398
+ viewportHeight: number,
399
+ ): void {
400
+ this.restore();
401
+ this.#animationFrame += 1;
402
+ this.#animationPrepared = true;
403
+ this.#prepareCamera(camera, viewportHeight);
404
+ if (!this.#prepareAnimated()) return;
405
+ // Start at each rig and each stand-in that observes one, never at the scene: the walk then visits
406
+ // the same objects a scene walk would have acted on, and nothing else.
407
+ const rootShown = this.#isVisibleInWorld(root as Object3D);
408
+ for (const ref of animationRateRoots) {
409
+ const rig = ref.deref();
410
+ if (rig !== undefined && this.#reaches(rig, root)) this.#visitRig(rig, rootShown);
411
+ }
412
+ for (const ref of animationRateCarriers) {
413
+ const carrier = ref.deref();
414
+ const sources = carrier === undefined ? undefined : animationRateSources.get(carrier);
415
+ if (carrier === undefined || sources === undefined) {
416
+ animationRateCarriers.delete(ref);
417
+ continue;
418
+ }
419
+ // A carrier inside a rig is visited by that rig's walk.
420
+ if (this.#animated.has(carrier)) continue;
421
+ let observes = false;
422
+ for (const source of sources.keys()) observes ||= this.#animated.has(source);
423
+ if (observes && this.#reaches(carrier, root)) carrier.traverseVisible(this.#animationVisitor);
424
+ }
425
+ }
426
+
427
+ /**
428
+ * The rig's visible walk, as `traverseVisible` would make it. Only its renderables act, so on the
429
+ * native engine, with the walk's root shown, each kept part asks whether it is shown, rather
430
+ * than the walk wrapping every bone across the boundary. A rig that reaches a shown root is itself
431
+ * shown, so a part shown in the world is exactly a part its rig's walk reaches.
432
+ *
433
+ * The answer is this file's own walk, not the engine's `__tnVisibleInWorld`: that call was one
434
+ * crossing per kept part (240 a frame on the stress lab's crowd), while `visible` is an engine
435
+ * field and `parent` a kept hierarchy answer, so the same walk in JS crosses nothing.
436
+ */
437
+ #visitRig(rig: Object3D, rootShown: boolean): void {
438
+ const parts = rootShown ? this.#rigParts.get(rig) : undefined;
439
+ if (
440
+ parts === undefined ||
441
+ typeof (rig as { __tnVisibleInWorld?: unknown }).__tnVisibleInWorld !== "function"
442
+ ) {
443
+ countEngineCost("cullRigWalks");
444
+ rig.traverseVisible(this.#animationVisitor);
445
+ return;
446
+ }
447
+ for (const part of parts) if (this.#isVisibleInWorld(part)) this.#visitAnimation(part);
448
+ }
449
+
450
+ /**
451
+ * True when a scene walk from `root` would visit `object`: it and every parent up to `root` are
452
+ * visible. A rate root above it answers false, since that root's own walk covers it.
453
+ */
454
+ #reaches(object: Object3D, root: unknown): boolean {
455
+ if (!object.visible) return false;
456
+ for (let node = object.parent; node !== null; node = node.parent) {
457
+ if (animationRateStates.has(node)) return false;
458
+ if (!node.visible) return false;
459
+ if (node === root) return true;
460
+ }
461
+ return object === root;
462
+ }
463
+
231
464
  /**
232
465
  * Hides every renderable under `root` that this camera resolves to fewer than the threshold,
233
466
  * then calls `restore` implicitly on the next call. Call {@link restore} after the render.
@@ -242,6 +475,11 @@ export class RenderCameraCull {
242
475
  viewportHeight: number,
243
476
  ): void {
244
477
  this.restore();
478
+ if (!this.#animationPrepared) {
479
+ this.#animationFrame += 1;
480
+ this.#prepareAnimated();
481
+ }
482
+ this.#animationPrepared = false;
245
483
  this.#considered = 0;
246
484
  this.#culled = 0;
247
485
  this.#exemptCameraAttached = 0;
@@ -250,13 +488,40 @@ export class RenderCameraCull {
250
488
  this.#exemptWithoutBounds = 0;
251
489
  this.#exemptDynamicBounds = 0;
252
490
  this.#exemptFrustumCulled = 0;
491
+ if (this.#prepareCamera(camera, viewportHeight, root)) return;
492
+ root.traverseVisible(this.#visitor);
493
+ }
494
+
495
+ /** Undoes every hide this gate made, leaving the authored scene as the game left it. */
496
+ restore(): void {
497
+ this.#engineRoot?.__restoreCull();
498
+ this.#engineRoot = undefined;
499
+ for (let index = 0; index < this.#hiddenCount; index += 1) {
500
+ (this.#hidden[index] as Object3D).visible = true;
501
+ }
502
+ this.#hiddenCount = 0;
503
+ }
504
+
505
+ dispose(): void {
506
+ this.restore();
507
+ this.#animationPrepared = false;
508
+ this.#camera = undefined;
509
+ this.#animated.clear();
510
+ this.#animatedFrom.length = 0;
511
+ this.#rigParts.clear();
512
+ this.#cameraParts.clear();
513
+ this.#cameraPartsOf = undefined;
514
+ }
515
+
516
+ /** Resolves the camera; returns true when the engine walked `root` itself and answered the counters. */
517
+ #prepareCamera(camera: Camera, viewportHeight: number, root?: unknown): boolean {
253
518
  this.#cameraResolved = true;
254
519
  this.#camera = undefined;
255
520
  // The walk runs whether or not the gate is enabled: turning the convention off must not turn
256
521
  // its measurement off, so a disabled gate still reports what it considered and would have
257
522
  // skipped. Only the hide below is gated by `#enabled`.
258
523
  const perspective = camera as Camera & { isPerspectiveCamera?: boolean; fov?: number };
259
- const engine = engineCullRoot(root);
524
+ const engine = root === undefined ? undefined : engineCullRoot(root);
260
525
  if (!Number.isFinite(viewportHeight) || viewportHeight <= 0) {
261
526
  this.#cameraResolved = false;
262
527
  } else if (
@@ -271,6 +536,10 @@ export class RenderCameraCull {
271
536
  } else {
272
537
  if (camera.matrixWorldAutoUpdate === true) camera.updateMatrixWorld();
273
538
  this.#camera = camera;
539
+ if (engine === undefined) {
540
+ // The engine finds what hangs from the camera itself; this set serves only the JS walk.
541
+ this.#findCameraParts(camera);
542
+ }
274
543
  this.#scale = viewportHeight / (2 * Math.tan((perspective.fov * Math.PI) / 360));
275
544
  }
276
545
  if (engine !== undefined) {
@@ -292,44 +561,67 @@ export class RenderCameraCull {
292
561
  this.#exemptDynamicBounds = counts[6] as number;
293
562
  this.#exemptFrustumCulled = counts[7] as number;
294
563
  this.#engineRoot = engine;
295
- return;
564
+ return true;
296
565
  }
297
566
  if (this.#camera !== undefined) {
298
567
  const elements = camera.matrixWorld.elements;
299
568
  this.#cameraX = elements[12] as number;
300
569
  this.#cameraY = elements[13] as number;
301
570
  this.#cameraZ = elements[14] as number;
571
+ const fx = -(elements[8] as number);
572
+ const fy = -(elements[9] as number);
573
+ const fz = -(elements[10] as number);
574
+ const length = Math.hypot(fx, fy, fz) || 1;
575
+ this.#ray.set([
576
+ this.#cameraX,
577
+ this.#cameraY,
578
+ this.#cameraZ,
579
+ fx / length,
580
+ fy / length,
581
+ fz / length,
582
+ ]);
302
583
  // The main frustum is what tells an off-camera shadow caster from a visible but unresolvable
303
584
  // one. Perspective cameras keep `matrixWorldInverse` in step inside `updateMatrixWorld`.
304
585
  this.#projectionScreen.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
305
- this.#frustum.setFromProjectionMatrix(this.#projectionScreen);
586
+ setFrustumPlanes(this.#planes, this.#projectionScreen.elements);
306
587
  }
307
- root.traverseVisible(this.#visitor);
588
+ return false;
308
589
  }
309
590
 
310
- /** Undoes every hide this gate made, leaving the authored scene as the game left it. */
311
- restore(): void {
312
- this.#engineRoot?.__restoreCull();
313
- this.#engineRoot = undefined;
314
- for (let index = 0; index < this.#hiddenCount; index += 1) {
315
- (this.#hidden[index] as Object3D).visible = true;
591
+ #visitAnimation(object: Object3D): void {
592
+ // Only a rig's own parts and the stand-ins that observe rigs can change a rate; everything else
593
+ // is left unread (each read is an engine crossing on the web engine).
594
+ const animated = this.#animated.has(object);
595
+ if (!animated && !animationRateSources.has(object)) return;
596
+ if (!isRenderable(object)) return;
597
+ this.#observeAnimationSources(object);
598
+ if (!animated) return;
599
+ if (this.#isCameraAttached(object)) {
600
+ this.#observeAnimation(object, undefined);
601
+ return;
316
602
  }
317
- this.#hiddenCount = 0;
318
- }
319
-
320
- dispose(): void {
321
- this.restore();
322
- this.#camera = undefined;
603
+ if (object.userData[ALWAYS_RENDER_KEY] === true) {
604
+ this.#observeAnimation(object, undefined);
605
+ return;
606
+ }
607
+ if (object.frustumCulled === false) {
608
+ this.#observeAnimation(object, undefined);
609
+ return;
610
+ }
611
+ this.#observeAnimation(object, boundsOf(object, this.#positionVersions, this.#animationFrame));
323
612
  }
324
613
 
325
614
  #visit(object: Object3D): void {
326
615
  if (!isRenderable(object)) return;
327
616
  this.#considered += 1;
617
+ this.#observeAnimationSources(object);
328
618
  if (this.#isCameraAttached(object)) {
619
+ this.#observeAnimation(object, undefined);
329
620
  this.#exemptCameraAttached += 1;
330
621
  return;
331
622
  }
332
623
  if (object.userData[ALWAYS_RENDER_KEY] === true) {
624
+ this.#observeAnimation(object, undefined);
333
625
  this.#exemptMarked += 1;
334
626
  return;
335
627
  }
@@ -337,6 +629,7 @@ export class RenderCameraCull {
337
629
  // trusted — the pooled tracer, particle and whitewater batches set it for exactly that
338
630
  // reason. A second, stricter cull does not get to override the opt-out.
339
631
  if (object.frustumCulled === false) {
632
+ this.#observeAnimation(object, undefined);
340
633
  this.#exemptFrustumCulled += 1;
341
634
  return;
342
635
  }
@@ -346,7 +639,8 @@ export class RenderCameraCull {
346
639
  // cheaply enumerable here, so where the gate cannot know, it keeps the caster. A caster the
347
640
  // main camera *can* see is ordinary geometry — its shadow is in view with it, and a
348
641
  // sub-resolution object casts a sub-resolution shadow.
349
- const sphere = boundsOf(object, this.#positionVersions);
642
+ const sphere = boundsOf(object, this.#positionVersions, this.#animationFrame);
643
+ this.#observeAnimation(object, sphere);
350
644
  // A buffer rewritten every frame has extents the gate cannot know without a full scan each
351
645
  // frame, which costs more than the draw it might remove. Keep it drawn, like an opt-out.
352
646
  if (sphere === DYNAMIC_BOUNDS) {
@@ -363,7 +657,8 @@ export class RenderCameraCull {
363
657
  this.#center.copy(sphere.center).applyMatrix4(object.matrixWorld);
364
658
  if (
365
659
  object.castShadow === true &&
366
- (!this.#cameraResolved || !this.#frustum.containsPoint(this.#center))
660
+ (!this.#cameraResolved ||
661
+ !inFrustum(this.#planes, this.#center.x, this.#center.y, this.#center.z, 0))
367
662
  ) {
368
663
  this.#exemptShadowCasters += 1;
369
664
  return;
@@ -374,8 +669,7 @@ export class RenderCameraCull {
374
669
  const dz = this.#center.z - this.#cameraZ;
375
670
  const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
376
671
  const worldRadius = sphere.radius * object.matrixWorld.getMaxScaleOnAxis();
377
- const projectedDiameter =
378
- (2 * worldRadius * this.#scale) / Math.max(distance - worldRadius, MIN_DISTANCE);
672
+ const projectedDiameter = projectedDiameterPixels(worldRadius, distance, this.#scale);
379
673
  if (projectedDiameter >= this.#minimumPixels) return;
380
674
  object.visible = false;
381
675
  this.#hidden[this.#hiddenCount] = object;
@@ -383,38 +677,249 @@ export class RenderCameraCull {
383
677
  this.#culled += 1;
384
678
  }
385
679
 
386
- #isCameraAttached(object: Object3D): boolean {
387
- const camera = this.#camera;
388
- if (camera === undefined) return false;
389
- for (let node = object.parent; node !== null; node = node.parent) {
390
- if (node === camera) return true;
680
+ #observeAnimation(
681
+ object: Object3D,
682
+ sphere: IBoundingSphereLike | typeof DYNAMIC_BOUNDS | undefined,
683
+ notRendered = false,
684
+ ): void {
685
+ // An object under no live rate root has no state above it.
686
+ const states = this.#animated.get(object);
687
+ if (states === undefined) return;
688
+ let rate = notRendered ? 8 : 1;
689
+ let radius = 0;
690
+ let banded = false;
691
+ if (
692
+ !notRendered &&
693
+ this.#cameraResolved &&
694
+ sphere !== undefined &&
695
+ sphere !== DYNAMIC_BOUNDS &&
696
+ Number.isFinite(sphere.radius) &&
697
+ sphere.radius > 0
698
+ ) {
699
+ this.#center.copy(sphere.center).applyMatrix4(object.matrixWorld);
700
+ radius = sphere.radius * object.matrixWorld.getMaxScaleOnAxis();
701
+ // A known bound on the camera's forward centre ray is the conservative observable target
702
+ // signal. Test each source independently so a nearer bound cannot hide a farther target.
703
+ banded = !rayMeetsSphere(this.#ray, this.#center.x, this.#center.y, this.#center.z, radius);
391
704
  }
392
- return false;
705
+ const { x, y, z } = this.#center;
706
+ for (const state of states) {
707
+ // The pixel band reads the whole rig this frame, not this part: Lantern Vale's hero is 51 rigid
708
+ // parts, the largest 80 px at 720p while the hero stands 170 px, and per part it held every
709
+ // other pose. A one-mesh rig's union is its own sphere.
710
+ // A part scaled to nothing projects 0 px: it leaves the rig to its other parts.
711
+ if (banded) rate = radius > 0 ? this.#bandRate(this.#rigSphere(state, x, y, z, radius)) : 8;
712
+ if (state.source === this && state.frame === this.#animationFrame)
713
+ state.rate = Math.min(state.rate, rate);
714
+ else state.rate = rate;
715
+ state.source = this;
716
+ state.frame = this.#animationFrame;
717
+ }
718
+ }
719
+
720
+ /** Grows `state`'s sphere for this frame to hold the part at `x, y, z` and `radius`: [frame, x, y, z, radius]. */
721
+ #rigSphere(
722
+ state: IAnimationRateState,
723
+ x: number,
724
+ y: number,
725
+ z: number,
726
+ radius: number,
727
+ ): Float64Array {
728
+ let union = this.#rigSpheres.get(state);
729
+ if (union === undefined) {
730
+ union = new Float64Array(5);
731
+ this.#rigSpheres.set(state, union);
732
+ }
733
+ // In place, a part at a time each frame: no array literal and no typed-array destructuring.
734
+ if (union[0] !== this.#animationFrame) {
735
+ union[0] = this.#animationFrame;
736
+ union[1] = x;
737
+ union[2] = y;
738
+ union[3] = z;
739
+ union[4] = radius;
740
+ } else {
741
+ const ux = union[1] as number;
742
+ const uy = union[2] as number;
743
+ const uz = union[3] as number;
744
+ const ur = union[4] as number;
745
+ const distance = Math.hypot(x - ux, y - uy, z - uz);
746
+ if (distance + radius > ur) {
747
+ if (distance + ur <= radius) {
748
+ union[1] = x;
749
+ union[2] = y;
750
+ union[3] = z;
751
+ union[4] = radius;
752
+ } else {
753
+ const grown = (distance + ur + radius) / 2;
754
+ const shift = (grown - ur) / distance;
755
+ union[1] = ux + (x - ux) * shift;
756
+ union[2] = uy + (y - uy) * shift;
757
+ union[3] = uz + (z - uz) * shift;
758
+ union[4] = grown;
759
+ }
760
+ }
761
+ }
762
+ return union;
763
+ }
764
+
765
+ #bandRate(sphere: Float64Array): number {
766
+ const x = sphere[1] as number;
767
+ const y = sphere[2] as number;
768
+ const z = sphere[3] as number;
769
+ const radius = sphere[4] as number;
770
+ if (!inFrustum(this.#planes, x, y, z, radius)) return 8;
771
+ const distance = Math.hypot(x - this.#cameraX, y - this.#cameraY, z - this.#cameraZ);
772
+ const pixels = projectedDiameterPixels(radius, distance, this.#scale);
773
+ // PRD-570's provisional pixel bands; the visual gate still has to earn these thresholds.
774
+ return pixels >= 128 ? 1 : pixels >= 32 ? 2 : pixels >= 8 ? 4 : 8;
775
+ }
776
+
777
+ #observeAnimationSources(object: Object3D): void {
778
+ const sources = animationRateSources.get(object);
779
+ if (sources === undefined) return;
780
+ for (const source of sources.keys()) {
781
+ if (!this.#animated.has(source)) continue;
782
+ const visible = this.#isVisibleInWorld(source);
783
+ if (this.#isCameraAttached(source)) {
784
+ this.#observeAnimation(source, undefined);
785
+ continue;
786
+ }
787
+ this.#observeAnimation(
788
+ source,
789
+ visible ? boundsOf(source, this.#positionVersions, this.#animationFrame) : undefined,
790
+ !visible,
791
+ );
792
+ }
793
+ }
794
+
795
+ /** Rebuilds {@link #cameraParts}, unless the engine's hierarchy has held still since. */
796
+ #findCameraParts(camera: Camera): void {
797
+ const revision = hierarchyRevision(camera);
798
+ if (
799
+ revision !== undefined &&
800
+ revision === this.#cameraPartsRevision &&
801
+ camera === this.#cameraPartsOf
802
+ )
803
+ return;
804
+ this.#cameraParts.clear();
805
+ camera.traverse(this.#collectCameraPart);
806
+ this.#cameraParts.delete(camera);
807
+ this.#cameraPartsOf = camera;
808
+ this.#cameraPartsRevision = revision;
809
+ }
810
+
811
+ #isVisibleInWorld(object: Object3D): boolean {
812
+ for (let node: Object3D | null = object; node !== null; node = node.parent) {
813
+ if (!node.visible) return false;
814
+ }
815
+ return true;
816
+ }
817
+
818
+ #isCameraAttached(object: Object3D): boolean {
819
+ return this.#camera !== undefined && this.#cameraParts.has(object);
820
+ }
821
+ }
822
+
823
+ /**
824
+ * three's `Ray.intersectsSphere`: the ray `[ox, oy, oz, dx, dy, dz]` (unit direction) passes within
825
+ * `radius` of the centre.
826
+ */
827
+ export function rayMeetsSphere(
828
+ ray: ArrayLike<number>,
829
+ x: number,
830
+ y: number,
831
+ z: number,
832
+ radius: number,
833
+ ): boolean {
834
+ if (radius < 0) return false;
835
+ const dx = x - (ray[0] as number);
836
+ const dy = y - (ray[1] as number);
837
+ const dz = z - (ray[2] as number);
838
+ const rx = ray[3] as number;
839
+ const ry = ray[4] as number;
840
+ const rz = ray[5] as number;
841
+ const along = dx * rx + dy * ry + dz * rz;
842
+ if (along < 0) return dx * dx + dy * dy + dz * dz <= radius * radius;
843
+ const ox = dx - rx * along;
844
+ const oy = dy - ry * along;
845
+ const oz = dz - rz * along;
846
+ return ox * ox + oy * oy + oz * oz <= radius * radius;
847
+ }
848
+
849
+ /** three's `Frustum.setFromProjectionMatrix(m)` (WebGL clip space, forward depth) into six [nx, ny, nz, d]. */
850
+ export function setFrustumPlanes(planes: Float64Array, me: ArrayLike<number>): void {
851
+ const row = (i: number, a: number, b: number, c: number, d: number) => {
852
+ const length = Math.hypot(a, b, c);
853
+ planes[i] = a / length;
854
+ planes[i + 1] = b / length;
855
+ planes[i + 2] = c / length;
856
+ planes[i + 3] = d / length;
857
+ };
858
+ const m = (index: number) => me[index] as number;
859
+ row(0, m(3) - m(0), m(7) - m(4), m(11) - m(8), m(15) - m(12));
860
+ row(4, m(3) + m(0), m(7) + m(4), m(11) + m(8), m(15) + m(12));
861
+ row(8, m(3) + m(1), m(7) + m(5), m(11) + m(9), m(15) + m(13));
862
+ row(12, m(3) - m(1), m(7) - m(5), m(11) - m(9), m(15) - m(13));
863
+ row(16, m(3) - m(2), m(7) - m(6), m(11) - m(10), m(15) - m(14));
864
+ row(20, m(3) + m(2), m(7) + m(6), m(11) + m(10), m(15) + m(14));
865
+ }
866
+
867
+ /** three's `Frustum.intersectsSphere` (`radius` 0: `containsPoint`) over {@link setFrustumPlanes}' planes. */
868
+ export function inFrustum(
869
+ planes: Float64Array,
870
+ x: number,
871
+ y: number,
872
+ z: number,
873
+ radius: number,
874
+ ): boolean {
875
+ for (let i = 0; i < 24; i += 4) {
876
+ const distance =
877
+ (planes[i] as number) * x +
878
+ (planes[i + 1] as number) * y +
879
+ (planes[i + 2] as number) * z +
880
+ (planes[i + 3] as number);
881
+ if (distance < -radius) return false;
393
882
  }
883
+ return true;
884
+ }
885
+
886
+ /** Pure projected-diameter formula shared by the draw gate and per-rig animation policy. */
887
+ export function projectedDiameterPixels(
888
+ radius: number,
889
+ distance: number,
890
+ pixelsPerWorldUnit: number,
891
+ ): number {
892
+ return (2 * radius * pixelsPerWorldUnit) / Math.max(distance - radius, MIN_DISTANCE);
394
893
  }
395
894
 
396
895
  function boundsOf(
397
896
  object: Object3D,
398
897
  versions: WeakMap<object, IPositionVersion>,
898
+ frame: number,
399
899
  ): IBoundingSphereLike | typeof DYNAMIC_BOUNDS | undefined {
400
900
  const cullable = object as ICullable;
401
901
  // An `InstancedMesh` carries its own instance-aware bound; the geometry one is not it.
402
902
  if (cullable.boundingSphere != null) return cullable.boundingSphere;
403
903
  const geometry = cullable.geometry;
404
904
  if (geometry === undefined) return undefined;
905
+ const known = versions.get(geometry);
906
+ // Animation preparation, draw culling and every part sharing this geometry read one frame's
907
+ // observation: on the Wasm engine each version read crosses the bridge.
908
+ if (known?.frame === frame && geometry.boundingSphere != null)
909
+ return known.stale ? DYNAMIC_BOUNDS : geometry.boundingSphere;
405
910
  const version = geometry.attributes?.position?.version;
406
911
  if (geometry.boundingSphere == null) {
407
912
  geometry.computeBoundingSphere?.();
408
913
  if (version !== undefined)
409
- versions.set(geometry, { version, changedLastConsult: false, stale: false });
914
+ versions.set(geometry, { version, frame, changedLastConsult: false, stale: false });
410
915
  return geometry.boundingSphere ?? undefined;
411
916
  }
412
917
  if (version === undefined) return geometry.boundingSphere ?? undefined;
413
- const known = versions.get(geometry);
414
918
  if (known === undefined) {
415
- versions.set(geometry, { version, changedLastConsult: false, stale: false });
919
+ versions.set(geometry, { version, frame, changedLastConsult: false, stale: false });
416
920
  return geometry.boundingSphere ?? undefined;
417
921
  }
922
+ known.frame = frame;
418
923
  if (known.version === version) {
419
924
  // A buffer that settled after a per-frame rewrite has knowable extents again: scan it once and
420
925
  // cull it like any other, rather than exempting it for the rest of the run. Settling also lets