@threenative/core 0.3.4 → 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 (176) hide show
  1. package/capabilities.json +1505 -79
  2. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  3. package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  4. package/dist/{game-CljaDv4D.d.ts → game-Bj8G1wmD.d.ts} +102 -11
  5. package/dist/hot.d.ts +4 -4
  6. package/dist/index.d.ts +712 -118
  7. package/dist/index.js +12423 -4955
  8. package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
  9. package/dist/playtest.d.ts +6 -10
  10. package/dist/playtest.js +47 -24
  11. package/dist/react-css.d.ts +62 -0
  12. package/dist/react-css.js +591 -0
  13. package/dist/react.d.ts +2 -2
  14. package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
  15. package/dist/terrain-jobs-worker.d.ts +2 -0
  16. package/dist/terrain-jobs-worker.js +130 -0
  17. package/dist/ui-layer.js +59 -8
  18. package/dist/world.d.ts +766 -73
  19. package/dist/world.js +9307 -3543
  20. package/gpl/recipes/export_world.py +18 -1
  21. package/mcp/blender-server.mjs +7 -4
  22. package/mcp/blender.mjs +3 -4
  23. package/mcp/engine-server.mjs +2 -2
  24. package/mcp/servers.mjs +4 -4
  25. package/package.json +15 -9
  26. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  27. package/patches/three@0.185.1.patch +6594 -700
  28. package/scripts/apply-three-patch.mjs +62 -4
  29. package/src/animation-blend.ts +264 -0
  30. package/src/animation-composition.ts +362 -0
  31. package/src/animation-layers.ts +260 -0
  32. package/src/animation-root-motion.ts +283 -0
  33. package/src/animation.ts +896 -0
  34. package/src/assets.ts +1303 -0
  35. package/src/atmosphere/index.ts +335 -0
  36. package/src/atmosphere/luts.ts +298 -0
  37. package/src/atmosphere/params.ts +323 -0
  38. package/src/audio.ts +912 -0
  39. package/src/billboard.ts +124 -0
  40. package/src/bone-lengths.ts +157 -0
  41. package/src/camera-shake.ts +116 -0
  42. package/src/canvas-layer.ts +47 -0
  43. package/src/clip-audit.ts +401 -0
  44. package/src/clustered-batch.ts +492 -0
  45. package/src/clustered-mesh.ts +638 -0
  46. package/src/compute-driven.ts +176 -0
  47. package/src/compute-timing.ts +318 -0
  48. package/src/config.ts +593 -0
  49. package/src/debug.ts +82 -0
  50. package/src/engine-render-hook.ts +25 -0
  51. package/src/entities.ts +79 -0
  52. package/src/entity-snapshot.ts +53 -0
  53. package/src/flight.ts +683 -0
  54. package/src/fluid-field.ts +748 -0
  55. package/src/fluid-particles.ts +1253 -0
  56. package/src/frame-budget.ts +1368 -0
  57. package/src/game.ts +2390 -0
  58. package/src/geometry-capture.ts +1098 -0
  59. package/src/gpu-class.ts +160 -0
  60. package/src/gpu-frame-observation.ts +424 -0
  61. package/src/gpu-readback.ts +143 -0
  62. package/src/gpu-scene-bvh.ts +464 -0
  63. package/src/grounding.ts +100 -0
  64. package/src/hot.ts +161 -0
  65. package/src/import-meta.d.ts +13 -0
  66. package/src/index.ts +1536 -0
  67. package/src/input.ts +690 -0
  68. package/src/instanced-batch-lod.ts +283 -0
  69. package/src/instanced-batch.ts +274 -0
  70. package/src/interpolation.ts +129 -0
  71. package/src/launch-diagnostics.ts +161 -0
  72. package/src/loop.ts +564 -0
  73. package/src/matrix-world.ts +245 -0
  74. package/src/merge-parts.ts +812 -0
  75. package/src/model-lod.ts +1315 -0
  76. package/src/net-protocol.ts +333 -0
  77. package/src/net-session.ts +477 -0
  78. package/src/net.ts +80 -0
  79. package/src/ocean/fft.ts +72 -0
  80. package/src/ocean/spectral.ts +728 -0
  81. package/src/particle-significance.ts +102 -0
  82. package/src/particles.ts +648 -0
  83. package/src/path-follow.ts +175 -0
  84. package/src/picking.ts +250 -0
  85. package/src/pipeline-census.ts +1566 -0
  86. package/src/platform.ts +210 -0
  87. package/src/playtest.ts +839 -0
  88. package/src/pointer-events.ts +411 -0
  89. package/src/pose-measure.ts +435 -0
  90. package/src/profiling/FrameCounters.ts +231 -0
  91. package/src/profiling/Spans.ts +548 -0
  92. package/src/profiling/opacity-convention.ts +21 -0
  93. package/src/profiling/render-list-validate.ts +175 -0
  94. package/src/profiling/render-trap-audit.ts +84 -0
  95. package/src/profiling/scene-warning.ts +190 -0
  96. package/src/profiling/span-probes.ts +191 -0
  97. package/src/profiling/unlit-foliage-warning.ts +149 -0
  98. package/src/projection-apply.ts +1529 -0
  99. package/src/projection-marker.ts +142 -0
  100. package/src/projection-plan.ts +1258 -0
  101. package/src/projection-skinned.ts +419 -0
  102. package/src/projection-stability.ts +409 -0
  103. package/src/projection-uniform.ts +328 -0
  104. package/src/random.ts +41 -0
  105. package/src/react-css.ts +604 -0
  106. package/src/react-glyphs.ts +114 -0
  107. package/src/react-host.ts +576 -0
  108. package/src/react-layout.ts +265 -0
  109. package/src/react.ts +60 -0
  110. package/src/render/alpha-antialiasing.ts +159 -0
  111. package/src/render/batched-velocity.ts +126 -0
  112. package/src/render/chain.ts +1021 -0
  113. package/src/render/daylight.ts +189 -0
  114. package/src/render/depth-pyramid.ts +596 -0
  115. package/src/render/foliage-alpha.ts +166 -0
  116. package/src/render/material-key.ts +60 -0
  117. package/src/render/mesh-pool.ts +144 -0
  118. package/src/render/probe-volume.ts +1668 -0
  119. package/src/render/resolution-subrect.ts +253 -0
  120. package/src/render/velocity.ts +442 -0
  121. package/src/render/virtual-shadow-pages.ts +827 -0
  122. package/src/render/virtual-shadow-partial.ts +174 -0
  123. package/src/render/virtual-shadow.ts +3330 -0
  124. package/src/render/world-impostor-surface.ts +722 -0
  125. package/src/render/world-impostor.ts +558 -0
  126. package/src/render-camera-cull.ts +441 -0
  127. package/src/render-pass-budget.ts +501 -0
  128. package/src/renderProjection.ts +758 -0
  129. package/src/renderer-config.ts +127 -0
  130. package/src/renderer.ts +1847 -0
  131. package/src/replay-protocol.ts +85 -0
  132. package/src/replay.ts +205 -0
  133. package/src/resolution-scaler.ts +819 -0
  134. package/src/rig-preparation.ts +271 -0
  135. package/src/ripple-field.ts +432 -0
  136. package/src/scale.ts +109 -0
  137. package/src/scene.ts +239 -0
  138. package/src/schedule.ts +155 -0
  139. package/src/skeletal-mesh.ts +61 -0
  140. package/src/skeleton.ts +100 -0
  141. package/src/snow-field.ts +744 -0
  142. package/src/softbody-topology.ts +269 -0
  143. package/src/softbody.ts +516 -0
  144. package/src/sprite-animator.ts +222 -0
  145. package/src/startup-readiness.ts +386 -0
  146. package/src/state.ts +66 -0
  147. package/src/static-transform.ts +274 -0
  148. package/src/storage-buffer.ts +253 -0
  149. package/src/streaming.ts +308 -0
  150. package/src/target-fps.ts +92 -0
  151. package/src/terrain-jobs-worker.ts +17 -0
  152. package/src/terrain-jobs.ts +353 -0
  153. package/src/textures.ts +39 -0
  154. package/src/tracers.ts +237 -0
  155. package/src/ui-bridge.ts +368 -0
  156. package/src/ui-hit-regions.ts +380 -0
  157. package/src/ui-layer.ts +83 -0
  158. package/src/ui-state.ts +220 -0
  159. package/src/version.ts +2 -0
  160. package/src/viewport.ts +253 -0
  161. package/src/warmup.ts +1357 -0
  162. package/src/water-surface.ts +384 -0
  163. package/src/wave-field.ts +524 -0
  164. package/src/world-capabilities.ts +131 -0
  165. package/src/world-cell-proxy.ts +392 -0
  166. package/src/world-cells.ts +10564 -0
  167. package/src/world-gpu-scene.ts +3354 -0
  168. package/src/world-heightmap.ts +82 -0
  169. package/src/world-package.ts +469 -0
  170. package/src/world-passes.ts +582 -0
  171. package/src/world-region.ts +17 -0
  172. package/src/world-terrain-splat.ts +564 -0
  173. package/src/world-tiles.ts +3826 -0
  174. package/src/world-topology.ts +370 -0
  175. package/src/world-validate.ts +48 -0
  176. package/src/world.ts +805 -0
