@viggle/splat-engine-three 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (117) hide show
  1. package/CHANGELOG.md +38 -0
  2. package/README.md +306 -33
  3. package/dist/chunks/chunk-BHNNSHJG.js +22298 -0
  4. package/dist/chunks/chunk-BHNNSHJG.js.map +7 -0
  5. package/dist/index.js +225 -3
  6. package/dist/types/anim/animation-conversion.d.ts +2 -2
  7. package/dist/types/anim/keyframe-splines.d.ts +17 -41
  8. package/dist/types/animation.d.ts +84 -28
  9. package/dist/types/armature.d.ts +280 -2
  10. package/dist/types/character.d.ts +163 -3
  11. package/dist/types/effects/index.d.ts +12 -0
  12. package/dist/types/effects/outlines/outline-effect.d.ts +98 -0
  13. package/dist/types/effects/outlines/outline-shaders.d.ts +14 -0
  14. package/dist/types/effects/pixelart/pixelart-effect.d.ts +152 -0
  15. package/dist/types/effects/pixelart/pixelart-shaders.d.ts +31 -0
  16. package/dist/types/effects/postfx/base-capturing-pass.d.ts +109 -0
  17. package/dist/types/effects/postfx/camera-frame.d.ts +103 -0
  18. package/dist/types/effects/postfx/frame-renderer.d.ts +32 -0
  19. package/dist/types/effects/postfx/frame-shaders.d.ts +19 -0
  20. package/dist/types/effects/postfx/mask.d.ts +44 -0
  21. package/dist/types/effects/postfx/postfx.d.ts +144 -0
  22. package/dist/types/effects/postfx/program.d.ts +74 -0
  23. package/dist/types/effects/postfx/uniforms.d.ts +24 -0
  24. package/dist/types/effects/postfx/webgl-program.d.ts +6 -0
  25. package/dist/types/effects/postfx/webgpu-program.d.ts +3 -0
  26. package/dist/types/effects/vfx/data-types.d.ts +100 -0
  27. package/dist/types/effects/vfx/index.d.ts +37 -0
  28. package/dist/types/effects/vfx/json-vfx-prefab.d.ts +94 -0
  29. package/dist/types/effects/vfx/layer-renderer.d.ts +118 -0
  30. package/dist/types/effects/vfx/layers/mesh.d.ts +124 -0
  31. package/dist/types/effects/vfx/layers/particle.d.ts +90 -0
  32. package/dist/types/effects/vfx/layers/shader.d.ts +130 -0
  33. package/dist/types/effects/vfx/layers/shared.d.ts +40 -0
  34. package/dist/types/effects/vfx/layers/sprite.d.ts +45 -0
  35. package/dist/types/effects/vfx/pool.d.ts +51 -0
  36. package/dist/types/effects/vfx/prefab.d.ts +48 -0
  37. package/dist/types/effects/vfx/prewarm.d.ts +17 -0
  38. package/dist/types/effects/vfx/stage.d.ts +115 -0
  39. package/dist/types/effects/vfx/webgpu-register.d.ts +2 -0
  40. package/dist/types/effects/webgpu-register.d.ts +2 -0
  41. package/dist/types/engine.d.ts +18 -0
  42. package/dist/types/environment.d.ts +96 -8
  43. package/dist/types/index.d.ts +36 -6
  44. package/dist/types/loader/animation/animation-glb.d.ts +4 -4
  45. package/dist/types/loader/character/load.d.ts +6 -1
  46. package/dist/types/loader/environment/lod-bundle.d.ts +123 -0
  47. package/dist/types/loader/environment/spz-decode.d.ts +88 -0
  48. package/dist/types/loader/environment/spz.d.ts +28 -0
  49. package/dist/types/loader/shared/asset-fetch.d.ts +11 -0
  50. package/dist/types/loader/shared/asset-loader.d.ts +86 -0
  51. package/dist/types/loader/shared/bin-cache.d.ts +41 -14
  52. package/dist/types/loader/shared/decode-worker.d.ts +27 -0
  53. package/dist/types/loader/shared/glb.d.ts +30 -0
  54. package/dist/types/loader/shared/inflate.d.ts +9 -0
  55. package/dist/types/loader/shared/pack-splats-task.d.ts +17 -0
  56. package/dist/types/loader/shared/sog-decode.d.ts +81 -0
  57. package/dist/types/loader/shared/sog.d.ts +17 -0
  58. package/dist/types/math.d.ts +7 -0
  59. package/dist/types/physics/ammo.d.ts +210 -0
  60. package/dist/types/physics/index.d.ts +11 -0
  61. package/dist/types/physics/joints.d.ts +157 -0
  62. package/dist/types/physics/physics-world.d.ts +193 -0
  63. package/dist/types/physics/rigid-body.d.ts +361 -0
  64. package/dist/types/presets/camera/camera-preset.d.ts +43 -0
  65. package/dist/types/presets/camera/third-person-camera.d.ts +63 -0
  66. package/dist/types/presets/character/body-shape.d.ts +109 -0
  67. package/dist/types/presets/character/character-reveal.d.ts +90 -0
  68. package/dist/types/presets/character/socket-loadout.d.ts +61 -0
  69. package/dist/types/presets/index.d.ts +13 -0
  70. package/dist/types/presets/vfx/mesh-flash.d.ts +51 -0
  71. package/dist/types/presets/visual/bone-overlay.d.ts +57 -0
  72. package/dist/types/proxy/environment-input.d.ts +30 -0
  73. package/dist/types/proxy/environment-source.d.ts +39 -0
  74. package/dist/types/proxy/proxy-debug.d.ts +106 -0
  75. package/dist/types/proxy/splat-source.d.ts +42 -0
  76. package/dist/types/proxy/voxelizer.d.ts +383 -0
  77. package/dist/types/relight/backend.d.ts +101 -0
  78. package/dist/types/relight/index.d.ts +6 -0
  79. package/dist/types/relight/relight-pass.d.ts +367 -0
  80. package/dist/types/relight/relight-placeholder.d.ts +2 -0
  81. package/dist/types/relight/relight-shaders.d.ts +4 -0
  82. package/dist/types/relight/shadow-bias.d.ts +26 -0
  83. package/dist/types/relight/splat-relight.d.ts +741 -0
  84. package/dist/types/relight/webgl-backend.d.ts +3 -0
  85. package/dist/types/relight/webgpu/backend.d.ts +3 -0
  86. package/dist/types/relight/webgpu-register.d.ts +2 -0
  87. package/dist/types/scene.d.ts +241 -0
  88. package/dist/types/skeletal/animation-player.d.ts +31 -3
  89. package/dist/types/skeletal/body-parts.d.ts +55 -0
  90. package/dist/types/skeletal/ragdoll-config.d.ts +115 -0
  91. package/dist/types/skeletal/ragdoll.d.ts +283 -0
  92. package/dist/types/skeletal/skeleton.d.ts +9 -2
  93. package/dist/types/splat/backend.d.ts +2 -0
  94. package/dist/types/splat/bone-binding.d.ts +1 -1
  95. package/dist/types/splat/color-modifier.d.ts +78 -0
  96. package/dist/types/splat/cut-groups.d.ts +27 -0
  97. package/dist/types/splat/depth-sort.d.ts +23 -5
  98. package/dist/types/splat/importance.d.ts +60 -0
  99. package/dist/types/splat/prune.d.ts +60 -0
  100. package/dist/types/splat/quality.d.ts +175 -0
  101. package/dist/types/splat/relight-binding.d.ts +39 -0
  102. package/dist/types/splat/reveal-bake.d.ts +43 -0
  103. package/dist/types/splat/reveal-look.d.ts +64 -0
  104. package/dist/types/splat/splat-mesh.d.ts +1 -0
  105. package/dist/types/splat/splat.d.ts +220 -0
  106. package/dist/types/splat/webgl/shaders.d.ts +5 -1
  107. package/dist/types/splat/webgl/splat-mesh.d.ts +6 -0
  108. package/dist/types/splat/webgpu/radix-sort.d.ts +3 -0
  109. package/dist/types/splat/webgpu/splat-mesh.d.ts +25 -0
  110. package/dist/types/three/splat-character.d.ts +56 -0
  111. package/dist/types/three/spz-loader.d.ts +35 -0
  112. package/dist/types/types.d.ts +6 -0
  113. package/dist/webgpu.js +1155 -156
  114. package/dist/webgpu.js.map +4 -4
  115. package/package.json +6 -2
  116. package/dist/chunks/chunk-MM6DJU6S.js +0 -7801
  117. package/dist/chunks/chunk-MM6DJU6S.js.map +0 -7
