@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.
- package/capabilities.json +1505 -79
- package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
- package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
- package/dist/{game-CljaDv4D.d.ts → game-Bj8G1wmD.d.ts} +102 -11
- package/dist/hot.d.ts +4 -4
- package/dist/index.d.ts +712 -118
- package/dist/index.js +12423 -4955
- package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
- package/dist/playtest.d.ts +6 -10
- package/dist/playtest.js +47 -24
- package/dist/react-css.d.ts +62 -0
- package/dist/react-css.js +591 -0
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
- package/dist/terrain-jobs-worker.d.ts +2 -0
- package/dist/terrain-jobs-worker.js +130 -0
- package/dist/ui-layer.js +59 -8
- package/dist/world.d.ts +766 -73
- package/dist/world.js +9307 -3543
- package/gpl/recipes/export_world.py +18 -1
- package/mcp/blender-server.mjs +7 -4
- package/mcp/blender.mjs +3 -4
- package/mcp/engine-server.mjs +2 -2
- package/mcp/servers.mjs +4 -4
- package/package.json +15 -9
- package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
- package/patches/three@0.185.1.patch +6594 -700
- package/scripts/apply-three-patch.mjs +62 -4
- package/src/animation-blend.ts +264 -0
- package/src/animation-composition.ts +362 -0
- package/src/animation-layers.ts +260 -0
- package/src/animation-root-motion.ts +283 -0
- package/src/animation.ts +896 -0
- package/src/assets.ts +1303 -0
- package/src/atmosphere/index.ts +335 -0
- package/src/atmosphere/luts.ts +298 -0
- package/src/atmosphere/params.ts +323 -0
- package/src/audio.ts +912 -0
- package/src/billboard.ts +124 -0
- package/src/bone-lengths.ts +157 -0
- package/src/camera-shake.ts +116 -0
- package/src/canvas-layer.ts +47 -0
- package/src/clip-audit.ts +401 -0
- package/src/clustered-batch.ts +492 -0
- package/src/clustered-mesh.ts +638 -0
- package/src/compute-driven.ts +176 -0
- package/src/compute-timing.ts +318 -0
- package/src/config.ts +593 -0
- package/src/debug.ts +82 -0
- package/src/engine-render-hook.ts +25 -0
- package/src/entities.ts +79 -0
- package/src/entity-snapshot.ts +53 -0
- package/src/flight.ts +683 -0
- package/src/fluid-field.ts +748 -0
- package/src/fluid-particles.ts +1253 -0
- package/src/frame-budget.ts +1368 -0
- package/src/game.ts +2390 -0
- package/src/geometry-capture.ts +1098 -0
- package/src/gpu-class.ts +160 -0
- package/src/gpu-frame-observation.ts +424 -0
- package/src/gpu-readback.ts +143 -0
- package/src/gpu-scene-bvh.ts +464 -0
- package/src/grounding.ts +100 -0
- package/src/hot.ts +161 -0
- package/src/import-meta.d.ts +13 -0
- package/src/index.ts +1536 -0
- package/src/input.ts +690 -0
- package/src/instanced-batch-lod.ts +283 -0
- package/src/instanced-batch.ts +274 -0
- package/src/interpolation.ts +129 -0
- package/src/launch-diagnostics.ts +161 -0
- package/src/loop.ts +564 -0
- package/src/matrix-world.ts +245 -0
- package/src/merge-parts.ts +812 -0
- package/src/model-lod.ts +1315 -0
- package/src/net-protocol.ts +333 -0
- package/src/net-session.ts +477 -0
- package/src/net.ts +80 -0
- package/src/ocean/fft.ts +72 -0
- package/src/ocean/spectral.ts +728 -0
- package/src/particle-significance.ts +102 -0
- package/src/particles.ts +648 -0
- package/src/path-follow.ts +175 -0
- package/src/picking.ts +250 -0
- package/src/pipeline-census.ts +1566 -0
- package/src/platform.ts +210 -0
- package/src/playtest.ts +839 -0
- package/src/pointer-events.ts +411 -0
- package/src/pose-measure.ts +435 -0
- package/src/profiling/FrameCounters.ts +231 -0
- package/src/profiling/Spans.ts +548 -0
- package/src/profiling/opacity-convention.ts +21 -0
- package/src/profiling/render-list-validate.ts +175 -0
- package/src/profiling/render-trap-audit.ts +84 -0
- package/src/profiling/scene-warning.ts +190 -0
- package/src/profiling/span-probes.ts +191 -0
- package/src/profiling/unlit-foliage-warning.ts +149 -0
- package/src/projection-apply.ts +1529 -0
- package/src/projection-marker.ts +142 -0
- package/src/projection-plan.ts +1258 -0
- package/src/projection-skinned.ts +419 -0
- package/src/projection-stability.ts +409 -0
- package/src/projection-uniform.ts +328 -0
- package/src/random.ts +41 -0
- package/src/react-css.ts +604 -0
- package/src/react-glyphs.ts +114 -0
- package/src/react-host.ts +576 -0
- package/src/react-layout.ts +265 -0
- package/src/react.ts +60 -0
- package/src/render/alpha-antialiasing.ts +159 -0
- package/src/render/batched-velocity.ts +126 -0
- package/src/render/chain.ts +1021 -0
- package/src/render/daylight.ts +189 -0
- package/src/render/depth-pyramid.ts +596 -0
- package/src/render/foliage-alpha.ts +166 -0
- package/src/render/material-key.ts +60 -0
- package/src/render/mesh-pool.ts +144 -0
- package/src/render/probe-volume.ts +1668 -0
- package/src/render/resolution-subrect.ts +253 -0
- package/src/render/velocity.ts +442 -0
- package/src/render/virtual-shadow-pages.ts +827 -0
- package/src/render/virtual-shadow-partial.ts +174 -0
- package/src/render/virtual-shadow.ts +3330 -0
- package/src/render/world-impostor-surface.ts +722 -0
- package/src/render/world-impostor.ts +558 -0
- package/src/render-camera-cull.ts +441 -0
- package/src/render-pass-budget.ts +501 -0
- package/src/renderProjection.ts +758 -0
- package/src/renderer-config.ts +127 -0
- package/src/renderer.ts +1847 -0
- package/src/replay-protocol.ts +85 -0
- package/src/replay.ts +205 -0
- package/src/resolution-scaler.ts +819 -0
- package/src/rig-preparation.ts +271 -0
- package/src/ripple-field.ts +432 -0
- package/src/scale.ts +109 -0
- package/src/scene.ts +239 -0
- package/src/schedule.ts +155 -0
- package/src/skeletal-mesh.ts +61 -0
- package/src/skeleton.ts +100 -0
- package/src/snow-field.ts +744 -0
- package/src/softbody-topology.ts +269 -0
- package/src/softbody.ts +516 -0
- package/src/sprite-animator.ts +222 -0
- package/src/startup-readiness.ts +386 -0
- package/src/state.ts +66 -0
- package/src/static-transform.ts +274 -0
- package/src/storage-buffer.ts +253 -0
- package/src/streaming.ts +308 -0
- package/src/target-fps.ts +92 -0
- package/src/terrain-jobs-worker.ts +17 -0
- package/src/terrain-jobs.ts +353 -0
- package/src/textures.ts +39 -0
- package/src/tracers.ts +237 -0
- package/src/ui-bridge.ts +368 -0
- package/src/ui-hit-regions.ts +380 -0
- package/src/ui-layer.ts +83 -0
- package/src/ui-state.ts +220 -0
- package/src/version.ts +2 -0
- package/src/viewport.ts +253 -0
- package/src/warmup.ts +1357 -0
- package/src/water-surface.ts +384 -0
- package/src/wave-field.ts +524 -0
- package/src/world-capabilities.ts +131 -0
- package/src/world-cell-proxy.ts +392 -0
- package/src/world-cells.ts +10564 -0
- package/src/world-gpu-scene.ts +3354 -0
- package/src/world-heightmap.ts +82 -0
- package/src/world-package.ts +469 -0
- package/src/world-passes.ts +582 -0
- package/src/world-region.ts +17 -0
- package/src/world-terrain-splat.ts +564 -0
- package/src/world-tiles.ts +3826 -0
- package/src/world-topology.ts +370 -0
- package/src/world-validate.ts +48 -0
- package/src/world.ts +805 -0
|
@@ -0,0 +1,362 @@
|
|
|
1
|
+
import {
|
|
2
|
+
type AnimationAction,
|
|
3
|
+
type AnimationClip,
|
|
4
|
+
LoopOnce,
|
|
5
|
+
LoopRepeat,
|
|
6
|
+
type Object3D,
|
|
7
|
+
Quaternion,
|
|
8
|
+
Vector3,
|
|
9
|
+
} from "three";
|
|
10
|
+
import { animationFinite } from "./animation-blend.js";
|
|
11
|
+
import { type IAnimationLayer, prepareAnimationLayers } from "./animation-layers.js";
|
|
12
|
+
import {
|
|
13
|
+
AnimationRootMotion,
|
|
14
|
+
type IAnimationMotionDelta,
|
|
15
|
+
type IAnimationRootMotionOptions,
|
|
16
|
+
} from "./animation-root-motion.js";
|
|
17
|
+
import { AnimationPlayer } from "./animation.js";
|
|
18
|
+
|
|
19
|
+
export interface IAnimationComposerOptions {
|
|
20
|
+
readonly root: Object3D;
|
|
21
|
+
/**
|
|
22
|
+
* Copied into owned pose snapshots at construction. Constant stock quaternion tracks use
|
|
23
|
+
* equivalent discrete sampling there; reauthor source keys before constructing a new composer.
|
|
24
|
+
*/
|
|
25
|
+
readonly clips: readonly AnimationClip[];
|
|
26
|
+
readonly samples: readonly string[];
|
|
27
|
+
readonly layers?: readonly IAnimationLayer[];
|
|
28
|
+
readonly rootMotion?: IAnimationRootMotionOptions;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
interface IComposerAction {
|
|
32
|
+
readonly action: AnimationAction;
|
|
33
|
+
readonly masked: boolean;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
interface IComposerSample {
|
|
37
|
+
readonly duration: number;
|
|
38
|
+
readonly actions: readonly IComposerAction[];
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
interface IComposerLayer {
|
|
42
|
+
readonly options: IAnimationLayer;
|
|
43
|
+
readonly action: AnimationAction;
|
|
44
|
+
weight: number;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* One bounded Three player/mixer. Game-owned intent supplies normalized sample weights;
|
|
49
|
+
* every base action samples one normalized phase, while layered events retain authored time.
|
|
50
|
+
*/
|
|
51
|
+
export class AnimationComposer {
|
|
52
|
+
readonly #player: AnimationPlayer;
|
|
53
|
+
#samples: readonly IComposerSample[];
|
|
54
|
+
#layers: readonly IComposerLayer[];
|
|
55
|
+
#weights: Float64Array;
|
|
56
|
+
#targets: Float64Array;
|
|
57
|
+
#starts: Float64Array;
|
|
58
|
+
#rootMotion: AnimationRootMotion | undefined;
|
|
59
|
+
readonly #before = new Vector3();
|
|
60
|
+
readonly #beforeRotation = new Quaternion();
|
|
61
|
+
readonly #accepted = new Vector3();
|
|
62
|
+
readonly #expectedRotation = new Quaternion();
|
|
63
|
+
readonly #observedRotation = new Quaternion();
|
|
64
|
+
readonly #up = new Vector3(0, 1, 0);
|
|
65
|
+
readonly #proposal = { translation: new Vector3(), yaw: 0 };
|
|
66
|
+
#acceptedYaw = 0;
|
|
67
|
+
#pending = false;
|
|
68
|
+
#tickDt = 0;
|
|
69
|
+
#clock = 0;
|
|
70
|
+
#speed = 1;
|
|
71
|
+
#duration = 0;
|
|
72
|
+
#elapsed = 0;
|
|
73
|
+
#disposed = false;
|
|
74
|
+
#clipBuffers = 0;
|
|
75
|
+
#clipBufferBytes = 0;
|
|
76
|
+
paused = false;
|
|
77
|
+
|
|
78
|
+
constructor(options: IAnimationComposerOptions) {
|
|
79
|
+
const sources = options.samples.map((name) => {
|
|
80
|
+
const source = options.clips.find((clip) => clip.name === name);
|
|
81
|
+
if (source === undefined) throw new Error(`AnimationComposer: missing clip '${name}'.`);
|
|
82
|
+
return source;
|
|
83
|
+
});
|
|
84
|
+
this.#rootMotion =
|
|
85
|
+
options.rootMotion === undefined
|
|
86
|
+
? undefined
|
|
87
|
+
: new AnimationRootMotion(options.root, sources, options.rootMotion);
|
|
88
|
+
const prepared = prepareAnimationLayers(
|
|
89
|
+
options.root,
|
|
90
|
+
options.clips,
|
|
91
|
+
options.samples,
|
|
92
|
+
options.layers ?? [],
|
|
93
|
+
this.#rootMotion?.node,
|
|
94
|
+
);
|
|
95
|
+
const buffers = new Set<ArrayBufferView>();
|
|
96
|
+
for (const clip of prepared.clips)
|
|
97
|
+
for (const track of clip.tracks) {
|
|
98
|
+
if (ArrayBuffer.isView(track.times)) buffers.add(track.times);
|
|
99
|
+
if (ArrayBuffer.isView(track.values)) buffers.add(track.values);
|
|
100
|
+
}
|
|
101
|
+
this.#clipBuffers = buffers.size;
|
|
102
|
+
for (const values of buffers) this.#clipBufferBytes += values.byteLength;
|
|
103
|
+
this.#player = new AnimationPlayer({
|
|
104
|
+
root: options.root,
|
|
105
|
+
clips: prepared.clips,
|
|
106
|
+
strideSync: false,
|
|
107
|
+
});
|
|
108
|
+
this.#samples = prepared.samples.map((sample) => ({
|
|
109
|
+
duration: sample.duration,
|
|
110
|
+
actions: sample.clips.map((clip) => ({
|
|
111
|
+
action: this.mixer.clipAction(clip).setEffectiveTimeScale(0).setEffectiveWeight(0).play(),
|
|
112
|
+
masked: clip.name.endsWith(":masked"),
|
|
113
|
+
})),
|
|
114
|
+
}));
|
|
115
|
+
this.#layers = prepared.layers.map((layer) => ({
|
|
116
|
+
options: layer.options,
|
|
117
|
+
action: this.mixer.clipAction(layer.clip),
|
|
118
|
+
weight: 0,
|
|
119
|
+
}));
|
|
120
|
+
this.#weights = new Float64Array(options.samples.length);
|
|
121
|
+
this.#targets = new Float64Array(options.samples.length);
|
|
122
|
+
this.#starts = new Float64Array(options.samples.length);
|
|
123
|
+
this.#weights[0] = 1;
|
|
124
|
+
this.#targets[0] = 1;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
get mixer() {
|
|
128
|
+
return this.#player.mixer;
|
|
129
|
+
}
|
|
130
|
+
get root() {
|
|
131
|
+
return this.#player.root;
|
|
132
|
+
}
|
|
133
|
+
get phase(): number {
|
|
134
|
+
return this.#clock % 1;
|
|
135
|
+
}
|
|
136
|
+
get speed(): number {
|
|
137
|
+
return this.#speed;
|
|
138
|
+
}
|
|
139
|
+
set speed(value: number) {
|
|
140
|
+
if (animationFinite(value, "speed") < 0)
|
|
141
|
+
throw new Error("AnimationComposer: speed must be nonnegative.");
|
|
142
|
+
this.#speed = value;
|
|
143
|
+
}
|
|
144
|
+
get weights(): readonly number[] {
|
|
145
|
+
return Array.from(this.#weights);
|
|
146
|
+
}
|
|
147
|
+
get sampleTimes(): readonly number[] {
|
|
148
|
+
return this.#samples.map((sample) => (sample.actions[0] as IComposerAction).action.time);
|
|
149
|
+
}
|
|
150
|
+
get resources() {
|
|
151
|
+
return {
|
|
152
|
+
actions: this.mixer.stats.actions.total,
|
|
153
|
+
bindings: this.mixer.stats.bindings.total,
|
|
154
|
+
scratchBytes: this.#weights.byteLength + this.#targets.byteLength + this.#starts.byteLength,
|
|
155
|
+
clipBuffers: this.#clipBuffers,
|
|
156
|
+
clipBufferBytes: this.#clipBufferBytes,
|
|
157
|
+
rootBuffers: this.#rootMotion?.buffers ?? 0,
|
|
158
|
+
rootBufferBytes: this.#rootMotion?.bufferBytes ?? 0,
|
|
159
|
+
};
|
|
160
|
+
}
|
|
161
|
+
/** Snapshots remain honest while blocked: phase advances at authored speed, never re-timed by the wall. */
|
|
162
|
+
get motion() {
|
|
163
|
+
return {
|
|
164
|
+
authority: this.#rootMotion === undefined ? "phase" : "rootMotion",
|
|
165
|
+
requested: this.#proposal.translation.clone(),
|
|
166
|
+
requestedYaw: this.#proposal.yaw,
|
|
167
|
+
accepted: this.#accepted.clone(),
|
|
168
|
+
acceptedYaw: this.#acceptedYaw,
|
|
169
|
+
blocked: this.blocked,
|
|
170
|
+
} as const;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
get blocked(): boolean {
|
|
174
|
+
return (
|
|
175
|
+
this.#proposal.translation.distanceToSquared(this.#accepted) > 1e-10 ||
|
|
176
|
+
Math.abs(this.#proposal.yaw - this.#acceptedYaw) > 1e-5
|
|
177
|
+
);
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
setWeights(weights: ArrayLike<number>, transition = 0): void {
|
|
181
|
+
this.#live();
|
|
182
|
+
if (weights.length !== this.#weights.length)
|
|
183
|
+
throw new Error("AnimationComposer: weight count differs from samples.");
|
|
184
|
+
if (animationFinite(transition, "transition") < 0)
|
|
185
|
+
throw new Error("AnimationComposer: transition must be nonnegative.");
|
|
186
|
+
let sum = 0;
|
|
187
|
+
for (let i = 0; i < weights.length; i += 1) {
|
|
188
|
+
const weight = animationFinite(weights[i] as number, `weight[${i}]`);
|
|
189
|
+
if (weight < 0) throw new Error("AnimationComposer: weights must be nonnegative.");
|
|
190
|
+
sum += weight;
|
|
191
|
+
}
|
|
192
|
+
if (!(sum > 0) || !Number.isFinite(sum))
|
|
193
|
+
throw new Error("AnimationComposer: weights must have a finite positive sum.");
|
|
194
|
+
let same = transition === this.#duration;
|
|
195
|
+
for (let i = 0; i < weights.length; i += 1)
|
|
196
|
+
if (this.#targets[i] !== (weights[i] as number) / sum) same = false;
|
|
197
|
+
if (same) return;
|
|
198
|
+
this.#starts.set(this.#weights);
|
|
199
|
+
for (let i = 0; i < weights.length; i += 1) this.#targets[i] = (weights[i] as number) / sum;
|
|
200
|
+
this.#duration = transition;
|
|
201
|
+
this.#elapsed = 0;
|
|
202
|
+
if (transition === 0) this.#weights.set(this.#targets);
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
setLayerWeight(name: string, weight: number): void {
|
|
206
|
+
this.#live();
|
|
207
|
+
if (animationFinite(weight, `'${name}' weight`) < 0 || weight > 1)
|
|
208
|
+
throw new Error(`AnimationComposer: '${name}' weight must be in [0,1].`);
|
|
209
|
+
const layer = this.#layers.find((layer) => layer.options.name === name);
|
|
210
|
+
if (layer === undefined) throw new Error(`AnimationComposer: unknown layer '${name}'.`);
|
|
211
|
+
if (weight > 0 && layer.weight === 0) {
|
|
212
|
+
layer.action
|
|
213
|
+
.reset()
|
|
214
|
+
.setLoop(
|
|
215
|
+
layer.options.once === true ? LoopOnce : LoopRepeat,
|
|
216
|
+
layer.options.once === true ? 1 : Number.POSITIVE_INFINITY,
|
|
217
|
+
)
|
|
218
|
+
.play();
|
|
219
|
+
layer.action.clampWhenFinished = layer.options.once === true;
|
|
220
|
+
}
|
|
221
|
+
layer.weight = weight;
|
|
222
|
+
layer.action.setEffectiveWeight(weight);
|
|
223
|
+
if (weight === 0) layer.action.stop();
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/** Explicit replay; repeated weight requests do not re-fire a completed one-shot. */
|
|
227
|
+
restartLayer(name: string): void {
|
|
228
|
+
this.#live();
|
|
229
|
+
const layer = this.#layers.find((layer) => layer.options.name === name);
|
|
230
|
+
if (layer === undefined) throw new Error(`AnimationComposer: unknown layer '${name}'.`);
|
|
231
|
+
layer.action.reset().setEffectiveWeight(layer.weight);
|
|
232
|
+
if (layer.weight > 0) layer.action.play();
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
update(dt: number): void {
|
|
236
|
+
if (this.#rootMotion !== undefined)
|
|
237
|
+
throw new Error(
|
|
238
|
+
"AnimationComposer: root motion requires advance, Rapier movement, then finish with accepted motion.",
|
|
239
|
+
);
|
|
240
|
+
this.advance(dt);
|
|
241
|
+
this.finish();
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
/** Borrowed proposal: queue it once with CharacterBody3D.move, then finish after physics. */
|
|
245
|
+
advance(dt: number): { readonly translation: Vector3; readonly yaw: number } {
|
|
246
|
+
this.#live();
|
|
247
|
+
if (this.#pending)
|
|
248
|
+
throw new Error("AnimationComposer: finish the previous fixed tick before advance.");
|
|
249
|
+
if (animationFinite(dt, "dt") < 0)
|
|
250
|
+
throw new Error("AnimationComposer: dt must be nonnegative.");
|
|
251
|
+
this.#rootMotion?.validateSpace();
|
|
252
|
+
if (this.#rootMotion !== undefined) {
|
|
253
|
+
const position = this.#rootMotion.body.position;
|
|
254
|
+
this.#before.set(
|
|
255
|
+
animationFinite(position.x, "body.x"),
|
|
256
|
+
animationFinite(position.y, "body.y"),
|
|
257
|
+
animationFinite(position.z, "body.z"),
|
|
258
|
+
);
|
|
259
|
+
}
|
|
260
|
+
const elapsed = this.paused ? 0 : dt;
|
|
261
|
+
this.#elapsed = Math.min(this.#duration, this.#elapsed + elapsed);
|
|
262
|
+
const progress = this.#duration > 0 ? this.#elapsed / this.#duration : 1;
|
|
263
|
+
let frequency = 0;
|
|
264
|
+
for (let i = 0; i < this.#samples.length; i += 1) {
|
|
265
|
+
this.#weights[i] =
|
|
266
|
+
(this.#starts[i] as number) +
|
|
267
|
+
((this.#targets[i] as number) - (this.#starts[i] as number)) * progress;
|
|
268
|
+
frequency += (this.#weights[i] as number) / (this.#samples[i] as IComposerSample).duration;
|
|
269
|
+
}
|
|
270
|
+
const previous = this.#clock;
|
|
271
|
+
this.#clock = animationFinite(this.#clock + elapsed * this.#speed * frequency, "phase clock");
|
|
272
|
+
const rounded = Math.round(this.#clock);
|
|
273
|
+
if (Math.abs(this.#clock - rounded) < 1e-12) this.#clock = rounded;
|
|
274
|
+
this.#proposal.translation.set(0, 0, 0);
|
|
275
|
+
this.#proposal.yaw = 0;
|
|
276
|
+
if (this.#rootMotion !== undefined) {
|
|
277
|
+
this.#beforeRotation.copy(this.#rootMotion.body.quaternion);
|
|
278
|
+
const proposal = this.#rootMotion.sample(previous, this.#clock, this.#weights);
|
|
279
|
+
this.#proposal.translation.copy(proposal.translation);
|
|
280
|
+
this.#proposal.yaw = proposal.yaw;
|
|
281
|
+
}
|
|
282
|
+
this.#pending = true;
|
|
283
|
+
this.#tickDt = elapsed;
|
|
284
|
+
return this.#proposal;
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
/** Final authored pose precedes the game's existing IK. This method never writes the body. */
|
|
288
|
+
finish(accepted?: IAnimationMotionDelta): void {
|
|
289
|
+
this.#live();
|
|
290
|
+
if (!this.#pending) throw new Error("AnimationComposer: advance must precede finish.");
|
|
291
|
+
if (this.#rootMotion !== undefined) {
|
|
292
|
+
if (accepted === undefined)
|
|
293
|
+
throw new Error("AnimationComposer: finish requires accepted Rapier motion.");
|
|
294
|
+
const body = this.#rootMotion.body;
|
|
295
|
+
this.#accepted.set(
|
|
296
|
+
animationFinite(accepted.translation.x, "accepted.x"),
|
|
297
|
+
animationFinite(accepted.translation.y, "accepted.y"),
|
|
298
|
+
animationFinite(accepted.translation.z, "accepted.z"),
|
|
299
|
+
);
|
|
300
|
+
this.#expectedRotation
|
|
301
|
+
.setFromAxisAngle(this.#up, animationFinite(accepted.yaw, "accepted.yaw"))
|
|
302
|
+
.premultiply(this.#beforeRotation)
|
|
303
|
+
.normalize();
|
|
304
|
+
const norm = body.quaternion.lengthSq();
|
|
305
|
+
if (!Number.isFinite(norm) || Math.abs(norm - 1) > 1e-5)
|
|
306
|
+
throw new Error(
|
|
307
|
+
"AnimationComposer: observed character body quaternion must be normalized.",
|
|
308
|
+
);
|
|
309
|
+
// Float32 physics round-off is a scale of a quaternion, not a different rotation.
|
|
310
|
+
this.#observedRotation.copy(body.quaternion).normalize();
|
|
311
|
+
if (
|
|
312
|
+
Math.abs(
|
|
313
|
+
animationFinite(body.position.x, "observed body.x") - this.#before.x - this.#accepted.x,
|
|
314
|
+
) > 1e-5 ||
|
|
315
|
+
Math.abs(
|
|
316
|
+
animationFinite(body.position.y, "observed body.y") - this.#before.y - this.#accepted.y,
|
|
317
|
+
) > 1e-5 ||
|
|
318
|
+
Math.abs(
|
|
319
|
+
animationFinite(body.position.z, "observed body.z") - this.#before.z - this.#accepted.z,
|
|
320
|
+
) > 1e-5 ||
|
|
321
|
+
this.#expectedRotation.angleTo(this.#observedRotation) > 1e-5
|
|
322
|
+
)
|
|
323
|
+
throw new Error(
|
|
324
|
+
"AnimationComposer: accepted motion differs from the observed character body.",
|
|
325
|
+
);
|
|
326
|
+
this.#acceptedYaw = accepted.yaw;
|
|
327
|
+
} else {
|
|
328
|
+
this.#accepted.set(0, 0, 0);
|
|
329
|
+
this.#acceptedYaw = 0;
|
|
330
|
+
}
|
|
331
|
+
const overrideWeight =
|
|
332
|
+
this.#layers.find((layer) => layer.options.mode === "override")?.weight ?? 0;
|
|
333
|
+
for (let i = 0; i < this.#samples.length; i += 1) {
|
|
334
|
+
const sample = this.#samples[i] as IComposerSample;
|
|
335
|
+
for (const { action, masked } of sample.actions) {
|
|
336
|
+
action.time = this.phase * sample.duration;
|
|
337
|
+
action.setEffectiveWeight((this.#weights[i] as number) * (masked ? 1 - overrideWeight : 1));
|
|
338
|
+
}
|
|
339
|
+
}
|
|
340
|
+
this.mixer.update(this.#tickDt);
|
|
341
|
+
this.#pending = false;
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
dispose(): void {
|
|
345
|
+
if (this.#disposed) return;
|
|
346
|
+
this.#disposed = true;
|
|
347
|
+
this.#player.dispose();
|
|
348
|
+
this.#rootMotion?.dispose();
|
|
349
|
+
this.#rootMotion = undefined;
|
|
350
|
+
this.#samples = [];
|
|
351
|
+
this.#layers = [];
|
|
352
|
+
this.#weights = new Float64Array(0);
|
|
353
|
+
this.#targets = new Float64Array(0);
|
|
354
|
+
this.#starts = new Float64Array(0);
|
|
355
|
+
this.#clipBuffers = 0;
|
|
356
|
+
this.#clipBufferBytes = 0;
|
|
357
|
+
}
|
|
358
|
+
|
|
359
|
+
#live(): void {
|
|
360
|
+
if (this.#disposed) throw new Error("AnimationComposer cannot be used after dispose.");
|
|
361
|
+
}
|
|
362
|
+
}
|
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
import {
|
|
2
|
+
AnimationClip,
|
|
3
|
+
AnimationUtils,
|
|
4
|
+
type Bone,
|
|
5
|
+
InterpolateDiscrete,
|
|
6
|
+
InterpolateLinear,
|
|
7
|
+
type KeyframeTrack,
|
|
8
|
+
NormalAnimationBlendMode,
|
|
9
|
+
type Object3D,
|
|
10
|
+
PropertyBinding,
|
|
11
|
+
QuaternionKeyframeTrack,
|
|
12
|
+
} from "three";
|
|
13
|
+
import { animationFinite } from "./animation-blend.js";
|
|
14
|
+
|
|
15
|
+
export interface IAnimationMask {
|
|
16
|
+
readonly bones: readonly string[];
|
|
17
|
+
readonly descendants?: boolean;
|
|
18
|
+
/** Explicit root ownership; refused when root motion owns that same track. */
|
|
19
|
+
readonly includeRoot?: boolean;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export interface IAnimationLayer {
|
|
23
|
+
readonly name: string;
|
|
24
|
+
readonly clip: string;
|
|
25
|
+
readonly mask: IAnimationMask;
|
|
26
|
+
readonly mode: "override" | "additive";
|
|
27
|
+
readonly once?: boolean;
|
|
28
|
+
readonly reference?: { readonly clip: AnimationClip; readonly time: number };
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export interface IPreparedAnimation {
|
|
32
|
+
readonly samples: readonly {
|
|
33
|
+
readonly duration: number;
|
|
34
|
+
readonly clips: readonly AnimationClip[];
|
|
35
|
+
}[];
|
|
36
|
+
readonly layers: readonly { readonly options: IAnimationLayer; readonly clip: AnimationClip }[];
|
|
37
|
+
readonly clips: readonly AnimationClip[];
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
interface IBindingTarget extends PropertyBinding {
|
|
41
|
+
readonly targetObject?: Object3D;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** Canonical UUID paths keep aliases for one property from becoming competing Three bindings. */
|
|
45
|
+
export function canonicalAnimationClip(root: Object3D, source: AnimationClip): AnimationClip {
|
|
46
|
+
if (source.blendMode !== NormalAnimationBlendMode)
|
|
47
|
+
throw new Error(
|
|
48
|
+
`AnimationComposer: '${source.name}' must be a normal clip; additive layers need an explicit reference.`,
|
|
49
|
+
);
|
|
50
|
+
if (source.tracks.length === 0)
|
|
51
|
+
throw new Error(`AnimationComposer: '${source.name}' has no tracks.`);
|
|
52
|
+
if (!(animationFinite(source.duration, `'${source.name}' duration`) > 0))
|
|
53
|
+
throw new Error(`AnimationComposer: '${source.name}' requires positive duration.`);
|
|
54
|
+
const seen = new Set<string>();
|
|
55
|
+
const tracks = source.tracks.map((track) => {
|
|
56
|
+
const parsed = PropertyBinding.parseTrackName(track.name);
|
|
57
|
+
if (
|
|
58
|
+
!["position", "quaternion", "scale"].includes(parsed.propertyName) ||
|
|
59
|
+
parsed.propertyIndex !== undefined
|
|
60
|
+
)
|
|
61
|
+
throw new Error(
|
|
62
|
+
`AnimationComposer: incompatible track '${track.name}'; use bone transforms, exclude face controls.`,
|
|
63
|
+
);
|
|
64
|
+
const binding = new PropertyBinding(root, track.name) as IBindingTarget;
|
|
65
|
+
binding.bind();
|
|
66
|
+
const node = binding.targetObject;
|
|
67
|
+
if (node?.isObject3D !== true)
|
|
68
|
+
throw new Error(`AnimationComposer: '${track.name}' does not bind a rig node.`);
|
|
69
|
+
const expected = parsed.propertyName === "quaternion" ? 4 : 3;
|
|
70
|
+
if (track.ValueTypeName !== (expected === 4 ? "quaternion" : "vector"))
|
|
71
|
+
throw new Error(`AnimationComposer: incompatible track type for '${track.name}'.`);
|
|
72
|
+
if (
|
|
73
|
+
track.getValueSize() !== expected ||
|
|
74
|
+
track.times.length === 0 ||
|
|
75
|
+
track.values.length !== track.times.length * expected
|
|
76
|
+
)
|
|
77
|
+
throw new Error(`AnimationComposer: incompatible values for '${track.name}'.`);
|
|
78
|
+
let last = Number.NEGATIVE_INFINITY;
|
|
79
|
+
for (const time of track.times) {
|
|
80
|
+
if (
|
|
81
|
+
animationFinite(time, `'${track.name}' key time`) <= last ||
|
|
82
|
+
time < 0 ||
|
|
83
|
+
time > source.duration
|
|
84
|
+
)
|
|
85
|
+
throw new Error(
|
|
86
|
+
`AnimationComposer: '${track.name}' key times must increase within the duration.`,
|
|
87
|
+
);
|
|
88
|
+
last = time;
|
|
89
|
+
}
|
|
90
|
+
for (const value of track.values) animationFinite(value, `'${track.name}' value`);
|
|
91
|
+
if (expected === 4) {
|
|
92
|
+
for (let i = 0; i < track.values.length; i += 4) {
|
|
93
|
+
const norm = Math.hypot(
|
|
94
|
+
track.values[i] as number,
|
|
95
|
+
track.values[i + 1] as number,
|
|
96
|
+
track.values[i + 2] as number,
|
|
97
|
+
track.values[i + 3] as number,
|
|
98
|
+
);
|
|
99
|
+
if (Math.abs(norm - 1) > 1e-5)
|
|
100
|
+
throw new Error(`AnimationComposer: '${track.name}' quaternion must be normalized.`);
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
const canonical = `${node.uuid}.${parsed.propertyName}`;
|
|
104
|
+
if (seen.has(canonical)) throw new Error(`AnimationComposer: duplicate track '${track.name}'.`);
|
|
105
|
+
seen.add(canonical);
|
|
106
|
+
const copy = track.clone();
|
|
107
|
+
copy.name = canonical;
|
|
108
|
+
return copy;
|
|
109
|
+
});
|
|
110
|
+
return new AnimationClip(source.name, source.duration, tracks);
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
function resolveMask(root: Object3D, mask: IAnimationMask, name: string): Set<string> {
|
|
114
|
+
if (mask.bones.length === 0) throw new Error(`AnimationComposer: '${name}' mask needs bones.`);
|
|
115
|
+
const bones = new Map<string, Bone[]>();
|
|
116
|
+
root.traverse((node) => {
|
|
117
|
+
if ((node as Bone).isBone !== true) return;
|
|
118
|
+
const entries = bones.get(node.name) ?? [];
|
|
119
|
+
entries.push(node as Bone);
|
|
120
|
+
bones.set(node.name, entries);
|
|
121
|
+
});
|
|
122
|
+
const selected = new Set<string>();
|
|
123
|
+
const add = (node: Object3D) => {
|
|
124
|
+
if ((node as Bone).isBone !== true) return;
|
|
125
|
+
if ((node.parent as Bone | null)?.isBone !== true && mask.includeRoot !== true)
|
|
126
|
+
throw new Error(
|
|
127
|
+
`AnimationComposer: '${name}' mask selects root '${node.name}'; select includeRoot explicitly.`,
|
|
128
|
+
);
|
|
129
|
+
selected.add(node.uuid);
|
|
130
|
+
};
|
|
131
|
+
for (const name of mask.bones) {
|
|
132
|
+
const entries = bones.get(name);
|
|
133
|
+
if (entries?.length !== 1)
|
|
134
|
+
throw new Error(
|
|
135
|
+
`AnimationComposer: mask bone '${name}' is missing or ambiguous on this cloned rig.`,
|
|
136
|
+
);
|
|
137
|
+
const bone = entries[0] as Bone;
|
|
138
|
+
if (mask.descendants === true) bone.traverse(add);
|
|
139
|
+
else add(bone);
|
|
140
|
+
}
|
|
141
|
+
return selected;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
function maskedClip(clip: AnimationClip, mask: ReadonlySet<string>, name: string): AnimationClip {
|
|
145
|
+
const tracks = clip.tracks.filter((track) =>
|
|
146
|
+
mask.has(track.name.slice(0, track.name.lastIndexOf("."))),
|
|
147
|
+
);
|
|
148
|
+
if (tracks.length === 0)
|
|
149
|
+
throw new Error(`AnimationComposer: '${name}' mask matches no clip tracks.`);
|
|
150
|
+
return new AnimationClip(name, clip.duration, tracks);
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/** VQ-05's one layer preparation owner; no source clip, pose or mixer mutation. */
|
|
154
|
+
export function prepareAnimationLayers(
|
|
155
|
+
root: Object3D,
|
|
156
|
+
sources: readonly AnimationClip[],
|
|
157
|
+
samples: readonly string[],
|
|
158
|
+
layers: readonly IAnimationLayer[],
|
|
159
|
+
consumedRoot?: Object3D,
|
|
160
|
+
): IPreparedAnimation {
|
|
161
|
+
const clips = new Map<string, AnimationClip>();
|
|
162
|
+
for (const source of sources) {
|
|
163
|
+
if (clips.has(source.name))
|
|
164
|
+
throw new Error(`AnimationComposer: duplicate clip '${source.name}'.`);
|
|
165
|
+
clips.set(source.name, source);
|
|
166
|
+
}
|
|
167
|
+
const get = (name: string) => {
|
|
168
|
+
const clip = clips.get(name);
|
|
169
|
+
if (clip === undefined) throw new Error(`AnimationComposer: missing clip '${name}'.`);
|
|
170
|
+
return canonicalAnimationClip(root, clip);
|
|
171
|
+
};
|
|
172
|
+
if (samples.length === 0 || new Set(samples).size !== samples.length)
|
|
173
|
+
throw new Error("AnimationComposer: samples must be nonempty and unique.");
|
|
174
|
+
if (
|
|
175
|
+
layers.filter((layer) => layer.mode === "override").length > 1 ||
|
|
176
|
+
layers.filter((layer) => layer.mode === "additive").length > 2
|
|
177
|
+
)
|
|
178
|
+
throw new Error("AnimationComposer: capacity is one override and two additive layers.");
|
|
179
|
+
const names = new Set<string>();
|
|
180
|
+
const preparedLayers = layers.map((options) => {
|
|
181
|
+
if (!["override", "additive"].includes(options.mode))
|
|
182
|
+
throw new Error(`AnimationComposer: '${options.name}' has invalid mode.`);
|
|
183
|
+
if (options.name.length === 0 || names.has(options.name))
|
|
184
|
+
throw new Error("AnimationComposer: layer names must be nonempty and unique.");
|
|
185
|
+
names.add(options.name);
|
|
186
|
+
const mask = resolveMask(root, options.mask, options.name);
|
|
187
|
+
if (consumedRoot !== undefined && mask.has(consumedRoot.uuid))
|
|
188
|
+
throw new Error("AnimationComposer: root-motion and layer root ownership conflict.");
|
|
189
|
+
const clip = maskedClip(get(options.clip), mask, `layer:${options.name}`);
|
|
190
|
+
if (options.mode === "additive") {
|
|
191
|
+
if (options.reference === undefined)
|
|
192
|
+
throw new Error(
|
|
193
|
+
`AnimationComposer: additive '${options.name}' requires an explicit reference pose.`,
|
|
194
|
+
);
|
|
195
|
+
const time = animationFinite(options.reference.time, `'${options.name}' reference time`);
|
|
196
|
+
const reference = canonicalAnimationClip(root, options.reference.clip);
|
|
197
|
+
if (time < 0 || time > reference.duration)
|
|
198
|
+
throw new Error(`AnimationComposer: '${options.name}' reference time is outside its clip.`);
|
|
199
|
+
for (const track of clip.tracks) {
|
|
200
|
+
const ref = reference.tracks.find((candidate) => candidate.name === track.name);
|
|
201
|
+
if (
|
|
202
|
+
ref === undefined ||
|
|
203
|
+
ref.ValueTypeName !== track.ValueTypeName ||
|
|
204
|
+
ref.getValueSize() !== track.getValueSize()
|
|
205
|
+
)
|
|
206
|
+
throw new Error(`AnimationComposer: reference pose lacks compatible '${track.name}'.`);
|
|
207
|
+
}
|
|
208
|
+
AnimationUtils.makeClipAdditive(clip, time * 30, reference, 30);
|
|
209
|
+
}
|
|
210
|
+
return { options, clip };
|
|
211
|
+
});
|
|
212
|
+
const override = preparedLayers.find((layer) => layer.options.mode === "override");
|
|
213
|
+
const overridden = new Set(override?.clip.tracks.map((track) => track.name));
|
|
214
|
+
const preparedSamples = samples.map((name) => {
|
|
215
|
+
const clip = get(name);
|
|
216
|
+
if (consumedRoot !== undefined) {
|
|
217
|
+
for (const track of clip.tracks) {
|
|
218
|
+
if (!track.name.startsWith(`${consumedRoot.uuid}.`)) continue;
|
|
219
|
+
const property = track.name.slice(track.name.lastIndexOf(".") + 1);
|
|
220
|
+
if (property !== "position" && property !== "quaternion") continue;
|
|
221
|
+
const reference =
|
|
222
|
+
property === "position"
|
|
223
|
+
? consumedRoot.position.toArray()
|
|
224
|
+
: consumedRoot.quaternion.toArray();
|
|
225
|
+
for (let offset = 0; offset < track.values.length; offset += reference.length)
|
|
226
|
+
track.values.set(reference, offset);
|
|
227
|
+
}
|
|
228
|
+
}
|
|
229
|
+
const groups: AnimationClip[] = [];
|
|
230
|
+
for (const masked of [false, true]) {
|
|
231
|
+
const tracks: KeyframeTrack[] = clip.tracks.filter(
|
|
232
|
+
(track) => overridden.has(track.name) === masked,
|
|
233
|
+
);
|
|
234
|
+
if (tracks.length > 0)
|
|
235
|
+
groups.push(
|
|
236
|
+
new AnimationClip(`sample:${name}:${masked ? "masked" : "base"}`, clip.duration, tracks),
|
|
237
|
+
);
|
|
238
|
+
}
|
|
239
|
+
return { duration: clip.duration, clips: groups };
|
|
240
|
+
});
|
|
241
|
+
const all = [
|
|
242
|
+
...preparedSamples.flatMap((sample) => sample.clips),
|
|
243
|
+
...preparedLayers.map((layer) => layer.clip),
|
|
244
|
+
];
|
|
245
|
+
if (all.length > 8)
|
|
246
|
+
throw new Error(
|
|
247
|
+
`AnimationComposer: requires ${all.length} actions; capacity is eight. Reduce samples or layers.`,
|
|
248
|
+
);
|
|
249
|
+
// Pose snapshots only: root-motion validation keeps its authored linear interpolants.
|
|
250
|
+
// Constant stock quaternion keys need no SLERP; retain every key, track and owned buffer.
|
|
251
|
+
for (const clip of all)
|
|
252
|
+
for (const track of clip.tracks)
|
|
253
|
+
if (
|
|
254
|
+
Object.getPrototypeOf(track) === QuaternionKeyframeTrack.prototype &&
|
|
255
|
+
track.getInterpolation() === InterpolateLinear &&
|
|
256
|
+
track.values.every((value, index) => value === track.values[index % 4])
|
|
257
|
+
)
|
|
258
|
+
track.setInterpolation(InterpolateDiscrete);
|
|
259
|
+
return { samples: preparedSamples, layers: preparedLayers, clips: all };
|
|
260
|
+
}
|