@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
@@ -36,6 +36,8 @@ export interface SplatEngineOptions {
36
36
  * backend matching the renderer that first draws it.
37
37
  */
38
38
  backend?: SplatBackend;
39
+ /** Initial {@link SplatEngine.legacyRootRotation}. Default `true`. */
40
+ legacyRootRotation?: boolean;
39
41
  }
40
42
  /**
41
43
  * Shared state for a set of splat characters and environments: the skeleton
@@ -74,6 +76,22 @@ export declare class SplatEngine {
74
76
  camera: Camera | null;
75
77
  /** Default animation-LOD bands for `Armature.setAnimationLod()` called with no arguments. */
76
78
  animLodPreset?: AnimLodPreset;
79
+ /**
80
+ * {@link Splat.minPixelSize} for every splat created through this engine
81
+ * from now on: splats smaller than this many pixels on screen are skipped.
82
+ * `0` (the default) draws all.
83
+ */
84
+ subPixelCull: number;
85
+ /**
86
+ * Default {@link Armature.legacyRootRotation} for this engine's characters:
87
+ * `true` pins the root bone's rotation to bind, as 0.1.1 did, so GLB clips
88
+ * face the way they always have here; `false` keeps the clip's root
89
+ * rotation, as the PlayCanvas build 0.3.2 does. A {@link Scene} defaults to
90
+ * `false`. An armature's own setting wins. Read every frame, so a change
91
+ * applies to the characters already loaded too; make it before their clips
92
+ * play (see {@link Armature.legacyRootRotation}).
93
+ */
94
+ legacyRootRotation: boolean;
77
95
  /** Number of {@link SplatEngine.update} calls so far. */
78
96
  frame: number;
79
97
  /** {@link SplatEngine.frame} of the most recent character pose evaluation. */
@@ -22,32 +22,120 @@ export interface LoadEnvironmentOptions {
22
22
  /** Explicit filename for extension detection on URLs without one. */
23
23
  filename?: string;
24
24
  }
25
+ /** @group Environment */
26
+ export interface LoadLodBundleOptions {
27
+ /** Object name. Default: `'lod_environment'`. */
28
+ name?: string;
29
+ /** World position. Default: origin. */
30
+ position?: {
31
+ x: number;
32
+ y: number;
33
+ z: number;
34
+ };
35
+ /**
36
+ * Authored euler angles in degrees. The loader stacks the bundle's
37
+ * RDF-to-Y-up correction (+180 degrees about X) on top: pass the same
38
+ * rotation you would give {@link Environment.load} for the monolithic splat.
39
+ */
40
+ rotation?: {
41
+ x: number;
42
+ y: number;
43
+ z: number;
44
+ };
45
+ /** Uniform scale. Default: 1. */
46
+ scale?: number;
47
+ /**
48
+ * Camera distance (world units) of the first LOD transition. Level `i`
49
+ * takes over from `lodBaseDistance * lodMultiplier^(i-1)`. Default: 8.
50
+ */
51
+ lodBaseDistance?: number;
52
+ /** Geometric ratio between successive LOD distance thresholds. Default: 3. */
53
+ lodMultiplier?: number;
54
+ /**
55
+ * Longest the bundle stays pinned to its coarsest level waiting for it to
56
+ * stream in (a stalled chunk), in ms. Counted from the first
57
+ * {@link SplatEngine.update}, not from load, and pushed back while chunks
58
+ * are still arriving. Default: 8000.
59
+ */
60
+ coarseTimeoutMs?: number;
61
+ /**
62
+ * Pin the whole bundle to one LOD level instead of switching by distance,
63
+ * for editor and debug previews. 0 is the finest; values outside the
64
+ * bundle's range are clamped.
65
+ */
66
+ fixedLodLevel?: number;
67
+ }
25
68
  /**
26
- * Gaussian-splat environment loaded into an engine.
69
+ * Gaussian-splat environment loaded into an engine: one splat file, or a
70
+ * streaming LOD bundle.
27
71
  *
28
72
  * A static, unskinned splat that responds to the engine's lighting registry
29
73
  * (sun + sky + point lights). Its depth sort runs in a worker and only when
30
74
  * the view direction changes, so a large scene costs nothing while the camera
31
75
  * is still.
32
76
  *
33
- * Construct via {@link Environment.load} - the constructor is internal.
77
+ * Construct via {@link Environment.load} or {@link Environment.loadLodBundle} -
78
+ * the constructor is internal.
34
79
  *
35
80
  * @group Environment
36
81
  */
