@viggle/splat-engine-three 0.1.1 → 0.3.0

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