@@ -0,0 +1,741 @@
1
+ import { Color, DirectionalLight, PointLight } from 'three';
2
+ import type { Camera, Light } from 'three';
3
+ import type { Character } from '../character';
4
+ import { Environment } from '../environment';
5
+ import type { ProxyMeshResult, ProxySurfaceStyle } from '../proxy/voxelizer';
6
+ import type { Scene } from '../scene';
7
+ import { Splat } from '../splat/splat';
8
+ import type { EnvironmentRefreshMode } from './relight-pass';
9
+ /**
10
+ * What {@link SplatRelight.preview} shows.
11
+ *
12
+ * - `off` - nothing.
13
+ * - `voxels` - the exact voxel cell boundary as lines, blocky and unsmoothed
14
+ * whatever surface the proxy uses. This is what `voxelSize` is judged
15
+ * against.
16
+ * - `mesh` - the proxy surface the lighting is rendered from, solid, with its
17
+ * own headlight shading, drawn over the splats and skinned by the same
18
+ * skeleton as the real proxy.
19
+ *
20
+ * @group Lighting
21
+ */
22
+ export type RelightPreviewMode = 'off' | 'voxels' | 'mesh';
23
+ /**
24
+ * Something {@link SplatRelight.add} can light: a {@link Character}, whose
25
+ * proxy is skinned by its armature; a lone {@link Splat}, whose proxy is a
26
+ * static mesh under the splat's object; or an {@link Environment}, whose proxy
27
+ * is a static mesh under the environment's object, voxelized coarser and with
28
+ * a solid floor - see {@link ENVIRONMENT_PROXY_DEFAULTS}.
29
+ *
30
+ * @group Lighting
31
+ */
32
+ export type RelightTarget = Character | Splat | Environment;
33
+ /** {@link RelightLightOptions.shadowType} values. */
34
+ type RelightShadowType = 'pcf1' | 'pcf3' | 'pcf5' | 'vsm16' | 'vsm32';
35
+ /**
36
+ * The voxelizer settings an {@link Environment} target takes in place of the
37
+ * component-wide ones, unless {@link RelightTargetOptions.proxy} overrides
38
+ * them. Every other knob follows the component.
39
+ *
40
+ * - `voxelSize: 0.1` m. The character default of 0.025 m resolves a finger; a
41
+ * receiver for a character's shadow needs the floor and the walls, not their
42
+ * texture. Measured on the bundled `chamber.spz` (1.2M splats) cropped to its
43
+ * room: 0.03 m is ~500k triangles and ~100 ms to build; 0.1 m is 91k
44
+ * triangles in ~33 ms, and the shadow edge on the floor is set by the
45
+ * character's proxy and the capture's splat size, not by this.
46
+ * - `castShadows: false` - see {@link RelightTargetOptions.castShadows}.
47
+ * - `floorFill: true`. A raw voxelization of a capture is a shell: the ground
48
+ * is one voxel thick, with pinholes wherever the capture was sparse, and a
49
+ * shadow falls straight through them.
50
+ *
51
+ * Voxel sizes are in WORLD metres for every static target: an environment
52
+ * loaded at scale 2 is voxelized at half the size in its own units.
53
+ *
54
+ * @group Lighting
55
+ */
56
+ export declare const ENVIRONMENT_PROXY_DEFAULTS: Readonly<Pick<RelightProxySettings, 'voxelSize' | 'floorFill'>>;
57
+ /**
58
+ * The LOD level an environment bundle's proxy is voxelized from when
59
+ * {@link RelightTargetOptions.lod} is omitted: `auto`, the coarsest level that
60
+ * is dense enough for the voxel size.
61
+ *
62
+ * Kept for the PlayCanvas build's API: this port's environment proxy reads
63
+ * whatever the environment's splat holds (see {@link RelightTargetOptions.lod}),
64
+ * so the value is recorded and not yet acted on.
65
+ *
66
+ * @group Lighting
67
+ */
68
+ export declare const ENVIRONMENT_DEFAULT_LOD: number | 'coarsest' | 'auto';
69
+ /**
70
+ * Per-target options for {@link SplatRelight.add}.
71
+ *
72
+ * @group Lighting
73
+ */
74
+ export interface RelightTargetOptions {
75
+ /**
76
+ * Voxelizer settings for this target only, over the component's (and, for
77
+ * an environment, over {@link ENVIRONMENT_PROXY_DEFAULTS}). Rebuilds only
78
+ * this target. See {@link SplatRelight.setTargetProxySettings}.
79
+ */
80
+ proxy?: Partial<RelightProxySettings>;
81
+ /**
82
+ * Environment only: the world-space box the proxy is built from. Splats
83
+ * outside it are ignored.
84
+ *
85
+ * The voxelizer builds one dense grid over everything it is given, and a
86
+ * capture's extent is set by its floaters: `chamber.spz`'s room is 6 m wide
87
+ * but its splats span 21 m, which coarsens a 0.03 m request to 0.15 m. On a
88
+ * whole game map (`survivor_map.spz` spans 560 x 350 x 830 m) no voxel size
89
+ * is both buildable and useful - crop it to where characters walk.
90
+ */
91
+ bounds?: {
92
+ min: {
93
+ x: number;
94
+ y: number;
95
+ z: number;
96
+ };
97
+ max: {
98
+ x: number;
99
+ y: number;
100
+ z: number;
101
+ };
102
+ } | null;
103
+ /**
104
+ * Environment LOD bundles only, in the PlayCanvas build: the level to
105
+ * voxelize. This port's streaming bundles voxelize what they have streamed
106
+ * in when the proxy is first built, so the option is accepted and not yet
107
+ * acted on. Default {@link ENVIRONMENT_DEFAULT_LOD}.
108
+ */
109
+ lod?: number | 'coarsest' | 'auto';
110
+ /**
111
+ * Whether this target's proxy casts into the lights' shadow maps. Default
112
+ * `true` for a character or a splat, `false` for an environment.
113
+ *
114
+ * A capture's own occlusion is already in its baked colours - a wall's
115
+ * shadow on the floor is IN the floor's colour - so an environment that also
116
+ * cast would darken it twice. Worse, a closed room's walls and ceiling put
117
+ * its whole interior, and every character in it, in the key light's shadow.
118
+ * What a capture is missing is the shadow of what moves through it, which is
119
+ * what the default keeps. Turn it on to have a character walk into a
120
+ * capture's shade.
121
+ */
122
+ castShadows?: boolean;
123
+ /**
124
+ * Draw this proxy into the screen-space lighting/visibility receiver maps.
125
+ * Default true. Set false for a shadow-only caster whose splats keep their
126
+ * baked appearance: its coarse silhouette must not overwrite lighting on
127
+ * environment splats behind it. It still casts into the shadow maps.
128
+ */
129
+ lightingReceiver?: boolean;
130
+ }
131
+ /**
132
+ * Where a target's proxy geometry came from. See {@link SplatRelight.proxySource}.
133
+ *
134
+ * @group Lighting
135
+ */
136
+ export interface RelightProxySource {
137
+ /** Splats handed to the voxelizer, after any crop. */
138
+ splats: number;
139
+ /** Splats read from the target, before the crop. */
140
+ sourceSplats: number;
141
+ /** LOD level read, `null` unless the target is an LOD bundle. */
142
+ lodLevel: number | null;
143
+ /** Levels available; `1` unless the target is an LOD bundle. */
144
+ lodLevels: number;
145
+ /** Milliseconds reading the source took. */
146
+ loadMs: number;
147
+ }
148
+ /**
149
+ * The voxelizer knobs {@link SplatRelight} exposes. Every one of them rebuilds
150
+ * the proxy mesh. See {@link ProxySettings} for what each does.
151
+ *
152
+ * @group Lighting
153
+ */
154
+ export interface RelightProxySettings {
155
+ /** `blocky` keeps voxel faces; `smooth` runs surface nets. Default `smooth`. */
156
+ surface: ProxySurfaceStyle;
157
+ /** Voxel edge, metres. Default `0.025`. */
158
+ voxelSize: number;
159
+ /** Splats below this alpha do not occupy a voxel. Default `0.04`. */
160
+ opacityThreshold: number;
161
+ /** Voxel rings grown around the occupied set. Default `0`. */
162
+ dilate: number;
163
+ /** Relaxation passes over the surface. Default `3`. */
164
+ smoothIterations: number;
165
+ /** Close the underside of the lowest occupied layer. Default `false`. */
166
+ floorFill: boolean;
167
+ }
168
+ /**
169
+ * The key light {@link SplatRelight} owns: a real three.js
170
+ * `DirectionalLight` that both the app's meshes (on its {@link layers}) and
171
+ * the proxies see.
172
+ *
173
+ * Colours and intensities are read the PlayCanvas way, so a scene authored for
174
+ * the PlayCanvas build lights the same: a CSS colour is gamma-space, and the
175
+ * light delivers `linear(colour) * intensity` (`linear(colour * intensity)`
176
+ * below 1) with no 1/pi.
177
+ *
178
+ * @group Lighting
179
+ */
180
+ export interface RelightLightOptions {
181
+ /** Azimuth in degrees. 0 = +Z, 90 = +X. Default `30`. */
182
+ azimuth?: number;
183
+ /** Elevation in degrees. 0 = horizon, 90 = overhead. Default `60`. */
184
+ elevation?: number;
185
+ /** CSS hex or a `Color` holding gamma-space values. Default `#fff2d9`. */
186
+ color?: string | Color;
187
+ /** Default `1`. */
188
+ intensity?: number;
189
+ /** Shadow map for meshes AND the proxy's cast shadows. Default `true`. */
190
+ castShadows?: boolean;
191
+ /**
192
+ * Metres the shadow map covers from the camera. Default `40`, the
193
+ * PlayCanvas default: the map is fitted every frame around the view frustum
194
+ * out to this distance.
195
+ */
196
+ shadowDistance?: number;
197
+ /** Shadow map texels a side. Default `1024`. */
198
+ shadowResolution?: number;
199
+ /**
200
+ * Depth bias against shadow acne, as PlayCanvas's light component takes it:
201
+ * 0 to 1, default `0.05`, the PlayCanvas default. It is applied as
202
+ * PlayCanvas applies it - a slope-scaled offset of `shadowBias x 10` shadow
203
+ * texels, on a shadow map whose depth range is fitted to its casters - so a
204
+ * number tuned in a PlayCanvas game means the same here. Under
205
+ * {@link shadowBiasMode} `'three'` it is three.js's `shadow.bias` instead.
206
+ */
207
+ shadowBias?: number;
208
+ /**
209
+ * Metres the shadow lookup moves along the surface normal, 0 to 1, as
210
+ * PlayCanvas's `normalOffsetBias`. Default `0`, the PlayCanvas default.
211
+ * Under {@link shadowBiasMode} `'three'` it is three.js's `shadow.normalBias`.
212
+ */
213
+ normalOffsetBias?: number;
214
+ /**
215
+ * `'playcanvas'` (the default): {@link shadowBias} and
216
+ * {@link normalOffsetBias} mean what they mean in PlayCanvas, and the result
217
+ * matches it. `'three'`: they are three.js's `shadow.bias` (default
218
+ * `-0.0005`) and `shadow.normalBias` (default `0`), used as given, on a
219
+ * shadow camera that spans four radii of the shadowed area.
220
+ */
221
+ shadowBiasMode?: 'playcanvas' | 'three';
222
+ /**
223
+ * How the shadow map is filtered, which is where a soft shadow EDGE comes
224
+ * from. Default `pcf3`.
225
+ *
226
+ * This is the lever to reach for before the compose blur. The softness
227
+ * happens in the shadow test, so it widens the penumbra and leaves the
228
+ * terminator across the subject exactly as sharp as it was;
229
+ * {@link SplatRelight.blurRadius} cannot separate the two, because by the
230
+ * time it runs they are the same channel.
231
+ *
232
+ * three.js filters shadows renderer-wide (`renderer.shadowMap.type`), so
233
+ * `pcf1` (basic) and the `vsm` types set that for every light in the app;
234
+ * `pcf3` and `pcf5` are PCF at radius 1 and 2 and change only this light.
235
+ */
236
+ shadowType?: RelightShadowType;
237
+ /** Blur kernel for the `vsm` shadow types, in texels. Default `11`. */
238
+ vsmBlurSize?: number;
239
+ /**
240
+ * How dark the shadow map is allowed to make a surface, `0..1`. Default `1`.
241
+ *
242
+ * The other half of "the shadow is too black": this lifts it at the light,
243
+ * so it applies to the proxy render and therefore to everything read out of
244
+ * the lighting channel - meshes in the scene included.
245
+ */
246
+ shadowIntensity?: number;
247
+ /**
248
+ * three.js layers (0..29) this light also lights the app's meshes on,
249
+ * beside the relight layers the component adds itself. Default `[0]`. `[]`
250
+ * keeps the light to the splats alone.
251
+ */
252
+ layers?: number[];
253
+ }
254
+ /**
255
+ * A point light. See {@link SplatRelight.addPointLight}.
256
+ *
257
+ * @group Lighting
258
+ */
259
+ export interface RelightPointLightOptions {
260
+ position?: {
261
+ x: number;
262
+ y: number;
263
+ z: number;
264
+ };
265
+ /** CSS hex or a `Color` holding gamma-space values. Default white. */
266
+ color?: string | Color;
267
+ /** Default `1`. */
268
+ intensity?: number;
269
+ /**
270
+ * Hard cutoff distance, metres. Default `5`. On the proxies the light falls
271
+ * off linearly to it, as in the PlayCanvas build.
272
+ */
273
+ range?: number;
274
+ /** Default `false`: omni shadows are six renders a frame. */
275
+ castShadows?: boolean;
276
+ /** three.js layers it also lights. Default `[0]`. */
277
+ layers?: number[];
278
+ }
279
+ /**
280
+ * Per-target overrides of the scene-wide relight knobs. See
281
+ * {@link SplatRelight.setParams}.
282
+ *
283
+ * @group Lighting
284
+ */
285
+ export interface RelightTargetParams {
286
+ strength?: number;
287
+ shadowStrength?: number;
288
+ ambient?: number;
289
+ /** CSS hex or a `Color`, applied as given - no colour-space conversion. */
290
+ tint?: string | Color;
291
+ }
292
+ /**
293
+ * Options for {@link SplatRelight.create}. Every one of them is also a live
294
+ * property; the property notes say which rebuild.
295
+ *
296
+ * @group Lighting
297
+ */
298
+ export interface SplatRelightOptions {
299
+ /** See {@link SplatRelight.strength}. Default `1`. */
300
+ strength?: number;
301
+ /** See {@link SplatRelight.shadowStrength}. Default `1`. */
302
+ shadowStrength?: number;
303
+ /** See {@link SplatRelight.setTint}. Default white. */
304
+ tint?: string | Color;
305
+ /** See {@link SplatRelight.ambient}. Default `0`. */
306
+ ambient?: number;
307
+ /** See {@link SplatRelight.referenceLuminance}. Default `1`. */
308
+ referenceLuminance?: number;
309
+ /** See {@link SplatRelight.blur}. Default `true`. */
310
+ blur?: boolean;
311
+ /** See {@link SplatRelight.blurRadius}. Default `1`. */
312
+ blurRadius?: number;
313
+ /** See {@link SplatRelight.shadowBlurRadius}. Default `1`. */
314
+ shadowBlurRadius?: number;
315
+ /**
316
+ * The owned key light. Default: one at the {@link RelightLightOptions}
317
+ * defaults. `null` owns none - bring your own and hand them to
318
+ * {@link SplatRelight.addLight}.
319
+ */
320
+ light?: RelightLightOptions | null;
321
+ /**
322
+ * Sky fill. Written to {@link Scene.ambientLight}, which is what both meshes
323
+ * and the relight compose read, so the two can never disagree. Gamma-space,
324
+ * as the scene's `ambientLight` option is: the compose linearizes it the
325
+ * PlayCanvas way. Omit to leave the scene's ambient alone.
326
+ */
327
+ sky?: {
328
+ color?: string | Color;
329
+ intensity?: number;
330
+ };
331
+ /** See {@link SplatRelight.resolutionScale}. Default `0.5`. */
332
+ resolutionScale?: number;
333
+ /** See {@link SplatRelight.receiveShadows}. Default `false`. */
334
+ receiveShadows?: boolean;
335
+ /** Voxelizer knobs. Defaults are {@link defaultProxySettings}. */
336
+ proxy?: Partial<RelightProxySettings>;
337
+ /** See {@link SplatRelight.preview}. Default `off`. */
338
+ preview?: RelightPreviewMode;
339
+ /** Camera the splats are viewed through. Default `scene.camera`. */
340
+ mainCamera?: Camera;
341
+ /** See {@link SplatRelight.environmentRefresh}. Default `auto`. */
342
+ environmentRefresh?: EnvironmentRefreshMode;
343
+ }
344
+ /**
345
+ * Relighting for gaussian splats: one component that voxelizes a proxy mesh
346
+ * from the splats, renders it with real three.js lights into a screen-space
347
+ * lighting texture, and has every splat sample that texture.
348
+ *
349
+ * ```ts
350
+ * const relight = SplatRelight.create(scene, {
351
+ * light: { azimuth: 38, elevation: 38, intensity: 2.2 },
352
+ * receiveShadows: true,
353
+ * });
354
+ * relight.add(character);
355
+ * relight.voxelSize = 0.04; // rebuilds the proxy next frame
356
+ * relight.strength = 0.5; // uniform, next frame
357
+ * relight.preview = 'mesh';
358
+ * ```
359
+ *
360
+ * The legacy {@link SunLight} / {@link SkyLight} / {@link PointLight} rig is a
361
+ * separate lighting path and is untouched by this one.
362
+ *
363
+ * ── Two kinds of parameter ────────────────────────────────────────────────
364
+ * Uniform-only knobs - `strength`, `shadowStrength`, `ambient`, tint,
365
+ * `referenceLuminance`, `blur`, the key light's direction, colour and
366
+ * intensity, the sky fill - are plain clamped setters and take effect on the
367
+ * next frame with nothing reallocated.
368
+ *
369
+ * Resource-shape knobs - `resolutionScale`, `receiveShadows`, and every
370
+ * voxelizer setting - only mark the component dirty. One idempotent allocator
371
+ * runs at the start of the next frame (or on {@link rebuild}): it re-voxelizes
372
+ * what is stale, tears down whatever holds a reference to the old resource
373
+ * FIRST (the pass's shadowless twins, the preview's shared skeleton), and only
374
+ * then builds the replacement. Several knobs moved in one frame cost one
375
+ * rebuild.
376
+ *
377
+ * ── Lifecycle ─────────────────────────────────────────────────────────────
378
+ * {@link create} hooks the scene's `preRender`, where each frame poses the
379
+ * proxies, renders the lighting and publishes it - before the main render, so
380
+ * the splats it draws sample this frame's light. A canvas resize reallocates
381
+ * the lighting targets on the next frame. {@link destroy} is final.
382
+ * All state lives on the instance - never in module globals.
383
+ *
384
+ * ── Why generation lives here ─────────────────────────────────────────────
385
+ * The proxy exists for lighting only. A collision mesh cannot share it (a
386
+ * convex collider is capped at 255 hull polygons; lighting wants the detail),
387
+ * so there is no second consumer to split a mesh component out for.
388
+ *
389
+ * @group Lighting
390
+ */
391
+ export declare class SplatRelight {
392
+ private _strength;
393
+ private _shadowStrength;
394
+ /** Raw, as the splat shader multiplies it: no colour-space conversion. */
395
+ private readonly _tint;
396
+ private _ambient;
397
+ private _referenceLuminance;
398
+ private _blurRadius;
399
+ private _shadowBlurRadius;
400
+ private _debug;
401
+ private _enabled;
402
+ private _environmentRefresh;
403
+ private _lightAzimuth;
404
+ private _lightElevation;
405
+ /** Gamma-space, as authored. */
406
+ private readonly _lightColor;
407
+ private _lightIntensity;
408
+ private readonly _skyColor;
409
+ private _skyIntensity;
410
+ private _resolutionScale;
411
+ private _receiveShadows;
412
+ private readonly _proxy;
413
+ private _proxyKey;
414
+ private _dirty;
415
+ private _preview;
416
+ private _previewMaterial;
417
+ private readonly _lightOpts;
418
+ private readonly _mainCameraOpt;
419
+ private _shadowDistance;
420
+ private readonly _scene;
421
+ private _pass;
422
+ private _keyLight;
423
+ /** {@link RelightLightOptions.shadowBiasMode} is `'three'`. */
424
+ private _threeShadowBias;
425
+ /** PlayCanvas's polygon-offset slope factor for the key light's shadow. */
426
+ private _slopeFactor;
427
+ /** The key light's bias as this instance's proxies take it. */
428
+ private readonly _shadowBias;
429
+ private readonly _targets;
430
+ private readonly _lights;
431
+ private readonly _offPreRender;
432
+ private _destroyed;
433
+ private _lastRebuildMs;
434
+ /**
435
+ * Build the component on `scene` and start lighting from the next frame.
436
+ *
437
+ * Throws when the renderer cannot render to half-float - lighting exceeds 1
438
+ * and the target must not clamp it - and when the scene renders with WebGPU
439
+ * but `@viggle/splat-engine-three/webgpu` was not imported.
440
+ */
441
+ static create(scene: Scene, opts?: SplatRelightOptions): SplatRelight;
442
+ private constructor();
443
+ /** Final teardown: proxies, targets, owned lights. Registered lights get their own layers back. Safe twice. */
444
+ destroy(): void;
445
+ /**
446
+ * Light a character, a splat or an environment. Each is voxelized at the
447
+ * start of the next frame (a few to a few tens of milliseconds, by voxel
448
+ * size) - a LOD-bundle environment once its first chunks have streamed in -
449
+ * and lit from that frame on.
450
+ *
451
+ * Idempotent: a second call returns the first call's promise and ignores its
452
+ * options. Drops the target once it is destroyed.
453
+ *
454
+ * @returns Settles once the target's proxy is first built.
455
+ */
456
+ add(target: RelightTarget, opts?: RelightTargetOptions): Promise<void>;
457
+ /** Stop lighting a target and free its proxy. No-op when unknown. */
458
+ remove(target: RelightTarget): void;
459
+ /**
460
+ * What one target is actually lit with: its overrides resolved against the
461
+ * scene-wide knobs, every field present. `null` when the target is unknown.
462
+ *
463
+ * The pair to {@link setParams}, and what a panel over these knobs reads so
464
+ * it does not have to keep a second copy of them. A copy is what goes stale:
465
+ * a target added without overrides follows the component, and a panel
466
+ * holding its own numbers would keep showing the ones it last wrote while
467
+ * the scene moved underneath. The tint is a copy, so mutating it changes
468
+ * nothing.
469
+ */
470
+ params(target: RelightTarget): Required<Omit<RelightTargetParams, 'tint'>> & {
471
+ tint: Color;
472
+ } | null;
473
+ /**
474
+ * Override the scene-wide knobs for one target, across all its LOD and
475
+ * variant splats. `null` drops the override. Uniform-only.
476
+ */
477
+ setParams(target: RelightTarget, params: RelightTargetParams | null): void;
478
+ /**
479
+ * The voxelized proxy for a target - vertex and triangle counts, voxel
480
+ * grid, build time. `null` for an unknown target or before its first build.
481
+ */
482
+ proxyMesh(target: RelightTarget): ProxyMeshResult | null;
483
+ /**
484
+ * What a target's proxy was built from: splat counts before and after the
485
+ * crop. `null` for an unknown target or before its source is in.
486
+ */
487
+ proxySource(target: RelightTarget): RelightProxySource | null;
488
+ /**
489
+ * The voxelizer settings one target is built with: the component's, then
490
+ * {@link ENVIRONMENT_PROXY_DEFAULTS} for an environment, then the target's
491
+ * own. A copy; `null` for an unknown target.
492
+ */
493
+ targetProxySettings(target: RelightTarget): RelightProxySettings | null;
494
+ /**
495
+ * Override voxelizer settings for one target; `null` drops every override.
496
+ * Only that target rebuilds, on the next frame or {@link rebuild}.
497
+ */
498
+ setTargetProxySettings(target: RelightTarget, next: Partial<RelightProxySettings> | null): void;
499
+ /**
500
+ * The owned directional key light, or `null` when built with
501
+ * `light: null`. For the rarer three.js settings - shadow camera, map type
502
+ * - that this component does not wrap. Its position and shadow camera are
503
+ * refitted every frame.
504
+ */
505
+ get keyLight(): DirectionalLight | null;
506
+ /**
507
+ * Have an existing three.js light reach the proxies.
508
+ *
509
+ * A light only reaches a proxy when it is enabled on the relight layers;
510
+ * this adds them to the light's own. Change a registered light's layers by
511
+ * removing and re-adding it. The light keeps three's own colour and falloff
512
+ * semantics, except that on the proxies a point light falls off linearly to
513
+ * its `distance`, as the PlayCanvas build's lights do.
514
+ */
515
+ addLight(light: Light): void;
516
+ /** Undo {@link addLight}: restores the light's own layers. */
517
+ removeLight(light: Light): void;
518
+ /**
519
+ * Create an omni light that reaches both the app's layers and the proxies,
520
+ * added to the scene. Owned: disposed with the component. Toggle it with
521
+ * `visible`; move it with `position`.
522
+ */
523
+ addPointLight(opts?: RelightPointLightOptions): PointLight;
524
+ /**
525
+ * How far the proxy lighting replaces the baked look, 0..1. Independent of
526
+ * {@link shadowStrength}: strength 0 with shadow strength 1 keeps the baked
527
+ * colours and darkens only where a proxy blocks the light - the look for an
528
+ * environment capture, whose baked lighting is real. With both at `0` on
529
+ * every target the pass stops rendering altogether - a true no-op in pixels
530
+ * and in cost.
531
+ */
532
+ get strength(): number;
533
+ set strength(v: number);
534
+ /**
535
+ * Cast-shadow depth on the splats, 0..1, independent of {@link strength}.
536
+ * Inert unless {@link receiveShadows} is on.
537
+ */
538
+ get shadowStrength(): number;
539
+ set shadowStrength(v: number);
540
+ /** Floor under the light term, so faces turned from every light are not black. */
541
+ get ambient(): number;
542
+ set ambient(v: number);
543
+ /** Tint on the received light only, never the base colour. Applied as given. */
544
+ getTint(): Color;
545
+ setTint(c: string | Color): void;
546
+ /**
547
+ * The proxy brightness that counts as "normally lit". Lighting is divided
548
+ * by it, so strength moves contrast rather than exposure. Calibrate it to
549
+ * the scene's key light.
550
+ */
551
+ get referenceLuminance(): number;
552
+ set referenceLuminance(v: number);
553
+ /** The 3x3 tent over the lighting texture that keeps animated lighting stable. */
554
+ get blur(): boolean;
555
+ set blur(v: boolean);
556
+ /**
557
+ * Radius of the tent over the lighting, in texels of the proxy target.
558
+ * Default `1`; `0` is a single tap and the raw bake.
559
+ *
560
+ * The knob that softens a cast shadow being read through {@link strength}
561
+ * alone - the shadow map lives in this channel - and it softens the
562
+ * terminator across the subject with it. For a soft shadow and a crisp
563
+ * subject, raise {@link shadowBlurRadius} instead, or filter the shadow map
564
+ * itself with {@link RelightLightOptions.shadowType}.
565
+ */
566
+ get blurRadius(): number;
567
+ set blurRadius(v: number);
568
+ /**
569
+ * Radius of the tent over the shadow-visibility channel, in texels of the
570
+ * proxy target. Default `1`.
571
+ *
572
+ * Inert while {@link shadowStrength} is 0 or the pass was built without
573
+ * `receiveShadows`, because nothing reads that channel then.
574
+ */
575
+ get shadowBlurRadius(): number;
576
+ set shadowBlurRadius(v: number);
577
+ /** Suspend the effect without dropping anything. */
578
+ get enabled(): boolean;
579
+ set enabled(v: boolean);
580
+ /**
581
+ * See {@link EnvironmentRefreshMode}: kept for the PlayCanvas build's API.
582
+ * Every splat in this port samples the live lighting each frame, so
583
+ * environments are always current whatever the mode.
584
+ */
585
+ get environmentRefresh(): EnvironmentRefreshMode;
586
+ set environmentRefresh(v: EnvironmentRefreshMode);
587
+ /** See {@link RelightPass.invalidateEnvironments}. */
588
+ invalidateEnvironments(): void;
589
+ /** Frames on which the published lighting changed, since the pass was last built. A cost probe. */
590
+ get environmentRefreshFrames(): number;
591
+ /**
592
+ * Paint the splats with the relight sample instead of lighting them:
593
+ * `1` the lighting, `2` the shadow visibility, `0` off. Diagnostic.
594
+ */
595
+ get debug(): number;
596
+ set debug(v: number);
597
+ /** Key light azimuth, degrees. 0 = +Z, 90 = +X. */
598
+ get lightAzimuth(): number;
599
+ set lightAzimuth(v: number);
600
+ /** Key light elevation, degrees, -90..90. */
601
+ get lightElevation(): number;
602
+ set lightElevation(v: number);
603
+ /** Key light intensity. */
604
+ get lightIntensity(): number;
605
+ set lightIntensity(v: number);
606
+ /** Key light colour, gamma-space as authored. */
607
+ getLightColor(): Color;
608
+ setLightColor(c: string | Color): void;
609
+ /**
610
+ * How dark the key light's shadow map is allowed to make a surface, `0..1`.
611
+ *
612
+ * Live, and the first thing to reach for when a cast shadow reads as a hole
613
+ * rather than as shade. It lifts the shadow where it is MADE, so everything
614
+ * downstream sees the lifted value - the proxy render, and therefore the
615
+ * lighting channel every splat samples. Reads `1` when there is no key
616
+ * light; setting it is then a no-op.
617
+ */
618
+ get lightShadowIntensity(): number;
619
+ set lightShadowIntensity(v: number);
620
+ /**
621
+ * How the key light's shadow map is filtered. See
622
+ * {@link RelightLightOptions.shadowType} - including which values are
623
+ * renderer-wide in three.js. Reads `pcf3` when there is no key light.
624
+ */
625
+ get lightShadowType(): RelightShadowType;
626
+ set lightShadowType(v: RelightShadowType);
627
+ /** Blur kernel for the `vsm` shadow types, in texels. Inert under `pcf`. */
628
+ get lightVsmBlurSize(): number;
629
+ set lightVsmBlurSize(v: number);
630
+ /** Sky fill intensity. No-op unless built with `sky`. Scene-wide. */
631
+ get skyIntensity(): number;
632
+ set skyIntensity(v: number);
633
+ /** Sky fill colour, or `null` when built without `sky`. */
634
+ getSkyColor(): Color | null;
635
+ setSkyColor(c: string | Color): void;
636
+ /** Lighting-texture size as a fraction of the canvas, 0.05..1. Reallocates. */
637
+ get resolutionScale(): number;
638
+ set resolutionScale(v: number);
639
+ /**
640
+ * Cast shadows on the splats. Costs a second proxy render a frame, so it is
641
+ * a rebuild: the pass is replaced.
642
+ */
643
+ get receiveShadows(): boolean;
644
+ set receiveShadows(v: boolean);
645
+ get surface(): ProxySurfaceStyle;
646
+ set surface(v: ProxySurfaceStyle);
647
+ get voxelSize(): number;
648
+ set voxelSize(v: number);
649
+ get opacityThreshold(): number;
650
+ set opacityThreshold(v: number);
651
+ get dilate(): number;
652
+ set dilate(v: number);
653
+ get smoothIterations(): number;
654
+ set smoothIterations(v: number);
655
+ get floorFill(): boolean;
656
+ set floorFill(v: boolean);
657
+ /** Every voxelizer knob at once. A copy. */
658
+ get proxySettings(): RelightProxySettings;
659
+ /** Set several voxelizer knobs; one rebuild however many change. */
660
+ setProxySettings(next: Partial<RelightProxySettings>): void;
661
+ /**
662
+ * Apply pending resource-shape changes now rather than at the start of the
663
+ * next frame - for a script that screenshots the result straight after.
664
+ */
665
+ rebuild(): void;
666
+ /** Milliseconds the last rebuild that did work took, voxelizing included. */
667
+ get lastRebuildMs(): number;
668
+ /**
669
+ * Off / voxels / mesh. Runtime-switchable, and never part of the lighting:
670
+ * voxels are lines, and the mesh preview is a separate mesh with its own
671
+ * material on layer 0, never on a relight layer. The first switch to
672
+ * `voxels` builds the cell overlay.
673
+ */
674
+ get preview(): RelightPreviewMode;
675
+ set preview(v: RelightPreviewMode);
676
+ /** The composed lighting texture, `rgb` light and `a` coverage. Debug only. */
677
+ get lightingTexture(): import("three").Texture<unknown, import("three").TextureEventMap> | null;
678
+ /** `[width, height]` of the lighting texture; `[0, 0]` before the pass exists. */
679
+ get resolution(): [number, number];
680
+ /**
681
+ * The three.js layer the proxies render on. Enabling it on a camera shows
682
+ * the raw proxy - a debugging aid.
683
+ */
684
+ get proxyLayerId(): number;
685
+ /** Whether the pass is rendering this frame (off with every strength and shadow strength at 0). */
686
+ get active(): boolean;
687
+ private _onPreRender;
688
+ /**
689
+ * The allocator. Idempotent: brings every resource-shape resource in line
690
+ * with the settings and does nothing where it already is.
691
+ */
692
+ private _ensure;
693
+ private _attachTarget;
694
+ /** Free one target's GPU state, holders of references first. */
695
+ private _releaseTarget;
696
+ private _previewMaterialFor;
697
+ private _syncPreview;
698
+ /** Push every uniform-only knob to the pass. Cheap; no allocation per call. */
699
+ private _pushParams;
700
+ private _pushTargetParams;
701
+ /** Make `entry.input` current. `false` while an environment has no splat to read yet. */
702
+ private _ensureInput;
703
+ /** The crop an environment's input is cut with, as a comparable string. */
704
+ private _inputKeyFor;
705
+ private _settingsFor;
706
+ private _createKeyLight;
707
+ private _applyKeyLightColor;
708
+ /**
709
+ * Point the key light along azimuth/elevation and fit its shadow camera.
710
+ *
711
+ * The toward-the-light vector is `(cosE sinA, sinE, cosE cosA)`. The shadow
712
+ * covers the view frustum out to the shadow distance, as PlayCanvas fits its
713
+ * directional shadows: the slice's bounding sphere, snapped to whole shadow
714
+ * texels in the light's frame so a moving camera does not make the shadow
715
+ * edges crawl.
716
+ */
717
+ private _placeKeyLight;
718
+ /**
719
+ * The depth span, along the light from {@link _center}, of the shadow
720
+ * casters whose bounds fall in the map's `radius` square: what PlayCanvas
721
+ * fits a directional shadow camera's near and far to. Into `_depthRange`;
722
+ * false when no caster is in the map.
723
+ */
724
+ private _casterDepthRange;
725
+ private _applySky;
726
+ private _registerLight;
727
+ private _stampLights;
728
+ /** The light's own layers, plus the relight layers the current pass draws. */
729
+ private _stampLight;
730
+ }
731
+ /**
732
+ * A character's LOD level with the most splats, and a key that changes when a
733
+ * denser one is loaded. Variant splats are not LOD levels and are skipped.
734
+ *
735
+ * @internal Exported for tests.
736
+ */
737
+ export declare function densestSplatOf(character: Pick<Character, 'splats'>): {
738
+ splat: Splat;
739
+ key: string;
740
+ };
741
+ export {};