37
82
  export declare class Environment {
38
- /** The splat that draws the environment. */
39
- readonly splat: Splat;
83
+ /**
84
+ * The three.js object for the environment. Transform it like any other.
85
+ * For a single file it is the {@link SplatMesh} itself; for a LOD bundle, a
86
+ * group whose child is whichever splat holds the levels drawn now.
87
+ */
88
+ readonly object3D: Object3D;
89
+ /**
90
+ * Resolves once the coarsest LOD level has streamed in and the full LOD
91
+ * range is open (or the stall guard gave up waiting), one frame after that
92
+ * frame was drawn. Already resolved for an environment without LOD levels.
93
+ * For a gate that needs the map visible first ("put the player in").
94
+ *
95
+ * Frames here are {@link SplatEngine.update} calls: a bundle streams only
96
+ * while the engine is being updated.
97
+ */
98
+ readonly coarseReady: Promise<void>;
99
+ private readonly _splat;
100
+ private readonly _lod;
40
101
  private constructor();
41
- /** The three.js object for the environment. Transform it like any other. */
42
- get object3D(): Object3D;
102
+ /**
103
+ * The splat that draws the environment - for render options, tint and
104
+ * grade. For a LOD bundle, the one drawing it now: replaced as levels
105
+ * change, with the options set on it carried over to its successor, and
106
+ * empty until the first chunks have arrived.
107
+ */
108
+ get splat(): Splat;
109
+ /** {@link object3D} under the PlayCanvas build's name. Hide it with `visible`, not `enabled`. */
110
+ get entity(): Object3D;
43
111
  /**
44
112
  * Fetch, decode and add an environment splat.
45
113
  *
46
- * Reads uncompressed 3D Gaussian Splatting `.ply` files.
114
+ * Reads uncompressed 3D Gaussian Splatting `.ply`, `.spz` (versions 1 to
115
+ * 4), and SOG (a `.sog` bundle or an unbundled `meta.json`). The format is
116
+ * told by the file name: pass `filename` when the URL does not end in one.
117
+ * `.spz` and SOG decode in a worker.
47
118
  *
48
119
  * @param url - Location of the splat file.
120
+ * @throws {EngineDisposedError} If `engine` is disposed before or while the file loads.
49
121
  */
50
122
  static load(engine: SplatEngine, url: string, opts?: LoadEnvironmentOptions): Promise<Environment>;
51
- /** Remove the environment and release its GPU resources. */
123
+ /**
124
+ * Load a streaming LOD bundle - a `lod-meta.json` octree manifest over SOG
125
+ * chunks, as splat-transform writes it - and add it to the engine.
126
+ *
127
+ * Unlike {@link load}, the splats are not one file: each octree leaf picks
128
+ * a detail level by its distance from {@link SplatEngine.camera} every
129
+ * {@link SplatEngine.update}, and the chunks those levels live in are
130
+ * fetched as they are needed. The promise resolves once the manifest is in;
131
+ * streaming then proceeds in the background, coarsest level first, the full
132
+ * range opening once it is drawn (see {@link coarseReady}). Without a
133
+ * camera the bundle stays at its coarsest level.
134
+ *
135
+ * @param url - Location of the `lod-meta.json`. Chunk paths in it are relative to it.
136
+ * @throws {EngineDisposedError} If `engine` is disposed before or while the manifest loads.
137
+ */
138
+ static loadLodBundle(engine: SplatEngine, url: string, opts?: LoadLodBundleOptions): Promise<Environment>;
139
+ /** Remove the environment and release its GPU resources. A LOD bundle stops streaming. */
52
140
  destroy(): void;
53
141
  }
@@ -4,19 +4,31 @@ export { SplatClipLoader, SplatPLYLoader, VSplatLoader } from './three/loaders';
4
4
  export { Animation as SplatClip } from './animation';
5
5
  export { SplatEngine, EngineDisposedError } from './engine';
6
6
  export type { SceneLighting, SplatEngineOptions } from './engine';
7
+ export { Scene, SceneDestroyedError } from './scene';
8
+ export type { CreateSceneOptions, RenderBackend, SceneEvent } from './scene';
9
+ export * from './effects';
10
+ export * from './physics';
7
11
  export { Character } from './character';
8
12
  export type { LoadCharacterOptions } from './character';
