@viggle/splat-engine-three 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. package/CHANGELOG.md +38 -0
  2. package/README.md +133 -20
  3. package/dist/chunks/chunk-BHNNSHJG.js +22298 -0
  4. package/dist/chunks/chunk-BHNNSHJG.js.map +7 -0
  5. package/dist/index.js +221 -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 +33 -6
  44. package/dist/types/loader/animation/animation-glb.d.ts +4 -4
  45. package/dist/types/loader/character/load.d.ts +6 -1
  46. package/dist/types/loader/environment/lod-bundle.d.ts +123 -0
  47. package/dist/types/loader/environment/spz-decode.d.ts +88 -0
  48. package/dist/types/loader/environment/spz.d.ts +28 -0
  49. package/dist/types/loader/shared/asset-fetch.d.ts +11 -0
  50. package/dist/types/loader/shared/asset-loader.d.ts +86 -0
  51. package/dist/types/loader/shared/bin-cache.d.ts +41 -14
  52. package/dist/types/loader/shared/decode-worker.d.ts +27 -0
  53. package/dist/types/loader/shared/glb.d.ts +30 -0
  54. package/dist/types/loader/shared/inflate.d.ts +9 -0
  55. package/dist/types/loader/shared/pack-splats-task.d.ts +17 -0
  56. package/dist/types/loader/shared/sog-decode.d.ts +81 -0
  57. package/dist/types/loader/shared/sog.d.ts +17 -0
  58. package/dist/types/math.d.ts +7 -0
  59. package/dist/types/physics/ammo.d.ts +210 -0
  60. package/dist/types/physics/index.d.ts +11 -0
  61. package/dist/types/physics/joints.d.ts +157 -0
  62. package/dist/types/physics/physics-world.d.ts +193 -0
  63. package/dist/types/physics/rigid-body.d.ts +361 -0
  64. package/dist/types/presets/camera/camera-preset.d.ts +43 -0
  65. package/dist/types/presets/camera/third-person-camera.d.ts +63 -0
  66. package/dist/types/presets/character/body-shape.d.ts +109 -0
  67. package/dist/types/presets/character/character-reveal.d.ts +90 -0
  68. package/dist/types/presets/character/socket-loadout.d.ts +61 -0
  69. package/dist/types/presets/index.d.ts +13 -0
  70. package/dist/types/presets/vfx/mesh-flash.d.ts +51 -0
  71. package/dist/types/presets/visual/bone-overlay.d.ts +57 -0
  72. package/dist/types/proxy/environment-input.d.ts +30 -0
  73. package/dist/types/proxy/environment-source.d.ts +39 -0
  74. package/dist/types/proxy/proxy-debug.d.ts +106 -0
  75. package/dist/types/proxy/splat-source.d.ts +42 -0
  76. package/dist/types/proxy/voxelizer.d.ts +383 -0
  77. package/dist/types/relight/backend.d.ts +101 -0
  78. package/dist/types/relight/index.d.ts +6 -0
  79. package/dist/types/relight/relight-pass.d.ts +367 -0
  80. package/dist/types/relight/relight-placeholder.d.ts +2 -0
  81. package/dist/types/relight/relight-shaders.d.ts +4 -0
  82. package/dist/types/relight/shadow-bias.d.ts +26 -0
  83. package/dist/types/relight/splat-relight.d.ts +741 -0
  84. package/dist/types/relight/webgl-backend.d.ts +3 -0
  85. package/dist/types/relight/webgpu/backend.d.ts +3 -0
  86. package/dist/types/relight/webgpu-register.d.ts +2 -0
  87. package/dist/types/scene.d.ts +241 -0
  88. package/dist/types/skeletal/animation-player.d.ts +31 -3
  89. package/dist/types/skeletal/body-parts.d.ts +55 -0
  90. package/dist/types/skeletal/ragdoll-config.d.ts +115 -0
  91. package/dist/types/skeletal/ragdoll.d.ts +283 -0
  92. package/dist/types/skeletal/skeleton.d.ts +9 -2
  93. package/dist/types/splat/backend.d.ts +2 -0
  94. package/dist/types/splat/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 +1123 -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
@@ -3,7 +3,11 @@ import type { Frustum } from 'three';
3
3
  import type { SplatEngine } from '../engine';
4
4
  import type { Mat4 } from '../math';
5
5
  import type { SplatWeights } from '../types';
6
+ import type { SplatColorModifier } from './color-modifier';
6
7
  import type { PackedSplats } from './packed-splats';
8
+ import type { SplatRelightBinding } from './relight-binding';
9
+ import type { RevealSkeleton } from './reveal-bake';
10
+ import type { RevealLook } from './reveal-look';
7
11
  import { SplatMesh } from './splat-mesh';
8
12
  import { TransformPalette } from './transform-palette';
9
13
  /** What a {@link Splat} is built from: packed gaussians, plus skinning data for characters. */
