@threenative/core 0.3.6 → 0.3.9

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,19 +1,25 @@
1
1
  import {
2
2
  InstancedBufferGeometry,
3
3
  type Material,
4
+ Matrix4,
4
5
  Mesh,
5
6
  type Object3D,
6
- type Skeleton,
7
+ Skeleton,
7
8
  type SkinnedMesh,
8
9
  } from "three";
9
10
  import {
10
11
  Fn,
12
+ If,
11
13
  attribute,
14
+ cos,
15
+ float,
12
16
  instanceIndex,
17
+ mat4,
13
18
  normalGeometry,
14
19
  normalLocal,
15
20
  positionGeometry,
16
21
  positionPrevious,
22
+ sin,
17
23
  storage,
18
24
  tangentGeometry,
19
25
  tangentLocal,
@@ -33,6 +39,55 @@ import {
33
39
  StorageBufferAttribute,
34
40
  } from "three/webgpu";
35
41
 
42
+ import { animationPacketTimeReaders } from "./animation-packet-state.js";
43
+ import {
44
+ type IAnimationPosePacket,
45
+ type IAnimationPoseVersion,
46
+ evaluateAnimationPoseFallback,
47
+ evaluateAnimationPosePacket,
48
+ readAnimationPosePacket,
49
+ readAnimationPosePacketTime,
50
+ refreshAnimationPosePacket,
51
+ skeletonUpdateIntact,
52
+ } from "./animation-pose-packet.js";
53
+ import { SPANS, beginSpan, endSpan } from "./profiling/Spans.js";
54
+ import { observeAnimationRates } from "./render-camera-cull.js";
55
+
56
+ const skeletonUpdate = Skeleton.prototype.update;
57
+ interface IRawDisplaySlot {
58
+ current?: IAnimationPosePacket;
59
+ previous?: IAnimationPosePacket;
60
+ retired: boolean;
61
+ writeFrame?: number;
62
+ /** Evaluations that may reuse the captured packet before the next full source re-read. */
63
+ trusted?: number;
64
+ /** What the last full write saw, so a held tick can prove nothing moved with three comparisons. */
65
+ hot?: { skeleton: Skeleton; world: Matrix4; evaluation: number };
66
+ expectedCurrent?: Float32Array;
67
+ expectedPrevious?: Float32Array;
68
+ }
69
+
70
+ /** Evaluations a captured RAW packet is reused before every source field is read again. */
71
+ const RAW_REVALIDATE_EVALUATIONS = 256;
72
+
73
+ const ANIMATION_RATE_STATE_KEY = "threenative.animationRateState";
74
+
75
+ interface IAnimationRateStateLike {
76
+ readonly evaluated: boolean;
77
+ readonly effectiveRate?: number;
78
+ readonly evaluation: number;
79
+ readonly gpuPoseEnabled?: boolean;
80
+ gpuPose?: boolean;
81
+ syncBones?: () => void;
82
+ }
83
+
84
+ /** Hands the pose back to the CPU: the player refreshes the bones to the current playhead first. */
85
+ function releaseGpuPose(state: IAnimationRateStateLike | undefined): void {
86
+ if (state?.gpuPose !== true) return;
87
+ state.gpuPose = false;
88
+ state.syncBones?.();
89
+ }
90
+
36
91
  /**
37
92
  * The skinned lane of the render projection: every rig that shares a geometry and material is one
38
93
  * instanced draw per pass instead of one draw per rig per pass.
@@ -196,6 +251,7 @@ export class SkinnedBatch {
196
251
  readonly bones: number;
197
252
  readonly capacity: number;
198
253
  readonly instances = new Map<Object3D, number>();
254
+ readonly #slotRigs = new Map<number, Object3D>();
199
255
  readonly free: number[] = [];
200
256
  used = 0;
201
257
  readonly #current: Float32Array;
@@ -206,9 +262,27 @@ export class SkinnedBatch {
206
262
  readonly #fresh: number[] = [];
207
263
  readonly #bindScratch = new Float64Array(16);
208
264
  readonly #updated = new WeakMap<Skeleton, number>();
265
+ // A RAW refresh substitutes for stock's first update. Materialize its CPU basis only
266
+ // if a later same-frame stock write actually needs the shared skeleton cache.
267
+ readonly #rawUpdates = new WeakMap<Skeleton, { frame: number; version: IAnimationPoseVersion }>();
268
+ readonly #writtenEvaluations = new WeakMap<Object3D, number>();
269
+ readonly #writtenWorldMatrices = new WeakMap<Object3D, Matrix4>();
209
270
  #frame = 0;
210
271
  #dirty = false;
211
272
  #sourceVersion: number;
273
+ readonly #rawSlots = new Map<number, IRawDisplaySlot>();
274
+ readonly #ownedSkeletons = new Map<number, Skeleton>();
275
+ readonly #skeletonOwners = new Map<Skeleton, Set<number>>();
276
+ #observed = false;
277
+ #reconciling = false;
278
+ #rawFrame = -1;
279
+ #rawDirtyFrame = -1;
280
+ #rawMeta = new Float32Array(0);
281
+ #rawData = new Float32Array(0);
282
+ #rawPrevious = new Float32Array(0);
283
+ #rawRoots = new Float32Array(0);
284
+ #rawPreviousRoots = new Float32Array(0);
285
+ readonly #rawAttributes: StorageBufferAttribute[] = [];
212
286
 
213
287
  constructor(options: ISkinnedBatchOptions) {
214
288
  const { first, capacity, velocity } = options;
@@ -255,21 +329,148 @@ export class SkinnedBatch {
255
329
  .add(palette.element(base.add(boneIndex.y)).mul(weight.y))
256
330
  .add(palette.element(base.add(boneIndex.z)).mul(weight.z))
257
331
  .add(palette.element(base.add(boneIndex.w)).mul(weight.w));
332
+ // The admitted packet layout is fixed; every other rig retains the stock node.
333
+ let rawMatrix: ((previousFrame: boolean) => ReturnType<typeof blend>) | undefined;
334
+ let rawMeta: ReturnType<typeof storage<"vec4">> | undefined;
335
+ if (this.bones === 12) {
336
+ this.#rawMeta = new Float32Array(capacity * 4);
337
+ this.#rawData = new Float32Array(capacity * 12 * 48);
338
+ this.#rawPrevious = new Float32Array(this.#rawData.length);
339
+ this.#rawRoots = new Float32Array(capacity * 32);
340
+ this.#rawPreviousRoots = new Float32Array(this.#rawRoots.length);
341
+ const input = (array: Float32Array, size: number) => {
342
+ const a = new StorageBufferAttribute(array, size);
343
+ this.#rawAttributes.push(a);
344
+ return a;
345
+ };
346
+ const metadata = storage(input(this.#rawMeta, 4), "vec4", capacity).toReadOnly();
347
+ rawMeta = metadata;
348
+ const raw = storage(input(this.#rawData, 4), "vec4", capacity * 144).toReadOnly();
349
+ const oldRaw = storage(input(this.#rawPrevious, 4), "vec4", capacity * 144).toReadOnly();
350
+ const roots = storage(input(this.#rawRoots, 16), "mat4", capacity * 2).toReadOnly();
351
+ const oldRoots = storage(
352
+ input(this.#rawPreviousRoots, 16),
353
+ "mat4",
354
+ capacity * 2,
355
+ ).toReadOnly();
356
+ rawMatrix = (old) => {
357
+ const data = old ? oldRaw : raw;
358
+ const root = old ? oldRoots : roots;
359
+ const time = old ? metadata.element(instanceIndex).w : metadata.element(instanceIndex).y;
360
+ const start = instanceIndex.mul(uint(144));
361
+ let world: ReturnType<typeof blend> = mat4();
362
+ let blended: ReturnType<typeof blend> = mat4();
363
+ for (let b = 0; b < 12; b++) {
364
+ const offset = start.add(uint(b * 12));
365
+ const at = (n: number) => data.element(offset.add(uint(n)));
366
+ const position = at(8);
367
+ const scale = at(9);
368
+ const times = at(10);
369
+ const values = at(11);
370
+ const second = time.greaterThan(times.y);
371
+ const t0 = second.select(times.y, times.x);
372
+ const t1 = second.select(times.z, times.y);
373
+ const v0 = second.select(values.y, values.x);
374
+ const v1 = second.select(values.z, values.y);
375
+ const z = v0.add(v1.sub(v0).mul(time.sub(t0).div(t1.sub(t0))));
376
+ const c = cos(z);
377
+ const sn = sin(z);
378
+ const local =
379
+ b === 0
380
+ ? mat4(at(0), at(1), at(2), at(3))
381
+ : mat4(
382
+ c.mul(scale.x),
383
+ sn.mul(scale.x),
384
+ 0,
385
+ 0,
386
+ sn.negate().mul(scale.y),
387
+ c.mul(scale.y),
388
+ 0,
389
+ 0,
390
+ 0,
391
+ 0,
392
+ scale.z,
393
+ 0,
394
+ position.x,
395
+ position.y,
396
+ position.z,
397
+ 1,
398
+ );
399
+ world = (
400
+ b === 0 ? root.element(instanceIndex.mul(uint(2))).mul(local) : world.mul(local)
401
+ ).toVar();
402
+ const palette = world.mul(mat4(at(4), at(5), at(6), at(7)));
403
+ const w = boneIndex.x
404
+ .equal(uint(b))
405
+ .select(weight.x, float(0))
406
+ .add(boneIndex.y.equal(uint(b)).select(weight.y, float(0)))
407
+ .add(boneIndex.z.equal(uint(b)).select(weight.z, float(0)))
408
+ .add(boneIndex.w.equal(uint(b)).select(weight.w, float(0)));
409
+ blended = b === 0 ? palette.mul(w) : blended.add(palette.mul(w));
410
+ }
411
+ return root
412
+ .element(instanceIndex.mul(uint(2)))
413
+ .mul(root.element(instanceIndex.mul(uint(2)).add(uint(1))))
414
+ .mul(blended);
415
+ };
416
+ }
258
417
  const hasTangent = source.getAttribute("tangent") !== undefined;
259
418
  const material = new NodeClass();
260
419
  this.#syncMaterial(material);
261
420
  material.positionNode = Fn(() => {
262
- const matrix = blend(current);
421
+ const matrix = mat4().toVar();
422
+ if (rawMatrix && rawMeta) {
423
+ const sample = rawMatrix;
424
+ If(rawMeta.element(instanceIndex).x.greaterThan(0), () => {
425
+ matrix.assign(sample(false));
426
+ }).Else(() => {
427
+ matrix.assign(blend(current));
428
+ });
429
+ } else matrix.assign(blend(current));
263
430
  normalLocal.assign(matrix.mul(vec4(normalGeometry, 0)).xyz);
264
431
  if (hasTangent) tangentLocal.assign(matrix.mul(vec4(tangentGeometry.xyz, 0)).xyz);
265
- if (previous !== undefined)
266
- positionPrevious.assign(blend(previous).mul(vec4(positionGeometry, 1)).xyz);
432
+ if (previous !== undefined) {
433
+ const oldMatrix = mat4().toVar();
434
+ if (rawMatrix && rawMeta) {
435
+ const sample = rawMatrix;
436
+ If(rawMeta.element(instanceIndex).z.greaterThan(0), () => {
437
+ oldMatrix.assign(sample(true));
438
+ }).Else(() => {
439
+ oldMatrix.assign(blend(previous));
440
+ });
441
+ } else oldMatrix.assign(blend(previous));
442
+ positionPrevious.assign(oldMatrix.mul(vec4(positionGeometry, 1)).xyz);
443
+ }
267
444
  return matrix.mul(vec4(positionGeometry, 1)).xyz;
268
445
  })();
269
446
  material.needsUpdate = true;
270
447
 
271
448
  this.mesh = new Mesh(geometry, material);
272
449
  this.mesh.matrixAutoUpdate = false;
450
+ observeAnimationRates(this.mesh, this.instances);
451
+ this.mesh.userData["threenative.animationPosePackets"] = () => ({
452
+ capacity: this.capacity,
453
+ bones: this.bones,
454
+ instanceCount: this.mesh.geometry.instanceCount,
455
+ previousEnabled: this.#previous !== undefined,
456
+ slots: [...this.instances].map(([rig, slot]) => {
457
+ const r = this.#rawSlots.get(slot);
458
+ const m = slot * 4;
459
+ return {
460
+ slot,
461
+ currentRaw: this.#rawMeta[m] === 1,
462
+ previousRaw: this.#rawMeta[m + 2] === 1,
463
+ currentTime: this.#rawMeta[m + 1] ?? 0,
464
+ previousTime: this.#rawMeta[m + 3] ?? 0,
465
+ retired: r?.retired === true,
466
+ ...(this.#writtenEvaluations.has(rig)
467
+ ? { currentEvaluation: this.#writtenEvaluations.get(rig) }
468
+ : {}),
469
+ ...(r?.previous ? { previousEvaluation: r.previous.version.evaluation } : {}),
470
+ };
471
+ }),
472
+ storage: { meta: Array.from(this.#rawMeta) },
473
+ });
273
474
  // The palette spans every rig; only the per-rig sources have meaningful bounds.
274
475
  this.mesh.frustumCulled = false;
275
476
  this.mesh.castShadow = first.castShadow;
@@ -282,16 +483,25 @@ export class SkinnedBatch {
282
483
  * before any rig writes, so every pass of the frame reads the same pair.
283
484
  */
284
485
  begin(): void {
486
+ this.#reconciling = false;
285
487
  this.#frame += 1;
286
488
  this.#syncMaterial(this.mesh.material);
287
489
  if (this.sourceMaterial.version !== this.#sourceVersion) {
288
490
  this.#sourceVersion = this.sourceMaterial.version;
289
491
  this.mesh.material.needsUpdate = true;
290
492
  }
493
+ this.#checkObservedEdits();
291
494
  if (this.#previous !== undefined) {
292
495
  this.#previous.set(this.#current);
293
496
  this.#dirty = true;
497
+ if (this.#observed)
498
+ for (const [slot, display] of this.#rawSlots)
499
+ display.expectedPrevious = this.#previous.slice(
500
+ slot * this.bones * 16,
501
+ (slot + 1) * this.bones * 16,
502
+ );
294
503
  }
504
+ this.#reconciling = true;
295
505
  }
296
506
 
297
507
  /** Copies the game's current material values onto the draw's twin, as three's own conversion does. */
@@ -313,7 +523,9 @@ export class SkinnedBatch {
313
523
  this.used += 1;
314
524
  }
315
525
  this.instances.set(rig, slot);
526
+ this.#slotRigs.set(slot, rig);
316
527
  this.#fresh.push(slot);
528
+ this.#trackSkeleton(slot, rig);
317
529
  return slot;
318
530
  }
319
531
 
@@ -321,43 +533,411 @@ export class SkinnedBatch {
321
533
  release(rig: Object3D): void {
322
534
  const slot = this.instances.get(rig);
323
535
  if (slot === undefined) return;
536
+ this.#untrackSkeleton(slot);
537
+ releaseGpuPose(animationRateStateOf(rig));
324
538
  this.instances.delete(rig);
539
+ this.#slotRigs.delete(slot);
540
+ this.#writtenEvaluations.delete(rig);
541
+ this.#writtenWorldMatrices.delete(rig);
325
542
  this.hide(slot);
543
+ this.#rawSlots.delete(slot);
326
544
  this.free.push(slot);
327
545
  }
328
546
 
329
547
  /** This frame's world-space bone matrices, `capacity × bones` of them in slot order. */
330
548
  get palette(): Float32Array {
549
+ this.#observe();
331
550
  return this.#current;
332
551
  }
333
552
 
334
553
  /** Last frame's palette, present only while a temporal stage asks for per-object history. */
335
554
  get history(): Float32Array | undefined {
555
+ if (this.#previous !== undefined) this.#observe();
336
556
  return this.#previous;
337
557
  }
338
558
 
339
559
  /** Marks a slot whose history must restart from its next pose. */
340
560
  restart(slot: number): void {
561
+ this.#invalidate(slot);
341
562
  this.#fresh.push(slot);
342
563
  }
343
564
 
344
565
  /** Collapses one slot for this frame; a hidden rig keeps its slot. */
345
566
  hide(slot: number): void {
567
+ this.#invalidate(slot);
346
568
  const stride = this.bones * 16;
347
569
  this.#current.fill(0, slot * stride, (slot + 1) * stride);
348
570
  this.#previous?.fill(0, slot * stride, (slot + 1) * stride);
571
+ const display = this.#rawSlots.get(slot);
572
+ if (display) {
573
+ display.current = undefined;
574
+ display.previous = undefined;
575
+ }
576
+ if (this.#rawMeta.length) {
577
+ this.#rawMeta.fill(0, slot * 4, slot * 4 + 4);
578
+ this.#markRawDirty();
579
+ }
349
580
  this.#dirty = true;
350
581
  }
351
582
 
583
+ #invalidate(slot: number): void {
584
+ const rig = this.#slotRigs.get(slot);
585
+ if (rig === undefined) return;
586
+ this.#writtenEvaluations.delete(rig);
587
+ this.#writtenWorldMatrices.delete(rig);
588
+ const display = this.#rawSlots.get(slot);
589
+ if (display) display.hot = undefined;
590
+ }
591
+
592
+ /**
593
+ * A held tick of a trusted RAW rig: the pose, the skeleton and the world matrix are the ones the
594
+ * last full write saw, so the only thing that moved is the playhead. Anything else, an observed
595
+ * batch included, takes the full path.
596
+ */
597
+ #writeHeld(slot: number, rig: SkinnedMesh, state: IAnimationRateStateLike | undefined): boolean {
598
+ const display = this.#rawSlots.get(slot);
599
+ const hot = display?.hot;
600
+ if (
601
+ display === undefined ||
602
+ hot === undefined ||
603
+ display.current === undefined ||
604
+ display.retired ||
605
+ this.#observed ||
606
+ (display.trusted ?? 0) <= 0
607
+ )
608
+ return false;
609
+ if (
610
+ state === undefined ||
611
+ state.evaluated ||
612
+ state.evaluation !== hot.evaluation ||
613
+ (state.effectiveRate ?? 1) <= 1 ||
614
+ rig.skeleton !== hot.skeleton ||
615
+ !hot.world.equals(rig.matrixWorld) ||
616
+ !skeletonUpdateIntact(hot.skeleton) ||
617
+ (this.#skeletonOwners.get(hot.skeleton)?.size ?? 0) > 1 ||
618
+ this.#fresh.includes(slot)
619
+ )
620
+ return false;
621
+ const time = animationPacketTimeReaders.get(rig)?.();
622
+ if (time === undefined) return false;
623
+ this.#prepareRawFrame();
624
+ display.writeFrame = this.#frame;
625
+ this.#rawMeta[slot * 4] = 1;
626
+ this.#rawMeta[slot * 4 + 1] = time;
627
+ this.#markRawDirty();
628
+ return true;
629
+ }
630
+
631
+ /** A packet at the playhead the meta row holds: held ticks move the meta, not the packet. */
632
+ #timed(packet: IAnimationPosePacket, slot: number, previous: boolean): IAnimationPosePacket {
633
+ const time = this.#rawMeta[slot * 4 + (previous ? 3 : 1)] as number;
634
+ return time === packet.time ? packet : { ...packet, time };
635
+ }
636
+
352
637
  /**
353
638
  * Writes one rig's world-space bone palette. Equals stock skinning's
354
639
  * `matrixWorld · bindMatrixInverse · boneMatrix · bindMatrix` per bone; in the default attached
355
640
  * bind mode `matrixWorld · bindMatrixInverse` is the identity and is skipped.
356
641
  */
357
642
  write(slot: number, rig: SkinnedMesh): void {
643
+ beginSpan(SPANS.skinnedWrite);
644
+ try {
645
+ const state = animationRateStateOf(rig);
646
+ // Attachments follow CPU bones, so their character must keep the same stock pose.
647
+ const attached =
648
+ (state?.effectiveRate ?? 1) > 1 &&
649
+ this.bones === 12 &&
650
+ rig.skeleton.bones.some((bone, index, bones) =>
651
+ bone.children.some((child) => child !== bones[index + 1]),
652
+ );
653
+ if (!attached && this.#writeHeld(slot, rig, state)) return;
654
+ this.#checkObservedEdits(slot);
655
+ // Named rate1 and ordinary stock owners never pay the capture/query path.
656
+ if (this.#rawMeta.length && ((state?.effectiveRate ?? 1) > 1 || this.#rawSlots.has(slot))) {
657
+ this.#prepareRawFrame();
658
+ this.#trackSkeleton(slot, rig, true);
659
+ let display = this.#rawSlots.get(slot);
660
+ if (!display) {
661
+ display = { retired: false };
662
+ this.#rawSlots.set(slot, display);
663
+ }
664
+ const held =
665
+ state !== undefined &&
666
+ !state.evaluated &&
667
+ this.#writtenEvaluations.get(rig) === state.evaluation &&
668
+ this.#writtenWorldMatrices.get(rig)?.equals(rig.matrixWorld);
669
+ const skeleton: unknown = rig.skeleton;
670
+ const update =
671
+ skeleton instanceof Skeleton
672
+ ? skeletonUpdateIntact(skeleton)
673
+ ? skeletonUpdate
674
+ : this.#method(skeleton, "update")
675
+ : undefined;
676
+ const shared =
677
+ skeleton instanceof Skeleton && (this.#skeletonOwners.get(skeleton)?.size ?? 0) > 1;
678
+ // First eligibility on a held tick must wait for a genuine stock refresh.
679
+ if (held && !display.current && !display.retired && update === skeletonUpdate && !shared) {
680
+ this.#writeStock(slot, rig, state);
681
+ return;
682
+ }
683
+ const repeatedRefresh = !held && display.writeFrame === this.#frame;
684
+ const packet =
685
+ state?.gpuPoseEnabled === true &&
686
+ !attached &&
687
+ !repeatedRefresh &&
688
+ !display.retired &&
689
+ (state?.effectiveRate ?? 1) > 1 &&
690
+ update === skeletonUpdate &&
691
+ !shared
692
+ ? display.current && held
693
+ ? readAnimationPosePacketTime(rig, display.current.version)
694
+ : display.current &&
695
+ (display.trusted ?? 0) > 0 &&
696
+ this.#writtenWorldMatrices.get(rig)?.equals(rig.matrixWorld) === true
697
+ ? refreshAnimationPosePacket(rig, display.current.version)
698
+ : readAnimationPosePacket(rig)
699
+ : undefined;
700
+ if (packet && state && !held) {
701
+ const reused = display.current?.version.keys === packet.version.keys;
702
+ display.trusted = reused ? (display.trusted ?? 0) - 1 : RAW_REVALIDATE_EVALUATIONS;
703
+ }
704
+ if (packet && state) {
705
+ state.gpuPose = true;
706
+ display.writeFrame = this.#frame;
707
+ if (!held && skeleton instanceof Skeleton)
708
+ this.#rawUpdates.set(skeleton, { frame: this.#frame, version: packet.version });
709
+ const changed = display.current?.version.keys !== packet.version.keys;
710
+ display.current = packet;
711
+ this.#packRaw(slot, packet, false, changed);
712
+ if (this.#fresh.includes(slot)) this.#packRaw(slot, packet, true);
713
+ this.#writtenEvaluations.set(rig, state.evaluation);
714
+ const world = this.#writtenWorldMatrices.get(rig) ?? new Matrix4();
715
+ world.copy(rig.matrixWorld);
716
+ this.#writtenWorldMatrices.set(rig, world);
717
+ if (skeleton instanceof Skeleton) {
718
+ const hot = display.hot;
719
+ if (hot) {
720
+ hot.skeleton = skeleton;
721
+ hot.world = world;
722
+ hot.evaluation = state.evaluation;
723
+ } else display.hot = { skeleton, world, evaluation: state.evaluation };
724
+ }
725
+ this.#syncObserved(slot, display);
726
+ return;
727
+ }
728
+ // The next player update sees the flag drop and refreshes the bones; this tick keeps stock's
729
+ // held semantics, which an observed palette edit relies on.
730
+ if (state) state.gpuPose = false;
731
+ if (held && display.current)
732
+ this.#current.set(
733
+ evaluateAnimationPoseFallback(display.current.version),
734
+ slot * this.bones * 16,
735
+ );
736
+ display.current = undefined;
737
+ display.retired ||= (state?.effectiveRate ?? 1) > 1 || update !== skeletonUpdate || shared;
738
+ this.#rawMeta[slot * 4] = 0;
739
+ this.#rawMeta[slot * 4 + 1] = 0;
740
+ this.#markRawDirty();
741
+ this.#dirty = true;
742
+ }
743
+ this.#writeStock(slot, rig, state);
744
+ const display = this.#rawSlots.get(slot);
745
+ if (display) this.#syncObserved(slot, display);
746
+ } finally {
747
+ endSpan(SPANS.skinnedWrite);
748
+ }
749
+ }
750
+
751
+ #method(object: object, key: string): unknown {
752
+ for (let owner: object | null = object; owner !== null; owner = Object.getPrototypeOf(owner)) {
753
+ const d = Object.getOwnPropertyDescriptor(owner, key);
754
+ if (d) return Object.hasOwn(d, "value") ? d.value : undefined;
755
+ }
756
+ return undefined;
757
+ }
758
+
759
+ #prepareRawFrame(): void {
760
+ if (this.#rawFrame === this.#frame) return;
761
+ this.#rawFrame = this.#frame;
762
+ for (const [slot, display] of this.#rawSlots) {
763
+ if (display.current && display.previous?.version.keys !== display.current.version.keys) {
764
+ this.#rawPrevious.set(this.#rawData.subarray(slot * 576, (slot + 1) * 576), slot * 576);
765
+ this.#rawPreviousRoots.set(this.#rawRoots.subarray(slot * 32, (slot + 1) * 32), slot * 32);
766
+ }
767
+ display.previous = display.current;
768
+ this.#rawMeta[slot * 4 + 2] = this.#rawMeta[slot * 4] as number;
769
+ this.#rawMeta[slot * 4 + 3] = this.#rawMeta[slot * 4 + 1] as number;
770
+ }
771
+ this.#markRawDirty();
772
+ }
773
+
774
+ #markRawDirty(force = false): void {
775
+ if (!force && this.#rawDirtyFrame === this.#frame) return;
776
+ this.#rawDirtyFrame = this.#frame;
777
+ for (const attribute of this.#rawAttributes) attribute.needsUpdate = true;
778
+ }
779
+
780
+ #packRaw(slot: number, packet: IAnimationPosePacket, old: boolean, changed = true): void {
781
+ const data = old ? this.#rawPrevious : this.#rawData;
782
+ const roots = old ? this.#rawPreviousRoots : this.#rawRoots;
783
+ const meta = slot * 4 + (old ? 2 : 0);
784
+ const v = packet.version;
785
+ this.#rawMeta[meta] = 1;
786
+ this.#rawMeta[meta + 1] = packet.time;
787
+ if (changed) {
788
+ roots.set(v.rootWorld, slot * 32);
789
+ roots.set(v.bindInverse, slot * 32 + 16);
790
+ for (let b = 0; b < 12; b++) {
791
+ const at = (slot * 12 + b) * 48;
792
+ const rest = v.rest[b];
793
+ const key = v.keys[b];
794
+ const inverse = v.bindInverses[b];
795
+ if (!rest || !inverse) throw new Error("incomplete owned raw pose");
796
+ data.set(rest.local, at);
797
+ data.set(inverse, at + 16);
798
+ data.set([...rest.position, b === 0 ? 0 : 1, ...rest.scale, 0], at + 32);
799
+ data.set(key ? [...key.times, 0, ...key.values, 0] : [0, 1, 2, 0, 0, 0, 0, 0], at + 40);
800
+ }
801
+ }
802
+ this.#markRawDirty();
803
+ }
804
+
805
+ #checkObservedEdits(only?: number): void {
806
+ if (!this.#observed) return;
807
+ for (const [slot, display] of this.#rawSlots) {
808
+ if (only !== undefined && slot !== only) continue;
809
+ if (this.#rawMeta[slot * 4] !== 1 && this.#rawMeta[slot * 4 + 2] !== 1) continue;
810
+ const changed = (actual: Float32Array | undefined, expected: Float32Array | undefined) =>
811
+ expected !== undefined &&
812
+ actual !== undefined &&
813
+ expected.some((v, i) => !Object.is(v, actual[slot * this.bones * 16 + i]));
814
+ if (
815
+ !changed(this.#current, display.expectedCurrent) &&
816
+ !changed(this.#previous, display.expectedPrevious)
817
+ )
818
+ continue;
819
+ display.current = undefined;
820
+ display.previous = undefined;
821
+ display.retired = true;
822
+ display.expectedCurrent = undefined;
823
+ display.expectedPrevious = undefined;
824
+ this.#rawMeta.fill(0, slot * 4, slot * 4 + 4);
825
+ this.#markRawDirty(true);
826
+ this.#currentAttribute.needsUpdate = true;
827
+ if (this.#previousAttribute) this.#previousAttribute.needsUpdate = true;
828
+ this.#dirty = true;
829
+ }
830
+ }
831
+
832
+ #syncObserved(slot: number, display: IRawDisplaySlot): void {
833
+ if (!this.#observed) return;
834
+ const offset = slot * this.bones * 16;
835
+ if (display.current) {
836
+ const matrix = evaluateAnimationPosePacket(this.#timed(display.current, slot, false));
837
+ this.#current.set(matrix, offset);
838
+ display.expectedCurrent = matrix;
839
+ } else display.expectedCurrent = this.#current.slice(offset, offset + this.bones * 16);
840
+ display.expectedPrevious = this.#previous?.slice(offset, offset + this.bones * 16);
841
+ this.#dirty = true;
842
+ }
843
+
844
+ #observe(): void {
845
+ this.#checkObservedEdits();
846
+ if (this.#observed) return;
847
+ this.#prepareRawFrame();
848
+ for (const [slot, display] of this.#rawSlots) {
849
+ const offset = slot * this.bones * 16;
850
+ if (display.current)
851
+ this.#current.set(
852
+ evaluateAnimationPosePacket(this.#timed(display.current, slot, false)),
853
+ offset,
854
+ );
855
+ const previous =
856
+ display.previous ??
857
+ (!this.#fresh.includes(slot) && this.#rawMeta[slot * 4 + 2] === 1
858
+ ? display.current
859
+ : undefined);
860
+ if (previous && this.#previous)
861
+ this.#previous.set(
862
+ evaluateAnimationPosePacket(this.#timed(previous, slot, previous === display.previous)),
863
+ offset,
864
+ );
865
+ display.expectedCurrent = this.#current.slice(offset, offset + this.bones * 16);
866
+ display.expectedPrevious = this.#previous?.slice(offset, offset + this.bones * 16);
867
+ }
868
+ this.#observed = true;
869
+ this.#currentAttribute.needsUpdate = true;
870
+ if (this.#previousAttribute) this.#previousAttribute.needsUpdate = true;
871
+ this.#dirty = true;
872
+ }
873
+
874
+ #untrackSkeleton(slot: number): void {
875
+ const skeleton = this.#ownedSkeletons.get(slot);
876
+ if (!skeleton) return;
877
+ const owners = this.#skeletonOwners.get(skeleton);
878
+ owners?.delete(slot);
879
+ if (!owners?.size) this.#skeletonOwners.delete(skeleton);
880
+ this.#ownedSkeletons.delete(slot);
881
+ }
882
+
883
+ #trackSkeleton(slot: number, rig: Object3D, charged = false): void {
884
+ const skeleton = (rig as SkinnedMesh).skeleton as unknown;
885
+ if (this.#ownedSkeletons.get(slot) === skeleton && !charged) return;
886
+ if (this.#ownedSkeletons.get(slot) !== skeleton) this.#untrackSkeleton(slot);
887
+ if (!(skeleton instanceof Skeleton)) return;
888
+ this.#ownedSkeletons.set(slot, skeleton);
889
+ let owners = this.#skeletonOwners.get(skeleton);
890
+ if (!owners) {
891
+ owners = new Set();
892
+ this.#skeletonOwners.set(skeleton, owners);
893
+ }
894
+ owners.add(slot);
895
+ if (owners.size < 2 || ![...owners].some((owner) => this.#rawSlots.get(owner)?.current)) return;
896
+ // Between reconciles, retain the last published RAW pose until begin advances its history.
897
+ if (!charged && !this.#reconciling) return;
898
+ // Late sharing must also revoke an already-written RAW owner before this draw.
899
+ if (!charged) beginSpan(SPANS.skinnedWrite);
900
+ try {
901
+ this.#prepareRawFrame();
902
+ for (const owner of owners) {
903
+ const display = this.#rawSlots.get(owner);
904
+ if (!display) continue;
905
+ if (display.current)
906
+ this.#current.set(
907
+ evaluateAnimationPoseFallback(display.current.version),
908
+ owner * this.bones * 16,
909
+ );
910
+ display.current = undefined;
911
+ display.retired = true;
912
+ this.#syncObserved(owner, display);
913
+ this.#rawMeta[owner * 4] = 0;
914
+ this.#rawMeta[owner * 4 + 1] = 0;
915
+ this.#dirty = true;
916
+ }
917
+ this.#markRawDirty();
918
+ } finally {
919
+ if (!charged) endSpan(SPANS.skinnedWrite);
920
+ }
921
+ }
922
+
923
+ #writeStock(slot: number, rig: SkinnedMesh, state: IAnimationRateStateLike | undefined): void {
924
+ const writtenWorld = this.#writtenWorldMatrices.get(rig);
925
+ if (
926
+ state !== undefined &&
927
+ !state.evaluated &&
928
+ this.#writtenEvaluations.get(rig) === state.evaluation &&
929
+ writtenWorld?.equals(rig.matrixWorld)
930
+ )
931
+ return;
358
932
  const skeleton = rig.skeleton;
359
933
  if (this.#updated.get(skeleton) !== this.#frame) {
360
- skeleton.update();
934
+ const captured = this.#rawUpdates.get(skeleton);
935
+ if (captured?.frame === this.#frame) {
936
+ (skeleton.boneMatrices as Float32Array).set(
937
+ evaluateAnimationPoseFallback(captured.version),
938
+ );
939
+ if (skeleton.boneTexture !== null) skeleton.boneTexture.needsUpdate = true;
940
+ } else skeleton.update();
361
941
  this.#updated.set(skeleton, this.#frame);
362
942
  }
363
943
  const bones = skeleton.boneMatrices as Float32Array;
@@ -385,10 +965,18 @@ export class SkinnedBatch {
385
965
  }
386
966
  }
387
967
  this.#dirty = true;
968
+ if (state !== undefined) {
969
+ this.#writtenEvaluations.set(rig, state.evaluation);
970
+ const nextWorld = writtenWorld ?? new Matrix4();
971
+ nextWorld.copy(rig.matrixWorld);
972
+ this.#writtenWorldMatrices.set(rig, nextWorld);
973
+ }
388
974
  }
389
975
 
390
976
  /** Ends one reconcile: brand-new slots get history equal to their pose, then the palette uploads. */
391
977
  end(): void {
978
+ this.#reconciling = false;
979
+ this.#checkObservedEdits();
392
980
  const stride = this.bones * 16;
393
981
  if (this.#previous !== undefined) {
394
982
  for (const slot of this.#fresh)
@@ -397,6 +985,12 @@ export class SkinnedBatch {
397
985
  slot * stride,
398
986
  );
399
987
  }
988
+ if (this.#observed && this.#previous)
989
+ for (const slot of this.#fresh) {
990
+ const display = this.#rawSlots.get(slot);
991
+ if (display)
992
+ display.expectedPrevious = this.#previous.slice(slot * stride, (slot + 1) * stride);
993
+ }
400
994
  this.#fresh.length = 0;
401
995
  this.mesh.geometry.instanceCount = this.used;
402
996
  if (!this.#dirty) return;
@@ -411,9 +1005,30 @@ export class SkinnedBatch {
411
1005
  */
412
1006
  dispose(): void {
413
1007
  this.mesh.removeFromParent();
1008
+ for (const rig of this.#slotRigs.values()) releaseGpuPose(animationRateStateOf(rig));
414
1009
  this.#currentAttribute.dispose();
415
1010
  this.#previousAttribute?.dispose();
1011
+ for (const attribute of this.#rawAttributes) attribute.dispose();
416
1012
  this.mesh.material.dispose();
417
1013
  this.instances.clear();
1014
+ this.#slotRigs.clear();
1015
+ this.mesh.userData["threenative.animationPosePackets"] = undefined;
1016
+ this.#rawSlots.clear();
1017
+ this.#ownedSkeletons.clear();
1018
+ this.#skeletonOwners.clear();
1019
+ }
1020
+ }
1021
+
1022
+ function animationRateStateOf(object: Object3D): IAnimationRateStateLike | undefined {
1023
+ for (let node: Object3D | null = object; node !== null; node = node.parent) {
1024
+ const value = node.userData[ANIMATION_RATE_STATE_KEY];
1025
+ if (
1026
+ typeof value === "object" &&
1027
+ value !== null &&
1028
+ typeof (value as IAnimationRateStateLike).evaluated === "boolean" &&
1029
+ typeof (value as IAnimationRateStateLike).evaluation === "number"
1030
+ )
1031
+ return value as IAnimationRateStateLike;
418
1032
  }
1033
+ return undefined;
419
1034
  }