@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
@@ -0,0 +1,283 @@
1
+ /**
2
+ * Ragdoll: physics-driven {@link PoseProvider} for a character.
3
+ *
4
+ * ## Mode is strictly binary
5
+ *
6
+ * When the ragdoll is enabled, animation evaluation is fully replaced
7
+ * by physics. No per-bone blend, no transition window. This is a
8
+ * deliberate design choice - it keeps the pose write-back path simple
9
+ * and makes it unambiguous which subsystem owns the pose at any
10
+ * moment. If you need "the right arm goes ragdoll while the rest
11
+ * keeps animating," this module isn't it; you'd build a partial-mask
12
+ * pose provider on the same {@link PoseProvider} hook instead.
13
+ *
14
+ * ## Rig conventions
15
+ *
16
+ * Bodies are placed assuming each bone's bind-pose **direction** is
17
+ * captured by `endBoneName` in the config (e.g. pelvis's direction is
18
+ * the vector to spine_03). For terminal bones without a useful end
19
+ * bone (head, hand, foot), the body axis defaults to the bone's
20
+ * bind-pose **local +Y** in model space - true for UE-style rigs that
21
+ * follow the standard humanoid bone naming (`pelvis`, `spine_NN`,
22
+ * `upperarm_l/r`, etc.). Other rig conventions can be supported by
23
+ * authoring a {@link RagdollConfig} that specifies `endBoneName`
24
+ * everywhere instead of relying on the fallback.
25
+ *
26
+ * Ported from the PlayCanvas build. The bone math is unchanged (it runs on
27
+ * the same `Mat4` / `Quat` kernel); the body entities become `Object3D`s
28
+ * carrying a {@link RigidBody} in the scene's {@link PhysicsWorld}.
29
+ *
30
+ * @module
31
+ * @group Ragdoll
32
+ */
33
+ import { Object3D, Vector3 } from 'three';
34
+ import type { Armature, PoseProvider } from '../armature';
35
+ import type { PhysicsWorld } from '../physics/physics-world';
36
+ import type { RigidBody, XYZ } from '../physics/rigid-body';
37
+ import type { Pose } from './pose';
38
+ import type { RagdollConfig } from './ragdoll-config';
39
+ /**
40
+ * Information passed to {@link Ragdoll.onLimbDetached} listeners.
41
+ *
42
+ * @group Ragdoll
43
+ */
44
+ export interface LimbDetachedInfo {
45
+ /** Bone name (as authored in the config) whose joint just severed. */
46
+ boneName: string;
47
+ /** World-space position of the joint anchor at the moment of
48
+ * severance. A natural spawn point for blood/spark VFX. */
49
+ worldPos: Vector3;
50
+ }
51
+ /**
52
+ * Physics-driven ragdoll for a character. Owns one capsule rigid body
53
+ * per configured bone plus the joints between them. Implements
54
+ * {@link PoseProvider}; the Armature itself has no ragdoll knowledge.
55
+ *
56
+ * Lifecycle:
57
+ * - Construct: cheap, no bodies yet, just resolves bone names.
58
+ * - `enable()`: build bodies + joints at the armature's current
59
+ * pose, install as the armature's `poseProvider`.
60
+ * - `applyImpulse(boneName, impulse)`: kick a specific body.
61
+ * - `disable()`: tear down, animation resumes.
62
+ *
63
+ * Bodies parent to the engine's `contentRoot` (not the armature's
64
+ * object); once active they have their own world transforms driven by
65
+ * Ammo. The armature object stays put - the pose write-back absorbs
66
+ * the world position into bone-local TRS, so the splat deforms to the
67
+ * physics-driven world either way. Trade-off: distance-LOD / frustum
68
+ * culling bands are computed against the spawn origin, not the
69
+ * ragdoll's drift. Fine for short-distance ragdolls.
70
+ *
71
+ * Requires a physics world: the armature's {@link Scene} created with
72
+ * {@link CreateSceneOptions.physics}, or one passed to the constructor;
73
+ * {@link enable} throws otherwise.
74
+ *
75
+ * @group Ragdoll
76
+ */
77
+ export declare class Ragdoll implements PoseProvider {
78
+ private readonly _armature;
79
+ private readonly _engine;
80
+ private readonly _armatureObject;
81
+ private readonly _skeleton;
82
+ private readonly _bindWorld;
83
+ /** Live reference to the armature's per-bone world matrices. */
84
+ private readonly _worldTransforms;
85
+ /** Ragdoll bone records, ordered to match the config. */
86
+ private readonly _bones;
87
+ /** boneIdx → ragdoll-bone record (lookup for parent-chain walks). */
88
+ private readonly _byBoneIdx;
89
+ private _active;
90
+ private _physics;
91
+ private _container;
92
+ private _joints;
93
+ private readonly _tmpMat;
94
+ private readonly _tmpMat2;
95
+ private readonly _entityWorld;
96
+ private _writePoseBoneWorld;
97
+ private _writePoseHas;
98
+ /**
99
+ * Build a Ragdoll bound to `armature`. The armature must already be
100
+ * attached to an engine (a character loaded into a scene).
101
+ *
102
+ * @param args.armature - Target armature. Must already be attached to a scene.
103
+ * @param args.config - Bone/joint descriptor. Defaults to
104
+ * {@link DEFAULT_HUMANOID_RAGDOLL} (works for any rig that follows
105
+ * the standard UE-style bone naming).
106
+ * @param args.physics - The world to simulate in. Defaults to the
107
+ * armature's scene's {@link Scene.physics}; pass one for an engine
108
+ * driven by your own loop rather than a {@link Scene}.
109
+ */
110
+ constructor(args: {
111
+ armature: Armature;
112
+ config?: RagdollConfig;
113
+ physics?: PhysicsWorld;
114
+ });
115
+ /** Build each `RagdollBone.subtreeBones` set by walking
116
+ * `Skeleton.parents`. O(numBones × numRagdollBones) - runs once. */
117
+ private _computeSubtrees;
118
+ /** Whether the ragdoll is currently active (bodies are in the physics world). */
119
+ get isActive(): boolean;
120
+ /**
121
+ * Live `Object3D` carrying the rigid body for `boneName`, or `null`
122
+ * if the ragdoll isn't active or no body is configured for that bone.
123
+ * Its `position` / `quaternion` are world-space (the ragdoll container
124
+ * sits at the content root's origin). Use with {@link getBody} to apply
125
+ * continued forces, read velocities, attach extra constraints, or wire
126
+ * bone-tracked effects to a specific limb. Reference is invalidated by
127
+ * {@link disable}.
128
+ */
129
+ getBodyEntity(boneName: string): Object3D | null;
130
+ /**
131
+ * The {@link RigidBody} for `boneName` - what `getBodyEntity(name).rigidbody`
132
+ * was in the PlayCanvas build. `null` under the same conditions as
133
+ * {@link getBodyEntity}.
134
+ */
135
+ getBody(boneName: string): RigidBody | null;
136
+ private _detachListeners;
137
+ /**
138
+ * Names of bones whose joint-to-parent has been severed during this
139
+ * enable() session (manually via {@link detach} or by Bullet's
140
+ * break threshold). Cleared on `disable()`.
141
+ */
142
+ get detachedBones(): readonly string[];
143
+ /**
144
+ * Sever the joint connecting `boneName`'s body to its parent body.
145
+ * The body and the skeletal subtree it represents continue to exist
146
+ * as free physics bodies - they just stop being constrained to the
147
+ * rest of the ragdoll. Fires {@link onLimbDetached}.
148
+ *
149
+ * No-op if the ragdoll is not active, the bone has no parent joint
150
+ * (root bone), or the bone has already been detached.
151
+ */
152
+ detach(boneName: string): void;
153
+ /**
154
+ * Subscribe to limb-detach events. Listener fires once per
155
+ * detachment (manual or break-threshold) while the ragdoll is
156
+ * active. Returns an unsubscribe function. All listeners are
157
+ * automatically cleared on {@link disable}.
158
+ *
159
+ * The reported `worldPos` is the joint anchor's world position at
160
+ * the moment of severance - a sensible spawn point for blood/spark
161
+ * VFX.
162
+ */
163
+ onLimbDetached(cb: (info: LimbDetachedInfo) => void): () => void;
164
+ /** Tear down a single bone's parent joint and fire listeners.
165
+ * Internal - used by manual {@link detach} and by the per-frame
166
+ * break-threshold poll in {@link writePose}. */
167
+ private _severJoint;
168
+ /** Per-frame poll: any joint with a break threshold whose
169
+ * `isBroken()` flipped this step gets severed via the normal
170
+ * detach path. Called from {@link writePose}. */
171
+ private _pollBrokenJoints;
172
+ /**
173
+ * Snap every linked splat's bone weights so each gaussian sits
174
+ * entirely on one side of the cut - either fully weighted to bones
175
+ * in `subtreeBones` (= goes with the detached limb) or fully
176
+ * weighted to bones outside (= stays with the rest of the body).
177
+ *
178
+ * Implementation: per splat, sum its weights on each side. The
179
+ * heavier side keeps its weights (zero out the other side's
180
+ * influences), then renormalize the remaining weights to sum to
181
+ * 1. Privatizes the splat's bone-weight buffers on first call so
182
+ * other character instances of the same asset are unaffected.
183
+ */
184
+ private _rewriteSplatWeightsForSubtree;
185
+ /**
186
+ * Take over from animation: build physics bodies at the current
187
+ * (animated) pose's world positions, wire up joints, and install
188
+ * this Ragdoll as the armature's pose provider. Apply impulses
189
+ * (e.g. for a death-kick) AFTER enable returns via
190
+ * {@link applyImpulse}.
191
+ *
192
+ * Caller's contract: the armature must have run update() at least
193
+ * once before enable(), so the bone world matrices used to place
194
+ * the bodies reflect the current animated pose.
195
+ *
196
+ * No-op if the ragdoll is already active. Throws if the engine has
197
+ * no physics world.
198
+ */
199
+ enable(opts?: {
200
+ /** Whether bodies collide with each other across joints. Default `false`. */
201
+ selfCollide?: boolean;
202
+ }): void;
203
+ /**
204
+ * Apply a world-space impulse (N·s) to the body for `boneName`. Pass
205
+ * `'*'` to apply the same impulse to every body - useful for an
206
+ * explosion-style push. Silently no-ops if the ragdoll isn't active
207
+ * or if the bone has no body.
208
+ *
209
+ * Typical use: kick the ragdoll on activation.
210
+ * ```ts
211
+ * ragdoll.enable();
212
+ * ragdoll.applyImpulse('pelvis', new THREE.Vector3(0, 8, -10));
213
+ * ```
214
+ */
215
+ applyImpulse(boneName: string, impulse: XYZ): void;
216
+ private _buildContainer;
217
+ /** Create one capsule body per ragdoll bone at its current animated
218
+ * world transform. Parent under the ragdoll container. */
219
+ private _buildBodies;
220
+ /** Wire up the joints linking each body to its parent body. Skips
221
+ * bones with no parent (root) or no joint descriptor. */
222
+ private _buildJoints;
223
+ /**
224
+ * Tear down the physics bodies and joints, and detach from the
225
+ * armature's pose-provider slot so animation resumes next frame.
226
+ * No-op if already disabled. Safe to call repeatedly.
227
+ */
228
+ disable(): void;
229
+ /**
230
+ * {@link PoseProvider.onDetach} - called by the Armature when it's
231
+ * destroyed or when another provider replaces us. Tears down bodies
232
+ * but does NOT touch `armature.poseProvider` (the setter is mid-
233
+ * transition; mutating it from here would either overwrite the new
234
+ * provider or recurse).
235
+ */
236
+ onDetach(): void;
237
+ /** Release physics bodies, joints, and the container object. Sets
238
+ * `_active = false`. Idempotent. */
239
+ private _teardownBodies;
240
+ /**
241
+ * Full cleanup: tear down bodies (if active) plus any debug
242
+ * visualization. Call when discarding a Ragdoll instance (e.g. on
243
+ * character respawn) - `disable()` alone leaves the debug viz
244
+ * running.
245
+ */
246
+ destroy(): void;
247
+ private _debugLines;
248
+ private _debugUnhook;
249
+ /** Whether the debug box visualization is currently visible. */
250
+ get debugVisible(): boolean;
251
+ /**
252
+ * Show or hide debug wireframe boxes mirroring each configured
253
+ * ragdoll body. Drawn without depth test so they always render on
254
+ * top of splats / standard meshes / each other. Boxes follow bones
255
+ * via the same `boneToBody` offset the physics bodies use, so they
256
+ * sit in the right place both during animation (no physics) and
257
+ * during ragdoll (physics-driven). Use for tuning capsule radii /
258
+ * lengths in the config.
259
+ */
260
+ setDebugVisible(visible: boolean): void;
261
+ /** Per-frame: refresh the corners of each body's box, written straight
262
+ * into the line buffer in the lines' parent frame. */
263
+ private _drawDebug;
264
+ /**
265
+ * {@link PoseProvider} implementation. Replaces the entire pose with
266
+ * values derived from the bodies' world transforms.
267
+ *
268
+ * Strategy: reset every bone to bind first, then overwrite the
269
+ * ragdoll-driven bones. Intermediate skeleton bones (e.g. spine_01
270
+ * sitting between pelvis and spine_03) stay at bind - they don't
271
+ * articulate. This is the simplification the "pure physics" mode
272
+ * buys us.
273
+ *
274
+ * The armature object is NOT moved to follow the pelvis. The
275
+ * bone-local TRS we write absorbs the world position; the splat
276
+ * deforms to the physics-driven world either way.
277
+ */
278
+ writePose(pose: Pose, _armature: Armature, _dt: number): void;
279
+ /** Read the bone's current world matrix from the armature's array.
280
+ * Falls back to armatureWorld * bindWorld if the array hasn't been
281
+ * populated yet (e.g. enable() called before the first update()). */
282
+ private _currentBoneWorld;
283
+ }
@@ -51,7 +51,14 @@ export declare class Skeleton {
51
51
  * transforms read the freshly-written parent.
52
52
  *
53
53
  * `out` is reused - entries are created lazily if missing, but the caller
54
- * owns the buffer (no per-frame allocation).
54
+ * owns the buffer (no per-frame allocation). Given `bones` (from
55
+ * {@link subsetOrder}), only those entries are written.
55
56
  */
56
- applyLocal(pose: Pose, entityWorldTransform: Mat4, out: Mat4[]): void;
57
+ applyLocal(pose: Pose, entityWorldTransform: Mat4, out: Mat4[], bones?: Int32Array | null): void;
58
+ /**
59
+ * `bones` and all their ancestors, parents first: the order
60
+ * {@link applyLocal} composes a subset in.
61
+ */
62
+ subsetOrder(bones: Iterable<number>): Int32Array;
63
+ private _composeBone;
57
64
  }