@@ -61,6 +65,21 @@ export declare class Splat {
61
65
  readonly tint: Vector4;
62
66
  /** x contrast, y saturation. Shared with the material by reference. */
63
67
  readonly grade: Vector2;
68
+ /**
69
+ * x opacity, y reveal amount, z reveal inverse (0/1), w cut amount. Shared
70
+ * with the material by reference. `(1, 1, 0, 0)` changes nothing.
71
+ */
72
+ readonly effects: Vector4;
73
+ /** Reveal look: band (width, hold, max stretch), sketch (lead, density, dot scale), tint (rgb, luminance floor). */
74
+ readonly revealBand: Vector4;
75
+ readonly revealSketch: Vector4;
76
+ readonly revealTint: Vector4;
77
+ /** Per-splat feet-to-head distance for the reveal. Skinned splats only, after {@link setReveal} opts in. */
78
+ revealDistanceTexture?: DataTexture;
79
+ /** Per-piece cut data, `numGroups x 1` each: offset + scale, pivot, axis + angle. See {@link setCutGroups}. */
80
+ groupOffsetsTexture?: DataTexture;
81
+ groupPivotsTexture?: DataTexture;
82
+ groupRotsTexture?: DataTexture;
64
83
  linkedArmature: any;
65
84
  /** Skinning influences normalised to exactly four slots per splat. */
66
85
  splatWeights?: SplatWeights;
@@ -92,6 +111,13 @@ export declare class Splat {
92
111
  private _pendingBoneTransforms;
93
112
  private _flatBones;
94
113
  private _variantMaskEnabled;
114
+ private _cutEnabled;
115
+ private _revealEnabled;
116
+ private _revealBaked;
117
+ private _colorModifier;
118
+ private _relight;
119
+ private _boneMapFirstIdx;
120
+ private _boneMapRemap;
95
121
  private _nonRigidCov;
96
122
  private _antiAlias;
97
123
  private _destroyed;
@@ -194,6 +220,134 @@ export declare class Splat {
194
220
  }): void;
195
221
  /** Per-splat colour grade. `(1, 1)` is a true no-op. */
196
222
  setGrade(contrast: number, saturation: number): void;
223
+ /**
224
+ * Like {@link setTint}, but multiplies: the splat colour times `color`, by
225
+ * `strength` (0..1). Darkens or browns while keeping the splat's own
226
+ * variation (cooking, scorching). `setTint` goes back to the mix.
227
+ */
228
+ setTintMultiply(strength: number, color?: {
229
+ r: number;
230
+ g: number;
231
+ b: number;
232
+ }): void;
233
+ /** Multiply every splat's alpha by `opacity` (0..1); 1, the default, leaves it. */
234
+ setOpacity(opacity: number): void;
235
+ /** The value last given to {@link setOpacity}. */
236
+ get opacity(): number;
237
+ /**
238
+ * Reveal amount in [0, 1]. At 1 (the default) the splat renders unchanged.
239
+ * Below 1 a bright front walks from feet to head, with sparse dots just
240
+ * ahead of it. Zero is invisible. `inverse` keeps the area ahead of the
241
+ * front instead, for outgoing transitions.
242
+ *
243
+ * The first call below 1 (or with `inverse`) opts the splat in: it bakes
244
+ * the per-splat distances through the linked {@link Armature} and rebuilds
245
+ * the shader. Call {@link Armature.prepareReveal} after loading to pay that
246
+ * up front. A splat that is never revealed pays nothing.
247
+ */
248
+ setReveal(amount: number, inverse?: boolean): void;
249
+ /**
250
+ * Change how the reveal looks. Unset fields keep their current value; the
251
+ * starting look is {@link DEFAULT_REVEAL_LOOK}.
252
+ */
253
+ setRevealLook(look: RevealLook): void;
254
+ /** Whether the reveal has been opted into - see {@link setReveal}. */
255
+ get revealEnabled(): boolean;
256
+ /** Whether {@link bakeReveal} has run for this splat. */
257
+ get revealBaked(): boolean;
258
+ private _enableReveal;
259
+ /**
260
+ * Bake the per-splat reveal distances against `skeleton`, opting the splat
261
+ * into the reveal. Called by {@link Armature.prepareReveal}.
262
+ *
263
+ * @param boneRemap - Splat bone index to armature bone, `-1` when unmapped,
264
+ * or `null` when the splat's bones are the armature's.
265
+ */
266
+ bakeReveal(skeleton: RevealSkeleton, boneRemap: ArrayLike<number> | null): void;
267
+ /** Whether {@link setCutGroups} has opted this splat in. */
268
+ get cutEnabled(): boolean;
269
+ /**
270
+ * Opt this splat into a "cut": its splats split into pieces that slide,
271
+ * tumble and scale apart. `groupIds` tags each splat with a piece; each
272
+ * piece gets a model-space `offset`, and optionally a `pivot` and a
273
+ * `rotation` (it tumbles rigidly about its pivot) and a uniform `scale`
274
+ * about the pivot. Starts fully cut ({@link setCut} 1); animate with
275
+ * `setCut`. Uses the {@link setSplatGroups} group ids.
276
+ *
277
+ * @param groupIds - per-splat piece, length {@link numSplats}.
278
+ * @param offsets - `numGroups x 3` model-space offsets.
279
+ * @param numGroups - the number of pieces.
280
+ * @param pivots - optional `numGroups x 3` pivots (default the origin).
281
+ * @param rotations - optional `numGroups x 4`: unit axis xyz, angle (rad).
282
+ * @param scales - optional `numGroups` uniform scales (default 1).
283
+ */
284
+ setCutGroups(groupIds: Uint8Array, offsets: Float32Array, numGroups: number, pivots?: Float32Array, rotations?: Float32Array, scales?: Float32Array): void;
285
+ /**
286
+ * Rewrite the pieces' offsets, pivots, rotations and scales without a
287
+ * shader rebuild, e.g. to dice finer on each chop, then show them fully
288
+ * cut. No-op before {@link setCutGroups}, or with more groups than it
289
+ * allocated.
290
+ */
291
+ setCutOffsets(offsets: Float32Array, numGroups: number, pivots?: Float32Array, rotations?: Float32Array, scales?: Float32Array): void;
292
+ /** How far apart the pieces are: 0 whole, 1 fully cut. No-op before {@link setCutGroups}. */
293
+ setCut(amount: number): void;
294
+ private _uploadCutData;
295
+ /** Set {@link localBounds} to the uncut bounds grown by the cut's reach, once. @internal */
296
+ private _padForCut;
297
+ private _cutPad;
298
+ private readonly _uncutBounds;
299
+ /** The hook set by {@link setColorModifier}, or `null`. */
300
+ get colorModifier(): SplatColorModifier | null;
301
+ /**
302
+ * Run a colour hook of the game's own on every splat, after the engine's
303
+ * colour work - see {@link SplatColorModifier}. `null` removes it. Each
304
+ * call rebuilds the shader; change the hook's uniforms to animate it.
305
+ */
306
+ setColorModifier(modifier: SplatColorModifier | null): void;
307
+ /** The relight writing into this splat, or `null`. @internal */
308
+ get relightBinding(): SplatRelightBinding | null;
309
+ /**
310
+ * Attach the per-splat output of a {@link SplatRelight}, or detach it with
311
+ * `null`. Rebuilds the shader when the relight turns on or off.
312
+ * @internal
313
+ */
314
+ setRelightBinding(binding: SplatRelightBinding | null): void;
315
+ /**
316
+ * Put the splat on exactly these three.js layers (0..31), for cameras that
317
+ * render a subset of the scene. `[0]` is the default.
318
+ */
319
+ setLayers(layerIds: number[]): void;
320
+ /**
321
+ * Record the palette base and source->target remap the armature chose when
322
+ * it bound this splat, so a later {@link reuploadBoneWeights} writes
323
+ * palette slots, not raw rig indices.
324
+ */
325
+ rememberBoneMapping(firstIdx: number, _numBones: number, remap: Int32Array | null): void;
326
+ /**
327
+ * `true` once this splat's bone weights are its own to edit. Splats built
328
+ * from shared decoded data (clones, overlays) share
329
+ * {@link Splat.splatWeights} until {@link privatizeBoneWeights}.
330
+ */
331
+ get boneWeightsArePrivate(): boolean;
332
+ private _weightsPrivate;
333
+ /**
334
+ * Give this splat its own copy of {@link Splat.splatWeights}, so editing
335
+ * them (a ragdoll detaching a limb, hit-based weight pruning) and calling
336
+ * {@link reuploadBoneWeights} leaves every other splat alone. Idempotent.
337
+ */
338
+ privatizeBoneWeights(): void;
339
+ /**
340
+ * Upload the current {@link Splat.splatWeights} to the GPU after editing
341
+ * them, through the palette mapping the armature chose. Call
342
+ * {@link privatizeBoneWeights} first.
343
+ */
344
+ reuploadBoneWeights(): void;
345
+ /**
346
+ * Splat centres (splat-local) in the latest pose. Under WebGL they are
347
+ * kept current anyway; under WebGPU this skins them on the CPU on demand,
348
+ * for picking or ground probes.
349
+ */
350
+ posedCenters(): Float32Array;
197
351
  /**
198
352
  * Assign each splat to a group and enable per-group visibility. All groups
199
353
  * start visible; toggle them with {@link Splat.setVariantMask}.
@@ -1,2 +1,6 @@
1
- export declare const SPLAT_VERTEX_GLSL = "\nprecision highp float;\nprecision highp int;\nprecision highp usampler2D;\n\n// Quad corner in [-1, 1].\nin vec3 position;\n// Index of the splat this instance draws; instances arrive back-to-front.\nin uint splatOrder;\n\nuniform mat4 modelMatrix;\nuniform mat4 viewMatrix;\nuniform mat4 projectionMatrix;\n\nuniform highp usampler2D tTransformA;\nuniform highp sampler2D tTransformB;\nuniform highp sampler2D tColor;\nuniform int uTexWidth;\n\n// Drawing-buffer size in pixels.\nuniform vec2 uViewport;\nuniform float uMinPixelSize;\n// 1 / the alpha a splat's quad is allowed to end at. Carried as the reciprocal\n// so the historic 1/255 cutoff arrives as exactly 255.0 and the two\n// expressions below reduce, bit for bit, to what they were before the cutoff\n// was a setting at all. See SplatQuality.quadAlphaCutoff.\nuniform float uAlphaCutoffScale;\n// World rotation (xyzw) and scale of the splat object.\nuniform vec4 uModelRotation;\nuniform vec3 uModelScale;\n// rgb tint colour, a tint amount.\nuniform vec4 uTint;\n// x contrast, y saturation.\nuniform vec2 uGrade;\n// 1 when the render target expects linear colour, 0 when it is display-referred.\nuniform float uOutputLinear;\n\nout mediump vec2 gaussianUV;\nout mediump vec4 gaussianColor;\n\n\nuniform vec3 uSunColor;\nuniform float uSunIntensity;\nuniform vec3 uAmbientColor;\nuniform int uPointLightCount;\nuniform highp sampler2D uPointLightTex;\n\n// Baked splat colour is multiplied by this. With no lights it is exactly 1.\nvec3 computeLitFactor(vec3 worldCenter) {\n vec3 lit = uAmbientColor + uSunColor * uSunIntensity;\n for (int i = 0; i < uPointLightCount; i++) {\n vec4 posRange = texelFetch(uPointLightTex, ivec2(i, 0), 0);\n vec4 colorInt = texelFetch(uPointLightTex, ivec2(i, 1), 0);\n vec3 toLight = posRange.xyz - worldCenter;\n float dist = length(toLight);\n float range = posRange.w;\n if (dist >= range) continue;\n float t = dist / range;\n float atten = 1.0 - t * t;\n atten = atten * atten;\n lit += colorInt.rgb * colorInt.w * atten;\n }\n return lit;\n}\n\n\nuniform highp sampler2D transformPalette;\n\n#ifdef USE_BONE_BLENDING\nuniform highp sampler2D boneIndices;\nuniform highp sampler2D boneWeights;\n#endif\n\n#ifdef USE_VARIANT_MASK\nuniform highp sampler2D splatGroupIds;\nuniform highp sampler2D splatVariantMask;\n\nbool isSplatHiddenByVariantMask(ivec2 splatUV) {\n float gidF = texelFetch(splatGroupIds, splatUV, 0).r;\n int gid = int(gidF + 0.5);\n float bit = texelFetch(splatVariantMask, ivec2(gid, 0), 0).r;\n return bit < 0.5;\n}\n#endif\n\nbool isReasonablePaletteTransform(mat4 t) {\n mat3 lin = mat3(t);\n vec3 s = vec3(length(lin[0]), length(lin[1]), length(lin[2]));\n // Reject only when EVERY column is near-zero (a truly empty palette slot).\n // Linear-blend skinning of two very different bone rotations produces a\n // candy-wrapper matrix with one short column; that is still a valid\n // mid-rotation transform. Requiring all columns to pass would collapse\n // joint-spanning splats (notably the neck) back to the bind pose.\n return any(greaterThan(s, vec3(1e-4)));\n}\n\nmat4 readTransformFromPalette(uint paletteIndex) {\n if (paletteIndex == 0u) {\n return mat4(1.0);\n }\n\n int u = int(paletteIndex % 512u) * 3;\n int v = int(paletteIndex / 512u);\n\n mat4 t;\n t[0] = texelFetch(transformPalette, ivec2(u, v), 0);\n t[1] = texelFetch(transformPalette, ivec2(u + 1, v), 0);\n t[2] = texelFetch(transformPalette, ivec2(u + 2, v), 0);\n t[3] = vec4(0.0, 0.0, 0.0, 1.0);\n\n mat4 result = transpose(t);\n if (!isReasonablePaletteTransform(result)) {\n return mat4(1.0);\n }\n return result;\n}\n\nmat4 getSplatPaletteTransform(ivec2 splatUV) {\n #ifdef USE_BONE_BLENDING\n vec4 boneIdxVec = texelFetch(boneIndices, splatUV, 0);\n vec4 boneWeightVec = texelFetch(boneWeights, splatUV, 0);\n float totalWeight = dot(boneWeightVec, vec4(1.0));\n if (totalWeight > 0.001) {\n mat4 blended = mat4(0.0);\n for (int i = 0; i < 4; i++) {\n float w = boneWeightVec[i];\n if (w > 0.001) {\n uint idx = uint(boneIdxVec[i] + 0.5);\n blended += readTransformFromPalette(idx) * w;\n }\n }\n mat4 result = blended / totalWeight;\n if (isReasonablePaletteTransform(result)) {\n return result;\n }\n }\n #endif\n\n return mat4(1.0);\n}\n\nvec4 mat3ToQuatXYZW(mat3 R) {\n vec4 q;\n float trace = R[0][0] + R[1][1] + R[2][2];\n if (trace > 0.0) {\n float s = sqrt(trace + 1.0) * 2.0;\n q.w = 0.25 * s;\n q.x = (R[1][2] - R[2][1]) / s;\n q.y = (R[2][0] - R[0][2]) / s;\n q.z = (R[0][1] - R[1][0]) / s;\n } else if (R[0][0] > R[1][1] && R[0][0] > R[2][2]) {\n float s = sqrt(1.0 + R[0][0] - R[1][1] - R[2][2]) * 2.0;\n q.w = (R[1][2] - R[2][1]) / s;\n q.x = 0.25 * s;\n q.y = (R[1][0] + R[0][1]) / s;\n q.z = (R[2][0] + R[0][2]) / s;\n } else if (R[1][1] > R[2][2]) {\n float s = sqrt(1.0 + R[1][1] - R[0][0] - R[2][2]) * 2.0;\n q.w = (R[2][0] - R[0][2]) / s;\n q.x = (R[1][0] + R[0][1]) / s;\n q.y = 0.25 * s;\n q.z = (R[2][1] + R[1][2]) / s;\n } else {\n float s = sqrt(1.0 + R[2][2] - R[0][0] - R[1][1]) * 2.0;\n q.w = (R[0][1] - R[1][0]) / s;\n q.x = (R[2][0] + R[0][2]) / s;\n q.y = (R[2][1] + R[1][2]) / s;\n q.z = 0.25 * s;\n }\n return q;\n}\n\n\nconst vec4 discardVec = vec4(0.0, 0.0, 2.0, 1.0);\n\nmat3 quatToMat3(vec4 R) {\n vec4 R2 = R + R;\n float X = R2.x * R.w;\n vec4 Y = R2.y * R;\n vec4 Z = R2.z * R;\n float W = R2.w * R.w;\n return mat3(\n 1.0 - Z.z - W, Y.z + X, Y.w - Z.x,\n Y.z - X, 1.0 - Y.y - W, Z.w + Y.x,\n Y.w + Z.x, Z.w - Y.x, 1.0 - Y.y - Z.z\n );\n}\n\nvec4 quatMul(vec4 a, vec4 b) {\n return vec4(\n a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,\n a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,\n a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,\n a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z\n );\n}\n\nvoid computeCovariance(vec4 rotation, vec3 scale, out vec3 covA, out vec3 covB) {\n mat3 rot = quatToMat3(rotation);\n mat3 M = transpose(mat3(\n scale.x * rot[0],\n scale.y * rot[1],\n scale.z * rot[2]\n ));\n covA = vec3(dot(M[0], M[0]), dot(M[0], M[1]), dot(M[0], M[2]));\n covB = vec3(dot(M[1], M[1]), dot(M[1], M[2]), dot(M[2], M[2]));\n}\n\nvec3 sRGBToLinear(vec3 c) {\n return mix(\n pow(c * 0.9478672986 + vec3(0.0521327014), vec3(2.4)),\n c * 0.0773993808,\n vec3(lessThanEqual(c, vec3(0.04045)))\n );\n}\n\nvoid main(void) {\n ivec2 splatUV = ivec2(int(splatOrder % uint(uTexWidth)), int(splatOrder / uint(uTexWidth)));\n uvec4 tA = texelFetch(tTransformA, splatUV, 0);\n vec4 tB = texelFetch(tTransformB, splatUV, 0);\n\n vec3 modelCenter = uintBitsToFloat(tA.xyz);\n vec3 packedRot = vec3(unpackHalf2x16(tA.w), tB.w);\n // xyzw, with w recovered: quaternions are stored on the w >= 0 hemisphere.\n vec4 srcRotation = vec4(packedRot, sqrt(max(0.0, 1.0 - dot(packedRot, packedRot))));\n vec3 srcScale = tB.xyz;\n\n // ---- Skin, then lift to world space --------------------------------\n mat4 palette = getSplatPaletteTransform(splatUV);\n vec3 modelDeformed = (palette * vec4(modelCenter, 1.0)).xyz;\n vec3 worldCenter = (modelMatrix * vec4(modelDeformed, 1.0)).xyz;\n\n vec4 worldRotation = quatMul(uModelRotation, srcRotation);\n if (worldRotation.w < 0.0) worldRotation = -worldRotation;\n vec3 worldScale = uModelScale * srcScale;\n\n #ifdef USE_BONE_BLENDING\n {\n // The full world-space skinning rotation comes from modelMatrix * palette;\n // the palette's own scale is deliberately dropped (rigid skinning).\n mat3 lin = mat3(modelMatrix * palette);\n vec3 s = vec3(length(lin[0]), length(lin[1]), length(lin[2]));\n if (s.x > 1e-5 && s.y > 1e-5 && s.z > 1e-5) {\n mat3 rot = mat3(lin[0] / s.x, lin[1] / s.y, lin[2] / s.z);\n vec4 composed = normalize(quatMul(mat3ToQuatXYZW(rot), srcRotation));\n if (composed.w < 0.0) composed = -composed;\n worldRotation = composed;\n }\n #ifdef USE_NONRIGID_COV\n // Bone-length scaling: the palette keeps its per-axis scale and the\n // gaussian stretches with the bone.\n worldScale *= s;\n #endif\n }\n #endif\n\n #ifdef USE_VARIANT_MASK\n if (isSplatHiddenByVariantMask(splatUV)) {\n gl_Position = discardVec;\n return;\n }\n #endif\n\n // ---- Project the centre --------------------------------------------\n bool ortho = projectionMatrix[3][3] == 1.0;\n vec4 centerView = viewMatrix * vec4(worldCenter, 1.0);\n if (!ortho && centerView.z > 0.0) {\n gl_Position = discardVec;\n return;\n }\n vec4 centerProj = projectionMatrix * centerView;\n centerProj.z = clamp(centerProj.z, -abs(centerProj.w), abs(centerProj.w));\n\n // ---- Project the covariance to a screen-space ellipse ----------------\n vec3 covA, covB;\n computeCovariance(worldRotation.wxyz, worldScale, covA, covB);\n mat3 Vrk = mat3(\n covA.x, covA.y, covA.z,\n covA.y, covB.x, covB.y,\n covA.z, covB.y, covB.z\n );\n\n float focal = uViewport.x * projectionMatrix[0][0];\n vec3 v = centerView.xyz;\n vec3 vp = ortho ? vec3(0.0, 0.0, 1.0) : v;\n float J1 = focal / vp.z;\n vec2 J2 = -J1 / vp.z * vp.xy;\n mat3 J = mat3(\n J1, 0.0, J2.x,\n 0.0, J1, J2.y,\n 0.0, 0.0, 0.0\n );\n mat3 W = transpose(mat3(viewMatrix));\n mat3 T = W * J;\n mat3 cov = transpose(T) * Vrk * T;\n\n #ifdef USE_ANTIALIAS\n float detOrig = cov[0][0] * cov[1][1] - cov[0][1] * cov[0][1];\n float detBlur = (cov[0][0] + 0.3) * (cov[1][1] + 0.3) - cov[0][1] * cov[0][1];\n float aaFactor = sqrt(max(detOrig / detBlur, 0.0));\n #endif\n\n float diagonal1 = cov[0][0] + 0.3;\n float offDiagonal = cov[0][1];\n float diagonal2 = cov[1][1] + 0.3;\n float mid = 0.5 * (diagonal1 + diagonal2);\n float radius = length(vec2((diagonal1 - diagonal2) / 2.0, offDiagonal));\n float lambda1 = mid + radius;\n float lambda2 = max(mid - radius, 0.1);\n\n float vmin = min(1024.0, min(uViewport.x, uViewport.y));\n float l1 = 2.0 * min(sqrt(2.0 * lambda1), vmin);\n float l2 = 2.0 * min(sqrt(2.0 * lambda2), vmin);\n if (max(l1, l2) < uMinPixelSize) {\n gl_Position = discardVec;\n return;\n }\n\n // Cull splats whose ellipse lies wholly off-screen.\n vec2 c = centerProj.ww / uViewport;\n if (any(greaterThan(abs(centerProj.xy) - vec2(max(l1, l2)) * c, centerProj.ww))) {\n gl_Position = discardVec;\n return;\n }\n\n vec2 diagonalVector = normalize(vec2(offDiagonal, lambda1 - diagonal1));\n vec2 v1 = l1 * diagonalVector;\n vec2 v2 = l2 * vec2(diagonalVector.y, -diagonalVector.x);\n vec2 cornerUV = position.xy;\n vec2 offset = (cornerUV.x * v1 + cornerUV.y * v2) * c;\n\n // ---- Colour -----------------------------------------------------------\n vec4 clr = texelFetch(tColor, splatUV, 0);\n #ifdef USE_ANTIALIAS\n clr.a *= aaFactor;\n #endif\n\n clr.rgb *= computeLitFactor(worldCenter);\n clr.rgb = mix(clr.rgb, uTint.rgb, clamp(uTint.a, 0.0, 1.0));\n // Identity grade is a true no-op: skipping it keeps HDR splat colours unclamped.\n if (uGrade.x != 1.0 || uGrade.y != 1.0) {\n clr.rgb = (clr.rgb - 0.5) * uGrade.x + 0.5;\n float luma = dot(clr.rgb, vec3(0.2126, 0.7152, 0.0722));\n clr.rgb = mix(vec3(luma), clr.rgb, uGrade.y);\n clr.rgb = clamp(clr.rgb, 0.0, 1.0);\n }\n\n // A splat whose peak alpha is already under the cutoff cannot put a\n // fragment on screen: its own quad would be empty.\n float alphaOverCutoff = clr.a * uAlphaCutoffScale;\n if (alphaOverCutoff <= 1.0) {\n gl_Position = discardVec;\n return;\n }\n\n // Shrink the quad to where the gaussian is still above the cutoff: fewer\n // fragments. At a cutoff of 1/255 the pixels are identical, since below\n // that frag() discards anyway; above it, this is the trade the setting\n // exists to make.\n float clip = min(1.0, sqrt(log(alphaOverCutoff)) * 0.5);\n offset *= clip;\n\n gl_Position = centerProj + vec4(offset, 0.0, 0.0);\n gaussianUV = cornerUV * clip;\n\n vec3 rgb = max(clr.rgb, 0.0);\n if (uOutputLinear > 0.5) rgb = sRGBToLinear(rgb);\n gaussianColor = vec4(rgb, clr.a);\n}\n";
1
+ /**
2
+ * The vertex stage, with a game colour hook (`USE_COLOR_MODIFIER`) spliced in
3
+ * where given. See SplatColorModifier.
4
+ */
5
+ export declare function splatVertexGLSL(colorModifier?: string): string;
2
6
  export declare const SPLAT_FRAGMENT_GLSL = "\nprecision highp float;\n\nin mediump vec2 gaussianUV;\nin mediump vec4 gaussianColor;\n\nlayout(location = 0) out highp vec4 fragColor;\n\nconst float EXP4 = exp(-4.0);\nconst float INV_EXP4 = 1.0 / (1.0 - EXP4);\n\n// exp(-4x) rescaled to hit exactly 0 at the quad edge (x = 1).\nfloat normExp(float x) {\n return (exp(x * -4.0) - EXP4) * INV_EXP4;\n}\n\nvoid main(void) {\n mediump float A = dot(gaussianUV, gaussianUV);\n if (A > 1.0) {\n discard;\n }\n mediump float alpha = normExp(A) * gaussianColor.a;\n if (alpha < 1.0 / 255.0) {\n discard;\n }\n // Premultiplied.\n fragColor = vec4(gaussianColor.rgb * alpha, alpha);\n}\n";
@@ -30,6 +30,8 @@ export declare class WebGLSplatImpl implements SplatRenderImpl {
30
30
  private _lastDz;
31
31
  /** The importance ordering the worker already holds, if any. */
32
32
  private _sentSubset;
33
+ /** Names of the colour hook's uniforms currently on the material. */
34
+ private _hookUniforms;
33
35
  /**
34
36
  * @param asyncSort - Sort in a worker and keep drawing the previous order
35
37
  * meanwhile. Right for large static splats; wrong for skinned ones, whose
@@ -42,6 +44,8 @@ export declare class WebGLSplatImpl implements SplatRenderImpl {
42
44
  requestSort(): void;
43
45
  /** Rebuild the shader variant after a feature toggle on the splat. */
44
46
  syncDefines(): void;
47
+ /** Point the relight uniforms at the splat's current binding. */
48
+ syncRelight(): void;
45
49
  /** The bone textures are the splat's own; flagging them is all there is to do. */
46
50
  syncBoneData(): void;
47
51
  /** Group ids live in the splat's own texture, which it flags itself. */
@@ -1,3 +1,4 @@
1
+ import { StorageBufferAttribute } from 'three/webgpu';
1
2
  type Node = any;
2
3
  /** Sort keys are 16 bits, sorted as two 8-bit digits. */
3
4
  export declare const SORT_KEY_BITS = 16;
@@ -35,6 +36,8 @@ export declare class GpuRadixSort {
35
36
  readonly resetNode: Node;
36
37
  /** Run, in order, after the pass that writes keys. */
37
38
  readonly sortNodes: Node[];
39
+ /** Every buffer the sort allocated, for the owner to free with its nodes. */
40
+ readonly attributes: StorageBufferAttribute[];
38
41
  private readonly _firstHistogram;
39
42
  constructor(count: number);
40
43
  /**
@@ -44,12 +44,27 @@ export declare class WebGPUSplatImpl implements SplatRenderImpl {
44
44
  private _projectNodes;
45
45
  /** The sort proper - needed only when the depth ORDER may have changed. */
46
46
  private _sortNodes;
47
+ /** Storage buffers the current build allocated. */
48
+ private _buffers;
49
+ /** Nodes and buffers of builds since replaced, freed on the next frame. */
50
+ private _retired;
51
+ /** The renderer that drew this splat, which owns its GPU buffers. */
52
+ private _renderer;
47
53
  private readonly _lastInputs;
48
54
  private readonly _inputs;
49
55
  private readonly _lastSortDirection;
50
56
  private _buildId;
51
57
  private _sortedBuildId;
52
58
  private _allNodes;
59
+ /** Relight texture nodes, re-pointed when the binding's textures change. */
60
+ private _relightTex;
61
+ private _relightShadowTex;
62
+ /** Cut texture nodes [offsets, pivots, rotations], re-pointed when a re-cut reallocates them. */
63
+ private _cutTex;
64
+ /** True when the colour can change with no input this backend can see (a game hook). */
65
+ private _alwaysProject;
66
+ /** Copies the game hook's uniform values into their nodes. */
67
+ private _syncHook;
53
68
  private readonly _u;
54
69
  constructor(host: Mesh, splat: Splat, lighting: WebGPULighting);
55
70
  /** The sort runs in the same frame as the draw; the order is never stale. */
@@ -59,6 +74,8 @@ export declare class WebGPUSplatImpl implements SplatRenderImpl {
59
74
  syncDefines(): void;
60
75
  syncBounds(): void;
61
76
  syncBoneData(): void;
77
+ /** The relight textures are re-pointed every frame; a new binding only needs a rebuild when one turns on or off. */
78
+ syncRelight(): void;
62
79
  syncVariantGroups(): void;
63
80
  /**
64
81
  * (Re)create the storage buffers, compute nodes and material nodes. Runs at
@@ -70,4 +87,10 @@ export declare class WebGPUSplatImpl implements SplatRenderImpl {
70
87
  /** Refresh this splat's uniforms and run whatever compute this frame needs. */
71
88
  private _prepare;
72
89
  dispose(): void;
90
+ /**
91
+ * Dispose replaced compute nodes and free their storage buffers. three.js
92
+ * frees a compute node's pipeline and bindings on dispose, but not the
93
+ * buffers they read; those it only frees with a geometry they belong to.
94
+ */
95
+ private _freeRetired;
73
96
  }
@@ -6,6 +6,8 @@ import { Character } from '../character';
6
6
  import type { SplatEngine } from '../engine';
7
7
  import type { CharacterBundle } from '../loader/character/load';
8
8
  import type { BodyRegion, BoneMask } from '../skeletal/bone-mask';
9
+ import type { SplatColorModifier } from '../splat/color-modifier';
10
+ import type { RevealLook } from '../splat/reveal-look';
9
11
  import type { Splat } from '../splat/splat';
10
12
  /**
11
13
  * What a clip's horizontal travel does to the character.
@@ -169,8 +171,34 @@ export declare class SplatCharacter extends Object3D<SplatCharacterEventMap> {
169
171
  * flash, a selection highlight. `amount = 0` restores the authored colour.
170
172
  */
171
173
  setTint(color: ColorRepresentation, amount?: number): this;
174
+ /**
175
+ * Multiply the character's colour by `color`, by `amount` (0..1): darkens or
176
+ * browns while keeping the character's own variation. {@link setTint}
177
+ * returns to the blend.
178
+ */
179
+ setTintMultiply(color: ColorRepresentation, amount?: number): this;
172
180
  /** Contrast and saturation multipliers for the character's colour. `(1, 1)` is unchanged. */
173
181
  setGrade(contrast: number, saturation: number): this;
182
+ /** Alpha multiplier for the whole character, 0..1. `1` draws it unchanged. */
183
+ get opacity(): number;
184
+ set opacity(value: number);
185
+ /**
186
+ * Reveal the character with a bright front walking from feet to head:
187
+ * `amount` 0 is hidden, 1 is the character unchanged. `inverse` keeps the
188
+ * part ahead of the front, for a character going out. The first call below
189
+ * 1 prepares the effect, which costs a frame on a large character; call
190
+ * {@link prepareReveal} after loading to pay it up front.
191
+ */
192
+ setReveal(amount: number, inverse?: boolean): this;
193
+ /** How the reveal looks; unset fields keep their value. See {@link RevealLook}. */
194
+ setRevealLook(look: RevealLook): this;
195
+ /** Pay the reveal's one-time setup now rather than on its first frame. */
196
+ prepareReveal(): this;
197
+ /**
198
+ * Run a colour function of your own on every splat after the engine's
199
+ * colour work; `null` removes it. See {@link SplatColorModifier}.
200
+ */
201
+ setColorModifier(modifier: SplatColorModifier | null): this;
174
202
  /**
175
203
  * Draw fewer of this character's splats as it gets further away.
176
204
  *
@@ -0,0 +1,35 @@
1
+ import { Loader } from 'three';
2
+ import type { LoadingManager } from 'three';
3
+ import { SplatEngine } from '../engine';
4
+ import type { SplatMesh } from '../splat/splat-mesh';
5
+ /**
6
+ * Loads an `.spz` Gaussian-splat capture (versions 1 to 4) as a static
7
+ * {@link SplatMesh}, the way {@link SplatPLYLoader} loads a `.ply`.
8
+ *
9
+ * ```ts
10
+ * const field = await new SplatSPZLoader().loadAsync('/assets/field.spz');
11
+ * scene.add(field);
12
+ * ```
13
+ *
14
+ * The file decodes and packs in a worker; version 4's zstd streams are
15
+ * inflated on the calling thread first, since no browser offers zstd to
16
+ * script. The mesh is given `renderOrder = -1` so it draws before characters,
17
+ * as {@link SplatPLYLoader}'s is.
18
+ *
19
+ * SPZ stores no coordinate convention of its own and none is applied here:
20
+ * the splats come out in the file's axes, as the PlayCanvas build reads them.
21
+ *
22
+ * @group Loaders
23
+ */
24
+ export declare class SplatSPZLoader extends Loader<SplatMesh> {
25
+ /**
26
+ * The engine loaded meshes belong to: the lights they respond to. Leave
27
+ * unset to use {@link SplatEngine.shared}.
28
+ */
29
+ engine: SplatEngine | null;
30
+ constructor(manager?: LoadingManager);
31
+ setEngine(engine: SplatEngine | null): this;
32
+ /** Decode bytes already in memory. `name` labels the mesh; for a loaded file it is the file's base name. */
33
+ parseAsync(data: ArrayBuffer, name?: string): Promise<SplatMesh>;
34
+ load(url: string, onLoad: (result: SplatMesh) => void, onProgress?: (event: ProgressEvent) => void, onError?: (error: unknown) => void): void;
35
+ }
@@ -19,6 +19,12 @@ export interface ArmatureData {
19
19
  stdMaleRestTranslations?: Float32Array;
20
20
  stdMaleRestRotations?: Float32Array;
21
21
  stdMaleParents?: Int32Array;
22
+ /**
23
+ * This rig's own bone names, index-aligned with the arrays above. Set for a
24
+ * rig that is not one of the bundled skeletons (a mesh character's GLB
25
+ * skeleton); name lookups then read these instead of the scene's library.
26
+ */
27
+ boneNames?: string[];
22
28
  }
23
29
  /** Per-splat skinning influences, `K` slots per splat. */
24
30
  export interface SplatWeights {