9
- export { Animation } from './animation';
10
- export type { AnimationEvent } from './animation';
13
+ export { Animation, clearAnimRootRotation } from './animation';
14
+ export type { AnimationEvent, AnimationLoadOptions } from './animation';
11
15
  export { Armature } from './armature';
12
- export type { AnimLodPreset, PoseProvider, RootMotionMode } from './armature';
16
+ export type { AnimLodPreset, PoseModifier, PoseProvider, RootMotionMode, RootOffsetProvider } from './armature';
17
+ export { Pose } from './skeletal/pose';
13
18
  export { Environment } from './environment';
14
- export type { LoadEnvironmentOptions } from './environment';
19
+ export type { LoadEnvironmentOptions, LoadLodBundleOptions } from './environment';
20
+ export { SplatSPZLoader } from './three/spz-loader';
21
+ export { decodeSplatFile, loadSplatAsset, loadSplatSource, setShareSplatResources } from './loader/shared/asset-loader';
22
+ export { decodeSpz } from './loader/environment/spz';
15
23
  export { Splat } from './splat/splat';
16
24
  export { SplatMesh } from './splat/splat-mesh';
17
25
  export { WebGLSplatBackend } from './splat/webgl/backend';
18
26
  export type { SplatBackend } from './splat/backend';
19
27
  export type { SplatOptions, SplatSource } from './splat/splat';
28
+ export type { SplatColorModifier, SplatColorModifierInputs } from './splat/color-modifier';
29
+ export { DEFAULT_ENV_REVEAL_LOOK, DEFAULT_REVEAL_LOOK } from './splat/reveal-look';
30
+ export type { RevealLook } from './splat/reveal-look';
31
+ export type { RevealSkeleton } from './splat/reveal-bake';
20
32
  export { packSplats } from './splat/packed-splats';
21
33
  export type { PackedSplats } from './splat/packed-splats';
22
34
  export { SplatQuality } from './splat/quality';
@@ -28,13 +40,28 @@ export { SkyLight } from './lighting/sky-light';
28
40
  export type { CreateSkyLightOptions } from './lighting/sky-light';
29
41
  export { PointLight } from './lighting/point-light';
30
42
  export type { CreatePointLightOptions } from './lighting/point-light';
31
- export { makeRegionMask } from './skeletal/bone-mask';
43
+ export { LOWER_BODY_BONE_NAMES, UPPER_BODY_BONE_NAMES, makeRegionMask, resolveBoneIndices } from './skeletal/bone-mask';
32
44
  export type { BodyRegion, BoneMask } from './skeletal/bone-mask';
33
45
  export type { AnimEventCallback, CrossfadeOptions } from './skeletal/animation-player';
34
- export type { BoneScaleInput } from './skeletal/bone-stretch';
46
+ export { computeBoneStretch } from './skeletal/bone-stretch';
47
+ export type { BoneScale, BoneScaleInput, BoneStretch } from './skeletal/bone-stretch';
35
48
  export { decodeCharacterBundle, loadCharacterBundle, loadCharacterBundleFromBytes } from './loader/character/load';
49
+ export { cachedFetch, indexAssetCache, installFetchInterceptor, isCached, setBinFetch, uninstallFetchInterceptor, } from './loader/shared/bin-cache';
50
+ export { setAssetFetch } from './loader/shared/asset-fetch';
51
+ export type { AssetFetch } from './loader/shared/asset-fetch';
36
52
  export type { CharacterBundle } from './loader/character/load';
37
53
  export { CharacterBundleError } from './loader/character/types';
38
54
  export { parseGaussianPly } from './loader/environment/ply';
39
55
  export type { SkeletonLibrary } from './loader/skeleton';
40
56
  export type { ArmatureData, SplatWeights } from './types';
