@viggle/splat-engine-three 0.1.1 → 0.3.0
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/CHANGELOG.md +58 -0
- package/README.md +158 -20
- package/dist/chunks/chunk-2GKWT24B.js +23182 -0
- package/dist/chunks/chunk-2GKWT24B.js.map +7 -0
- package/dist/index.js +235 -3
- package/dist/types/anim/animation-conversion.d.ts +2 -2
- package/dist/types/anim/keyframe-splines.d.ts +17 -41
- package/dist/types/animation.d.ts +84 -28
- package/dist/types/armature.d.ts +280 -2
- package/dist/types/character.d.ts +120 -2
- package/dist/types/effects/index.d.ts +12 -0
- package/dist/types/effects/outlines/outline-effect.d.ts +98 -0
- package/dist/types/effects/outlines/outline-shaders.d.ts +14 -0
- package/dist/types/effects/pixelart/pixelart-effect.d.ts +152 -0
- package/dist/types/effects/pixelart/pixelart-shaders.d.ts +31 -0
- package/dist/types/effects/postfx/base-capturing-pass.d.ts +109 -0
- package/dist/types/effects/postfx/camera-frame.d.ts +103 -0
- package/dist/types/effects/postfx/frame-renderer.d.ts +32 -0
- package/dist/types/effects/postfx/frame-shaders.d.ts +19 -0
- package/dist/types/effects/postfx/mask.d.ts +44 -0
- package/dist/types/effects/postfx/postfx.d.ts +144 -0
- package/dist/types/effects/postfx/program.d.ts +74 -0
- package/dist/types/effects/postfx/uniforms.d.ts +24 -0
- package/dist/types/effects/postfx/webgl-program.d.ts +6 -0
- package/dist/types/effects/postfx/webgpu-program.d.ts +3 -0
- package/dist/types/effects/vfx/data-types.d.ts +100 -0
- package/dist/types/effects/vfx/index.d.ts +37 -0
- package/dist/types/effects/vfx/json-vfx-prefab.d.ts +94 -0
- package/dist/types/effects/vfx/layer-renderer.d.ts +118 -0
- package/dist/types/effects/vfx/layers/mesh.d.ts +124 -0
- package/dist/types/effects/vfx/layers/particle.d.ts +90 -0
- package/dist/types/effects/vfx/layers/shader.d.ts +130 -0
- package/dist/types/effects/vfx/layers/shared.d.ts +40 -0
- package/dist/types/effects/vfx/layers/sprite.d.ts +45 -0
- package/dist/types/effects/vfx/pool.d.ts +51 -0
- package/dist/types/effects/vfx/prefab.d.ts +48 -0
- package/dist/types/effects/vfx/prewarm.d.ts +17 -0
- package/dist/types/effects/vfx/stage.d.ts +115 -0
- package/dist/types/effects/vfx/webgpu-register.d.ts +2 -0
- package/dist/types/effects/webgpu-register.d.ts +2 -0
- package/dist/types/engine.d.ts +18 -0
- package/dist/types/environment.d.ts +96 -8
- package/dist/types/index.d.ts +35 -6
- package/dist/types/loader/animation/animation-glb.d.ts +4 -4
- package/dist/types/loader/character/load.d.ts +6 -1
- package/dist/types/loader/environment/lod-bundle.d.ts +123 -0
- package/dist/types/loader/environment/spz-decode.d.ts +88 -0
- package/dist/types/loader/environment/spz.d.ts +28 -0
- package/dist/types/loader/shared/asset-fetch.d.ts +11 -0
- package/dist/types/loader/shared/asset-loader.d.ts +86 -0
- package/dist/types/loader/shared/bin-cache.d.ts +41 -14
- package/dist/types/loader/shared/decode-worker.d.ts +27 -0
- package/dist/types/loader/shared/glb.d.ts +30 -0
- package/dist/types/loader/shared/inflate.d.ts +9 -0
- package/dist/types/loader/shared/pack-splats-task.d.ts +17 -0
- package/dist/types/loader/shared/sog-decode.d.ts +81 -0
- package/dist/types/loader/shared/sog.d.ts +17 -0
- package/dist/types/math.d.ts +198 -13
- package/dist/types/physics/ammo.d.ts +217 -0
- package/dist/types/physics/index.d.ts +11 -0
- package/dist/types/physics/joints.d.ts +206 -0
- package/dist/types/physics/physics-world.d.ts +194 -0
- package/dist/types/physics/rigid-body.d.ts +361 -0
- package/dist/types/presets/camera/camera-preset.d.ts +43 -0
- package/dist/types/presets/camera/third-person-camera.d.ts +63 -0
- package/dist/types/presets/character/body-shape.d.ts +109 -0
- package/dist/types/presets/character/character-reveal.d.ts +90 -0
- package/dist/types/presets/character/socket-loadout.d.ts +61 -0
- package/dist/types/presets/index.d.ts +13 -0
- package/dist/types/presets/vfx/mesh-flash.d.ts +51 -0
- package/dist/types/presets/visual/bone-overlay.d.ts +57 -0
- package/dist/types/proxy/environment-input.d.ts +30 -0
- package/dist/types/proxy/environment-source.d.ts +39 -0
- package/dist/types/proxy/proxy-debug.d.ts +106 -0
- package/dist/types/proxy/splat-source.d.ts +42 -0
- package/dist/types/proxy/voxelizer.d.ts +383 -0
- package/dist/types/relight/backend.d.ts +101 -0
- package/dist/types/relight/index.d.ts +6 -0
- package/dist/types/relight/relight-pass.d.ts +367 -0
- package/dist/types/relight/relight-placeholder.d.ts +2 -0
- package/dist/types/relight/relight-shaders.d.ts +4 -0
- package/dist/types/relight/shadow-bias.d.ts +26 -0
- package/dist/types/relight/splat-relight.d.ts +760 -0
- package/dist/types/relight/webgl-backend.d.ts +3 -0
- package/dist/types/relight/webgpu/backend.d.ts +3 -0
- package/dist/types/relight/webgpu-register.d.ts +2 -0
- package/dist/types/scene.d.ts +291 -0
- package/dist/types/skeletal/animation-player.d.ts +31 -3
- package/dist/types/skeletal/body-parts.d.ts +55 -0
- package/dist/types/skeletal/ragdoll-config.d.ts +115 -0
- package/dist/types/skeletal/ragdoll.d.ts +283 -0
- package/dist/types/skeletal/skeleton.d.ts +9 -2
- package/dist/types/splat/backend.d.ts +2 -0
- package/dist/types/splat/color-modifier.d.ts +78 -0
- package/dist/types/splat/cut-groups.d.ts +27 -0
- package/dist/types/splat/relight-binding.d.ts +39 -0
- package/dist/types/splat/reveal-bake.d.ts +43 -0
- package/dist/types/splat/reveal-look.d.ts +64 -0
- package/dist/types/splat/splat-mesh.d.ts +1 -0
- package/dist/types/splat/splat.d.ts +154 -0
- package/dist/types/splat/webgl/shaders.d.ts +5 -1
- package/dist/types/splat/webgl/splat-mesh.d.ts +4 -0
- package/dist/types/splat/webgpu/radix-sort.d.ts +3 -0
- package/dist/types/splat/webgpu/splat-mesh.d.ts +23 -0
- package/dist/types/three/splat-character.d.ts +28 -0
- package/dist/types/three/spz-loader.d.ts +35 -0
- package/dist/types/types.d.ts +6 -0
- package/dist/webgpu.js +1137 -154
- package/dist/webgpu.js.map +4 -4
- package/package.json +6 -2
- package/dist/chunks/chunk-WN5WBKM4.js +0 -8606
- package/dist/chunks/chunk-WN5WBKM4.js.map +0 -7
package/dist/types/armature.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { Group } from 'three';
|
|
2
|
+
import type { Object3D } from 'three';
|
|
2
3
|
import { Mat4, Quat, Vec3 } from './math';
|
|
3
4
|
import type { SplatEngine } from './engine';
|
|
4
5
|
import type { AnimEventCallback } from './skeletal/animation-player';
|
|
@@ -83,6 +84,44 @@ export interface PoseProvider {
|
|
|
83
84
|
* @group Characters & Animation
|
|
84
85
|
*/
|
|
85
86
|
export type RootMotionMode = 'off' | 'apply' | 'extract';
|
|
87
|
+
/**
|
|
88
|
+
* Supplies a corrective pivot translation for one frame. Installed via
|
|
89
|
+
* {@link Armature.rootOffsetProvider} and called once per {@link Armature.update}
|
|
90
|
+
* with the current animation frame time, after the pose is evaluated and before
|
|
91
|
+
* bone transforms are composed - so the offset lands in the same frame's bone
|
|
92
|
+
* matrices with no lag.
|
|
93
|
+
*
|
|
94
|
+
* Return `null` for "no offset this frame". The returned vector is read
|
|
95
|
+
* immediately and not retained, so returning a reused scratch object is fine.
|
|
96
|
+
*
|
|
97
|
+
* @group Characters & Animation
|
|
98
|
+
*/
|
|
99
|
+
export type RootOffsetProvider = (frameTime: number) => {
|
|
100
|
+
x: number;
|
|
101
|
+
y: number;
|
|
102
|
+
z: number;
|
|
103
|
+
} | null;
|
|
104
|
+
/**
|
|
105
|
+
* Refines the freshly-evaluated pose in place, once per {@link Armature.update}.
|
|
106
|
+
*
|
|
107
|
+
* Unlike {@link PoseProvider}, which REPLACES animation, a modifier runs on top
|
|
108
|
+
* of it: the player has already written `pose`, overlay layers have already been
|
|
109
|
+
* composed, and the modifier gets the last word before the rig-convention clamps
|
|
110
|
+
* and the world-transform composition. Return nothing - edit `pose` in place.
|
|
111
|
+
*
|
|
112
|
+
* This is the hook for corrections that are a function of the animated pose
|
|
113
|
+
* rather than a replacement for it: an additive limb offset, a loop-seam
|
|
114
|
+
* dissolve, a look-at, a blink. `dt` is the seconds the clip advanced this
|
|
115
|
+
* evaluation (0 for {@link Armature.forcePoseRefresh}). `null` (the default)
|
|
116
|
+
* is no modifier and costs nothing.
|
|
117
|
+
*
|
|
118
|
+
* Deliberately NOT run by {@link Armature.probeBoneWorldPositions}: a probe
|
|
119
|
+
* measures the clip, and a correction derived from a probe that already
|
|
120
|
+
* contained it would feed back into itself.
|
|
121
|
+
*
|
|
122
|
+
* @group Characters & Animation
|
|
123
|
+
*/
|
|
124
|
+
export type PoseModifier = (pose: Pose, armature: Armature, dt: number) => void;
|
|
86
125
|
/**
|
|
87
126
|
* Composition root for one character: holds the three.js pivot object and
|
|
88
127
|
* wires together a {@link Skeleton}, an {@link AnimationPlayer}, a working
|
|
@@ -107,9 +146,49 @@ export declare class Armature {
|
|
|
107
146
|
/** Number of bones in the rig. */
|
|
108
147
|
numBones: number;
|
|
109
148
|
private readonly _skeleton;
|
|
149
|
+
/**
|
|
150
|
+
* Cap on how far one {@link update} may advance the clip, in seconds.
|
|
151
|
+
* `Infinity` (the default) tracks the wall clock.
|
|
152
|
+
*
|
|
153
|
+
* PlayCanvas clamps a long frame to `app.maxDeltaTime` (100ms), which a
|
|
154
|
+
* 30fps clip crosses three frames at once - a visible lurch. Cap it across
|
|
155
|
+
* an expected stall, then restore: capping drifts behind real time, which a
|
|
156
|
+
* loop hides but steady-state playback should not.
|
|
157
|
+
*/
|
|
158
|
+
maxAnimDt: number;
|
|
159
|
+
/**
|
|
160
|
+
* Corrective per-frame pivot translation, or `null` (the default) for none.
|
|
161
|
+
* See {@link RootOffsetProvider}.
|
|
162
|
+
*
|
|
163
|
+
* The offset composes ON TOP of whatever {@link rootMotionMode} routing
|
|
164
|
+
* produced and is measured from the base position {@link move} last set, so it
|
|
165
|
+
* cannot ratchet: every frame writes an absolute position, never an increment.
|
|
166
|
+
* `move` keeps owning the base placement; the provider only ever nudges.
|
|
167
|
+
*
|
|
168
|
+
* Used by callers that precompute a corrective root path from a clip - ground
|
|
169
|
+
* snap and foot pinning being the obvious ones - and want it applied every
|
|
170
|
+
* frame without fighting the base placement for ownership of the entity.
|
|
171
|
+
*/
|
|
172
|
+
rootOffsetProvider: RootOffsetProvider | null;
|
|
173
|
+
/**
|
|
174
|
+
* Per-frame refinement of the animated pose, or `null` (the default) for
|
|
175
|
+
* none. See {@link PoseModifier}.
|
|
176
|
+
*/
|
|
177
|
+
poseModifier: PoseModifier | null;
|
|
178
|
+
/**
|
|
179
|
+
* Former name of {@link poseModifier}, kept for compatibility. Same hook, same slot in the frame.
|
|
180
|
+
*
|
|
181
|
+
* @deprecated Use {@link poseModifier}.
|
|
182
|
+
*/
|
|
183
|
+
get posePostProcess(): PoseModifier | null;
|
|
184
|
+
set posePostProcess(fn: PoseModifier | null);
|
|
110
185
|
private readonly _currentPose;
|
|
111
186
|
private readonly _snapshotPose;
|
|
112
187
|
private readonly _worldTransforms;
|
|
188
|
+
private _probePose;
|
|
189
|
+
private _revealPrepared;
|
|
190
|
+
private _revealSkeleton;
|
|
191
|
+
private readonly _probeTransforms;
|
|
113
192
|
private _engine;
|
|
114
193
|
private readonly _worldMatrix;
|
|
115
194
|
private _player;
|
|
@@ -117,6 +196,12 @@ export declare class Armature {
|
|
|
117
196
|
private _provider;
|
|
118
197
|
private readonly _layers;
|
|
119
198
|
private readonly _layerTmpQ;
|
|
199
|
+
private _drivenNodes;
|
|
200
|
+
private _evaluatedBones;
|
|
201
|
+
/** {@link _evaluatedBones} with ancestors, root and pelvis, parents first. */
|
|
202
|
+
private _evaluatedOrder;
|
|
203
|
+
private readonly _nodeTmpV;
|
|
204
|
+
private readonly _nodeTmpQ;
|
|
120
205
|
/**
|
|
121
206
|
* Optional override that drives the pose in place of animation.
|
|
122
207
|
* Setting this to a non-null value skips animation evaluation; the
|
|
@@ -177,6 +262,8 @@ export declare class Armature {
|
|
|
177
262
|
private _hasLastPelvis;
|
|
178
263
|
private _rootMotionAccumDx;
|
|
179
264
|
private _rootMotionAccumDz;
|
|
265
|
+
private readonly _rootMotionTmp;
|
|
266
|
+
private _legacyRootRotation;
|
|
180
267
|
private _lodNearDist;
|
|
181
268
|
private _lodFarDist;
|
|
182
269
|
private _lodNearStride;
|
|
@@ -188,6 +275,28 @@ export declare class Armature {
|
|
|
188
275
|
private _sortLodFarStride;
|
|
189
276
|
private _sortLodFrameCounter;
|
|
190
277
|
constructor(name: string, armatureData: ArmatureData);
|
|
278
|
+
/**
|
|
279
|
+
* Drive scene-graph nodes from this armature's pose: a skinned mesh's bones,
|
|
280
|
+
* index-aligned with the rig and listed parents first. Each update writes the
|
|
281
|
+
* bone world transforms onto them, and the armature evaluates whenever nodes
|
|
282
|
+
* are attached - it otherwise poses only while a linked splat is in view.
|
|
283
|
+
* `null` detaches.
|
|
284
|
+
*/
|
|
285
|
+
driveNodes(nodes: readonly Object3D[] | null): void;
|
|
286
|
+
/**
|
|
287
|
+
* Pose only these bones (with their ancestors, the root and the pelvis) on
|
|
288
|
+
* each {@link update}; every other bone keeps its last bone matrix and
|
|
289
|
+
* driven-node pose. For a reader of a few bones of a large rig. `null` (the
|
|
290
|
+
* default) poses every bone.
|
|
291
|
+
*/
|
|
292
|
+
evaluateOnly(bones: readonly number[] | null): void;
|
|
293
|
+
private _applyEvaluatedBones;
|
|
294
|
+
/**
|
|
295
|
+
* Per-bone inverse bind-pose matrices (bind space to bone-local), for
|
|
296
|
+
* load-time passes over splat weights that need each bone's joint origin in
|
|
297
|
+
* the splats' rest space. Read-only.
|
|
298
|
+
*/
|
|
299
|
+
get inverseBindPose(): readonly Mat4[];
|
|
191
300
|
/** Splats currently being driven by this armature. */
|
|
192
301
|
get linkedSplats(): Set<Splat>;
|
|
193
302
|
/**
|
|
@@ -213,6 +322,22 @@ export declare class Armature {
|
|
|
213
322
|
* bone transforms so the splat appears in the correct pose immediately.
|
|
214
323
|
*/
|
|
215
324
|
linkSplat(splat: Splat): void;
|
|
325
|
+
/**
|
|
326
|
+
* Opt every linked splat into the reveal ahead of time - see
|
|
327
|
+
* {@link Splat.setReveal}. Bakes each splat's feet-to-head distances (about
|
|
328
|
+
* 10 ms per 50k splats on a desktop) and recompiles its shader once, so
|
|
329
|
+
* call it after loading rather than when the reveal starts. Splats linked
|
|
330
|
+
* later are baked as they link.
|
|
331
|
+
*/
|
|
332
|
+
prepareReveal(): void;
|
|
333
|
+
/**
|
|
334
|
+
* {@link Splat.bakeReveal} for one splat. The distances depend
|
|
335
|
+
* only on the skeleton, so they are derived once and shared - a character
|
|
336
|
+
* links one splat per LOD plus any variants.
|
|
337
|
+
*/
|
|
338
|
+
private _bakeReveal;
|
|
339
|
+
/** This rig's {@link buildRevealSkeleton}, from its bind pose. */
|
|
340
|
+
private _buildRevealSkeleton;
|
|
216
341
|
/**
|
|
217
342
|
* Stop driving the given splat. The splat is not destroyed; it just no
|
|
218
343
|
* longer receives bone transform updates.
|
|
@@ -245,6 +370,11 @@ export declare class Armature {
|
|
|
245
370
|
*/
|
|
246
371
|
get rootMotion(): boolean;
|
|
247
372
|
set rootMotion(v: boolean);
|
|
373
|
+
/**
|
|
374
|
+
* The entity position root motion applies off - see {@link rootMotionMode}.
|
|
375
|
+
* Set by {@link move}. Read-only; the vector is live.
|
|
376
|
+
*/
|
|
377
|
+
get rootMotionBase(): Readonly<Vec3>;
|
|
248
378
|
/**
|
|
249
379
|
* Return the pelvis X/Z delta accumulated since the previous call (or since
|
|
250
380
|
* the armature was created / `rootMotionMode` was changed), and reset the
|
|
@@ -266,6 +396,23 @@ export declare class Armature {
|
|
|
266
396
|
*/
|
|
267
397
|
get lockPelvisY(): boolean;
|
|
268
398
|
set lockPelvisY(v: boolean);
|
|
399
|
+
/**
|
|
400
|
+
* When `true`, the root bone's rotation is pinned to bind each frame and
|
|
401
|
+
* root motion is read straight off the pelvis, as in 0.1.1: a GLB clip whose
|
|
402
|
+
* root carries a yaw (every MetaHuman preset carries 180°) does not turn the
|
|
403
|
+
* character. When `false`, the clip's root rotation is kept and root motion
|
|
404
|
+
* is turned with it, as in the PlayCanvas build 0.3.2.
|
|
405
|
+
*
|
|
406
|
+
* Defaults to the engine's {@link SplatEngine.legacyRootRotation}: `true` on
|
|
407
|
+
* a `SplatEngine`, `false` on a `Scene`. Assign `null` to follow the engine
|
|
408
|
+
* again. `.anim` clips look the same either way; their root rotation is
|
|
409
|
+
* reset at parse.
|
|
410
|
+
*
|
|
411
|
+
* Set it before a clip plays: changed mid-clip under root-motion `'apply'`,
|
|
412
|
+
* the character jumps by twice its current pelvis offset.
|
|
413
|
+
*/
|
|
414
|
+
get legacyRootRotation(): boolean;
|
|
415
|
+
set legacyRootRotation(v: boolean | null);
|
|
269
416
|
get isPlaying(): boolean;
|
|
270
417
|
get isFinished(): boolean;
|
|
271
418
|
get paused(): boolean;
|
|
@@ -313,6 +460,53 @@ export declare class Armature {
|
|
|
313
460
|
* the first update.
|
|
314
461
|
*/
|
|
315
462
|
get boneWorldMatrices(): readonly Mat4[];
|
|
463
|
+
/** Index of the pelvis bone (a Mixamo `Hips` counts), or -1 for none. */
|
|
464
|
+
get pelvisBoneIndex(): number;
|
|
465
|
+
/**
|
|
466
|
+
* Sample the world-space POSITION of selected bones at an explicit animation
|
|
467
|
+
* frame time, writing `x, y, z` triples into `out` in the order the indices
|
|
468
|
+
* were given. `out` must hold at least `boneIndices.length * 3` numbers; an
|
|
469
|
+
* out-of-range index writes zeroes.
|
|
470
|
+
*
|
|
471
|
+
* This is the precompute probe. {@link Armature.update} is the wrong tool for
|
|
472
|
+
* sweeping a clip: it advances time, it pushes to linked splats, and it bails
|
|
473
|
+
* out before evaluating anything at all when the character is outside the
|
|
474
|
+
* camera frustum - so an off-screen character cannot be measured through it.
|
|
475
|
+
* This call skips culling and skinning entirely, leaves playback state
|
|
476
|
+
* untouched (time, crossfade, event cursor), and can be run for every frame of
|
|
477
|
+
* a clip back to back.
|
|
478
|
+
*
|
|
479
|
+
* The same rig-convention clamps the live path applies (pelvis X/Z to bind,
|
|
480
|
+
* pelvis-Y lock, root-bone translation / scale clamp) are applied to the
|
|
481
|
+
* probed pose, so sampled positions line up with rendered ones - the clip's
|
|
482
|
+
* root ORIENTATION is preserved in both, so a sweep and the render agree on
|
|
483
|
+
* which way the character faces. Root-motion ROUTING is deliberately
|
|
484
|
+
* not run: probing must not move the entity or feed the extract accumulator.
|
|
485
|
+
* {@link poseModifier} is not run either - see the note on that type.
|
|
486
|
+
*
|
|
487
|
+
* Positions include the pivot's current world transform, so they are in the
|
|
488
|
+
* same world space {@link getBoneWorldMatrix} reports. The pelvis X/Z clamp
|
|
489
|
+
* means what a sweep measures is the clip's IN-PLACE motion, whatever
|
|
490
|
+
* {@link rootMotionMode} is doing to the entity live.
|
|
491
|
+
*
|
|
492
|
+
* Plain numbers cross the boundary on purpose: consumers can sweep a clip
|
|
493
|
+
* without depending on PlayCanvas types.
|
|
494
|
+
*
|
|
495
|
+
* Returns `false` when the armature is not attached to a scene or no animation
|
|
496
|
+
* is active.
|
|
497
|
+
*/
|
|
498
|
+
probeBoneWorldPositions(frameTime: number, boneIndices: readonly number[], out: Float32Array | number[]): boolean;
|
|
499
|
+
/**
|
|
500
|
+
* Evaluate the active clip at an explicit frame time into `outPose`, with no
|
|
501
|
+
* crossfade and no playback-state mutation. The pose-level counterpart of
|
|
502
|
+
* {@link probeBoneWorldPositions}: parent-local TRS rather than world
|
|
503
|
+
* positions, for callers that want to blend toward a sampled pose (a loop
|
|
504
|
+
* seam) rather than measure one.
|
|
505
|
+
*
|
|
506
|
+
* The rig-convention clamps are applied, matching what the live path renders.
|
|
507
|
+
* Returns `false` when no animation is active.
|
|
508
|
+
*/
|
|
509
|
+
probePose(frameTime: number, outPose: Pose): boolean;
|
|
316
510
|
/**
|
|
317
511
|
* Snap any active crossfade to its terminal state (target pose fully
|
|
318
512
|
* applied) on the next {@link Armature.update}. Useful when scrubbing
|
|
@@ -334,6 +528,27 @@ export declare class Armature {
|
|
|
334
528
|
* mounted to a bone, particle emitters following a bone, etc.
|
|
335
529
|
*/
|
|
336
530
|
getBoneWorldMatrix(boneIdx: number): Mat4 | null;
|
|
531
|
+
/**
|
|
532
|
+
* Recompose the bone world-transform array from the current pose and entity
|
|
533
|
+
* transform immediately, bypassing the frustum/LOD gates that {@link update}
|
|
534
|
+
* applies. Use when you need {@link boneWorldMatrices} to reflect a fresh
|
|
535
|
+
* entity transform *right now* even if the armature is off-screen - e.g. after
|
|
536
|
+
* teleporting a character to a spot the camera isn't looking at and then
|
|
537
|
+
* sampling its bones (building a ragdoll, snapping an attachment). No-op if the
|
|
538
|
+
* armature isn't attached to a scene yet.
|
|
539
|
+
*/
|
|
540
|
+
refreshBoneTransforms(): void;
|
|
541
|
+
/**
|
|
542
|
+
* Evaluate the playing clip and push the pose to the splats NOW, bypassing
|
|
543
|
+
* every {@link update} throttle (rate divider, frustum gate, animation LOD).
|
|
544
|
+
* Call after reactivating or teleporting a pooled character, so its first
|
|
545
|
+
* visible frame shows the clip instead of the stale pose the throttles left
|
|
546
|
+
* (often the bind pose). The full form of {@link refreshBoneTransforms},
|
|
547
|
+
* which only recomposes the bone matrices from the current pose. Runs the
|
|
548
|
+
* layers and {@link poseModifier} with `dt` 0. No-op with no clip or
|
|
549
|
+
* before the armature has splats.
|
|
550
|
+
*/
|
|
551
|
+
forcePoseRefresh(): void;
|
|
337
552
|
/**
|
|
338
553
|
* Name of the currently-playing animation, or `null` if no animation is
|
|
339
554
|
* active. Mirrors {@link AnimationPlayer.currentAnimationName}.
|
|
@@ -374,6 +589,8 @@ export declare class Armature {
|
|
|
374
589
|
rootMotion?: boolean;
|
|
375
590
|
loop?: boolean;
|
|
376
591
|
preserveTime?: boolean;
|
|
592
|
+
continueSource?: boolean;
|
|
593
|
+
easing?: 'linear' | 'smoothstep';
|
|
377
594
|
}): boolean;
|
|
378
595
|
/**
|
|
379
596
|
* Play `animName` on the named overlay layer, gated to `mask`'s bone set.
|
|
@@ -413,9 +630,17 @@ export declare class Armature {
|
|
|
413
630
|
/**
|
|
414
631
|
* Resolve named rig conventions once skeleton library is available.
|
|
415
632
|
* If `boneNames` is present, looks up "root" and any name containing
|
|
416
|
-
* "pelvis"; otherwise falls back to bone index 0
|
|
633
|
+
* "pelvis" (or a Mixamo-style "Hips"); otherwise falls back to bone index 0
|
|
634
|
+
* as root. The rig's own names win over the scene library's.
|
|
417
635
|
*/
|
|
418
636
|
private _resolveRigIndices;
|
|
637
|
+
/**
|
|
638
|
+
* Advance every overlay layer's clock, crossfade and fade-out by `dt`
|
|
639
|
+
* without evaluating. {@link update} does this itself; call it directly
|
|
640
|
+
* when driving the pose with `update(0)` (e.g. an editor scrubbing the base
|
|
641
|
+
* clip), or the layers never move.
|
|
642
|
+
*/
|
|
643
|
+
tickLayers(dt: number): void;
|
|
419
644
|
/**
|
|
420
645
|
* Compose overlay layers onto `_currentPose`. Each layer ticks its own
|
|
421
646
|
* player, evaluates a full pose into a scratch buffer, then per masked
|
|
@@ -429,12 +654,59 @@ export declare class Armature {
|
|
|
429
654
|
* - root-motion routing - `'apply'` writes `baseline + (pelvis − bind)`
|
|
430
655
|
* to the pivot; `'extract'` accumulates the per-frame pelvis Δ;
|
|
431
656
|
* `'off'` does nothing.
|
|
657
|
+
* - the {@link rootOffsetProvider} correction, composed on top of whatever
|
|
658
|
+
* routing produced.
|
|
432
659
|
* - pelvis X/Z clamp to bind in bone space (always - the motion lives on
|
|
433
660
|
* the pivot / in the consumed delta, not on the bone).
|
|
434
661
|
* - pelvis-Y lock to bind (when {@link lockPelvisY} is set).
|
|
435
|
-
* - root-bone
|
|
662
|
+
* - root-bone translation / scale clamp to bind.
|
|
436
663
|
*/
|
|
437
664
|
private _applyRigPostClamps;
|
|
665
|
+
/**
|
|
666
|
+
* Take a horizontal pelvis offset measured in BONE space and return it in the
|
|
667
|
+
* entity's parent space, which is where {@link consumeRootMotionDelta} and the
|
|
668
|
+
* `'apply'` entity write both promise to deliver it.
|
|
669
|
+
*
|
|
670
|
+
* The pelvis is a child of the root bone, so its parent-local X/Z live in the
|
|
671
|
+
* root's frame, not the entity's. Those two frames coincide only while the
|
|
672
|
+
* root's rotation is identity - which used to be guaranteed by the root clamp
|
|
673
|
+
* resetting rotation, and is no longer: a clip whose root carries a yaw (every
|
|
674
|
+
* MetaHuman GLB preset carries a constant 180°) now keeps it, so the offset has
|
|
675
|
+
* to be rotated to stay in the frame the contract names. Rotating by identity
|
|
676
|
+
* is a no-op, so clips whose root is identity - every `.anim`, whose root
|
|
677
|
+
* rotation `Animation.parse` resets - route exactly as before.
|
|
678
|
+
*
|
|
679
|
+
* Y is deliberately dropped on the way in: root motion is a ground-plane
|
|
680
|
+
* concept here, and the caller only ever reads X/Z back out.
|
|
681
|
+
*
|
|
682
|
+
* Returns a reused scratch vector - read it immediately, do not retain.
|
|
683
|
+
*/
|
|
684
|
+
private _pelvisOffsetToEntitySpace;
|
|
685
|
+
/**
|
|
686
|
+
* Pelvis X/Z (and optionally Y) plus root-bone clamps - the bone-space half of
|
|
687
|
+
* the rig conventions, with no routing side effects. Shared by the live update
|
|
688
|
+
* and by the probes, which must not move the entity.
|
|
689
|
+
*
|
|
690
|
+
* The root bone is pinned to its bind TRANSLATION and to unit scale, so a clip
|
|
691
|
+
* cannot slide or resize the whole character behind the pelvis clamp's back:
|
|
692
|
+
* root translation would move the character in world space without ever
|
|
693
|
+
* showing up in the pelvis delta that root-motion routing measures, and the
|
|
694
|
+
* "in-place" guarantee this method and the probes advertise would be a lie.
|
|
695
|
+
*
|
|
696
|
+
* Its ROTATION is deliberately left alone. A yaw on the root is orientation,
|
|
697
|
+
* not motion - it is how a clip states which way the character faces, and it
|
|
698
|
+
* is constant for the whole clip in every artifact we ship (all 57 MetaHuman
|
|
699
|
+
* GLB presets carry exactly 180° about Y; a `.anim`'s root is reset to
|
|
700
|
+
* identity at parse, see `clearAnimRootRotation`).
|
|
701
|
+
* Resetting it used to delete that statement and render preset clips facing
|
|
702
|
+
* backwards. What the reset was really protecting - pelvis bone space and
|
|
703
|
+
* entity space agreeing - is kept by {@link _pelvisOffsetToEntitySpace}
|
|
704
|
+
* instead, which is the frame conversion the routing actually needed.
|
|
705
|
+
*
|
|
706
|
+
* Under {@link legacyRootRotation} (a `SplatEngine`'s default) the rotation
|
|
707
|
+
* is still pinned to bind, as in 0.1.1, so existing apps keep their facing.
|
|
708
|
+
*/
|
|
709
|
+
private _clampPoseToRigConventions;
|
|
438
710
|
/**
|
|
439
711
|
* Apply runtime bone scaling. Each entry scales a bone's flesh + segment in
|
|
440
712
|
* its own frame - `{ along, width, thickness }` (each defaulting to `1`), or
|
|
@@ -448,6 +720,12 @@ export declare class Armature {
|
|
|
448
720
|
setBoneStretch(factors: Record<string, BoneScaleInput> | null): void;
|
|
449
721
|
/** Push the current pose through skeleton + skinning. Called at link time. */
|
|
450
722
|
private _pushPose;
|
|
723
|
+
/**
|
|
724
|
+
* World transforms onto the driven nodes, parents first so each write reads
|
|
725
|
+
* an already-placed parent. Rotation is taken scale-free; each node keeps its
|
|
726
|
+
* own local scale.
|
|
727
|
+
*/
|
|
728
|
+
private _writeDrivenNodes;
|
|
451
729
|
private _cameraFrustum;
|
|
452
730
|
/**
|
|
453
731
|
* The pivot's world matrix in the skeletal core's own matrix type. Refreshes
|
|
@@ -2,10 +2,12 @@ import { Vector3 } from 'three';
|
|
|
2
2
|
import type { Object3D } from 'three';
|
|
3
3
|
import { Armature } from './armature';
|
|
4
4
|
import type { SplatEngine } from './engine';
|
|
5
|
+
import type { SplatColorModifier } from './splat/color-modifier';
|
|
5
6
|
import type { CharacterBundle } from './loader/character/load';
|
|
6
7
|
import type { AnimEventCallback } from './skeletal/animation-player';
|
|
7
8
|
import type { BodyRegion, BoneMask } from './skeletal/bone-mask';
|
|
8
9
|
import { Splat } from './splat/splat';
|
|
10
|
+
import type { RevealLook } from './splat/reveal-look';
|
|
9
11
|
/**
|
|
10
12
|
* Options for {@link Character.load}.
|
|
11
13
|
*
|
|
@@ -99,6 +101,14 @@ export declare class Character {
|
|
|
99
101
|
private _renderLodFarDist;
|
|
100
102
|
private _activeLevel;
|
|
101
103
|
private _variantSplats;
|
|
104
|
+
/** Layer ids applied by {@link setLayers}; null = PC default (World). */
|
|
105
|
+
private _layerIds;
|
|
106
|
+
/** See-through copies from {@link addOverlaySplat}. Own their layers, so
|
|
107
|
+
* {@link setLayers} leaves them alone; lifecycle is the character's. */
|
|
108
|
+
private _overlaySplats;
|
|
109
|
+
/** Set by {@link setOpacity}; a later overlay copy starts at it. */
|
|
110
|
+
private _opacity;
|
|
111
|
+
private _colorModifier;
|
|
102
112
|
/** Whether this character is live (ticking + rendering). Toggled by
|
|
103
113
|
* {@link setActive} for object pooling - a deactivated character keeps all
|
|
104
114
|
* its GPU resources (splats, textures, compiled shaders) but stops
|
|
@@ -146,6 +156,10 @@ export declare class Character {
|
|
|
146
156
|
*/
|
|
147
157
|
entityToGroundY(entityY: number): number;
|
|
148
158
|
private _updateHandler;
|
|
159
|
+
/** The host wants the per-frame tick (`disableAutoUpdate` clears it). */
|
|
160
|
+
private _autoUpdate;
|
|
161
|
+
/** The tick is registered on `app` right now. */
|
|
162
|
+
private _updateAttached;
|
|
149
163
|
/** Skeleton + animation controller. */
|
|
150
164
|
armature: Armature;
|
|
151
165
|
private _engine;
|
|
@@ -179,6 +193,27 @@ export declare class Character {
|
|
|
179
193
|
* ```
|
|
180
194
|
*/
|
|
181
195
|
static load(engine: SplatEngine, urlOrUrls: string | string[], opts?: LoadCharacterOptions): Promise<Character>;
|
|
196
|
+
/**
|
|
197
|
+
* Start downloading a character bundle now; a later {@link Character.load}
|
|
198
|
+
* of the same URL reuses the bytes.
|
|
199
|
+
*/
|
|
200
|
+
static prefetch(url: string): void;
|
|
201
|
+
/**
|
|
202
|
+
* The async first half of {@link Character.load}: download and decode the
|
|
203
|
+
* bundle(s), building no scene objects. Pair it with
|
|
204
|
+
* {@link Character.buildFromLoadResults} to choose WHEN the synchronous
|
|
205
|
+
* half (GPU upload, `new Splat`) runs: a game that spawns several characters
|
|
206
|
+
* in one frame can build them together.
|
|
207
|
+
*
|
|
208
|
+
* Each result is one character's: build it once.
|
|
209
|
+
*/
|
|
210
|
+
static fetchParsed(_engine: SplatEngine, urlOrUrls: string | string[]): Promise<CharacterBundle[]>;
|
|
211
|
+
/**
|
|
212
|
+
* The synchronous second half of {@link Character.load}: build the armature
|
|
213
|
+
* and splat(s) from {@link Character.fetchParsed}'s results. `defaultName`
|
|
214
|
+
* names the embedded animation when `opts.name` doesn't.
|
|
215
|
+
*/
|
|
216
|
+
static buildFromLoadResults(engine: SplatEngine, results: CharacterBundle[], defaultName: string, opts?: LoadCharacterOptions): Character;
|
|
182
217
|
/**
|
|
183
218
|
* Load a `.bin` character bundle from in-memory bytes.
|
|
184
219
|
*
|
|
@@ -226,6 +261,9 @@ export declare class Character {
|
|
|
226
261
|
/** Build + register the per-frame update handler. Called once at
|
|
227
262
|
* construction; kept separate so the handler can close over `this`. */
|
|
228
263
|
private _wireUpdate;
|
|
264
|
+
/** Register the per-frame tick exactly when the character is active, the
|
|
265
|
+
* host hasn't taken the tick over, and it isn't destroyed. */
|
|
266
|
+
private _syncUpdateHook;
|
|
229
267
|
/** Pick the render-LOD level for this frame based on camera distance.
|
|
230
268
|
* near band → L0; far band → last; in between → intermediate level. */
|
|
231
269
|
private _pickRenderLevel;
|
|
@@ -309,6 +347,40 @@ export declare class Character {
|
|
|
309
347
|
g: number;
|
|
310
348
|
b: number;
|
|
311
349
|
}): void;
|
|
350
|
+
/**
|
|
351
|
+
* {@link Splat.setTintMultiply} for every LOD level: multiply the colour
|
|
352
|
+
* by `color` with `strength` 0..1. {@link setTint} goes back to the mix.
|
|
353
|
+
*/
|
|
354
|
+
setTintMultiply(strength: number, color?: {
|
|
355
|
+
r: number;
|
|
356
|
+
g: number;
|
|
357
|
+
b: number;
|
|
358
|
+
}): void;
|
|
359
|
+
/**
|
|
360
|
+
* {@link Splat.setColorModifier} for every LOD level, variant and overlay
|
|
361
|
+
* splat, including ones added later. `null` removes it.
|
|
362
|
+
*/
|
|
363
|
+
setColorModifier(modifier: SplatColorModifier | null): void;
|
|
364
|
+
/**
|
|
365
|
+
* Opacity in [0, 1] for every LOD level, variant and overlay splat - see
|
|
366
|
+
* {@link Splat.setOpacity}. 1, the default, draws the character unchanged.
|
|
367
|
+
*/
|
|
368
|
+
setOpacity(opacity: number): void;
|
|
369
|
+
/**
|
|
370
|
+
* Reveal amount in [0, 1] for every LOD level, variant and overlay splat - see
|
|
371
|
+
* {@link Splat.setReveal}. 0 hides the character entirely (without
|
|
372
|
+
* touching entity enabled state, so no placement recompile), 1 renders it
|
|
373
|
+
* unchanged. `inverse` keeps the area ahead of the moving front instead,
|
|
374
|
+
* which is useful when handing off between two characters.
|
|
375
|
+
*/
|
|
376
|
+
setReveal(amount: number, inverse?: boolean): void;
|
|
377
|
+
/** {@link Splat.setRevealLook} for every LOD level, variant and overlay splat. */
|
|
378
|
+
setRevealLook(look: RevealLook): void;
|
|
379
|
+
/**
|
|
380
|
+
* Pay the reveal's one-time setup now instead of on its first frame - see
|
|
381
|
+
* {@link Armature.prepareReveal}.
|
|
382
|
+
*/
|
|
383
|
+
prepareReveal(): void;
|
|
312
384
|
/**
|
|
313
385
|
* Re-sort every LOD splat. Cheap when called on inactive splats (no GPU
|
|
314
386
|
* sort runs there), and necessary for the active one to reflect a fresh
|
|
@@ -316,6 +388,37 @@ export declare class Character {
|
|
|
316
388
|
* inactive LOD doesn't render with a stale sort order.
|
|
317
389
|
*/
|
|
318
390
|
requestSort(): void;
|
|
391
|
+
/**
|
|
392
|
+
* Put every LOD and variant splat on the given three.js layers (see
|
|
393
|
+
* {@link Splat.setLayers}). Remembered so variants attached later land on
|
|
394
|
+
* the same layers. `[0]` restores the default.
|
|
395
|
+
*/
|
|
396
|
+
setLayers(layerIds: number[]): void;
|
|
397
|
+
/**
|
|
398
|
+
* Add a second cloud of the active LOD, sharing this armature (so it
|
|
399
|
+
* animates in lockstep) but on `layerIds`. With the body occluded by real
|
|
400
|
+
* objects, this copy is what shows through obstacles: give it a see-through
|
|
401
|
+
* look with its own {@link Splat.setOpacity} or {@link Splat.setColorModifier}
|
|
402
|
+
* (the PlayCanvas build's `applyOverlaySplatStyle` is not ported).
|
|
403
|
+
* Synchronous: reuses the decoded data.
|
|
404
|
+
*/
|
|
405
|
+
addOverlaySplat(layerIds: number[]): Splat;
|
|
406
|
+
/** Carry the character-wide opacity and colour hook onto a splat added after they were set. */
|
|
407
|
+
private _applyLook;
|
|
408
|
+
/** Read-only view of the overlay copies from {@link addOverlaySplat}. */
|
|
409
|
+
get overlaySplats(): readonly Splat[];
|
|
410
|
+
/**
|
|
411
|
+
* Take one overlay copy back off, the inverse of {@link addOverlaySplat}.
|
|
412
|
+
*
|
|
413
|
+
* It exists so a caller can stop compositing a character against an
|
|
414
|
+
* environment WITHOUT reloading the character. Adding an overlay was already
|
|
415
|
+
* synchronous and in place; removing one was not possible at all, so the only
|
|
416
|
+
* way back was to destroy the body and load it again - a reload of the one
|
|
417
|
+
* thing on screen that had not changed.
|
|
418
|
+
*
|
|
419
|
+
* A splat that is not one of this character's overlays is ignored.
|
|
420
|
+
*/
|
|
421
|
+
removeOverlaySplat(splat: Splat): void;
|
|
319
422
|
/**
|
|
320
423
|
* World-space Y of the character's lowest point, using
|
|
321
424
|
* {@link Splat.getGroundWorldY}'s noise-robust low-quantile estimate across
|
|
@@ -449,6 +552,8 @@ export declare class Character {
|
|
|
449
552
|
loop?: boolean;
|
|
450
553
|
rootMotion?: boolean;
|
|
451
554
|
preserveTime?: boolean;
|
|
555
|
+
continueSource?: boolean;
|
|
556
|
+
easing?: 'linear' | 'smoothstep';
|
|
452
557
|
}): boolean;
|
|
453
558
|
/**
|
|
454
559
|
* Play `animName` on the named overlay layer, restricted to a bone mask.
|
|
@@ -488,6 +593,10 @@ export declare class Character {
|
|
|
488
593
|
* to the pivot's movement speed.
|
|
489
594
|
*/
|
|
490
595
|
get playbackSpeed(): number;
|
|
596
|
+
/** Position in the base clip, in frames (30 fps by convention). Set it to
|
|
597
|
+
* seek - e.g. to a clip's touchdown frame when the physics lands. */
|
|
598
|
+
get animationTime(): number;
|
|
599
|
+
set animationTime(v: number);
|
|
491
600
|
set playbackSpeed(v: number);
|
|
492
601
|
/**
|
|
493
602
|
* `true` when a non-looping animation has reached its last frame and is no
|
|
@@ -563,14 +672,23 @@ export declare class Character {
|
|
|
563
672
|
* Detach the per-frame playback tick without touching rendering/GPU
|
|
564
673
|
* resources (unlike {@link setActive}). For hosts that drive the armature's
|
|
565
674
|
* clock themselves and apply their own per-frame pose edits, the auto-tick
|
|
566
|
-
* would re-evaluate and overwrite those edits. Idempotent.
|
|
675
|
+
* would re-evaluate and overwrite those edits. Idempotent. The same as
|
|
676
|
+
* {@link disableAutoUpdate}.
|
|
567
677
|
*/
|
|
568
678
|
detachAutoUpdate(): void;
|
|
679
|
+
/**
|
|
680
|
+
* Stop the automatic per-frame update, for a host that drives it itself
|
|
681
|
+
* with {@link update}; otherwise the character would update twice a frame.
|
|
682
|
+
* Stays off across `setActive` until {@link enableAutoUpdate}. Idempotent.
|
|
683
|
+
*/
|
|
684
|
+
disableAutoUpdate(): void;
|
|
685
|
+
/** Give the per-frame update back to the engine. Idempotent. */
|
|
686
|
+
enableAutoUpdate(): void;
|
|
569
687
|
/**
|
|
570
688
|
* Advance this character by `dt` seconds: pick the render LOD, evaluate the
|
|
571
689
|
* pose, push it to the splats. `engine.update()` calls this for every
|
|
572
690
|
* character still on auto-update; call it yourself after
|
|
573
|
-
* {@link
|
|
691
|
+
* {@link disableAutoUpdate}.
|
|
574
692
|
*/
|
|
575
693
|
update(dt: number): void;
|
|
576
694
|
/**
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
export { PostFX } from './postfx/postfx';
|
|
2
|
+
export type { PostFXFrameConfig, PostFXInstallContext, PostFXPass, PostFXRenderContext, } from './postfx/postfx';
|
|
3
|
+
export { CameraFrame, TONEMAP_ACES, TONEMAP_ACES2, TONEMAP_FILMIC, TONEMAP_HEJL, TONEMAP_LINEAR, TONEMAP_NEUTRAL, TONEMAP_NONE, } from './postfx/camera-frame';
|
|
4
|
+
export type { EffectColor, FrameColor } from './postfx/camera-frame';
|
|
5
|
+
export { BaseCapturingPass } from './postfx/base-capturing-pass';
|
|
6
|
+
export type { BaseCapturingPassOptions, PostFXUniformScope } from './postfx/base-capturing-pass';
|
|
7
|
+
export type { PostFXUniformValue } from './postfx/uniforms';
|
|
8
|
+
export type { MaskTarget } from './postfx/mask';
|
|
9
|
+
export { PixelartEffect } from './pixelart/pixelart-effect';
|
|
10
|
+
export type { PixelartEffectOptions } from './pixelart/pixelart-effect';
|
|
11
|
+
export { OutlineEffect } from './outlines/outline-effect';
|
|
12
|
+
export type { OutlineAddOptions, OutlineEffectOptions } from './outlines/outline-effect';
|