@@ -34,6 +34,8 @@ export interface SplatRenderImpl {
34
34
  syncBoneData(): void;
35
35
  /** Re-upload per-splat group ids after {@link Splat.setSplatGroups}. */
36
36
  syncVariantGroups(): void;
37
+ /** Rebind the relight inputs after {@link Splat.setRelightBinding} swapped one binding for another. */
38
+ syncRelight(): void;
37
39
  /** Called from the host mesh's `onBeforeRender`, once per draw. */
38
40
  beforeRender(renderer: unknown, camera: Camera): void;
39
41
  /** Release GPU resources. The splat's own textures are not this object's to free. */
@@ -35,4 +35,4 @@ export declare function initializeSplatBoneMapping(splat: Splat, numBones: numbe
35
35
  * Returns an empty `Int32Array` when the splat has no weights data - callers
36
36
  * treat that as "fall back to walking every bone."
37
37
  */
38
- export declare function buildSplatBoneIndexList(splat: Splat, numBones: number): Int32Array;
38
+ export declare function buildSplatBoneIndexList(splat: Splat, numBones: number, firstPaletteIdx: number): Int32Array;
@@ -0,0 +1,78 @@
1
+ import type { IUniform } from 'three';
2
+ /**
3
+ * Values the colour hook can read, as TSL nodes. See {@link SplatColorModifier.tsl}.
4
+ *
5
+ * @group Splats
6
+ */
7
+ export interface SplatColorModifierInputs {
8
+ /** World-space centre of the splat, skinned. `vec3`. */
9
+ center: unknown;
10
+ /** Model-space centre, skinned (and cut), before the object's own transform. `vec3`. */
11
+ modelCenter: unknown;
12
+ /** Model-space centre in the rest pose, as stored in the file. `vec3`. */
13
+ restCenter: unknown;
14
+ /** Index of the splat in its cloud. `uint`. */
15
+ splatIndex: unknown;
16
+ /** The colour the engine computed: rgb, and alpha before the gaussian falloff. `vec4`. */
17
+ color: unknown;
18
+ /** One uniform node per {@link SplatColorModifier.uniforms} entry, by the same name. */
19
+ uniforms: Record<string, unknown>;
20
+ }
21
+ /**
22
+ * A per-splat colour hook that runs after the engine's own colour work -
23
+ * lighting, tint, relight, grade, reveal, opacity - and can change any of it.
24
+ *
25
+ * The three.js counterpart of the PlayCanvas build's work-buffer modifier
26
+ * (`setWorkBufferModifier` with `WORK_BUFFER_MODIFIER_GLSL/WGSL`): instead of
27
+ * splicing into the engine's shader source, a game supplies one function per
28
+ * backend and the engine calls it.
29
+ *
30
+ * Give `glsl` for `THREE.WebGLRenderer`, and `wgsl` or `tsl` for
31
+ * `WebGPURenderer`. A splat drawn by a renderer whose source is missing
32
+ * renders as if no hook were set.
33
+ *
34
+ * ```ts
35
+ * const fade = { uFade: { value: 1 } };
36
+ * character.setColorModifier({
37
+ * uniforms: fade,
38
+ * glsl: `void modifySplatColor(vec3 center, vec3 modelCenter, vec3 restCenter, uint splatIndex, inout vec4 color) {
39
+ * color.a *= uFade;
40
+ * }`,
41
+ * wgsl: `fn modifySplatColor(center: vec3f, modelCenter: vec3f, restCenter: vec3f, splatIndex: u32,
42
+ * color: vec4f, uFade: f32) -> vec4f {
43
+ * return vec4f(color.rgb, color.a * uFade);
44
+ * }`,
45
+ * });
46
+ * fade.uFade.value = 0.5; // takes effect next frame
47
+ * ```
48
+ *
49
+ * @group Splats
50
+ */
51
+ export interface SplatColorModifier {
52
+ /**
53
+ * Uniforms the hook reads, by name. Change `.value` at any time; the
54
+ * objects are bound by reference. Values may be numbers or three.js
55
+ * `Vector2/3/4`, `Color`, `Matrix3/4`.
56
+ */
57
+ uniforms?: Record<string, IUniform>;
58
+ /**
59
+ * GLSL ES 3.00 source defining
60
+ * `void modifySplatColor(vec3 center, vec3 modelCenter, vec3 restCenter, uint splatIndex, inout vec4 color)`.
61
+ * May define helpers. Each uniform is declared for you with the GLSL type
62
+ * matching its value; do not redeclare it.
63
+ */
64
+ glsl?: string;
65
+ /**
66
+ * WGSL source defining
67
+ * `fn modifySplatColor(center: vec3f, modelCenter: vec3f, restCenter: vec3f, splatIndex: u32, color: vec4f, ...) -> vec4f`,
68
+ * with one further parameter per uniform, named after it. Used when `tsl`
69
+ * is not given.
70
+ */
71
+ wgsl?: string;
72
+ /** A TSL builder returning the new colour (`vec4`). Takes precedence over `wgsl`. */
73
+ tsl?: (inputs: SplatColorModifierInputs) => unknown;
74
+ }
75
+ /** GLSL type of a uniform value, for the declarations generated around a hook. @internal */
76
+ export declare function glslTypeOf(value: unknown): string;
77
+ /** The GLSL a hook contributes to the vertex stage: declarations, then its source. @internal */
78
+ export declare function colorModifierGLSL(modifier: SplatColorModifier): string;
@@ -0,0 +1,27 @@
1
+ /**
2
+ * The CPU side of a splat "cut" (`Splat.setCutGroups`): packing the per-piece
3
+ * data into the three `numGroups x 1` RGBA32F textures the work-buffer shader
4
+ * reads, and a reference of the shader's per-splat transform for tests.
5
+ */
6
+ export interface PackedCutGroups {
7
+ /** xyz = model-space offset, w = the piece's uniform scale (default 1). */
8
+ offsets: Float32Array;
9
+ /** xyz = pivot (default the origin), w unused. */
10
+ pivots: Float32Array;
11
+ /** xyz = unit rotation axis (default +Y), w = angle in radians (default 0). */
12
+ rotations: Float32Array;
13
+ }
14
+ /**
15
+ * Pack per-piece data for the shader. `offsets` and `pivots` are
16
+ * `numGroups x 3`, `rotations` `numGroups x 4` (axis xyz, angle), `scales`
17
+ * `numGroups`. The scale defaults to 1, never 0, since the shader multiplies
18
+ * by it; the axis defaults to +Y so a stray angle stays well defined.
19
+ */
20
+ export declare function packCutGroups(offsets: ArrayLike<number>, numGroups: number, pivots?: ArrayLike<number>, rotations?: ArrayLike<number>, scales?: ArrayLike<number>): PackedCutGroups;
21
+ /**
22
+ * Where the shader's `applyGroupCut` moves a model-space point of piece `g`
23
+ * at cut `amount`: rotate about the pivot (Rodrigues) by `angle * amount`,
24
+ * scale about the pivot by `mix(1, scale, amount)`, then slide by
25
+ * `offset * amount`. Mirrors the GLSL and WGSL; used by tests.
26
+ */
27
+ export declare function applyGroupCutCpu(point: readonly [number, number, number], packed: PackedCutGroups, g: number, amount: number): [number, number, number];
@@ -19,7 +19,13 @@ export declare function projectBoundsOnDirection(min: ArrayLike<number>, max: Ar
19
19
  /** Synchronous sorter with its own scratch buffers. One per splat. */
20
20
  export declare class DepthSorter {
21
21
  private readonly _scratch;
22
- sort(centers: Float32Array, count: number, dx: number, dy: number, dz: number, depthMin: number, depthMax: number, order: Uint32Array): void;
22
+ /**
23
+ * @param count - How many splats take part. With `subset`, the length of
24
+ * the prefix of it to use; without, the splats are `[0, count)`.
25
+ * @param subset - Splat indices to sort, for a count LOD. See
26
+ * {@link Splat.setCountLod}.
27
+ */
28
+ sort(centers: Float32Array, count: number, dx: number, dy: number, dz: number, depthMin: number, depthMax: number, order: Uint32Array, subset?: Uint32Array | null): void;
23
29
  }
24
30
  export interface SortRequest {
25
31
  dx: number;
@@ -27,6 +33,11 @@ export interface SortRequest {
27
33
  dz: number;
28
34
  depthMin: number;
29
35
  depthMax: number;
36
+ /**
37
+ * How many splats to order, for a count LOD. Defaults to all of them; with
38
+ * a subset set, the length of the prefix of it to use.
39
+ */
40
+ count?: number;
30
41
  }
31
42
  /**
32
43
  * Worker-backed sorter for static splats.
@@ -46,11 +57,18 @@ export declare class AsyncDepthSorter {
46
57
  private _order;
47
58
  /**
48
59
  * @param centers - Flat `[x,y,z] * count`. Copied into the worker once.
49
- * @param onSorted - Called with each finished order. The array is only valid
50
- * for the duration of the call - it goes back to the worker on the next
51
- * request - so copy out of it before returning.
60
+ * @param onSorted - Called with each finished order and how many of its
61
+ * entries are current. The array is only valid for the duration of the call
62
+ * - it goes back to the worker on the next request - so copy out of it
63
+ * before returning.
64
+ */
65
+ constructor(centers: Float32Array, count: number, onSorted: (order: Uint32Array, count: number) => void);
66
+ /**
67
+ * Give the worker the importance ordering a count LOD selects from. Sent
68
+ * once and kept there, like the centres; after this a request carries only
69
+ * how many of its entries to use.
52
70
  */
53
- constructor(centers: Float32Array, count: number, onSorted: (order: Uint32Array) => void);
71
+ setSubset(subset: Uint32Array): void;
54
72
  /** True while a sort is running in the worker. */
55
73
  get busy(): boolean;
56
74
  request(req: SortRequest): void;
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Ranking splats by how much they contribute, and the spatial bucketing both
3
+ * users of that ranking share.
4
+ *
5
+ * Two features are built on it. {@link pruneSplats} throws the weakest splats
6
+ * away at load; the count LOD ({@link Splat.setCountLod}) keeps them all and
7
+ * processes a prefix of the ranking that shrinks with distance. The ranking
8
+ * has to be the same one in both cases, which is why it lives here rather than
9
+ * in either of them.
10
+ */
11
+ import type { PackedSplats } from './packed-splats';
12
+ /**
13
+ * Group indices by spatial cell without a comparison sort: hash the cells to
14
+ * dense ids, count, prefix-sum, scatter.
15
+ *
16
+ * O(n) with one map probe per splat, against the O(n log n) a sort over a
17
+ * composite key would cost - which measured 11-16 ms of a ~40 ms character
18
+ * load in the Unity build this is ported from.
19
+ */
20
+ export declare function bucketByCell(cellKey: Float64Array, n: number): {
21
+ order: Uint32Array;
22
+ start: Uint32Array;
23
+ cells: number;
24
+ };
25
+ /**
26
+ * One splat's cell key on a `1 / voxelSize` grid whose origin is `min`.
27
+ *
28
+ * The one definition of the grid. Both users of it have to agree - a splat
29
+ * pruned by one rule and ranked by another would be thinned twice in the same
30
+ * place - and they walk different layouts, so what they share is this rather
31
+ * than a loop.
32
+ */
33
+ export declare function cellKeyOf(x: number, y: number, z: number, minX: number, minY: number, minZ: number, invVoxel: number): number;
34
+ /**
35
+ * Cell keys for `centers`, with the grid origin at the actual minimum of the
36
+ * positions rather than at any declared bounds, which can carry a margin the
37
+ * grid should not inherit.
38
+ */
39
+ export declare function cellKeysFor(centers: Float32Array, count: number, voxelSize: number): Float64Array;
40
+ /**
41
+ * Splat indices ordered so that any prefix of the result is a good-looking
42
+ * subset of the whole: the most important splat of every cell first, then the
43
+ * second of every cell, and so on.
44
+ *
45
+ * Importance within a cell is opacity times the two largest gaussian axes -
46
+ * the area the splat actually paints, which the Unity build measured as
47
+ * ranking 0.80 with the ink each splat deposits, at no cost to compute.
48
+ *
49
+ * The round-robin across cells is what makes this usable as a prefix, and it
50
+ * is the same decision the load-time prune makes for the same reason: ranked
51
+ * globally, a prefix would be every strong splat on the jacket and none of the
52
+ * many individually-faint ones that make up a face, so the face would be the
53
+ * first thing to go. Taken a rank at a time across cells, every region thins
54
+ * by the same proportion at every prefix length, so a character at 30% looks
55
+ * like a sparser version of itself rather than a damaged one.
56
+ *
57
+ * Costs one pass over the splats plus a small sort inside each cell, and is
58
+ * built once, the first time a count LOD asks for it.
59
+ */
60
+ export declare function buildImportanceOrder(packed: PackedSplats, voxelSize: number): Uint32Array;
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Load-time splat removal: the two passes that make a character cheaper by
3
+ * containing fewer splats, rather than by drawing each one faster.
4
+ *
5
+ * Both run on the decoded attribute columns, before {@link packSplats} turns
6
+ * them into texels, so a removed splat costs nothing anywhere afterwards -
7
+ * no texel, no CPU skinning slot, no sort slot, no quad. That is what
8
+ * separates these from {@link SplatQuality.quadAlphaCutoff}, which shrinks
9
+ * quads and saves rasterisation alone.
10
+ *
11
+ * Ported from the Unity build's `SplatCharacterBinData.CullByOpacity` and
12
+ * `PruneByImportance`, including the two decisions in them that are easy to
13
+ * get wrong: ranking inside spatial cells rather than globally, and selecting
14
+ * rather than sorting within a cell.
15
+ */
16
+ import type { SplatAttributes } from '../loader/character/types';
17
+ import type { SplatWeights } from '../types';
18
+ /** What {@link pruneSplats} did, for a caller that wants to log or report it. */
19
+ export interface PruneReport {
20
+ /** Splats the decode handed in. */
21
+ numSplatsIn: number;
22
+ /** Splats left after both passes. This is what every consumer should read. */
23
+ numSplatsOut: number;
24
+ /** Removed by the opacity floor. */
25
+ droppedByOpacity: number;
26
+ /** Removed by the per-voxel importance quota, on top of the opacity floor. */
27
+ droppedByImportance: number;
28
+ /**
29
+ * The skinning influences, re-viewed onto the compacted prefix when anything
30
+ * was removed, or the caller's own object when nothing was. `undefined` for
31
+ * a splat with no skinning.
32
+ *
33
+ * Handed back rather than mutated in place because the arrays' *length* is
34
+ * what says how many influences each splat has: `Splat` divides it by the
35
+ * splat count to recover `K`, and leaving a pruned set at its original
36
+ * length would make that division report a `K` several times too large.
37
+ */
38
+ weights?: SplatWeights;
39
+ }
40
+ export interface PruneOptions {
41
+ /** Defaults to {@link SplatQuality.minOpacity}. */
42
+ minOpacity?: number;
43
+ /** Defaults to {@link SplatQuality.pruneRatio}. */
44
+ pruneRatio?: number;
45
+ /** Defaults to {@link SplatQuality.pruneVoxelSize}. */
46
+ voxelSize?: number;
47
+ }
48
+ /**
49
+ * Remove splats the current quality settings say are not worth carrying,
50
+ * compacting every column in place.
51
+ *
52
+ * `attributes` and `weights` are mutated: their arrays keep their allocated
53
+ * length and the returned count is what every consumer should read, which is
54
+ * exactly how {@link packSplats} already uses `numSplats`. Order is preserved,
55
+ * so whatever spatial coherence the file had survives.
56
+ *
57
+ * Returns the input count unchanged, having touched nothing, when both knobs
58
+ * are off - the default - so this sits on the load path for free.
59
+ */
60
+ export declare function pruneSplats(numSplats: number, attributes: SplatAttributes, weights?: SplatWeights, opts?: PruneOptions): PruneReport;