@viggle/splat-engine-three 0.1.0 → 0.2.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 (117) hide show
  1. package/CHANGELOG.md +38 -0
  2. package/README.md +306 -33
  3. package/dist/chunks/chunk-BHNNSHJG.js +22298 -0
  4. package/dist/chunks/chunk-BHNNSHJG.js.map +7 -0
  5. package/dist/index.js +225 -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 +163 -3
  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 +36 -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 +7 -0
  59. package/dist/types/physics/ammo.d.ts +210 -0
  60. package/dist/types/physics/index.d.ts +11 -0
  61. package/dist/types/physics/joints.d.ts +157 -0
  62. package/dist/types/physics/physics-world.d.ts +193 -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 +741 -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 +241 -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/bone-binding.d.ts +1 -1
  95. package/dist/types/splat/color-modifier.d.ts +78 -0
  96. package/dist/types/splat/cut-groups.d.ts +27 -0
  97. package/dist/types/splat/depth-sort.d.ts +23 -5
  98. package/dist/types/splat/importance.d.ts +60 -0
  99. package/dist/types/splat/prune.d.ts +60 -0
  100. package/dist/types/splat/quality.d.ts +175 -0
  101. package/dist/types/splat/relight-binding.d.ts +39 -0
  102. package/dist/types/splat/reveal-bake.d.ts +43 -0
  103. package/dist/types/splat/reveal-look.d.ts +64 -0
  104. package/dist/types/splat/splat-mesh.d.ts +1 -0
  105. package/dist/types/splat/splat.d.ts +220 -0
  106. package/dist/types/splat/webgl/shaders.d.ts +5 -1
  107. package/dist/types/splat/webgl/splat-mesh.d.ts +6 -0
  108. package/dist/types/splat/webgpu/radix-sort.d.ts +3 -0
  109. package/dist/types/splat/webgpu/splat-mesh.d.ts +25 -0
  110. package/dist/types/three/splat-character.d.ts +56 -0
  111. package/dist/types/three/spz-loader.d.ts +35 -0
  112. package/dist/types/types.d.ts +6 -0
  113. package/dist/webgpu.js +1155 -156
  114. package/dist/webgpu.js.map +4 -4
  115. package/package.json +6 -2
  116. package/dist/chunks/chunk-MM6DJU6S.js +0 -7801
  117. package/dist/chunks/chunk-MM6DJU6S.js.map +0 -7