@@ -0,0 +1,271 @@
1
+ import type { AnimationClip, Object3D } from "three";
2
+
3
+ /**
4
+ * Skeletal preparation reused across clones of one source rig.
5
+ *
6
+ * Creating a `SkeletalMesh3D` from the same source and clip set performs two per-instance
7
+ * measurements: a property-binding audit for every required clip, and a full-rig foot-plant
8
+ * sample the first time an in-place clip's ground speed is read. Both are properties of the
9
+ * source rig and the clip, not of the instance, so a party of identical characters pays for
10
+ * them once per member and sees nothing for it.
11
+ *
12
+ * This caches the two derived numbers only — never mixers, actions, bones, poses or the public
13
+ * `.stride` report. Ownership hangs off the source object in a `WeakMap`, so a discarded source
14
+ * releases its cache, and each number is guarded by a content signature: a changed hierarchy,
15
+ * binding path, track value or clip duration is a different signature and a miss. A clone whose
16
+ * own bind pose was edited before it is measured is likewise not eligible, which keeps one
17
+ * clone's mutation from poisoning another's value.
18
+ *
19
+ * The unguarded per-instance path is the fallback for anything that cannot be represented safely:
20
+ * ambiguous node names, non-bone tracks, a clip that does not drive every node, or a rig under a
21
+ * non-uniform or tilted world transform.
22
+ */
23
+
24
+ const FNV_OFFSET = 2166136261;
25
+ const FNV_PRIME = 16777619;
26
+ /** The absolute scale difference within which a rig counts as uniformly scaled. */
27
+ const UNIFORM_SCALE_EPSILON = 1e-4;
28
+ /** Off-axis contribution within which a world matrix counts as yaw-only. */
29
+ const YAW_EPSILON = 1e-4;
30
+
31
+ /** A stride measured at unit world scale, so uniformly scaled clones can share it. */
32
+ export interface ISharedStride {
33
+ /** Metres of ground per clip-second at rate 1, per unit of uniform world scale. */
34
+ readonly groundSpeed: number;
35
+ readonly inPlace: boolean;
36
+ }
37
+
38
+ interface IBindingEntry {
39
+ readonly signature: string;
40
+ readonly bound: number;
41
+ }
42
+
43
+ interface IStrideEntry {
44
+ readonly signature: string;
45
+ readonly stride: ISharedStride;
46
+ }
47
+
48
+ const floatBits = new Float64Array(1);
49
+ const floatWords = new Uint32Array(floatBits.buffer);
50
+
51
+ function hashString(hash: number, value: string): number {
52
+ let result = hash;
53
+ for (let index = 0; index < value.length; index += 1) {
54
+ result = Math.imul(result ^ value.charCodeAt(index), FNV_PRIME);
55
+ }
56
+ return result;
57
+ }
58
+
59
+ function hashFloat(hash: number, value: number): number {
60
+ floatBits[0] = value;
61
+ const low = floatWords[0] ?? 0;
62
+ const high = floatWords[1] ?? 0;
63
+ return Math.imul(Math.imul(hash ^ low, FNV_PRIME) ^ high, FNV_PRIME);
64
+ }
65
+
66
+ function signatureOf(hash: number): string {
67
+ return (hash >>> 0).toString(16).padStart(8, "0");
68
+ }
69
+
70
+ /** The node part of an ordinary bone-transform track, or `undefined` for any other track. */
71
+ function ordinaryTrackNode(track: string): string | undefined {
72
+ for (const property of [".position", ".quaternion", ".scale"]) {
73
+ if (track.endsWith(property)) {
74
+ const node = track.slice(0, track.length - property.length);
75
+ return node.length === 0 ? undefined : node;
76
+ }
77
+ }
78
+ return undefined;
79
+ }
80
+
81
+ /**
82
+ * True when every descendant node is uniquely named and every track is an ordinary
83
+ * bone-transform track on a named node. Ambiguous names, `.morphTargetInfluences` or material
84
+ * and custom property tracks are outside what sharing can represent safely.
85
+ */
86
+ function ordinaryRig(source: Object3D, clips: readonly AnimationClip[]): boolean {
87
+ const names = new Set<string>();
88
+ let duplicate = false;
89
+ source.traverse((object) => {
90
+ if (object === source) return;
91
+ if (object.name.length === 0) return;
92
+ if (names.has(object.name)) duplicate = true;
93
+ names.add(object.name);
94
+ });
95
+ if (duplicate) return false;
96
+ for (const clip of clips) {
97
+ for (const track of clip.tracks) {
98
+ if (ordinaryTrackNode(track.name) === undefined) return false;
99
+ }
100
+ }
101
+ return true;
102
+ }
103
+
104
+ /**
105
+ * A clip drives every bone when each bone name appears as a track target.
106
+ *
107
+ * The sample starts from the rig's current pose and overwrites the nodes the clip drives, so an
108
+ * untracked *bone* carries whatever the previous clip left it in — the one input that differs
109
+ * between two clones. Untracked mesh or prop nodes keep a static local transform, which the
110
+ * source clone gave every instance, so they do not disqualify reuse.
111
+ */
112
+ function drivesEveryBone(source: Object3D, clip: AnimationClip): boolean {
113
+ const needed = new Set<string>();
114
+ source.traverse((object) => {
115
+ if (object !== source && (object as { isBone?: boolean }).isBone === true)
116
+ needed.add(object.name);
117
+ });
118
+ if (needed.size === 0) return false;
119
+ for (const track of clip.tracks) {
120
+ const node = ordinaryTrackNode(track.name);
121
+ if (node !== undefined) needed.delete(node);
122
+ }
123
+ return needed.size === 0;
124
+ }
125
+
126
+ /** Binding resolves by node name, so only names and track targets can change the audit. */
127
+ function bindingSignature(source: Object3D, clip: AnimationClip): string | undefined {
128
+ let hash = FNV_OFFSET;
129
+ source.traverse((object) => {
130
+ if (object === source) return;
131
+ hash = hashString(hash, object.name);
132
+ hash = hashString(hash, object.type);
133
+ });
134
+ for (const track of clip.tracks) hash = hashString(hash, track.name);
135
+ return signatureOf(hash);
136
+ }
137
+
138
+ /**
139
+ * The stride sample starts from the rig's current pose and overwrites only the nodes the clip
140
+ * drives, so sharing requires full coverage; then only the clip's content matters. Duration and
141
+ * values are hashed, not the track object, so an in-place edit is a different signature.
142
+ */
143
+ function strideSignature(source: Object3D, clip: AnimationClip): string | undefined {
144
+ if (!drivesEveryBone(source, clip)) return undefined;
145
+ let hash = FNV_OFFSET;
146
+ hash = hashString(hash, clip.name);
147
+ hash = hashFloat(hash, clip.duration);
148
+ const driven = new Set<string>();
149
+ for (const track of clip.tracks) {
150
+ const node = ordinaryTrackNode(track.name);
151
+ if (node !== undefined) driven.add(node);
152
+ hash = hashString(hash, track.name);
153
+ const values = track.values;
154
+ hash = hashFloat(hash, values.length);
155
+ for (let index = 0; index < values.length; index += 1) {
156
+ hash = hashFloat(hash, values[index] ?? 0);
157
+ }
158
+ }
159
+ // An untracked mesh or prop starts from the pose its clone arrived with, so its local transform
160
+ // is an input the sampled result depends on. Hashing it makes a mutated prop a miss. The rig
161
+ // root's own transform is left out: translation, yaw and uniform scale are normalized out and
162
+ // checked separately by `uniformYawScale`.
163
+ source.traverse((object) => {
164
+ if (object === source) return;
165
+ if ((object as { isBone?: boolean }).isBone === true) return;
166
+ if (object.name.length > 0 && driven.has(object.name)) return;
167
+ hash = hashString(hash, object.name);
168
+ hash = hashFloat(hash, object.position.x);
169
+ hash = hashFloat(hash, object.position.y);
170
+ hash = hashFloat(hash, object.position.z);
171
+ hash = hashFloat(hash, object.quaternion.x);
172
+ hash = hashFloat(hash, object.quaternion.y);
173
+ hash = hashFloat(hash, object.quaternion.z);
174
+ hash = hashFloat(hash, object.quaternion.w);
175
+ hash = hashFloat(hash, object.scale.x);
176
+ hash = hashFloat(hash, object.scale.y);
177
+ hash = hashFloat(hash, object.scale.z);
178
+ });
179
+ return signatureOf(hash);
180
+ }
181
+
182
+ /**
183
+ * The uniform world scale of a yaw-only, untilted transform, or `undefined` when the transform
184
+ * carries a tilt, a mirror or a non-uniform scale that the normalized value cannot represent.
185
+ */
186
+ export function uniformYawScale(matrixWorld: {
187
+ readonly elements: ArrayLike<number>;
188
+ }): number | undefined {
189
+ const e = matrixWorld.elements;
190
+ const e0 = e[0] ?? 0;
191
+ const e1 = e[1] ?? 0;
192
+ const e2 = e[2] ?? 0;
193
+ const e4 = e[4] ?? 0;
194
+ const e5 = e[5] ?? 0;
195
+ const e6 = e[6] ?? 0;
196
+ const e8 = e[8] ?? 0;
197
+ const e9 = e[9] ?? 0;
198
+ const e10 = e[10] ?? 0;
199
+ const scaleX = Math.hypot(e0, e1, e2);
200
+ const scaleY = Math.hypot(e4, e5, e6);
201
+ const scaleZ = Math.hypot(e8, e9, e10);
202
+ if (!(scaleX > 0) || !(scaleY > 0) || !(scaleZ > 0)) return undefined;
203
+ if (
204
+ Math.abs(scaleX - scaleY) > UNIFORM_SCALE_EPSILON ||
205
+ Math.abs(scaleY - scaleZ) > UNIFORM_SCALE_EPSILON
206
+ ) {
207
+ return undefined;
208
+ }
209
+ // A yaw-only rotation leaves the Y axis vertical and keeps both horizontal axes level.
210
+ const upY = e5 / scaleY;
211
+ if (
212
+ Math.abs(e1 / scaleX) > YAW_EPSILON ||
213
+ Math.abs(e9 / scaleZ) > YAW_EPSILON ||
214
+ Math.abs(e4 / scaleY) > YAW_EPSILON ||
215
+ Math.abs(e6 / scaleY) > YAW_EPSILON ||
216
+ Math.abs(Math.abs(upY) - 1) > YAW_EPSILON
217
+ ) {
218
+ return undefined;
219
+ }
220
+ const determinant =
221
+ e0 * (e5 * e10 - e6 * e9) - e1 * (e4 * e10 - e6 * e8) + e2 * (e4 * e9 - e5 * e8);
222
+ if (!(determinant > 0)) return undefined;
223
+ return (scaleX + scaleY + scaleZ) / 3;
224
+ }
225
+
226
+ export class RigPreparation {
227
+ readonly #binding = new Map<AnimationClip, IBindingEntry>();
228
+ readonly #stride = new Map<AnimationClip, IStrideEntry>();
229
+
230
+ /** The cached binding count for an equivalent preparation, or `undefined` on a miss. */
231
+ boundCount(source: Object3D, clip: AnimationClip): number | undefined {
232
+ const entry = this.#binding.get(clip);
233
+ if (entry === undefined) return undefined;
234
+ if (!ordinaryRig(source, [clip])) return undefined;
235
+ const signature = bindingSignature(source, clip);
236
+ return signature !== undefined && signature === entry.signature ? entry.bound : undefined;
237
+ }
238
+
239
+ rememberBound(source: Object3D, clip: AnimationClip, bound: number): void {
240
+ if (!ordinaryRig(source, [clip])) return;
241
+ const signature = bindingSignature(source, clip);
242
+ if (signature !== undefined) this.#binding.set(clip, { signature, bound });
243
+ }
244
+
245
+ /** The cached unit-scale stride for an equivalent, fully covered clip, or `undefined`. */
246
+ stride(source: Object3D, clip: AnimationClip): ISharedStride | undefined {
247
+ const entry = this.#stride.get(clip);
248
+ if (entry === undefined) return undefined;
249
+ if (!ordinaryRig(source, [clip])) return undefined;
250
+ const signature = strideSignature(source, clip);
251
+ return signature !== undefined && signature === entry.signature ? entry.stride : undefined;
252
+ }
253
+
254
+ rememberStride(source: Object3D, clip: AnimationClip, stride: ISharedStride): void {
255
+ if (!ordinaryRig(source, [clip])) return;
256
+ const signature = strideSignature(source, clip);
257
+ if (signature !== undefined) this.#stride.set(clip, { signature, stride });
258
+ }
259
+ }
260
+
261
+ const preparations = new WeakMap<Object3D, RigPreparation>();
262
+
263
+ /** The preparation cache owned by a source rig, created on first clone. */
264
+ export function rigPreparation(source: Object3D): RigPreparation {
265
+ let preparation = preparations.get(source);
266
+ if (preparation === undefined) {
267
+ preparation = new RigPreparation();
268
+ preparations.set(source, preparation);
269
+ }
270
+ return preparation;
271
+ }