57
+ export { VfxStage, VfxPool, JsonVfxPrefab, JsonVfxInstance, prewarmJsonVfxPrefabs, VfxLayerRegistry, defaultLayerRegistry, ParticleLayerRenderer, MeshLayerRenderer, SpriteLayerRenderer, ShaderLayerRenderer, validateShaderGLSL, DEFAULT_SHADER_FRAGMENT, DEFAULT_SHADER_FRAGMENT_WGSL, getVfxMesh, buildVfxSphereMesh, buildVfxRingMesh, buildVfxSpikeMesh, buildVfxQuadMesh, } from './effects/vfx';
58
+ export type { IVfxPrefab, IVfxInstance, VfxSpawnOptions, VfxStageOptions, VfxLayerRenderer, VfxLayerInstance, VfxLayerBuildContext, VfxLayerUpdateContext, VfxEffectData, VfxDataFile, VfxLayer, VfxLayerBase, VfxLayerTypeMap, VfxParticleLayer, VfxMeshLayer, VfxSpriteLayer, VfxShaderLayer, VfxShaderUniform, VfxShaderGeometry, VfxTrailConfig, VfxMeshInstancing, VfxSinPulse, MeshShape, InstancePattern, CurvePoint, ColorCurvePoint, } from './effects/vfx';
59
+ export * from './presets';
60
+ export { BodyPart, NUM_BODY_PARTS, ALL_BODY_PARTS, bodyPartLabel, classifyBone, buildBoneToGroup } from './skeletal/body-parts';
61
+ export { loadGlbFromUrl, setGlbLoader } from './loader/shared/glb';
62
+ export type { GlbCallback } from './loader/shared/glb';
63
+ export { ENVIRONMENT_DEFAULT_LOD, ENVIRONMENT_PROXY_DEFAULTS, SplatRelight } from './relight/splat-relight';
64
+ export type { RelightLightOptions, RelightPointLightOptions, RelightPreviewMode, RelightProxySettings, RelightProxySource, RelightTarget, RelightTargetOptions, RelightTargetParams, SplatRelightOptions, } from './relight/splat-relight';
65
+ export type { EnvironmentRefreshMode } from './relight/relight-pass';
66
+ export { alphaFromLogits, buildProxyMesh, buildVoxelGrid, defaultProxySettings, extractSurface } from './proxy/voxelizer';
67
+ export type { BoneIndexArray, ProxyGridVec, ProxyMeshInput, ProxyMeshResult, ProxySettings, ProxySurfaceStyle, SurfaceSettings, VoxelGrid, VoxelGridSettings, } from './proxy/voxelizer';
@@ -1,3 +1,4 @@
1
+ import type { SkeletalKeyframeEntry } from '../../animation';
1
2
  /**
2
3
  * Decoded contents of an *armature GLB* - a glTF 2.0 binary carrying a bone
3
4
  * hierarchy, a skin, and one animation clip. Produced by the offline MetaHuman
@@ -6,8 +7,8 @@
6
7
  * @internal
7
8
  */