package/dist/index.js CHANGED
@@ -1,11 +1,65 @@
1
1
  import {
2
+ ALL_BODY_PARTS,
2
3
  Animation,
3
4
  Armature,
5
+ BODYGROUP_DEFAULT,
6
+ BODYGROUP_DYNAMIC,
7
+ BODYGROUP_ENGINE_1,
8
+ BODYGROUP_ENGINE_2,
9
+ BODYGROUP_ENGINE_3,
10
+ BODYGROUP_KINEMATIC,
11
+ BODYGROUP_NONE,
12
+ BODYGROUP_STATIC,
13
+ BODYGROUP_TRIGGER,
14
+ BODYGROUP_USER_1,
15
+ BODYGROUP_USER_2,
16
+ BODYGROUP_USER_3,
17
+ BODYGROUP_USER_4,
18
+ BODYGROUP_USER_5,
19
+ BODYGROUP_USER_6,
20
+ BODYGROUP_USER_7,
21
+ BODYGROUP_USER_8,
22
+ BODYMASK_ALL,
23
+ BODYMASK_NONE,
24
+ BODYMASK_NOT_STATIC,
25
+ BODYMASK_NOT_STATIC_KINEMATIC,
26
+ BODYMASK_STATIC,
27
+ BODY_PART_SLUGS,
28
+ BaseCapturingPass,
29
+ BodyPart,
30
+ BodyShapeVariant,
31
+ BoneOverlay,
32
+ CameraFrame,
4
33
  Character,
5
34
  CharacterBundleError,
35
+ DEFAULT_ENV_REVEAL_LOOK,
36
+ DEFAULT_HUMANOID_RAGDOLL,
37
+ DEFAULT_REVEAL_LOOK,
38
+ DEFAULT_REVEAL_PRESET,
39
+ DEFAULT_SHADER_FRAGMENT,
40
+ DEFAULT_SHADER_FRAGMENT_WGSL,
41
+ ENVIRONMENT_DEFAULT_LOD,
42
+ ENVIRONMENT_PROXY_DEFAULTS,
6
43
  EngineDisposedError,
7
44
  Environment,
45
+ JsonVfxInstance,
46
+ JsonVfxPrefab,
47
+ LOWER_BODY_BONE_NAMES,
48
+ MeshFlash,
49
+ MeshLayerRenderer,
50
+ NUM_BODY_PARTS,
51
+ OutlineEffect,
52
+ ParticleLayerRenderer,
53
+ PhysicsWorld,
54
+ PixelartEffect,
8
55
  PointLight,
56
+ Pose,
57
+ PostFX,
58
+ Ragdoll,
59
+ RigidBody,
60
+ Scene,
61
+ SceneDestroyedError,
62
+ ShaderLayerRenderer,
9
63
  SkyLight,
10
64
  Splat,
11
65
  SplatCharacter,
@@ -13,24 +67,135 @@ import {
13
67
  SplatEngine,
14
68
  SplatMesh,
15
69
  SplatPLYLoader,
70
+ SplatQuality,
71
+ SplatRelight,
72
+ SplatSPZLoader,
73
+ SpriteLayerRenderer,
16
74
  SunLight,
75
+ TONEMAP_ACES,
76
+ TONEMAP_ACES2,
77
+ TONEMAP_FILMIC,
78
+ TONEMAP_HEJL,
79
+ TONEMAP_LINEAR,
80
+ TONEMAP_NEUTRAL,
81
+ TONEMAP_NONE,
82
+ ThirdPersonCamera,
83
+ UPPER_BODY_BONE_NAMES,
17
84
  VSplatLoader,
85
+ VfxLayerRegistry,
86
+ VfxPool,
87
+ VfxStage,
18
88
  WebGLSplatBackend,
89
+ alphaFromLogits,
90
+ bodyPartLabel,
91
+ buildBoneToGroup,
92
+ buildProxyMesh,
93
+ buildStretch,
94
+ buildVfxQuadMesh,
95
+ buildVfxRingMesh,
96
+ buildVfxSphereMesh,
97
+ buildVfxSpikeMesh,
98
+ buildVoxelGrid,
99
+ cachedFetch,
100
+ classifyBone,
101
+ clearAnimRootRotation,
102
+ computeBoneStretch,
103
+ createConeTwistJoint,
104
+ createGeneric6DofJoint,
105
+ createHingeJoint,
19
106
  decodeCharacterBundle,
107
+ decodeSplatFile,
108
+ decodeSpz,
109
+ defaultLayerRegistry,
110
+ defaultProxySettings,
111
+ extractSurface,
112
+ getVfxMesh,
113
+ indexAssetCache,
114
+ installFetchInterceptor,
115
+ isCached,
116
+ isSocketRemoval,
20
117
  loadCharacterBundle,
21
118
  loadCharacterBundleFromBytes,
119
+ loadGlbFromUrl,
120
+ loadSplatAsset,
121
+ loadSplatSource,
22
122
  makeRegionMask,
123
+ mergeSocketLoadout,
23
124
  packSplats,
24
- parseGaussianPly
25
- } from "./chunks/chunk-MM6DJU6S.js";
125
+ parseGaussianPly,
126
+ playReveal,
127
+ prewarmJsonVfxPrefabs,
128
+ pruneSplats,
129
+ resolveBoneIndices,
130
+ setAssetFetch,
131
+ setBinFetch,
132
+ setGlbLoader,
133
+ setShareSplatResources,
134
+ uninstallFetchInterceptor,
135
+ validateShaderGLSL
136
+ } from "./chunks/chunk-BHNNSHJG.js";
26
137
  export {
138
+ ALL_BODY_PARTS,
27
139
  Animation,
28
140
  Armature,
141
+ BODYGROUP_DEFAULT,
142
+ BODYGROUP_DYNAMIC,
143
+ BODYGROUP_ENGINE_1,
144
+ BODYGROUP_ENGINE_2,
145
+ BODYGROUP_ENGINE_3,
146
+ BODYGROUP_KINEMATIC,
147
+ BODYGROUP_NONE,
148
+ BODYGROUP_STATIC,
149
+ BODYGROUP_TRIGGER,
150
+ BODYGROUP_USER_1,
151
+ BODYGROUP_USER_2,
152
+ BODYGROUP_USER_3,
153
+ BODYGROUP_USER_4,
154
+ BODYGROUP_USER_5,
155
+ BODYGROUP_USER_6,
156
+ BODYGROUP_USER_7,
157
+ BODYGROUP_USER_8,
158
+ BODYMASK_ALL,
159
+ BODYMASK_NONE,
160
+ BODYMASK_NOT_STATIC,
161
+ BODYMASK_NOT_STATIC_KINEMATIC,
162
+ BODYMASK_STATIC,
163
+ BODY_PART_SLUGS,
164
+ BaseCapturingPass,
165
+ BodyPart,
166
+ BodyShapeVariant,
167
+ BoneOverlay,
168
+ CameraFrame,
29
169
  Character,
30
170
  CharacterBundleError,
171
+ DEFAULT_ENV_REVEAL_LOOK,
172
+ DEFAULT_HUMANOID_RAGDOLL,
173
+ DEFAULT_REVEAL_LOOK,
174
+ DEFAULT_REVEAL_PRESET,
175
+ DEFAULT_SHADER_FRAGMENT,
176
+ DEFAULT_SHADER_FRAGMENT_WGSL,
177
+ ENVIRONMENT_DEFAULT_LOD,
178
+ ENVIRONMENT_PROXY_DEFAULTS,
31
179
  EngineDisposedError,
32
180
  Environment,
181
+ JsonVfxInstance,
182
+ JsonVfxPrefab,
183
+ LOWER_BODY_BONE_NAMES,
184
+ MeshFlash,
185
+ MeshLayerRenderer,
186
+ NUM_BODY_PARTS,
187
+ OutlineEffect,
188
+ ParticleLayerRenderer,
189
+ PhysicsWorld,
190
+ PixelartEffect,
33
191
  PointLight,
192
+ Pose,
193
+ PostFX,
194
+ Ragdoll,
195
+ RigidBody,
196
+ Scene,
197
+ SceneDestroyedError,
198
+ ShaderLayerRenderer,
34
199
  SkyLight,
35
200
  Splat,
36
201
  SplatCharacter,
@@ -39,14 +204,71 @@ export {
39
204
  SplatEngine,
40
205
  SplatMesh,
41
206
  SplatPLYLoader,
207
+ SplatQuality,
208
+ SplatRelight,
209
+ SplatSPZLoader,
210
+ SpriteLayerRenderer,
42
211
  SunLight,
212
+ TONEMAP_ACES,
213
+ TONEMAP_ACES2,
214
+ TONEMAP_FILMIC,
215
+ TONEMAP_HEJL,
216
+ TONEMAP_LINEAR,
217
+ TONEMAP_NEUTRAL,
218
+ TONEMAP_NONE,
219
+ ThirdPersonCamera,
220
+ UPPER_BODY_BONE_NAMES,
43
221
  VSplatLoader,
222
+ VfxLayerRegistry,
223
+ VfxPool,
224
+ VfxStage,
44
225
  WebGLSplatBackend,
226
+ alphaFromLogits,
227
+ bodyPartLabel,
228
+ buildBoneToGroup,
229
+ buildProxyMesh,
230
+ buildStretch,
231
+ buildVfxQuadMesh,
232
+ buildVfxRingMesh,
233
+ buildVfxSphereMesh,
234
+ buildVfxSpikeMesh,
235
+ buildVoxelGrid,
236
+ cachedFetch,
237
+ classifyBone,
238
+ clearAnimRootRotation,
239
+ computeBoneStretch,
240
+ createConeTwistJoint,
241
+ createGeneric6DofJoint,
242
+ createHingeJoint,
45
243
  decodeCharacterBundle,
244
+ decodeSplatFile,
245
+ decodeSpz,
246
+ defaultLayerRegistry,
247
+ defaultProxySettings,
248
+ extractSurface,
249
+ getVfxMesh,
250
+ indexAssetCache,
251
+ installFetchInterceptor,
252
+ isCached,
253
+ isSocketRemoval,
46
254
  loadCharacterBundle,
47
255
  loadCharacterBundleFromBytes,
256
+ loadGlbFromUrl,
257
+ loadSplatAsset,
258
+ loadSplatSource,
48
259
  makeRegionMask,
260
+ mergeSocketLoadout,
49
261
  packSplats,
50
- parseGaussianPly
262
+ parseGaussianPly,
263
+ playReveal,
264
+ prewarmJsonVfxPrefabs,
265
+ pruneSplats,
266
+ resolveBoneIndices,
267
+ setAssetFetch,
268
+ setBinFetch,
269
+ setGlbLoader,
270
+ setShareSplatResources,
271
+ uninstallFetchInterceptor,
272
+ validateShaderGLSL
51
273
  };
52
274
  //# sourceMappingURL=index.js.map
@@ -2,7 +2,7 @@ import { Animation } from '../animation';
2
2
  import type { SkeletonLibrary } from '../types';
3
3
  /**
4
4
  * Walk the raw 4×4 bone matrices stored in `animationData.data` and produce
5
- * the per-bone keyframe + spline cache used at playback time.
5
+ * the per-bone keys used at playback time.
6
6
  *
7
7
  * Idempotent - subsequent calls on the same `Animation` are no-ops (guarded
8
8
  * by `Animation.skeletalConverted`). {@link Animation.register} calls this
@@ -12,7 +12,7 @@ import type { SkeletonLibrary } from '../types';
12
12
  * matrices are no longer needed and would otherwise hold ~16 floats per bone
13
13
  * per frame in memory for the lifetime of the animation.
14
14
  */
15
- export declare function convertSkeletalAnimation(animationData: Animation, _skeletonLibrary: SkeletonLibrary): void;
15
+ export declare function convertSkeletalAnimation(animationData: Animation, skeletonLibrary?: SkeletonLibrary): void;
16
16
  /**
17
17
  * Return a view of `animationData` remapped to the target armature's bone
18
18
  * count, handling rig mismatches (e.g. a 1185-bone source animation played on
@@ -1,59 +1,35 @@
1
- import { Quat, Vec3 } from '../math';
1
+ import type { SkeletalKeyframeEntry } from '../animation';
2
2
  import type { RestPose } from './rest-relative';
3
3
  import { CubicSpline } from './spline';
4
- /** One sample on a per-bone animation curve. */
5
- export interface Pose {
6
- frame: number;
7
- position: Vec3;
8
- rotation: Quat;
9
- scale: Vec3;
10
- }
11
4
  /**
12
- * Per-bone keyframe entry: a list of poses sorted by frame plus the cached
13
- * cubic spline that interpolates them. `spline` is null when there are fewer
14
- * than two poses (a constant-pose bone - the consumer samples `poses[0]`).
5
+ * Per-bone curve as {@link buildArmatureKeyframes} emits it. Flat, not per-key
6
+ * objects: at 441 bones x 495 keys that allocation dominates the build.
15
7
  */
16
- export interface KeyframeEntryData {
17
- poses: Pose[];
8
+ export interface ArmatureKeyframeEntry {
9
+ /** Frame time per key, ascending. `length` is the key count. */
10
+ frames: Float32Array;
11
+ /** `[x,y,z]` per key. */
12
+ positions: Float32Array;
13
+ /** `[x,y,z,w]` per key, in the hemisphere the clip authored. */
14
+ rotations: Float32Array;
15
+ /** `[x,y,z]` per key. */
16
+ scales: Float32Array;
17
+ /** Null below two keys, or when the bone is dense enough not to need one. */
18
18
  spline: CubicSpline | null;
19
19
  }
20
- interface RebuildOptions {
21
- /** Include poses where `frame === duration`. Default `false`. */
22
- includeEnd?: boolean;
23
- /** Build a looping spline that wraps at `duration`. Default `false`. */
24
- looping?: boolean;
25
- }
26
- /**
27
- * Filter `poses` against `[0, duration)` (or `[0, duration]` when
28
- * `options.includeEnd`), sort by frame, and build the cubic spline that
29
- * interpolates them.
30
- *
31
- * Returns `{ poses, spline }`: a fresh sorted poses array (callers should
32
- * replace their original) and the spline, or `null` if fewer than two poses
33
- * survive the filter.
34
- *
35
- * Quaternion sign is normalized along the timeline so neighboring keys take
36
- * the short arc - without this the spline would interpolate the long way
37
- * around whenever a sample flips hemisphere.
38
- */
39
- export declare function rebuildKeyframeSpline(poses: Pose[], duration: number, options?: RebuildOptions): {
40
- poses: Pose[];
41
- spline: CubicSpline | null;
42
- };
43
20
  /**
44
21
  * Build the per-bone keyframe array an armature samples from at playback time.
45
22
  *
46
23
  * For each bone in `libraryKeyframes` whose index is below `numBones`:
47
24
  * 1. convert every pose into the bone's rest-relative space (so playback can
48
25
  * blend a delta on top of the rest pose), and
49
- * 2. rebuild the cubic spline, filtered+sorted by frame and wrapped for
50
- * looping if requested.
26
+ * 2. build the cubic spline that interpolates them, unless the bone is keyed
27
+ * densely enough not to need one.
51
28
  *
52
29
  * Result is a sparse array of length `numBones`; bones not referenced by the
53
30
  * source map stay `null` and fall back to rest pose at evaluation time.
54
31
  *
55
- * If `restPose.positions` is empty (rig has no rest data), poses are emitted
32
+ * If `restPose.positions` is empty (rig has no rest data), keys are emitted
56
33
  * unchanged - the rest-relative conversion no-ops.
57
34
  */
58
- export declare function buildArmatureKeyframes(libraryKeyframes: Map<number, KeyframeEntryData>, numFrames: number, numBones: number, restPose: RestPose, looping: boolean, translationMask?: Uint8Array): Array<KeyframeEntryData | null>;
59
- export {};
35
+ export declare function buildArmatureKeyframes(libraryKeyframes: Map<number, SkeletalKeyframeEntry>, numFrames: number, numBones: number, restPose: RestPose, looping: boolean, translationMask?: Uint8Array, bones?: ArrayLike<number> | null): Array<ArmatureKeyframeEntry | null>;
@@ -1,5 +1,3 @@
1
- import type { Quat, Vec3 } from './math';
2
- import type { CubicSpline } from './anim/spline';
3
1
  import type { SplatEngine } from './engine';
4
2
  /**
5
3
  * A frame-aligned event attached to an {@link Animation}. Events are fired by
@@ -21,23 +19,43 @@ export interface AnimationEvent {
21
19
  payload?: unknown;
22
20
  }
23
21
  /**
24
- * Per-bone keyframe entry inside a {@link SkeletalStore}.
22
+ * How {@link Animation.load} reads a clip, for clips converted from FBX.
23
+ *
24
+ * - `referenceFrameMode: 'first-frame'`: frame 0 is an import reference pose,
25
+ * not part of the motion. Each bone plays only its delta from frame 0, on
26
+ * top of the target rig's rest pose (or `referenceBaseAnimation`'s first
27
+ * frame when given, e.g. an idle clip). Implies `rigidBones`.
28
+ * - `rigidBones`: strip shear and non-uniform scale from every bone matrix
29
+ * before taking its rotation, and keep bone scale at 1. FBX conversion can
30
+ * leave both in the 3x3 basis; splat skinning expects rigid bones.
31
+ *
32
+ * All default off: a clip loaded without options plays exactly as before.
33
+ */
34
+ export interface AnimationLoadOptions {
35
+ referenceFrameMode?: 'first-frame';
36
+ referenceBaseAnimation?: Animation;
37
+ rigidBones?: boolean;
38
+ }
39
+ /**
40
+ * One bone's keys inside a {@link SkeletalStore}, ascending by frame. Flat
41
+ * arrays because a clip can hold ~135k keys. Read-only: cached copies of a
42
+ * clip share them.
25
43
  * @internal
26
44
  */
27
45
  export interface SkeletalKeyframeEntry {
28
- poses: Array<{
29
- frame: number;
30
- position: Vec3;
31
- rotation: Quat;
32
- scale: Vec3;
33
- }>;
34
- spline: CubicSpline | null;
46
+ /** Frame per key. `length` is the key count. */
47
+ frames: Float32Array;
48
+ /** `[x,y,z]` per key. */
49
+ positions: Float32Array;
50
+ /** `[x,y,z,w]` per key. */
51
+ rotations: Float32Array;
52
+ /** `[x,y,z]` per key. */
53
+ scales: Float32Array;
35
54
  }
36
55
  /**
37
- * Engine-private cache attached to an {@link Animation} after
38
- * {@link convertSkeletalAnimation} processes the raw matrices into
39
- * per-bone keyframes + splines. Subsequent registrations and playback reads
40
- * go through this store rather than re-walking the raw `Float32Array`.
56
+ * Per-bone keys of an {@link Animation}: read from a GLB, or converted from
57
+ * `.anim` matrices by {@link convertSkeletalAnimation}. Playback reads these,
58
+ * not `data`.
41
59
  *
42
60
  * @internal
43
61
  */
@@ -46,13 +64,26 @@ export interface SkeletalStore {
46
64
  manualBones: Set<number>;
47
65
  source: string;
48
66
  }
67
+ /**
68
+ * Reset the root bone (bone 0) to identity rotation in every frame of a
69
+ * `.anim` matrix block, keeping its translation. Exported for tests.
70
+ *
71
+ * A `.anim` does not state a facing on its root: the engine reset the root's
72
+ * rotation every frame until the rig clamp started keeping it (so a MetaHuman
73
+ * GLB's constant 180° root yaw could survive), and `.anim` clips were authored
74
+ * against that reset. Some library clips carry a stray constant 90° there
75
+ * (`idle_relax`, `walk_forward_relax`, `idle2`) that used to be discarded, and
76
+ * would now turn the character 90°. Dropping it here keeps every `.anim`
77
+ * playing as it always has; a GLB clip's root yaw is untouched.
78
+ */
79
+ export declare function clearAnimRootRotation(data: Float32Array, numFrames: number, numBones: number): void;
49
80
  /**
50
81
  * Parsed skeletal animation data.
51
82
  *
52
83
  * An `Animation` is the deserialized form of one clip, whatever it was
53
- * authored as. It holds a flat `Float32Array` of per-bone 4×4 matrices indexed
54
- * by frame and bone. Once registered on an engine under a name, characters can play
55
- * it via {@link Character.playAnimation} / {@link Character.crossfadeTo}.
84
+ * authored as: per-bone position, rotation and scale keys. Once registered on
85
+ * an engine under a name, characters can play it via
86
+ * {@link Character.playAnimation} / {@link Character.crossfadeTo}.
56
87
  *
57
88
  * The primary entry point is {@link Animation.loadGlb}, which fetches a
58
89
  * MetaHuman GLB, parses and registers it in one call. For custom fetch
@@ -65,7 +96,8 @@ export interface SkeletalStore {
65
96
  */
66
97
  export declare class Animation {
67
98
  /** Column-major bone matrices (translation at `[12..14]`, the layout
68
- * `THREE.Matrix4.elements` uses), length `numFrames * numBones * 16`. */
99
+ * `THREE.Matrix4.elements` uses), length `numFrames * numBones * 16`.
100
+ * Empty for a GLB clip and once registered. */
69
101
  data: Float32Array;
70
102
  /** Number of animation frames. */
71
103
  numFrames: number;
@@ -101,7 +133,17 @@ export declare class Animation {
101
133
  * or assigned directly by game code before {@link Animation.register}.
102
134
  */
103
135
  events?: AnimationEvent[];
104
- /** @internal Set by convertSkeletalAnimation on first registration. */
136
+ /**
137
+ * Treat frame 0 as an import reference pose and apply only each bone's
138
+ * motion delta from it on top of the target rig's rest pose. Set from the
139
+ * `.anim` header's `referenceFrameMode`, or by {@link Animation.load}'s
140
+ * options; must be set before {@link Animation#register}.
141
+ */
142
+ referenceFrameMode?: 'first-frame';
143
+ /** The target neutral pose used when `referenceFrameMode` is set (its frame 0 per bone). */
144
+ referenceBaseAnimation?: Animation;
145
+ /** Strip shear/scale from bone matrices on conversion (see {@link AnimationLoadOptions}). */
146
+ rigidBones?: boolean;
105
147
  /** The clip's own name, where its file gave one. Not the name it is registered under. */
106
148
  name: string;
107
149
  /** Frames per second the clip was authored at. `30` unless the file says otherwise. */
@@ -111,6 +153,7 @@ export declare class Animation {
111
153
  private _registeredIn;
112
154
  /** Length in seconds at the authored frame rate. */
113
155
  get duration(): number;
156
+ /** @internal Set by convertSkeletalAnimation on first registration. */
114
157
  skeletalConverted: boolean;
115
158
  /** @internal Per-bone keyframe cache produced by convertSkeletalAnimation. */
116
159
  skeletalStore?: SkeletalStore;
@@ -138,11 +181,8 @@ export declare class Animation {
138
181
  * hierarchy and one animation clip, carrying no real geometry (as produced
139
182
  * by the offline MetaHuman GLB exporter).
140
183
  *
141
- * The result is indistinguishable from {@link Animation.parse} output: the
142
- * clip's absolute parent-local TRS is packed into the same flat 4x4 bone
143
- * matrices, so every downstream stage - `convertSkeletalAnimation`,
144
- * `filterAnimationForArmature`, `AnimationPlayer` - behaves exactly as it
145
- * does for a `.anim`.
184
+ * Reads the clip's parent-local TRS into the same per-bone keys a `.anim`
185
+ * is converted to, so both play identically. `data` stays empty.
146
186
  *
147
187
  * `animationName` selects a clip by name when the GLB holds more than one;
148
188
  * omitted, the first clip is used. Pair with {@link Animation#register} to
@@ -160,6 +200,8 @@ export declare class Animation {
160
200
  static parseGlb(buffer: ArrayBuffer, animationName?: string): Animation;
161
201
  /**
162
202
  * Fetch, parse, and register a `.anim` file on the engine under `name`.
203
+ * Loaded keys are shared read-only; metadata and registration
204
+ * are local to the returned Animation. Use `parse` for editable source poses.
163
205
  *
164
206
  * After this resolves, characters can play it via
165
207
  * `character.playAnimation(name)` / `character.crossfadeTo(name)`.
@@ -170,11 +212,20 @@ export declare class Animation {
170
212
  * await Animation.load(engine, '/assets/idle.anim', 'idle');
171
213
  * character.playAnimation('idle', { loop: true });
172
214
  * ```
215
+ * `options` reads a clip converted from FBX (see {@link AnimationLoadOptions}).
216
+ */
217
+ static load(engine: SplatEngine, url: string, name: string, options?: AnimationLoadOptions): Promise<Animation>;
218
+ /**
219
+ * A clip loaded with {@link AnimationLoadOptions} gets its own unconverted
220
+ * copy: `register` converts it against the engine's rig, which a reference
221
+ * pose needs, and its keys differ from the shared plain conversion.
173
222
  */
174
- static load(engine: SplatEngine, url: string, name: string): Promise<Animation>;
223
+ private static _withConversionOptions;
175
224
  /**
176
225
  * Fetch, parse, and register a MetaHuman GLB on the engine under `name`.
177
226
  * The GLB counterpart of {@link Animation.load}.
227
+ * Like `load`, returns a local wrapper over shared read-only keys.
228
+ * Use `fromGlb` directly when an unshared copy is needed.
178
229
  *
179
230
  * `animationName` selects a clip inside the GLB by name; omitted, the first
180
231
  * clip is used. After this resolves, characters can play it via
@@ -189,11 +240,16 @@ export declare class Animation {
189
240
  * ```
190
241
  */
191
242
  static loadGlb(engine: SplatEngine, url: string, name: string, animationName?: string): Promise<Animation>;
243
+ /** Start downloading now; a later `load` of the same URL reuses the bytes. */
244
+ static prefetch(url: string): void;
245
+ private static readonly _convertedLimit;
246
+ private static _convertedCache;
247
+ private static _convertedLoading;
248
+ private static _loadConverted;
192
249
  /**
193
250
  * Process-wide ArrayBuffer cache for .anim URLs. Each `SplatEngine` still
194
- * gets its own parsed `Animation` (storage arrays are mutated by the
195
- * skeletal converter so they're not safely shareable across scenes),
196
- * but the network bytes are shared. Avoids re-downloading the same
251
+ * gets its own `Animation` wrapper; converted source data is shared by the
252
+ * bounded cache above. Avoids re-downloading the same
197
253
  * idle/walk clips every time the app swaps one engine for another.
198
254
  */
199
255
  private static _bufferCache;