@threenative/core 0.3.3 → 0.3.5

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 (182) hide show
  1. package/capabilities.json +2019 -59
  2. package/dist/{assets-CYKk2WTu.d.ts → assets-CqvE429w.d.ts} +45 -3
  3. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  4. package/dist/{canvas-layer-C1SnMoJ-.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  5. package/dist/{game-D_6r-k4Y.d.ts → game-Bj8G1wmD.d.ts} +242 -17
  6. package/dist/hot.d.ts +5 -5
  7. package/dist/index.d.ts +1131 -105
  8. package/dist/index.js +15201 -4782
  9. package/dist/model-lod-BDAUYgsS.d.ts +197 -0
  10. package/dist/playtest.d.ts +6 -4
  11. package/dist/playtest.js +84 -11
  12. package/dist/react-css.d.ts +62 -0
  13. package/dist/react-css.js +591 -0
  14. package/dist/react.d.ts +2 -2
  15. package/dist/{renderer-Cy4qeBOA.d.ts → renderer-9yEo9hPa.d.ts} +676 -21
  16. package/dist/terrain-jobs-worker.d.ts +2 -0
  17. package/dist/terrain-jobs-worker.js +130 -0
  18. package/dist/ui-layer.d.ts +5 -3
  19. package/dist/ui-layer.js +59 -8
  20. package/dist/world.d.ts +1596 -17
  21. package/dist/world.js +17035 -521
  22. package/gpl/fixtures/make_world_fixture.py +184 -0
  23. package/gpl/recipes/_common.py +11 -0
  24. package/gpl/recipes/decimate.py +11 -5
  25. package/gpl/recipes/export_world.py +699 -0
  26. package/mcp/blender-server.mjs +61 -4
  27. package/mcp/blender.mjs +3 -4
  28. package/mcp/engine-server.mjs +55 -21
  29. package/mcp/servers.mjs +4 -4
  30. package/package.json +15 -9
  31. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  32. package/patches/three@0.185.1.patch +8246 -389
  33. package/scripts/apply-three-patch.mjs +123 -41
  34. package/src/animation-blend.ts +264 -0
  35. package/src/animation-composition.ts +362 -0
  36. package/src/animation-layers.ts +260 -0
  37. package/src/animation-root-motion.ts +283 -0
  38. package/src/animation.ts +896 -0
  39. package/src/assets.ts +1303 -0
  40. package/src/atmosphere/index.ts +335 -0
  41. package/src/atmosphere/luts.ts +298 -0
  42. package/src/atmosphere/params.ts +323 -0
  43. package/src/audio.ts +912 -0
  44. package/src/billboard.ts +124 -0
  45. package/src/bone-lengths.ts +157 -0
  46. package/src/camera-shake.ts +116 -0
  47. package/src/canvas-layer.ts +47 -0
  48. package/src/clip-audit.ts +401 -0
  49. package/src/clustered-batch.ts +492 -0
  50. package/src/clustered-mesh.ts +638 -0
  51. package/src/compute-driven.ts +176 -0
  52. package/src/compute-timing.ts +318 -0
  53. package/src/config.ts +593 -0
  54. package/src/debug.ts +82 -0
  55. package/src/engine-render-hook.ts +25 -0
  56. package/src/entities.ts +79 -0
  57. package/src/entity-snapshot.ts +53 -0
  58. package/src/flight.ts +683 -0
  59. package/src/fluid-field.ts +748 -0
  60. package/src/fluid-particles.ts +1253 -0
  61. package/src/frame-budget.ts +1368 -0
  62. package/src/game.ts +2390 -0
  63. package/src/geometry-capture.ts +1098 -0
  64. package/src/gpu-class.ts +160 -0
  65. package/src/gpu-frame-observation.ts +424 -0
  66. package/src/gpu-readback.ts +143 -0
  67. package/src/gpu-scene-bvh.ts +464 -0
  68. package/src/grounding.ts +100 -0
  69. package/src/hot.ts +161 -0
  70. package/src/import-meta.d.ts +13 -0
  71. package/src/index.ts +1536 -0
  72. package/src/input.ts +690 -0
  73. package/src/instanced-batch-lod.ts +283 -0
  74. package/src/instanced-batch.ts +274 -0
  75. package/src/interpolation.ts +129 -0
  76. package/src/launch-diagnostics.ts +161 -0
  77. package/src/loop.ts +564 -0
  78. package/src/matrix-world.ts +245 -0
  79. package/src/merge-parts.ts +812 -0
  80. package/src/model-lod.ts +1315 -0
  81. package/src/net-protocol.ts +333 -0
  82. package/src/net-session.ts +477 -0
  83. package/src/net.ts +80 -0
  84. package/src/ocean/fft.ts +72 -0
  85. package/src/ocean/spectral.ts +728 -0
  86. package/src/particle-significance.ts +102 -0
  87. package/src/particles.ts +648 -0
  88. package/src/path-follow.ts +175 -0
  89. package/src/picking.ts +250 -0
  90. package/src/pipeline-census.ts +1566 -0
  91. package/src/platform.ts +210 -0
  92. package/src/playtest.ts +839 -0
  93. package/src/pointer-events.ts +411 -0
  94. package/src/pose-measure.ts +435 -0
  95. package/src/profiling/FrameCounters.ts +231 -0
  96. package/src/profiling/Spans.ts +548 -0
  97. package/src/profiling/opacity-convention.ts +21 -0
  98. package/src/profiling/render-list-validate.ts +175 -0
  99. package/src/profiling/render-trap-audit.ts +84 -0
  100. package/src/profiling/scene-warning.ts +190 -0
  101. package/src/profiling/span-probes.ts +191 -0
  102. package/src/profiling/unlit-foliage-warning.ts +149 -0
  103. package/src/projection-apply.ts +1529 -0
  104. package/src/projection-marker.ts +142 -0
  105. package/src/projection-plan.ts +1258 -0
  106. package/src/projection-skinned.ts +419 -0
  107. package/src/projection-stability.ts +409 -0
  108. package/src/projection-uniform.ts +328 -0
  109. package/src/random.ts +41 -0
  110. package/src/react-css.ts +604 -0
  111. package/src/react-glyphs.ts +114 -0
  112. package/src/react-host.ts +576 -0
  113. package/src/react-layout.ts +265 -0
  114. package/src/react.ts +60 -0
  115. package/src/render/alpha-antialiasing.ts +159 -0
  116. package/src/render/batched-velocity.ts +126 -0
  117. package/src/render/chain.ts +1021 -0
  118. package/src/render/daylight.ts +189 -0
  119. package/src/render/depth-pyramid.ts +596 -0
  120. package/src/render/foliage-alpha.ts +166 -0
  121. package/src/render/material-key.ts +60 -0
  122. package/src/render/mesh-pool.ts +144 -0
  123. package/src/render/probe-volume.ts +1668 -0
  124. package/src/render/resolution-subrect.ts +253 -0
  125. package/src/render/velocity.ts +442 -0
  126. package/src/render/virtual-shadow-pages.ts +827 -0
  127. package/src/render/virtual-shadow-partial.ts +174 -0
  128. package/src/render/virtual-shadow.ts +3330 -0
  129. package/src/render/world-impostor-surface.ts +722 -0
  130. package/src/render/world-impostor.ts +558 -0
  131. package/src/render-camera-cull.ts +441 -0
  132. package/src/render-pass-budget.ts +501 -0
  133. package/src/renderProjection.ts +758 -0
  134. package/src/renderer-config.ts +127 -0
  135. package/src/renderer.ts +1847 -0
  136. package/src/replay-protocol.ts +85 -0
  137. package/src/replay.ts +205 -0
  138. package/src/resolution-scaler.ts +819 -0
  139. package/src/rig-preparation.ts +271 -0
  140. package/src/ripple-field.ts +432 -0
  141. package/src/scale.ts +109 -0
  142. package/src/scene.ts +239 -0
  143. package/src/schedule.ts +155 -0
  144. package/src/skeletal-mesh.ts +61 -0
  145. package/src/skeleton.ts +100 -0
  146. package/src/snow-field.ts +744 -0
  147. package/src/softbody-topology.ts +269 -0
  148. package/src/softbody.ts +516 -0
  149. package/src/sprite-animator.ts +222 -0
  150. package/src/startup-readiness.ts +386 -0
  151. package/src/state.ts +66 -0
  152. package/src/static-transform.ts +274 -0
  153. package/src/storage-buffer.ts +253 -0
  154. package/src/streaming.ts +308 -0
  155. package/src/target-fps.ts +92 -0
  156. package/src/terrain-jobs-worker.ts +17 -0
  157. package/src/terrain-jobs.ts +353 -0
  158. package/src/textures.ts +39 -0
  159. package/src/tracers.ts +237 -0
  160. package/src/ui-bridge.ts +368 -0
  161. package/src/ui-hit-regions.ts +380 -0
  162. package/src/ui-layer.ts +83 -0
  163. package/src/ui-state.ts +220 -0
  164. package/src/version.ts +2 -0
  165. package/src/viewport.ts +253 -0
  166. package/src/warmup.ts +1357 -0
  167. package/src/water-surface.ts +384 -0
  168. package/src/wave-field.ts +524 -0
  169. package/src/world-capabilities.ts +131 -0
  170. package/src/world-cell-proxy.ts +392 -0
  171. package/src/world-cells.ts +10564 -0
  172. package/src/world-gpu-scene.ts +3354 -0
  173. package/src/world-heightmap.ts +82 -0
  174. package/src/world-package.ts +469 -0
  175. package/src/world-passes.ts +582 -0
  176. package/src/world-region.ts +17 -0
  177. package/src/world-terrain-splat.ts +564 -0
  178. package/src/world-tiles.ts +3826 -0
  179. package/src/world-topology.ts +370 -0
  180. package/src/world-validate.ts +48 -0
  181. package/src/world.ts +805 -0
  182. package/dist/gpu-readback-CMklJs6r.d.ts +0 -112
@@ -0,0 +1,419 @@
1
+ import {
2
+ InstancedBufferGeometry,
3
+ type Material,
4
+ Mesh,
5
+ type Object3D,
6
+ type Skeleton,
7
+ type SkinnedMesh,
8
+ } from "three";
9
+ import {
10
+ Fn,
11
+ attribute,
12
+ instanceIndex,
13
+ normalGeometry,
14
+ normalLocal,
15
+ positionGeometry,
16
+ positionPrevious,
17
+ storage,
18
+ tangentGeometry,
19
+ tangentLocal,
20
+ uint,
21
+ vec4,
22
+ } from "three/tsl";
23
+ import {
24
+ MeshBasicNodeMaterial,
25
+ MeshLambertNodeMaterial,
26
+ MeshMatcapNodeMaterial,
27
+ MeshNormalNodeMaterial,
28
+ MeshPhongNodeMaterial,
29
+ MeshPhysicalNodeMaterial,
30
+ MeshStandardNodeMaterial,
31
+ MeshToonNodeMaterial,
32
+ type NodeMaterial,
33
+ StorageBufferAttribute,
34
+ } from "three/webgpu";
35
+
36
+ /**
37
+ * The skinned lane of the render projection: every rig that shares a geometry and material is one
38
+ * instanced draw per pass instead of one draw per rig per pass.
39
+ *
40
+ * Three's WebGPU backend submits each `SkinnedMesh` as its own render object — its own bone
41
+ * buffer, bind group and draw — in the main pass and again in every shadow pass. Here each rig is a
42
+ * slot in one storage palette of world-space bone matrices, and one vertex shader indexes it by
43
+ * `instanceIndex`. The CPU work per rig is what stock skinning already does: one `skeleton.update`
44
+ * and one matrix product per bone, written straight into the palette the GPU reads.
45
+ *
46
+ * The world transform is folded into each palette matrix, so the draw's own model matrix is the
47
+ * identity and a rig costs no instance-matrix buffer. That fold is exact for normals only when the
48
+ * rig's world transform has uniform scale and no shear, which is why the mirror keeps any other
49
+ * rig on its own draw. Hidden rigs and freed slots carry zero matrices: every triangle collapses
50
+ * and is discarded before rasterisation, and the slot is recycled without rebuilding the draw.
51
+ *
52
+ * The authored `SkinnedMesh` stays in the game's scene, untouched, so raycasts, bounds and
53
+ * animation keep targeting the game's own object. Only what the renderer is handed changes.
54
+ */
55
+
56
+ type NodeMaterialClass = new () => NodeMaterial;
57
+
58
+ /** The same classic-to-node mapping three's `NodeLibrary.fromMaterial` applies at draw time. */
59
+ const NODE_CLASSES: ReadonlyMap<string, NodeMaterialClass> = new Map<string, NodeMaterialClass>([
60
+ ["MeshBasicMaterial", MeshBasicNodeMaterial],
61
+ ["MeshLambertMaterial", MeshLambertNodeMaterial],
62
+ ["MeshMatcapMaterial", MeshMatcapNodeMaterial],
63
+ ["MeshNormalMaterial", MeshNormalNodeMaterial],
64
+ ["MeshPhongMaterial", MeshPhongNodeMaterial],
65
+ ["MeshPhysicalMaterial", MeshPhysicalNodeMaterial],
66
+ ["MeshStandardMaterial", MeshStandardNodeMaterial],
67
+ ["MeshToonMaterial", MeshToonNodeMaterial],
68
+ ]);
69
+
70
+ /**
71
+ * Properties never copied from the game's material onto the draw's. `positionNode` is the lane's
72
+ * own deformation; `_listeners` would hand the renderer's dispose hook for the game's material to
73
+ * the draw's; `id`/`uuid` keep the draw a distinct material to every cache keyed on them; and
74
+ * `version` is followed rather than copied, so the twin recompiles exactly when the game's does.
75
+ */
76
+ const UNSYNCED = new Set(["positionNode", "_listeners", "id", "uuid", "version"]);
77
+
78
+ function nodeClassOf(material: Material): NodeMaterialClass | undefined {
79
+ if (Reflect.get(material, "isNodeMaterial") === true) {
80
+ return material.constructor as NodeMaterialClass;
81
+ }
82
+ return NODE_CLASSES.get(material.type);
83
+ }
84
+
85
+ /**
86
+ * Why a material cannot draw through the lane's shader, or `undefined` when it can. A material that
87
+ * already moves its own vertices would be overwritten by the palette deformation, so it keeps
88
+ * three's own skinning path.
89
+ */
90
+ export function skinnedMaterialBlocked(material: Material): boolean {
91
+ return (
92
+ nodeClassOf(material) === undefined ||
93
+ Reflect.get(material, "positionNode") != null ||
94
+ Reflect.get(material, "castShadowPositionNode") != null ||
95
+ Reflect.get(material, "displacementMap") != null
96
+ );
97
+ }
98
+
99
+ /**
100
+ * Whether a per-instance colour may stand in for this material's base colour.
101
+ *
102
+ * Closed on purpose, and closed on the same table the skinned lane converts through: only a classic
103
+ * material class three is known to turn into a node material whose diffuse colour *is*
104
+ * `material.color` qualifies. A node material is refused outright — a custom graph decides for
105
+ * itself what a colour means, and a shader three has never heard of cannot be asked what it would
106
+ * do with a multiply. A material class this table does not name is refused for the same reason.
107
+ */
108
+ export function tintableMaterial(material: Material): boolean {
109
+ return Reflect.get(material, "isNodeMaterial") !== true && NODE_CLASSES.has(material.type);
110
+ }
111
+
112
+ /**
113
+ * True when `elements` is a rotation times a positive uniform scale plus a translation — the only
114
+ * world transform whose fold into the bone palette leaves normals exactly where stock skinning's
115
+ * normal matrix puts them.
116
+ */
117
+ export function isSimilarityTransform(elements: ArrayLike<number>): boolean {
118
+ const x0 = elements[0] as number;
119
+ const x1 = elements[1] as number;
120
+ const x2 = elements[2] as number;
121
+ const y0 = elements[4] as number;
122
+ const y1 = elements[5] as number;
123
+ const y2 = elements[6] as number;
124
+ const z0 = elements[8] as number;
125
+ const z1 = elements[9] as number;
126
+ const z2 = elements[10] as number;
127
+ const xx = x0 * x0 + x1 * x1 + x2 * x2;
128
+ const yy = y0 * y0 + y1 * y1 + y2 * y2;
129
+ const zz = z0 * z0 + z1 * z1 + z2 * z2;
130
+ if (!(xx > 1e-16)) return false;
131
+ const tolerance = xx * 1e-5;
132
+ if (Math.abs(yy - xx) > tolerance || Math.abs(zz - xx) > tolerance) return false;
133
+ if (Math.abs(x0 * y0 + x1 * y1 + x2 * y2) > tolerance) return false;
134
+ if (Math.abs(x0 * z0 + x1 * z1 + x2 * z2) > tolerance) return false;
135
+ if (Math.abs(y0 * z0 + y1 * z1 + y2 * z2) > tolerance) return false;
136
+ // Positive determinant: a mirrored rig would draw inside-out under the source's face culling.
137
+ const determinant =
138
+ x0 * (y1 * z2 - y2 * z1) - y0 * (x1 * z2 - x2 * z1) + z0 * (x1 * y2 - x2 * y1);
139
+ return determinant > 0 && elements[3] === 0 && elements[7] === 0 && elements[11] === 0;
140
+ }
141
+
142
+ /** out[o..o+16] = a[ao..ao+16] × b[bo..bo+16], column-major as three stores them. */
143
+ function multiply(
144
+ a: ArrayLike<number>,
145
+ ao: number,
146
+ b: ArrayLike<number>,
147
+ bo: number,
148
+ out: Float32Array | Float64Array,
149
+ o: number,
150
+ ): void {
151
+ const a00 = a[ao] as number;
152
+ const a10 = a[ao + 1] as number;
153
+ const a20 = a[ao + 2] as number;
154
+ const a01 = a[ao + 4] as number;
155
+ const a11 = a[ao + 5] as number;
156
+ const a21 = a[ao + 6] as number;
157
+ const a02 = a[ao + 8] as number;
158
+ const a12 = a[ao + 9] as number;
159
+ const a22 = a[ao + 10] as number;
160
+ const a03 = a[ao + 12] as number;
161
+ const a13 = a[ao + 13] as number;
162
+ const a23 = a[ao + 14] as number;
163
+ // Affine only: the bottom row of every matrix here is (0, 0, 0, 1), which three guarantees for
164
+ // bone and world matrices built from position/quaternion/scale.
165
+ for (let column = 0; column < 4; column += 1) {
166
+ const b0 = b[bo + column * 4] as number;
167
+ const b1 = b[bo + column * 4 + 1] as number;
168
+ const b2 = b[bo + column * 4 + 2] as number;
169
+ const b3 = b[bo + column * 4 + 3] as number;
170
+ const at = o + column * 4;
171
+ out[at] = a00 * b0 + a01 * b1 + a02 * b2 + a03 * b3;
172
+ out[at + 1] = a10 * b0 + a11 * b1 + a12 * b2 + a13 * b3;
173
+ out[at + 2] = a20 * b0 + a21 * b1 + a22 * b2 + a23 * b3;
174
+ out[at + 3] = b3;
175
+ }
176
+ }
177
+
178
+ function isIdentity(elements: ArrayLike<number>): boolean {
179
+ for (let index = 0; index < 16; index += 1) {
180
+ if (elements[index] !== (index % 5 === 0 ? 1 : 0)) return false;
181
+ }
182
+ return true;
183
+ }
184
+
185
+ export interface ISkinnedBatchOptions {
186
+ readonly first: SkinnedMesh;
187
+ readonly capacity: number;
188
+ readonly velocity: boolean;
189
+ }
190
+
191
+ /** One skinned draw: a palette of `capacity × bones` world-space matrices and the shader reading it. */
192
+ export class SkinnedBatch {
193
+ readonly mesh: Mesh<InstancedBufferGeometry, NodeMaterial>;
194
+ /** The game's material; the draw's is a node twin re-synced from it every frame. */
195
+ readonly sourceMaterial: Material;
196
+ readonly bones: number;
197
+ readonly capacity: number;
198
+ readonly instances = new Map<Object3D, number>();
199
+ readonly free: number[] = [];
200
+ used = 0;
201
+ readonly #current: Float32Array;
202
+ readonly #previous: Float32Array | undefined;
203
+ readonly #currentAttribute: StorageBufferAttribute;
204
+ readonly #previousAttribute: StorageBufferAttribute | undefined;
205
+ /** Slots whose history must equal their first pose rather than whatever a previous owner left. */
206
+ readonly #fresh: number[] = [];
207
+ readonly #bindScratch = new Float64Array(16);
208
+ readonly #updated = new WeakMap<Skeleton, number>();
209
+ #frame = 0;
210
+ #dirty = false;
211
+ #sourceVersion: number;
212
+
213
+ constructor(options: ISkinnedBatchOptions) {
214
+ const { first, capacity, velocity } = options;
215
+ const NodeClass = nodeClassOf(first.material as Material);
216
+ if (NodeClass === undefined) throw new Error("SkinnedBatch requires a convertible material.");
217
+ this.sourceMaterial = first.material as Material;
218
+ this.#sourceVersion = this.sourceMaterial.version;
219
+ this.bones = first.skeleton.bones.length;
220
+ this.capacity = capacity;
221
+ const floats = capacity * this.bones * 16;
222
+ this.#current = new Float32Array(floats);
223
+ this.#currentAttribute = new StorageBufferAttribute(this.#current, 16);
224
+ if (velocity) {
225
+ this.#previous = new Float32Array(floats);
226
+ this.#previousAttribute = new StorageBufferAttribute(this.#previous, 16);
227
+ }
228
+
229
+ // The game's vertex buffers by reference, never copied: the draw uploads nothing the source
230
+ // geometry has not already uploaded, and a game streaming into its attributes is followed.
231
+ const source = first.geometry;
232
+ const geometry = new InstancedBufferGeometry();
233
+ for (const name in source.attributes) {
234
+ if (Object.hasOwn(source.attributes, name))
235
+ geometry.setAttribute(name, source.attributes[name] as never);
236
+ }
237
+ geometry.setIndex(source.index);
238
+ for (const group of source.groups)
239
+ geometry.addGroup(group.start, group.count, group.materialIndex);
240
+ geometry.instanceCount = 0;
241
+
242
+ const count = capacity * this.bones;
243
+ const current = storage(this.#currentAttribute, "mat4", count).toReadOnly();
244
+ const previous =
245
+ this.#previousAttribute === undefined
246
+ ? undefined
247
+ : storage(this.#previousAttribute, "mat4", count).toReadOnly();
248
+ const boneIndex = attribute<"uvec4">("skinIndex", "uvec4");
249
+ const weight = attribute<"vec4">("skinWeight", "vec4");
250
+ const base = instanceIndex.mul(uint(this.bones));
251
+ const blend = (palette: typeof current) =>
252
+ palette
253
+ .element(base.add(boneIndex.x))
254
+ .mul(weight.x)
255
+ .add(palette.element(base.add(boneIndex.y)).mul(weight.y))
256
+ .add(palette.element(base.add(boneIndex.z)).mul(weight.z))
257
+ .add(palette.element(base.add(boneIndex.w)).mul(weight.w));
258
+ const hasTangent = source.getAttribute("tangent") !== undefined;
259
+ const material = new NodeClass();
260
+ this.#syncMaterial(material);
261
+ material.positionNode = Fn(() => {
262
+ const matrix = blend(current);
263
+ normalLocal.assign(matrix.mul(vec4(normalGeometry, 0)).xyz);
264
+ 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);
267
+ return matrix.mul(vec4(positionGeometry, 1)).xyz;
268
+ })();
269
+ material.needsUpdate = true;
270
+
271
+ this.mesh = new Mesh(geometry, material);
272
+ this.mesh.matrixAutoUpdate = false;
273
+ // The palette spans every rig; only the per-rig sources have meaningful bounds.
274
+ this.mesh.frustumCulled = false;
275
+ this.mesh.castShadow = first.castShadow;
276
+ this.mesh.receiveShadow = first.receiveShadow;
277
+ this.mesh.layers.mask = first.layers.mask;
278
+ }
279
+
280
+ /**
281
+ * Starts one reconcile: the frame's history becomes last frame's pose. Called once per frame
282
+ * before any rig writes, so every pass of the frame reads the same pair.
283
+ */
284
+ begin(): void {
285
+ this.#frame += 1;
286
+ this.#syncMaterial(this.mesh.material);
287
+ if (this.sourceMaterial.version !== this.#sourceVersion) {
288
+ this.#sourceVersion = this.sourceMaterial.version;
289
+ this.mesh.material.needsUpdate = true;
290
+ }
291
+ if (this.#previous !== undefined) {
292
+ this.#previous.set(this.#current);
293
+ this.#dirty = true;
294
+ }
295
+ }
296
+
297
+ /** Copies the game's current material values onto the draw's twin, as three's own conversion does. */
298
+ #syncMaterial(target: NodeMaterial): void {
299
+ const from = this.sourceMaterial;
300
+ for (const key in from) {
301
+ if (!UNSYNCED.has(key)) Reflect.set(target, key, Reflect.get(from, key));
302
+ }
303
+ }
304
+
305
+ /** Claims a slot for `rig`, or returns `undefined` when the batch is full. */
306
+ claim(rig: Object3D): number | undefined {
307
+ let slot = this.instances.get(rig);
308
+ if (slot !== undefined) return slot;
309
+ slot = this.free.pop();
310
+ if (slot === undefined) {
311
+ if (this.used >= this.capacity) return undefined;
312
+ slot = this.used;
313
+ this.used += 1;
314
+ }
315
+ this.instances.set(rig, slot);
316
+ this.#fresh.push(slot);
317
+ return slot;
318
+ }
319
+
320
+ /** Returns a rig's slot to the free list with a collapsed pose, so it draws nothing. */
321
+ release(rig: Object3D): void {
322
+ const slot = this.instances.get(rig);
323
+ if (slot === undefined) return;
324
+ this.instances.delete(rig);
325
+ this.hide(slot);
326
+ this.free.push(slot);
327
+ }
328
+
329
+ /** This frame's world-space bone matrices, `capacity × bones` of them in slot order. */
330
+ get palette(): Float32Array {
331
+ return this.#current;
332
+ }
333
+
334
+ /** Last frame's palette, present only while a temporal stage asks for per-object history. */
335
+ get history(): Float32Array | undefined {
336
+ return this.#previous;
337
+ }
338
+
339
+ /** Marks a slot whose history must restart from its next pose. */
340
+ restart(slot: number): void {
341
+ this.#fresh.push(slot);
342
+ }
343
+
344
+ /** Collapses one slot for this frame; a hidden rig keeps its slot. */
345
+ hide(slot: number): void {
346
+ const stride = this.bones * 16;
347
+ this.#current.fill(0, slot * stride, (slot + 1) * stride);
348
+ this.#previous?.fill(0, slot * stride, (slot + 1) * stride);
349
+ this.#dirty = true;
350
+ }
351
+
352
+ /**
353
+ * Writes one rig's world-space bone palette. Equals stock skinning's
354
+ * `matrixWorld · bindMatrixInverse · boneMatrix · bindMatrix` per bone; in the default attached
355
+ * bind mode `matrixWorld · bindMatrixInverse` is the identity and is skipped.
356
+ */
357
+ write(slot: number, rig: SkinnedMesh): void {
358
+ const skeleton = rig.skeleton;
359
+ if (this.#updated.get(skeleton) !== this.#frame) {
360
+ skeleton.update();
361
+ this.#updated.set(skeleton, this.#frame);
362
+ }
363
+ const bones = skeleton.boneMatrices as Float32Array;
364
+ const bind = rig.bindMatrix.elements;
365
+ const bindIsIdentity = isIdentity(bind);
366
+ const detached = rig.bindMode !== "attached";
367
+ const prefix = this.#bindScratch;
368
+ if (detached)
369
+ multiply(rig.matrixWorld.elements, 0, rig.bindMatrixInverse.elements, 0, prefix, 0);
370
+ const out = this.#current;
371
+ const offset = slot * this.bones * 16;
372
+ // The common case is one contiguous copy: `skeleton.update` has already written this rig's
373
+ // bone matrices in palette order, and an identity bind matrix leaves them unchanged.
374
+ if (bindIsIdentity) out.set(bones, offset);
375
+ else {
376
+ for (let bone = 0; bone < this.bones; bone += 1) {
377
+ multiply(bones, bone * 16, bind, 0, out, offset + bone * 16);
378
+ }
379
+ }
380
+ if (detached) {
381
+ for (let bone = 0; bone < this.bones; bone += 1) {
382
+ const at = offset + bone * 16;
383
+ // In place is safe: `multiply` reads each right-hand column before writing it.
384
+ multiply(prefix, 0, out, at, out, at);
385
+ }
386
+ }
387
+ this.#dirty = true;
388
+ }
389
+
390
+ /** Ends one reconcile: brand-new slots get history equal to their pose, then the palette uploads. */
391
+ end(): void {
392
+ const stride = this.bones * 16;
393
+ if (this.#previous !== undefined) {
394
+ for (const slot of this.#fresh)
395
+ this.#previous.set(
396
+ this.#current.subarray(slot * stride, (slot + 1) * stride),
397
+ slot * stride,
398
+ );
399
+ }
400
+ this.#fresh.length = 0;
401
+ this.mesh.geometry.instanceCount = this.used;
402
+ if (!this.#dirty) return;
403
+ this.#dirty = false;
404
+ this.#currentAttribute.needsUpdate = true;
405
+ if (this.#previousAttribute !== undefined) this.#previousAttribute.needsUpdate = true;
406
+ }
407
+
408
+ /**
409
+ * Releases the palette buffers and the draw's material. The geometry is not disposed: its vertex
410
+ * buffers are the game's own, and disposing it would free them under the source mesh.
411
+ */
412
+ dispose(): void {
413
+ this.mesh.removeFromParent();
414
+ this.#currentAttribute.dispose();
415
+ this.#previousAttribute?.dispose();
416
+ this.mesh.material.dispose();
417
+ this.instances.clear();
418
+ }
419
+ }