@viggle/splat-engine-three 0.1.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +58 -0
- package/README.md +158 -20
- package/dist/chunks/chunk-2GKWT24B.js +23182 -0
- package/dist/chunks/chunk-2GKWT24B.js.map +7 -0
- package/dist/index.js +235 -3
- package/dist/types/anim/animation-conversion.d.ts +2 -2
- package/dist/types/anim/keyframe-splines.d.ts +17 -41
- package/dist/types/animation.d.ts +84 -28
- package/dist/types/armature.d.ts +280 -2
- package/dist/types/character.d.ts +120 -2
- package/dist/types/effects/index.d.ts +12 -0
- package/dist/types/effects/outlines/outline-effect.d.ts +98 -0
- package/dist/types/effects/outlines/outline-shaders.d.ts +14 -0
- package/dist/types/effects/pixelart/pixelart-effect.d.ts +152 -0
- package/dist/types/effects/pixelart/pixelart-shaders.d.ts +31 -0
- package/dist/types/effects/postfx/base-capturing-pass.d.ts +109 -0
- package/dist/types/effects/postfx/camera-frame.d.ts +103 -0
- package/dist/types/effects/postfx/frame-renderer.d.ts +32 -0
- package/dist/types/effects/postfx/frame-shaders.d.ts +19 -0
- package/dist/types/effects/postfx/mask.d.ts +44 -0
- package/dist/types/effects/postfx/postfx.d.ts +144 -0
- package/dist/types/effects/postfx/program.d.ts +74 -0
- package/dist/types/effects/postfx/uniforms.d.ts +24 -0
- package/dist/types/effects/postfx/webgl-program.d.ts +6 -0
- package/dist/types/effects/postfx/webgpu-program.d.ts +3 -0
- package/dist/types/effects/vfx/data-types.d.ts +100 -0
- package/dist/types/effects/vfx/index.d.ts +37 -0
- package/dist/types/effects/vfx/json-vfx-prefab.d.ts +94 -0
- package/dist/types/effects/vfx/layer-renderer.d.ts +118 -0
- package/dist/types/effects/vfx/layers/mesh.d.ts +124 -0
- package/dist/types/effects/vfx/layers/particle.d.ts +90 -0
- package/dist/types/effects/vfx/layers/shader.d.ts +130 -0
- package/dist/types/effects/vfx/layers/shared.d.ts +40 -0
- package/dist/types/effects/vfx/layers/sprite.d.ts +45 -0
- package/dist/types/effects/vfx/pool.d.ts +51 -0
- package/dist/types/effects/vfx/prefab.d.ts +48 -0
- package/dist/types/effects/vfx/prewarm.d.ts +17 -0
- package/dist/types/effects/vfx/stage.d.ts +115 -0
- package/dist/types/effects/vfx/webgpu-register.d.ts +2 -0
- package/dist/types/effects/webgpu-register.d.ts +2 -0
- package/dist/types/engine.d.ts +18 -0
- package/dist/types/environment.d.ts +96 -8
- package/dist/types/index.d.ts +35 -6
- package/dist/types/loader/animation/animation-glb.d.ts +4 -4
- package/dist/types/loader/character/load.d.ts +6 -1
- package/dist/types/loader/environment/lod-bundle.d.ts +123 -0
- package/dist/types/loader/environment/spz-decode.d.ts +88 -0
- package/dist/types/loader/environment/spz.d.ts +28 -0
- package/dist/types/loader/shared/asset-fetch.d.ts +11 -0
- package/dist/types/loader/shared/asset-loader.d.ts +86 -0
- package/dist/types/loader/shared/bin-cache.d.ts +41 -14
- package/dist/types/loader/shared/decode-worker.d.ts +27 -0
- package/dist/types/loader/shared/glb.d.ts +30 -0
- package/dist/types/loader/shared/inflate.d.ts +9 -0
- package/dist/types/loader/shared/pack-splats-task.d.ts +17 -0
- package/dist/types/loader/shared/sog-decode.d.ts +81 -0
- package/dist/types/loader/shared/sog.d.ts +17 -0
- package/dist/types/math.d.ts +198 -13
- package/dist/types/physics/ammo.d.ts +217 -0
- package/dist/types/physics/index.d.ts +11 -0
- package/dist/types/physics/joints.d.ts +206 -0
- package/dist/types/physics/physics-world.d.ts +194 -0
- package/dist/types/physics/rigid-body.d.ts +361 -0
- package/dist/types/presets/camera/camera-preset.d.ts +43 -0
- package/dist/types/presets/camera/third-person-camera.d.ts +63 -0
- package/dist/types/presets/character/body-shape.d.ts +109 -0
- package/dist/types/presets/character/character-reveal.d.ts +90 -0
- package/dist/types/presets/character/socket-loadout.d.ts +61 -0
- package/dist/types/presets/index.d.ts +13 -0
- package/dist/types/presets/vfx/mesh-flash.d.ts +51 -0
- package/dist/types/presets/visual/bone-overlay.d.ts +57 -0
- package/dist/types/proxy/environment-input.d.ts +30 -0
- package/dist/types/proxy/environment-source.d.ts +39 -0
- package/dist/types/proxy/proxy-debug.d.ts +106 -0
- package/dist/types/proxy/splat-source.d.ts +42 -0
- package/dist/types/proxy/voxelizer.d.ts +383 -0
- package/dist/types/relight/backend.d.ts +101 -0
- package/dist/types/relight/index.d.ts +6 -0
- package/dist/types/relight/relight-pass.d.ts +367 -0
- package/dist/types/relight/relight-placeholder.d.ts +2 -0
- package/dist/types/relight/relight-shaders.d.ts +4 -0
- package/dist/types/relight/shadow-bias.d.ts +26 -0
- package/dist/types/relight/splat-relight.d.ts +760 -0
- package/dist/types/relight/webgl-backend.d.ts +3 -0
- package/dist/types/relight/webgpu/backend.d.ts +3 -0
- package/dist/types/relight/webgpu-register.d.ts +2 -0
- package/dist/types/scene.d.ts +291 -0
- package/dist/types/skeletal/animation-player.d.ts +31 -3
- package/dist/types/skeletal/body-parts.d.ts +55 -0
- package/dist/types/skeletal/ragdoll-config.d.ts +115 -0
- package/dist/types/skeletal/ragdoll.d.ts +283 -0
- package/dist/types/skeletal/skeleton.d.ts +9 -2
- package/dist/types/splat/backend.d.ts +2 -0
- package/dist/types/splat/color-modifier.d.ts +78 -0
- package/dist/types/splat/cut-groups.d.ts +27 -0
- package/dist/types/splat/relight-binding.d.ts +39 -0
- package/dist/types/splat/reveal-bake.d.ts +43 -0
- package/dist/types/splat/reveal-look.d.ts +64 -0
- package/dist/types/splat/splat-mesh.d.ts +1 -0
- package/dist/types/splat/splat.d.ts +154 -0
- package/dist/types/splat/webgl/shaders.d.ts +5 -1
- package/dist/types/splat/webgl/splat-mesh.d.ts +4 -0
- package/dist/types/splat/webgpu/radix-sort.d.ts +3 -0
- package/dist/types/splat/webgpu/splat-mesh.d.ts +23 -0
- package/dist/types/three/splat-character.d.ts +28 -0
- package/dist/types/three/spz-loader.d.ts +35 -0
- package/dist/types/types.d.ts +6 -0
- package/dist/webgpu.js +1137 -154
- package/dist/webgpu.js.map +4 -4
- package/package.json +6 -2
- package/dist/chunks/chunk-WN5WBKM4.js +0 -8606
- package/dist/chunks/chunk-WN5WBKM4.js.map +0 -7
|
@@ -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. */
|
|
@@ -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];
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { Matrix4, Vector3, Vector4 } from 'three';
|
|
2
|
+
import type { Texture } from 'three';
|
|
3
|
+
/**
|
|
4
|
+
* What a relight writes for one splat: the screen-space lighting it rendered
|
|
5
|
+
* for the splat's proxy, and how to sample it. The splat shader projects each
|
|
6
|
+
* splat centre through {@link viewProjection} into {@link texture} and
|
|
7
|
+
* multiplies its colour by the lighting found there.
|
|
8
|
+
*
|
|
9
|
+
* The {@link SplatRelight} system owns and updates these; a splat only reads
|
|
10
|
+
* them. Every field is bound by reference, so a relight updates a binding in
|
|
11
|
+
* place and the next frame picks it up.
|
|
12
|
+
*
|
|
13
|
+
* Mirrors the PlayCanvas build's `uRelight*` work-buffer uniforms.
|
|
14
|
+
*
|
|
15
|
+
* @internal
|
|
16
|
+
*/
|
|
17
|
+
export declare class SplatRelightBinding {
|
|
18
|
+
/** rgb = lighting, a = proxy coverage. */
|
|
19
|
+
texture: Texture | null;
|
|
20
|
+
/** r = shadow visibility, g = coverage. */
|
|
21
|
+
shadowTexture: Texture | null;
|
|
22
|
+
/** The view-projection the textures were rendered with. */
|
|
23
|
+
readonly viewProjection: Matrix4;
|
|
24
|
+
/** xy = 1 / texture size, z = 1 / reference luminance, w = 1 when the textures are valid. */
|
|
25
|
+
readonly params: Vector4;
|
|
26
|
+
/** 0..1: how much of the lighting is applied. */
|
|
27
|
+
strength: number;
|
|
28
|
+
readonly tint: Vector3;
|
|
29
|
+
/** Lighting floor, so a splat in full shade keeps some of its colour. */
|
|
30
|
+
ambient: number;
|
|
31
|
+
/** 0..1: how much of the shadow is applied. */
|
|
32
|
+
shadowStrength: number;
|
|
33
|
+
/** 1 when the textures' rows run top-down. */
|
|
34
|
+
flipY: number;
|
|
35
|
+
/** 0 off, 1 lighting debug colours, 2 shadow visibility. */
|
|
36
|
+
debug: number;
|
|
37
|
+
/** Bumped by the relight whenever a field changes, so a backend can skip work. */
|
|
38
|
+
version: number;
|
|
39
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The reveal's per-splat bake: a continuous feet-to-head coordinate along the
|
|
3
|
+
* skeleton, so the front of {@link Splat.setReveal} walks up the body rather
|
|
4
|
+
* than sweeping a flat plane. Pure, so it runs without a GPU.
|
|
5
|
+
*/
|
|
6
|
+
/** Skeleton distances shared by every splat of one character. */
|
|
7
|
+
export interface RevealSkeleton {
|
|
8
|
+
/** Bind-pose bone positions, `numBones * 3`. */
|
|
9
|
+
pos: Float32Array;
|
|
10
|
+
/** Distance from the nearest foot; `-1` = off the body graph. */
|
|
11
|
+
chain: Float32Array;
|
|
12
|
+
/** Parents, with deformation helpers flattened out. */
|
|
13
|
+
parents: Int32Array;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Distances along the body graph, measured from the nearest foot. Pelvis is
|
|
17
|
+
* `pelvisHint` when given, else from the rig's bone names; failing both, the
|
|
18
|
+
* bone nearest `centre`.
|
|
19
|
+
*/
|
|
20
|
+
export declare function buildRevealSkeleton(pos: Float32Array, parents: ArrayLike<number>, names: readonly string[], centre: {
|
|
21
|
+
x: number;
|
|
22
|
+
y: number;
|
|
23
|
+
z: number;
|
|
24
|
+
}, pelvisHint?: number): RevealSkeleton | null;
|
|
25
|
+
/** A splat cloud's rest positions and its `k` bone influences per splat. */
|
|
26
|
+
export interface RevealSplats {
|
|
27
|
+
x: ArrayLike<number>;
|
|
28
|
+
y: ArrayLike<number>;
|
|
29
|
+
z: ArrayLike<number>;
|
|
30
|
+
indices: ArrayLike<number>;
|
|
31
|
+
weights: ArrayLike<number>;
|
|
32
|
+
numSplats: number;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Write each splat's normalized distance, 0 at the feet and 1 at the far end
|
|
36
|
+
* of the body, into `out`: its position projected onto the nearest bone
|
|
37
|
+
* segment of its influences, interpolated along {@link RevealSkeleton.chain}.
|
|
38
|
+
* Returns false, leaving `out` untouched, when the skeleton has no length.
|
|
39
|
+
*
|
|
40
|
+
* @param boneRemap - Splat bone index to skeleton bone, `-1` when unmapped,
|
|
41
|
+
* or `null` when they already agree.
|
|
42
|
+
*/
|
|
43
|
+
export declare function bakeRevealDistances(out: Float32Array, splats: RevealSplats, skeleton: RevealSkeleton, boneRemap: ArrayLike<number> | null): boolean;
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How a character reveal looks: a bright band that walks the skeleton from
|
|
3
|
+
* feet to head, with sparse sketch dots just ahead of it. Distances are
|
|
4
|
+
* fractions of that feet-to-head path. Every field is optional; unset fields
|
|
5
|
+
* keep their current value. See {@link Character.setReveal}.
|
|
6
|
+
*
|
|
7
|
+
* @group Splats
|
|
8
|
+
*/
|
|
9
|
+
export interface RevealLook {
|
|
10
|
+
/** Width of the bright band behind the front. */
|
|
11
|
+
bandWidth?: number;
|
|
12
|
+
/** Share of the band held at full brightness before it fades, 0-1. */
|
|
13
|
+
bandHold?: number;
|
|
14
|
+
/** Longest a splat may stretch inside the band, in multiples of its shortest axis. */
|
|
15
|
+
bandMaxStretch?: number;
|
|
16
|
+
/** How far ahead of the front the sketch dots start. */
|
|
17
|
+
sketchLead?: number;
|
|
18
|
+
/** Share of splats drawn as sketch dots, 0-1. */
|
|
19
|
+
sketchDensity?: number;
|
|
20
|
+
/** Size of a sketch dot relative to its splat. */
|
|
21
|
+
sketchScale?: number;
|
|
22
|
+
/** Colour the band leans toward, 0-1 per channel. */
|
|
23
|
+
tint?: {
|
|
24
|
+
r: number;
|
|
25
|
+
g: number;
|
|
26
|
+
b: number;
|
|
27
|
+
};
|
|
28
|
+
/** Luminance below which the band is lifted toward {@link tint}. */
|
|
29
|
+
tintFloor?: number;
|
|
30
|
+
}
|
|
31
|
+
/** The engine's default reveal look. */
|
|
32
|
+
export declare const DEFAULT_REVEAL_LOOK: Readonly<Required<RevealLook>>;
|
|
33
|
+
/**
|
|
34
|
+
* The default look for an ENVIRONMENT reveal, where the sweep is radial
|
|
35
|
+
* distance from the capture point rather than a path up a body. Distances are
|
|
36
|
+
* fractions of the room's radius either way, so these are the same numbers
|
|
37
|
+
* read against a different subject - and the subject is what moves them.
|
|
38
|
+
*
|
|
39
|
+
* A body's feet-to-head coordinate is a line: a narrow band shows a thin ring
|
|
40
|
+
* of it, and a sweep up it is legible. A room's radius is a SHELL, and a
|
|
41
|
+
* Flow2D capture keeps most of its splats in the one shell that is its walls,
|
|
42
|
+
* so the character's 0.07 band crosses nearly the whole room in a single
|
|
43
|
+
* instant - a flashbulb, not an assembly. The band is wider here and holds
|
|
44
|
+
* less of its width at full brightness, which turns that slab into a front
|
|
45
|
+
* with a falloff behind it; a wide band at the character's 0.6 hold would be
|
|
46
|
+
* a wall of white across the entire frame instead.
|
|
47
|
+
*
|
|
48
|
+
* The dots thin out for the same reason. A character is a few hundred
|
|
49
|
+
* thousand splats in the middle of the frame, where 15% of them reads as a
|
|
50
|
+
* sketch; a scene is millions of them filling it edge to edge, where 15%
|
|
51
|
+
* reads as fog. They also lead by more than the band is wide, so the shape of
|
|
52
|
+
* the room is legible just before it lands.
|
|
53
|
+
*
|
|
54
|
+
* The colour is deliberately the character's, unchanged: the two reveals are
|
|
55
|
+
* one effect seen on two subjects, and a scene that assembled in a different
|
|
56
|
+
* hue would say they were not.
|
|
57
|
+
*/
|
|
58
|
+
export declare const DEFAULT_ENV_REVEAL_LOOK: Readonly<Required<RevealLook>>;
|
|
59
|
+
/**
|
|
60
|
+
* Write the set fields of `look` into the shader's three uniforms:
|
|
61
|
+
* `band` = (width, hold, max stretch), `sketch` = (lead, density, dot scale),
|
|
62
|
+
* `tint` = (r, g, b, luminance floor).
|
|
63
|
+
*/
|
|
64
|
+
export declare function packRevealLook(look: RevealLook, band: Float32Array, sketch: Float32Array, tint: Float32Array): void;
|
|
@@ -47,6 +47,7 @@ export declare class SplatMesh extends Mesh {
|
|
|
47
47
|
syncBounds(): void;
|
|
48
48
|
syncBoneData(): void;
|
|
49
49
|
syncVariantGroups(): void;
|
|
50
|
+
syncRelight(): void;
|
|
50
51
|
onBeforeRender(renderer: unknown, _scene: unknown, camera: Camera): void;
|
|
51
52
|
/**
|
|
52
53
|
* A second mesh drawing the same splat data, at the same transform. The
|