@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.
- package/CHANGELOG.md +38 -0
- package/README.md +306 -33
- package/dist/chunks/chunk-BHNNSHJG.js +22298 -0
- package/dist/chunks/chunk-BHNNSHJG.js.map +7 -0
- package/dist/index.js +225 -3
- package/dist/types/anim/animation-conversion.d.ts +2 -2
- package/dist/types/anim/keyframe-splines.d.ts +17 -41
- package/dist/types/animation.d.ts +84 -28
- package/dist/types/armature.d.ts +280 -2
- package/dist/types/character.d.ts +163 -3
- package/dist/types/effects/index.d.ts +12 -0
- package/dist/types/effects/outlines/outline-effect.d.ts +98 -0
- package/dist/types/effects/outlines/outline-shaders.d.ts +14 -0
- package/dist/types/effects/pixelart/pixelart-effect.d.ts +152 -0
- package/dist/types/effects/pixelart/pixelart-shaders.d.ts +31 -0
- package/dist/types/effects/postfx/base-capturing-pass.d.ts +109 -0
- package/dist/types/effects/postfx/camera-frame.d.ts +103 -0
- package/dist/types/effects/postfx/frame-renderer.d.ts +32 -0
- package/dist/types/effects/postfx/frame-shaders.d.ts +19 -0
- package/dist/types/effects/postfx/mask.d.ts +44 -0
- package/dist/types/effects/postfx/postfx.d.ts +144 -0
- package/dist/types/effects/postfx/program.d.ts +74 -0
- package/dist/types/effects/postfx/uniforms.d.ts +24 -0
- package/dist/types/effects/postfx/webgl-program.d.ts +6 -0
- package/dist/types/effects/postfx/webgpu-program.d.ts +3 -0
- package/dist/types/effects/vfx/data-types.d.ts +100 -0
- package/dist/types/effects/vfx/index.d.ts +37 -0
- package/dist/types/effects/vfx/json-vfx-prefab.d.ts +94 -0
- package/dist/types/effects/vfx/layer-renderer.d.ts +118 -0
- package/dist/types/effects/vfx/layers/mesh.d.ts +124 -0
- package/dist/types/effects/vfx/layers/particle.d.ts +90 -0
- package/dist/types/effects/vfx/layers/shader.d.ts +130 -0
- package/dist/types/effects/vfx/layers/shared.d.ts +40 -0
- package/dist/types/effects/vfx/layers/sprite.d.ts +45 -0
- package/dist/types/effects/vfx/pool.d.ts +51 -0
- package/dist/types/effects/vfx/prefab.d.ts +48 -0
- package/dist/types/effects/vfx/prewarm.d.ts +17 -0
- package/dist/types/effects/vfx/stage.d.ts +115 -0
- package/dist/types/effects/vfx/webgpu-register.d.ts +2 -0
- package/dist/types/effects/webgpu-register.d.ts +2 -0
- package/dist/types/engine.d.ts +18 -0
- package/dist/types/environment.d.ts +96 -8
- package/dist/types/index.d.ts +36 -6
- package/dist/types/loader/animation/animation-glb.d.ts +4 -4
- package/dist/types/loader/character/load.d.ts +6 -1
- package/dist/types/loader/environment/lod-bundle.d.ts +123 -0
- package/dist/types/loader/environment/spz-decode.d.ts +88 -0
- package/dist/types/loader/environment/spz.d.ts +28 -0
- package/dist/types/loader/shared/asset-fetch.d.ts +11 -0
- package/dist/types/loader/shared/asset-loader.d.ts +86 -0
- package/dist/types/loader/shared/bin-cache.d.ts +41 -14
- package/dist/types/loader/shared/decode-worker.d.ts +27 -0
- package/dist/types/loader/shared/glb.d.ts +30 -0
- package/dist/types/loader/shared/inflate.d.ts +9 -0
- package/dist/types/loader/shared/pack-splats-task.d.ts +17 -0
- package/dist/types/loader/shared/sog-decode.d.ts +81 -0
- package/dist/types/loader/shared/sog.d.ts +17 -0
- package/dist/types/math.d.ts +7 -0
- package/dist/types/physics/ammo.d.ts +210 -0
- package/dist/types/physics/index.d.ts +11 -0
- package/dist/types/physics/joints.d.ts +157 -0
- package/dist/types/physics/physics-world.d.ts +193 -0
- package/dist/types/physics/rigid-body.d.ts +361 -0
- package/dist/types/presets/camera/camera-preset.d.ts +43 -0
- package/dist/types/presets/camera/third-person-camera.d.ts +63 -0
- package/dist/types/presets/character/body-shape.d.ts +109 -0
- package/dist/types/presets/character/character-reveal.d.ts +90 -0
- package/dist/types/presets/character/socket-loadout.d.ts +61 -0
- package/dist/types/presets/index.d.ts +13 -0
- package/dist/types/presets/vfx/mesh-flash.d.ts +51 -0
- package/dist/types/presets/visual/bone-overlay.d.ts +57 -0
- package/dist/types/proxy/environment-input.d.ts +30 -0
- package/dist/types/proxy/environment-source.d.ts +39 -0
- package/dist/types/proxy/proxy-debug.d.ts +106 -0
- package/dist/types/proxy/splat-source.d.ts +42 -0
- package/dist/types/proxy/voxelizer.d.ts +383 -0
- package/dist/types/relight/backend.d.ts +101 -0
- package/dist/types/relight/index.d.ts +6 -0
- package/dist/types/relight/relight-pass.d.ts +367 -0
- package/dist/types/relight/relight-placeholder.d.ts +2 -0
- package/dist/types/relight/relight-shaders.d.ts +4 -0
- package/dist/types/relight/shadow-bias.d.ts +26 -0
- package/dist/types/relight/splat-relight.d.ts +741 -0
- package/dist/types/relight/webgl-backend.d.ts +3 -0
- package/dist/types/relight/webgpu/backend.d.ts +3 -0
- package/dist/types/relight/webgpu-register.d.ts +2 -0
- package/dist/types/scene.d.ts +241 -0
- package/dist/types/skeletal/animation-player.d.ts +31 -3
- package/dist/types/skeletal/body-parts.d.ts +55 -0
- package/dist/types/skeletal/ragdoll-config.d.ts +115 -0
- package/dist/types/skeletal/ragdoll.d.ts +283 -0
- package/dist/types/skeletal/skeleton.d.ts +9 -2
- package/dist/types/splat/backend.d.ts +2 -0
- package/dist/types/splat/bone-binding.d.ts +1 -1
- package/dist/types/splat/color-modifier.d.ts +78 -0
- package/dist/types/splat/cut-groups.d.ts +27 -0
- package/dist/types/splat/depth-sort.d.ts +23 -5
- package/dist/types/splat/importance.d.ts +60 -0
- package/dist/types/splat/prune.d.ts +60 -0
- package/dist/types/splat/quality.d.ts +175 -0
- package/dist/types/splat/relight-binding.d.ts +39 -0
- package/dist/types/splat/reveal-bake.d.ts +43 -0
- package/dist/types/splat/reveal-look.d.ts +64 -0
- package/dist/types/splat/splat-mesh.d.ts +1 -0
- package/dist/types/splat/splat.d.ts +220 -0
- package/dist/types/splat/webgl/shaders.d.ts +5 -1
- package/dist/types/splat/webgl/splat-mesh.d.ts +6 -0
- package/dist/types/splat/webgpu/radix-sort.d.ts +3 -0
- package/dist/types/splat/webgpu/splat-mesh.d.ts +25 -0
- package/dist/types/three/splat-character.d.ts +56 -0
- package/dist/types/three/spz-loader.d.ts +35 -0
- package/dist/types/types.d.ts +6 -0
- package/dist/webgpu.js +1155 -156
- package/dist/webgpu.js.map +4 -4
- package/package.json +6 -2
- package/dist/chunks/chunk-MM6DJU6S.js +0 -7801
- 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
|
-
|
|
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
|
|
50
|
-
*
|
|
51
|
-
* request - so copy out of it
|
|
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
|
-
|
|
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;
|