8
9
  export interface ArmatureGlbAnimation {
9
- /** Bone matrices in {@link Animation.data} layout: `numFrames * numBones * 16`. */
10
- data: Float32Array;
10
+ /** Per-bone keys, every bone keyed on every frame. The frames array is shared. */
11
+ keyframes: Map<number, SkeletalKeyframeEntry>;
11
12
  numFrames: number;
12
13
  numBones: number;
13
14
  /** Bone names in bone-index order (canonical rig order when recognised). */
@@ -61,8 +62,7 @@ export interface ArmatureGlbAnimation {
61
62
  */
62
63
  export declare const CONSTANT_TRANSLATION_EPS = 0.00001;
63
64
  /**
64
- * Parse an armature GLB into the flat bone-matrix form that {@link Animation}
65
- * holds after {@link Animation.parse}.
65
+ * Parse an armature GLB into the per-bone keys {@link Animation} plays from.
66
66
  *
67
67
  * **Bones are resolved by NAME, never by node index.** The joint set comes from
68
68
  * `skins[0].joints` when a skin is present (files we write, and anything
@@ -27,7 +27,12 @@ export interface CharacterBundle {
27
27
  * @throws {CharacterBundleError} carrying the format spec's error category.
28
28
  */
29
29
  export declare function decodeCharacterBundle(file: ArrayBuffer): Promise<CharacterBundle>;
30
- /** Fetch and decode a character bundle. */
30
+ /**
31
+ * Fetch and decode a character bundle. With `setShareSplatResources(true)`,
32
+ * characters loaded from one URL share the decode.
33
+ */
31
34
  export declare function loadCharacterBundle(url: string): Promise<CharacterBundle>;
35
+ /** Start downloading a character bundle; a later {@link loadCharacterBundle} reuses the bytes. */
36
+ export declare function prefetchCharacterBundle(url: string): void;
32
37
  /** Decode a character bundle from bytes already in memory. */
33
38
  export declare function loadCharacterBundleFromBytes(bytes: Uint8Array): Promise<CharacterBundle>;
@@ -0,0 +1,123 @@
1
+ /**
2
+ * Streaming LOD bundles: a `lod-meta.json` octree manifest over chunk files
3
+ * (SOG `meta.json`s as splat-transform writes them), each chunk holding one
4
+ * detail level of a run of octree leaves.
5
+ *
6
+ * PlayCanvas streams these itself; this is the same policy over this
7
+ * package's renderer. Every frame each leaf picks a level by its distance from
8
+ * the camera, the chunk files those levels live in are fetched (coarser and
9
+ * nearer first), and once a leaf's level has arrived the splats drawn are
10
+ * rebuilt as ONE splat holding every leaf at its current level.
11
+ *
12
+ * One splat and not one per leaf or per chunk, because splats from separate
13
+ * meshes are layered by draw order rather than depth (see the README): a
14
+ * scene drawn as many meshes composites far leaves over near ones. A single
15
+ * splat is sorted as a whole, which is what PlayCanvas's unified gsplat
16
+ * rendering does. The price is that a level change re-uploads the scene; the
17
+ * old splat keeps drawing until the new one has its first depth order, so the
18
+ * switch never shows a gap.
19
+ *
20
+ * There is always a splat, so that render options set on it before anything
21
+ * has streamed in carry over: until the first chunks arrive it is an empty one
22
+ * kept out of the scene.
23
+ */
24
+ import { Group } from 'three';
25
+ import type { SplatEngine } from '../../engine';
26
+ import { Splat } from '../../splat/splat';
27
+ /** A `lod-meta.json`, as splat-transform writes it and PlayCanvas's `GSplatOctree` reads it. */
28
+ export interface LodManifest {
29
+ lodLevels: number;
30
+ /** Chunk files, relative to the manifest. */
31
+ filenames: string[];
32
+ /** An optional splat drawn whole at every distance (a skybox), relative to the manifest. */
33
+ environment?: string | null;
34
+ tree: LodTreeNode;
35
+ }
36
+ interface LodTreeNode {
37
+ bound: {
38
+ min: number[];
39
+ max: number[];
40
+ };
41
+ children?: LodTreeNode[];
42
+ /** Leaves only: where each level of this leaf's splats is, keyed by level. */
43
+ lods?: Record<string, {
44
+ file: number;
45
+ offset?: number;
46
+ count?: number;
47
+ }>;
48
+ }
49
+ /** Tuning for {@link LodBundle}, as `LoadLodBundleOptions` carries it. */
50
+ export interface LodBundleSettings {
51
+ lodBaseDistance: number;
52
+ lodMultiplier: number;
53
+ coarseTimeoutMs: number;
54
+ fixedLodLevel?: number;
55
+ }
56
+ /** @internal Drives one bundle; owned by its `Environment`. */
57
+ export declare class LodBundle {
58
+ /** Carries the bundle's transform; the splat drawing it is its child. */
59
+ readonly root: Group<import("three").Object3DEventMap>;
60
+ readonly coarseReady: Promise<void>;
61
+ private readonly _engine;
62
+ private readonly _settings;
63
+ private readonly _leaves;
64
+ private readonly _files;
65
+ private readonly _environmentFile;
66
+ /** Per leaf: the level it should show now, and the level the drawn splat holds (-1: none). */
67
+ private readonly _desired;
68
+ private readonly _drawn;
69
+ private readonly _distance;
70
+ private _rangeMin;
71
+ private _rangeMax;
72
+ private _drawnEnvironment;
73
+ private _splat;
74
+ /** The splat being swapped in, drawing alongside {@link _splat} until its first sort lands. */
75
+ private _incoming;
76
+ private _loadsInFlight;
77
+ private _coarsePinned;
78
+ private _coarseTimer;
79
+ private _resolveCoarse;
80
+ private _coarseOpenedFrame;
81
+ private readonly _removeUpdater;
82
+ private _destroyed;
83
+ constructor(engine: SplatEngine, manifestUrl: string, manifest: LodManifest, settings: LodBundleSettings);
84
+ /** The splat drawing the bundle now: empty, and not in the scene, until its first chunks have arrived. */
85
+ get splat(): Splat;
86
+ destroy(): void;
87
+ private _update;
88
+ /** Each leaf's level for this frame, from its distance to the camera. */
89
+ private _chooseLevels;
90
+ /**
91
+ * Distance from the camera to each leaf's box, in the bundle's local space,
92
+ * scaled as PlayCanvas scales it: by the bundle's world scale, by the field
93
+ * of view relative to 45 degrees (a narrower view sees farther, so detail
94
+ * holds out longer), and up to 1.5x for a box behind the camera.
95
+ */
96
+ private _evaluateDistances;
97
+ /** Start downloads for the chunks the chosen levels need: coarser levels first, then nearer leaves. */
98
+ private _requestFiles;
99
+ private _load;
100
+ /**
101
+ * What each leaf can draw this frame: its chosen level once that chunk is
102
+ * in, else whatever it draws already, so a level change never opens a hole.
103
+ * When that differs from what is drawn, build the splat that draws it.
104
+ * One swap at a time: the next waits for the last one's first sort.
105
+ */
106
+ private _rebuildIfChanged;
107
+ /** One splat set holding every leaf at its level in `levels`, plus the environment splat. */
108
+ private _composite;
109
+ private _swapIn;
110
+ /** Retire the old splat once the incoming one draws a sorted frame. */
111
+ private _finishSwap;
112
+ private _unloadIdleFiles;
113
+ /**
114
+ * While pinned to the coarsest level: open the full range once every leaf
115
+ * draws it, or once the stall guard fires. The guard is armed by the first
116
+ * frame, not at load - nothing streams until frames run, and a game may
117
+ * show a menu for a while first - and pushed back while chunks are still
118
+ * arriving, so a slow connection streaming steadily is not a stall.
119
+ */
120
+ private _watchCoarse;
121
+ private _openRange;
122
+ }
123
+ export {};
@@ -0,0 +1,88 @@
1
+ /**
2
+ * The CPU half of an `.spz` decode: header, framing and the per-attribute
3
+ * unpack into the 3DGS PLY conventions every other format here decodes to.
4
+ *
5
+ * Ported from the PlayCanvas build's `spz-format.ts` / `spz-decode.ts`, minus
6
+ * the decompression (injected by `spz.ts`, which has the platform in it).
7
+ *
8
+ * ── Why every function here stands alone ────────────────────────────────
9
+ *
10
+ * These functions are also the source text of the decode worker
11
+ * (`decode-worker.ts` stringifies them), so they may call each other but
12
+ * must not read anything else at module scope: no imports, no module-level
13
+ * constants. Tables live inside the function that uses them. The one import,
14
+ * `inflateCapped`, is a stand-alone function the worker carries too.
15
+ */
16
+ import type { SplatAttributes } from '../character/types';
17
+ /** The fields of an SPZ header this reader acts on. */
18
+ export interface SpzHeader {
19
+ version: number;
20
+ numPoints: number;
21
+ shDegree: number;
22
+ fractionalBits: number;
23
+ /** Trained with anti-aliasing. Read, not applied: the PlayCanvas build ignores it too. */
24
+ antialiased: boolean;
25
+ /** Version 4: how many zstd streams the table of contents lists. */
26
+ numStreams: number;
27
+ /** Version 4: where the table of contents starts. */
28
+ tocByteOffset: number;
29
+ }
30
+ /**
31
+ * The header of an UNCOMPRESSED file (version 4, or a gunzipped 1-3), or
32
+ * `null` when these bytes do not start with the "NGSP" magic - which is how a
33
+ * caller tells the two framings apart without parsing anything twice.
34
+ */
35
+ export declare function readSpzHeader(file: Uint8Array): SpzHeader | null;
36
+ /**
37
+ * Refuse a header no file of ours could have written. A point count past
38
+ * spz-js's own ceiling is a corrupt header rather than a scene, and allocating
39
+ * from it is how that becomes a crash instead of an error.
40
+ */
41
+ export declare function checkSpzHeader(head: SpzHeader): void;
42
+ /**
43
+ * Byte length of each attribute stream, in the writer's order: positions,
44
+ * alphas, colours, scales, rotations, SH. That order is the writer's and not
45
+ * the format document's, and it matters: colours and scales are both 3 bytes
46
+ * a point, so a reader that guessed from sizes would silently swap a scene's
47
+ * colour for its size. Version 4 skips empty streams, so SH is 0 here when
48
+ * absent and its table of contents lists one stream fewer.
49
+ */
50
+ export declare function spzStreamSizes(head: SpzHeader): number[];
51
+ /** Versions 1-3: one gzip stream holding the header, then each attribute in order. */
52
+ export declare function splitLegacySpz(raw: Uint8Array, head: SpzHeader): Uint8Array[];
53
+ /**
54
+ * Unpack the attribute streams into the 3DGS PLY conventions
55
+ * {@link SplatAttributes} carries, with the PlayCanvas build's arithmetic:
56
+ *
57
+ * - colour: the DC spherical-harmonic term, `(byte / 255 - 0.5) / 0.15`;
58
+ * - opacity: the raw logit `log(a / (1 - a))`, infinite at the ends as there;
59
+ * - scale: the natural log, `byte / 16 - 10`;
60
+ * - rotation: stored `xyzw`, returned with `rot_0 = w`.
61
+ *
62
+ * Higher SH bands are not read: splats here are lit flat, by their DC colour.
63
+ */
64
+ export declare function unpackSpz(streams: Uint8Array[], head: SpzHeader): SplatAttributes;
65
+ /**
66
+ * The splat order PlayCanvas's `GSplatData.calcMortonOrder` produces (10 bits
67
+ * per axis over the cloud's bounds), by a stable two-pass radix sort. The
68
+ * PlayCanvas build stores every `.spz` in this order: neighbours in space are
69
+ * neighbours in memory, which is what the depth sort and every later pass
70
+ * over the cloud read in.
71
+ */
72
+ export declare function mortonOrder(x: Float32Array, y: Float32Array, z: Float32Array): Uint32Array;
73
+ /** Every attribute of `splats`, permuted by `order`. */
74
+ export declare function reorderSplats(splats: SplatAttributes, order: Uint32Array): SplatAttributes;
75
+ /**
76
+ * The worker's whole `.spz` job, given the file already split into streams
77
+ * (version 4, inflated by the caller) or still gzipped (versions 1-3, inflated
78
+ * here - `DecompressionStream` exists in a worker; zstd does not).
79
+ */
80
+ export declare function decodeSpzTask(input: {
81
+ gzip: Uint8Array;
82
+ } | {
83
+ head: SpzHeader;
84
+ streams: Uint8Array[];
85
+ }): Promise<{
86
+ numSplats: number;
87
+ splats: SplatAttributes;
88
+ }>;
@@ -0,0 +1,28 @@
1
+ /**
2
+ * `.spz` captures, decoded and packed for a {@link Splat}.
3
+ *
4
+ * Reads every version the PlayCanvas build reads: 1 to 3, which wrap the
5
+ * whole file in gzip, and 4, which has a plaintext header, a table of contents
6
+ * and one zstd stream per attribute.
7
+ *
8
+ * The decompression is split by what the platform offers. Gzip is
9
+ * `DecompressionStream`, which a worker has, so a gzipped file goes to the
10
+ * decode worker whole. Zstd is not in any browser's script API - Chrome takes
11
+ * it as a Content-Encoding, which is a different thing - so version 4 streams
12
+ * are inflated here with `zstddec` (the reference decoder as WASM, carried
13
+ * inside this bundle), and only the unpack and the packing go to the worker.
14
+ */
15
+ import type { PackedSplats } from '../../splat/packed-splats';
16
+ /**
17
+ * Decode an `.spz` file into packed splats, in Morton order.
18
+ *
19
+ * The framing is read off the bytes, never off a name: a file that starts
20
+ * with the "NGSP" magic is version 4, one that starts with gzip's is 1-3.
21
+ * Anything else is refused here, in those words - handed to a decompressor it
22
+ * would fail as "incorrect header check", which names neither the file nor
23
+ * the format.
24
+ *
25
+ * @throws If the bytes are not an SPZ this reader understands.
26
+ * @group Loaders
27
+ */
28
+ export declare function decodeSpz(file: Uint8Array): Promise<PackedSplats>;
@@ -0,0 +1,11 @@
1
+ /** Host-supplied transport, e.g. for renewing expiring URLs before a download. */
2
+ export type AssetFetch = (url: string, init?: RequestInit) => Promise<Response>;
3
+ /**
4
+ * Replace the network transport under the asset cache. A transport that calls
5
+ * the global `fetch` while `installFetchInterceptor` is active reaches the
6
+ * interceptor again and recurses: capture `fetch` before installing it.
7
+ */
8
+ export declare function setAssetFetch(fetcher: AssetFetch): void;
9
+ /** @internal Called by the fetch interceptor before it replaces `globalThis.fetch`. */
10
+ export declare function setPageFetch(fetcher: typeof fetch | null): void;
11
+ export declare function fetchAsset(url: string, init?: RequestInit): Promise<Response>;
@@ -0,0 +1,86 @@
1
+ /**
2
+ * Splat files by URL, whatever their format: fetched, decoded, packed.
3
+ *
4
+ * The three.js counterpart of the PlayCanvas build's `loadSplatAsset`. There
5
+ * it returns a PlayCanvas asset for the caller to mount on a `gsplat` entity;
6
+ * here it returns a {@link Splat} for the caller to add to a scene, and the
7
+ * decoded data behind it is a {@link SplatSource} any number of splats can be
8
+ * built from.
9
+ */
10
+ import type { SplatEngine } from '../../engine';
11
+ import { Splat } from '../../splat/splat';
12
+ import type { SplatSource } from '../../splat/splat';
13
+ /** The splat formats {@link loadSplatSource} reads, as told by the file name. */
14
+ type SplatFormat = 'ply' | 'spz' | 'sog' | 'sog-meta';
15
+ /** File name of `url`, without directory or query string. */
16
+ export declare function fileNameOf(url: string): string;
17
+ /** The format a file name says, or `null` for one this package does not read. */
18
+ export declare function splatFormatOf(filename: string): SplatFormat | null;
19
+ /**
20
+ * Share one decode among every load of the same file, for a game that spawns
21
+ * many of one model. Off by default: each load decodes its own copy. Affects
22
+ * loads after the call; turning it off releases what it holds.
23
+ *
24
+ * Decoded data is held until sharing is turned off: it is not reference
25
+ * counted, so a game that cycles through many distinct files should leave
26
+ * this off.
27
+ *
28
+ * @group Loaders
29
+ */
30
+ export declare function setShareSplatResources(enabled: boolean): void;
31
+ /**
32
+ * `decode()`, or - with {@link setShareSplatResources} on - the result of an
33
+ * earlier `decode()` for the same `kind` of load of the same file. The result
34
+ * must be treated as read-only by everything that receives it.
35
+ * @internal
36
+ */
37
+ export declare function sharedDecode<T>(kind: string, url: string, decode: () => Promise<T>): Promise<T>;
38
+ /**
39
+ * Decode a splat file already in memory. `filename` names the format; an
40
+ * unbundled SOG (`meta.json`) cannot be read this way, since its images are
41
+ * separate files.
42
+ *
43
+ * @throws If the format is not one this package reads, or the bytes are not that format.
44
+ * @group Loaders
45
+ */
46
+ export declare function decodeSplatFile(data: ArrayBuffer, filename: string): Promise<SplatSource>;
47
+ /**
48
+ * Fetch and decode a splat file: `.ply` (uncompressed 3D Gaussian Splatting),
49
+ * `.spz` (versions 1-4), `.sog`, or an unbundled SOG's `meta.json`.
50
+ *
51
+ * The bytes go through the asset cache (`cachedFetch`). With
52
+ * {@link setShareSplatResources} on, repeated loads of one file share one decode.
53
+ *
54
+ * @param filename - Names the format when the URL does not (a signed CDN URL). Default: the URL's file name.
55
+ * @group Loaders
56
+ */
57
+ export declare function loadSplatSource(url: string, filename?: string): Promise<SplatSource>;
58
+ /**
59
+ * {@link loadSplatSource} without the sharing: always a fresh fetch and
60
+ * decode, for a caller that manages the lifetime of what it loads.
61
+ * @internal
62
+ */
63
+ export declare function fetchSplatSource(url: string, filename?: string): Promise<SplatSource>;
64
+ /**
65
+ * Load a Gaussian-splat file as an unparented {@link Splat}: add its
66
+ * `object3D` to a scene, or to a character's bone, yourself.
67
+ *
68
+ * The PlayCanvas build's `loadSplatAsset`, which returns an asset to mount on
69
+ * a `gsplat` entity; the splat is that mounted thing. See
70
+ * {@link loadSplatSource} for the formats and {@link setShareSplatResources}
71
+ * for loading one model many times.
72
+ *
73
+ * @param filename - Names the format when the URL does not (a signed CDN URL). Default: the URL's file name.
74
+ * @throws {EngineDisposedError} If `engine` is disposed before or while the file loads.
75
+ *
76
+ * @example
77
+ * ```ts
78
+ * const prop = await loadSplatAsset(engine, '/assets/crate.spz');
79
+ * prop.object3D.position.set(1, 0, 0);
80
+ * scene.add(prop.object3D);
81
+ * ```
82
+ *
83
+ * @group Loaders
84
+ */
85
+ export declare function loadSplatAsset(engine: SplatEngine, url: string, filename?: string): Promise<Splat>;
86
+ export {};