@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.
Files changed (112) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/README.md +158 -20
  3. package/dist/chunks/chunk-2GKWT24B.js +23182 -0
  4. package/dist/chunks/chunk-2GKWT24B.js.map +7 -0
  5. package/dist/index.js +235 -3
  6. package/dist/types/anim/animation-conversion.d.ts +2 -2
  7. package/dist/types/anim/keyframe-splines.d.ts +17 -41
  8. package/dist/types/animation.d.ts +84 -28
  9. package/dist/types/armature.d.ts +280 -2
  10. package/dist/types/character.d.ts +120 -2
  11. package/dist/types/effects/index.d.ts +12 -0
  12. package/dist/types/effects/outlines/outline-effect.d.ts +98 -0
  13. package/dist/types/effects/outlines/outline-shaders.d.ts +14 -0
  14. package/dist/types/effects/pixelart/pixelart-effect.d.ts +152 -0
  15. package/dist/types/effects/pixelart/pixelart-shaders.d.ts +31 -0
  16. package/dist/types/effects/postfx/base-capturing-pass.d.ts +109 -0
  17. package/dist/types/effects/postfx/camera-frame.d.ts +103 -0
  18. package/dist/types/effects/postfx/frame-renderer.d.ts +32 -0
  19. package/dist/types/effects/postfx/frame-shaders.d.ts +19 -0
  20. package/dist/types/effects/postfx/mask.d.ts +44 -0
  21. package/dist/types/effects/postfx/postfx.d.ts +144 -0
  22. package/dist/types/effects/postfx/program.d.ts +74 -0
  23. package/dist/types/effects/postfx/uniforms.d.ts +24 -0
  24. package/dist/types/effects/postfx/webgl-program.d.ts +6 -0
  25. package/dist/types/effects/postfx/webgpu-program.d.ts +3 -0
  26. package/dist/types/effects/vfx/data-types.d.ts +100 -0
  27. package/dist/types/effects/vfx/index.d.ts +37 -0
  28. package/dist/types/effects/vfx/json-vfx-prefab.d.ts +94 -0
  29. package/dist/types/effects/vfx/layer-renderer.d.ts +118 -0
  30. package/dist/types/effects/vfx/layers/mesh.d.ts +124 -0
  31. package/dist/types/effects/vfx/layers/particle.d.ts +90 -0
  32. package/dist/types/effects/vfx/layers/shader.d.ts +130 -0
  33. package/dist/types/effects/vfx/layers/shared.d.ts +40 -0
  34. package/dist/types/effects/vfx/layers/sprite.d.ts +45 -0
  35. package/dist/types/effects/vfx/pool.d.ts +51 -0
  36. package/dist/types/effects/vfx/prefab.d.ts +48 -0
  37. package/dist/types/effects/vfx/prewarm.d.ts +17 -0
  38. package/dist/types/effects/vfx/stage.d.ts +115 -0
  39. package/dist/types/effects/vfx/webgpu-register.d.ts +2 -0
  40. package/dist/types/effects/webgpu-register.d.ts +2 -0
  41. package/dist/types/engine.d.ts +18 -0
  42. package/dist/types/environment.d.ts +96 -8
  43. package/dist/types/index.d.ts +35 -6
  44. package/dist/types/loader/animation/animation-glb.d.ts +4 -4
  45. package/dist/types/loader/character/load.d.ts +6 -1
  46. package/dist/types/loader/environment/lod-bundle.d.ts +123 -0
  47. package/dist/types/loader/environment/spz-decode.d.ts +88 -0
  48. package/dist/types/loader/environment/spz.d.ts +28 -0
  49. package/dist/types/loader/shared/asset-fetch.d.ts +11 -0
  50. package/dist/types/loader/shared/asset-loader.d.ts +86 -0
  51. package/dist/types/loader/shared/bin-cache.d.ts +41 -14
  52. package/dist/types/loader/shared/decode-worker.d.ts +27 -0
  53. package/dist/types/loader/shared/glb.d.ts +30 -0
  54. package/dist/types/loader/shared/inflate.d.ts +9 -0
  55. package/dist/types/loader/shared/pack-splats-task.d.ts +17 -0
  56. package/dist/types/loader/shared/sog-decode.d.ts +81 -0
  57. package/dist/types/loader/shared/sog.d.ts +17 -0
  58. package/dist/types/math.d.ts +198 -13
  59. package/dist/types/physics/ammo.d.ts +217 -0
  60. package/dist/types/physics/index.d.ts +11 -0
  61. package/dist/types/physics/joints.d.ts +206 -0
  62. package/dist/types/physics/physics-world.d.ts +194 -0
  63. package/dist/types/physics/rigid-body.d.ts +361 -0
  64. package/dist/types/presets/camera/camera-preset.d.ts +43 -0
  65. package/dist/types/presets/camera/third-person-camera.d.ts +63 -0
  66. package/dist/types/presets/character/body-shape.d.ts +109 -0
  67. package/dist/types/presets/character/character-reveal.d.ts +90 -0
  68. package/dist/types/presets/character/socket-loadout.d.ts +61 -0
  69. package/dist/types/presets/index.d.ts +13 -0
  70. package/dist/types/presets/vfx/mesh-flash.d.ts +51 -0
  71. package/dist/types/presets/visual/bone-overlay.d.ts +57 -0
  72. package/dist/types/proxy/environment-input.d.ts +30 -0
  73. package/dist/types/proxy/environment-source.d.ts +39 -0
  74. package/dist/types/proxy/proxy-debug.d.ts +106 -0
  75. package/dist/types/proxy/splat-source.d.ts +42 -0
  76. package/dist/types/proxy/voxelizer.d.ts +383 -0
  77. package/dist/types/relight/backend.d.ts +101 -0
  78. package/dist/types/relight/index.d.ts +6 -0
  79. package/dist/types/relight/relight-pass.d.ts +367 -0
  80. package/dist/types/relight/relight-placeholder.d.ts +2 -0
  81. package/dist/types/relight/relight-shaders.d.ts +4 -0
  82. package/dist/types/relight/shadow-bias.d.ts +26 -0
  83. package/dist/types/relight/splat-relight.d.ts +760 -0
  84. package/dist/types/relight/webgl-backend.d.ts +3 -0
  85. package/dist/types/relight/webgpu/backend.d.ts +3 -0
  86. package/dist/types/relight/webgpu-register.d.ts +2 -0
  87. package/dist/types/scene.d.ts +291 -0
  88. package/dist/types/skeletal/animation-player.d.ts +31 -3
  89. package/dist/types/skeletal/body-parts.d.ts +55 -0
  90. package/dist/types/skeletal/ragdoll-config.d.ts +115 -0
  91. package/dist/types/skeletal/ragdoll.d.ts +283 -0
  92. package/dist/types/skeletal/skeleton.d.ts +9 -2
  93. package/dist/types/splat/backend.d.ts +2 -0
  94. package/dist/types/splat/color-modifier.d.ts +78 -0
  95. package/dist/types/splat/cut-groups.d.ts +27 -0
  96. package/dist/types/splat/relight-binding.d.ts +39 -0
  97. package/dist/types/splat/reveal-bake.d.ts +43 -0
  98. package/dist/types/splat/reveal-look.d.ts +64 -0
  99. package/dist/types/splat/splat-mesh.d.ts +1 -0
  100. package/dist/types/splat/splat.d.ts +154 -0
  101. package/dist/types/splat/webgl/shaders.d.ts +5 -1
  102. package/dist/types/splat/webgl/splat-mesh.d.ts +4 -0
  103. package/dist/types/splat/webgpu/radix-sort.d.ts +3 -0
  104. package/dist/types/splat/webgpu/splat-mesh.d.ts +23 -0
  105. package/dist/types/three/splat-character.d.ts +28 -0
  106. package/dist/types/three/spz-loader.d.ts +35 -0
  107. package/dist/types/types.d.ts +6 -0
  108. package/dist/webgpu.js +1137 -154
  109. package/dist/webgpu.js.map +4 -4
  110. package/package.json +6 -2
  111. package/dist/chunks/chunk-WN5WBKM4.js +0 -8606
  112. package/dist/chunks/chunk-WN5WBKM4.js.map +0 -7
@@ -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 as root.
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 full clamp to bind.
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 detachAutoUpdate}.
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';