@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
package/CHANGELOG.md ADDED
@@ -0,0 +1,38 @@
1
+ # Changelog
2
+
3
+ ## 0.2.0
4
+
5
+ Brings the port level with `@viggle/splat-engine` 0.3.2, the PlayCanvas build the mini games run on. An app written against 0.1.1 keeps working unchanged: the API is a superset of 0.1.1's, the legacy lights (`SunLight`, `SkyLight`, `PointLight`) are as they were, and characters face and move as they did. The PlayCanvas build's newer behaviour comes with `Scene`, the entry point games ported from it use.
6
+
7
+ ### Changed
8
+
9
+ - **Rig, animation and bundle code synced with the PlayCanvas build 0.3.2.** Under a `Scene`, poses match that build bit for bit (the A/B suite's `--ref current`). Two of its changes would turn existing apps' characters, so they follow the entry point:
10
+ - A GLB clip's root rotation. The MetaHuman presets carry a constant 180° yaw on the root bone. A `SplatEngine` (and so the loaders and `SplatEngine.shared`) pins the root bone's rotation to bind as 0.1.1 did, and its characters face as before; a `Scene` keeps the yaw as 0.3.2 does. `legacyRootRotation` on `SplatEngineOptions`, `CreateSceneOptions`, the engine or one armature picks either. Root motion turns with the root.
11
+ - A `.anim` clip's root rotation is reset at parse; some library clips carried a stray constant 90° yaw there. Under a `SplatEngine` the root was pinned anyway, so nothing changes there.
12
+ - **GLB clips are read straight into per-bone keys**, as in 0.3.2, rather than packed into matrices and decomposed again. Against 0.1.1 an animated pose moves by up to 4 mm (the A/B suite's `--ref start`); `Animation.data` is empty for GLB clips.
13
+ - **Bundle size.** An app that uses only the three.js-style loaders grows from 197 KB to 233 KB minified; one on the engine-level API from 193 KB to 252 KB. Relight, VFX, physics and post-processing tree-shake out unless used.
14
+
15
+ ### Added
16
+
17
+ - **`Scene`**, the PlayCanvas build's `Scene` for three.js: `Scene.create(canvas, opts)` makes the renderer (WebGL, or WebGPU with `backend: 'webgpu'` from the `/webgpu` entry), camera, loop (`start`, `on('update' | 'postUpdate' | 'preRender' | 'postRender')`, `maxFps`), sizing (`maxPixelRatio`, `setResolution`), `postfx`, `getOrCreateCameraFrame` and teardown. It is a `SplatEngine`, so `Character.load(scene, …)` works unchanged. `SceneDestroyedError` is `EngineDisposedError` under the PlayCanvas build's name.
18
+ - **Splat effects**, on both backends: `setOpacity`, `setTintMultiply`, `setReveal` / `setRevealLook` / `bakeReveal` (with `Armature.prepareReveal`, `DEFAULT_REVEAL_LOOK`), `setCutGroups` / `setCutOffsets` / `setCut`, `setLayers`, `posedCenters`, `privatizeBoneWeights` / `reuploadBoneWeights`. On `Character`, opacity, reveal and colour hooks reach every LOD level, variant and overlay; `setTint` and `setTintMultiply` reach every LOD level, as `setTint` always has. `SplatCharacter` gains `opacity`, `setTintMultiply`, `setReveal`, `setRevealLook`, `prepareReveal`.
19
+ - **Colour hooks**: `Splat.setColorModifier` / `Character.setColorModifier` run a game's own GLSL, WGSL or TSL on every splat after the engine's colour work, with uniforms bound by reference. This replaces splicing into the PlayCanvas build's `WORK_BUFFER_MODIFIER_GLSL/WGSL`.
20
+ - **`SplatRelight`**, the PlayCanvas build's current lighting: characters and environments lit through voxel proxies (`buildProxyMesh`, `buildVoxelGrid`, …), with sun shadows, point lights and sky, on both backends. `shadowBias` and `normalOffsetBias` take PlayCanvas's numbers and give its picture; `shadowBiasMode: 'three'` takes three.js's instead. The legacy lights are untouched; new lighting work goes here.
21
+ - **Post-processing**: `CameraFrame` (tone mapping with PlayCanvas's `TONEMAP_*`, bloom, grading, vignette, MSAA, sharpen), `PostFX` with `BaseCapturingPass` (PlayCanvas-dialect GLSL / WGSL fragments run unchanged), `PixelartEffect`, `OutlineEffect`.
22
+ - **Physics**: `PhysicsWorld` on the game's own Ammo (`Scene.create({ physics })`) - rigid bodies on `Object3D`s, raycasts, contact and trigger events, `BODYGROUP_*` / `BODYMASK_*` - plus `createConeTwistJoint` / `createHingeJoint` / `createGeneric6DofJoint`, and `Ragdoll` with `DEFAULT_HUMANOID_RAGDOLL` and limb detachment.
23
+ - **Splat scenes**: `.spz` versions 1-4, SOG, `Environment.loadLodBundle` with distance-switched levels, `coarseReady`, `SplatSPZLoader`, `loadSplatAsset`, `loadSplatSource`, `setShareSplatResources`. Decoding runs in an inline worker, or on the main thread where a Content Security Policy blocks it. Version 4 imports `zstddec`, a new dependency, on demand: an import map must map it, and a CSP must allow `connect-src data:` and `script-src 'wasm-unsafe-eval'`.
24
+ - **VFX and presets**: `VfxStage`, `JsonVfxPrefab`, `VfxPool`, the particle / sprite / mesh / shader layers, `prewarmJsonVfxPrefabs`, `MeshFlash`, `playReveal`, `ThirdPersonCamera`, `BodyShapeVariant`, `BoneOverlay`, `mergeSocketLoadout`, `loadGlbFromUrl` (which imports three.js's `GLTFLoader` from `three/addons/` on first use).
25
+ - **Character**: `fetchParsed` / `buildFromLoadResults`, `disableAutoUpdate` / `enableAutoUpdate`, `addOverlaySplat` / `removeOverlaySplat`, `setLayers`.
26
+ - **Armature**: `poseModifier`, `rootOffsetProvider`, `driveNodes`, `tickLayers`, `prepareReveal`, `legacyRootRotation`.
27
+ - **Animation**: `Animation.load` options for clips converted from FBX (`referenceFrameMode`, `referenceBaseAnimation`, `rigidBones`), `prefetch`, crossfade `continueSource` / `easing`.
28
+ - **Asset cache**: `cachedFetch`, `isCached`, `indexAssetCache`, `installFetchInterceptor` / `uninstallFetchInterceptor` (a routed request keeps its headers, credentials and abort signal), `setBinFetch`, `setAssetFetch`. Character bundles held in memory are capped at 96 MB, least recently used out first, as in the PlayCanvas build.
29
+ - **Exports** `UPPER_BODY_BONE_NAMES`, `LOWER_BODY_BONE_NAMES`, `resolveBoneIndices`, `computeBoneStretch`, the body-part helpers.
30
+ - **A/B suite**: `--ref current` compares against the current PlayCanvas build (`npm install --prefix ab/ref-pc`), with cases for every effect above; `ab/check-scene.mjs` covers the `Scene`, `ab/check-fixes.mjs` the review fixes; each module above has its own check against the PlayCanvas reference.
31
+
32
+ ### Differs from the PlayCanvas build
33
+
34
+ - `Ragdoll.writePose` places the spine top, neck and arm bones on their bodies; the PlayCanvas build up to 0.3.2 leaves them 4-18 cm off. The fix is WarpEngine-github/SplatEngine#11, for the PlayCanvas build's next release after 0.3.2.
35
+ - Changing a `RigidBody`'s `type` re-makes the joints that hold it against its new Ammo body; the PlayCanvas build leaves them on the freed one.
36
+ - `SplatRelight` applies PlayCanvas's slope-scaled shadow bias where the proxies receive the key light's shadow, not to every caster as it draws. The relit splats match; meshes of the game's own that receive that shadow get only the constant part.
37
+ - `SplatRelight` under a long shadow distance (the default 40 m, where one shadow texel is several centimetres): the PlayCanvas build self-shadows a character's lit side in coarse patches; this port leaves more of it lit. At 8 m the two match.
38
+ - Not ported: the environment reveal, shock, `clipDistance`, `splatSizeMax`, `sampleWorldPoints`, `probeGroundDepth` (`DEFAULT_ENV_REVEAL_LOOK` is exported for its values only), `applyOverlaySplatStyle`, SSAO (`CameraFrame.ssao` is kept and draws nothing).
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # @viggle/splat-engine-three
2
2
 
3
- Gaussian-splat characters for three.js. Load `.vsplat` characters as `Object3D`s, play MetaHuman GLB skeletal animations with crossfade blending, load `.ply` splat scenes, and render them in your own three.js scene under `WebGLRenderer` or `WebGPURenderer`.
3
+ Gaussian-splat characters for three.js. Load `.vsplat` characters as `Object3D`s, play MetaHuman GLB skeletal animations with crossfade blending, load `.ply` / `.spz` / `.sog` splat scenes and LOD bundles, and render them in your own three.js scene under `WebGLRenderer` or `WebGPURenderer`.
4
4
 
5
- A port of [`@viggle/splat-engine`](https://www.npmjs.com/package/@viggle/splat-engine) with no PlayCanvas dependency. The rig, animation and bundle-decoding code is shared with that package; the renderer is new.
5
+ A port of [`@viggle/splat-engine`](https://www.npmjs.com/package/@viggle/splat-engine) 0.3.2 with no PlayCanvas dependency. The rig, animation and bundle-decoding code is shared with that package; the renderer is new. Everything a game built on that package uses is here too - its `Scene`, relighting, post-processing, physics and ragdolls, VFX and presets - so a game can move across (see [The game-engine layer](#the-game-engine-layer)).
6
6
 
7
7
  ## Install
8
8
 
@@ -82,6 +82,10 @@ character.clip; // what is playing, or null
82
82
  character.addEventListener('finished', (e) => {}); // a non-looping clip ended
83
83
  character.addEventListener('loop', (e) => {}); // a looping clip wrapped
84
84
 
85
+ // Optional for grounded clips such as a dance; pins the lowest splats to y=0.
86
+ // Leave unset for jumps or other intentional airborne motion.
87
+ character.groundLockY = 0;
88
+
85
89
  // A second clip on part of the body, over the base clip
86
90
  character.playLayer('wave', waveClip, { region: 'upperBody', weight: 0.8 });
87
91
  character.stopLayer('wave', 0.2);
@@ -98,6 +102,12 @@ const twin = character.clone(); // shares the decoded data, not th
98
102
  character.dispose(); // free GPU resources
99
103
  ```
100
104
 
105
+ Expression `.vsplat` bundles with 119 bones use their 86 body bones and
106
+ per-character body rest lengths. Their remaining 33 facial influences follow
107
+ the head as a rigid group, keeping the face connected during animation. This
108
+ does not reproduce independent facial expressions; use a 441-bone character
109
+ for those.
110
+
101
111
  Animation goes through this class, not `AnimationMixer`: a splat character has no `Bone` hierarchy for a mixer to drive. A `SplatClip` is not tied to a character - play one clip on any number of them, and call `clip.dispose()` when you are done with it.
102
112
 
103
113
  For several copies of one character, load it once and `clone()` it; loading the same file twice decodes it twice.
@@ -143,7 +153,7 @@ await renderer.init();
143
153
  | Depth sort | CPU - main thread for characters, a worker for static meshes | GPU, compute |
144
154
  | Per-character CPU cost | re-skins every splat centre each frame to feed the sort | a pose evaluation and a palette upload |
145
155
 
146
- **Use WebGPU when you can.** With animated characters on screen a frame costs about 40% of what it does under WebGL, because nothing per-splat happens on the CPU. See [Performance](#performance).
156
+ **Use WebGPU when you can.** Its cost per animated character is about a third of WebGL's, because nothing per-splat happens on the CPU. See [Performance](#performance).
147
157
 
148
158
  `WebGPURenderer` must actually be running on WebGPU. Its WebGL2 fallback (`forceWebGL`, or a browser without WebGPU) has no compute shaders and cannot draw splats; the package logs an error saying so. Check before you build the scene, and use `THREE.WebGLRenderer` on those devices:
149
159
 
@@ -167,12 +177,17 @@ That setting applies to the whole renderer: other materials in the scene are the
167
177
 
168
178
  Ported, and checked against the PlayCanvas build by the A/B suite (see [Verification](#verification)):
169
179
 
170
- - Characters - loading `.vsplat` bundles, position / rotation / scale, tint, colour grade
180
+ - Characters - loading `.vsplat` bundles, position / rotation / scale, tint (mix and multiply), colour grade, opacity, the feet-to-head reveal, cut pieces, colour hooks
171
181
  - Animation - GLB clips, crossfade, layers with bone masks, root motion
172
- - Rig - pose evaluation, bone-length scaling (`setBoneStretch`)
173
- - Splat scenes - uncompressed `.ply`, with position / rotation / scale
174
- - `SunLight`, `SkyLight`, `PointLight`
182
+ - Rig - pose evaluation, bone-length scaling (`setBoneStretch`, stretching and shrinking)
183
+ - Splat scenes - `.ply`, `.spz` (versions 1-4), SOG, and streamed LOD bundles (`Environment.loadLodBundle`)
184
+ - `SunLight`, `SkyLight`, `PointLight` (against the version this port started from; the current PlayCanvas build has removed them)
185
+ - `SplatRelight` - characters and environments lit through voxel proxies, with sun shadows and point lights
186
+ - `Scene`, `CameraFrame` (tone mapping, bloom, grading, vignette), `PostFX` and `BaseCapturingPass`, `PixelartEffect`, `OutlineEffect`
187
+ - `PhysicsWorld` (Ammo rigid bodies, raycasts, contact and trigger events), joints, `Ragdoll`
188
+ - `VfxStage` and JSON prefabs (particle, sprite, mesh and shader layers), `MeshFlash`, `playReveal`, `ThirdPersonCamera`, `BodyShapeVariant`, `BoneOverlay`, socket loadouts
175
189
  - Render options - anti-aliasing, sub-pixel culling, per-group visibility (`setSplatGroups` / `setVariantMask`)
190
+ - Quality settings - `SplatQuality`, ported from the Unity build of the same engine rather than from the PlayCanvas one. Everything that applies to a renderer with no offscreen splat target; see [Tuning](#tuning) for which of its knobs did not come across and why.
176
191
 
177
192
  Ported from the same source, but not exercised by the suite for want of test assets:
178
193
 
@@ -181,13 +196,98 @@ Ported from the same source, but not exercised by the suite for want of test ass
181
196
  - Multi-level character LOD (`Character.load([...])`, `addLodLevel`, `setRenderLod`) and variant splats (`addVariantSplat`)
182
197
  - Animation LOD and sort LOD
183
198
 
184
- Not ported:
199
+ Not ported, because no game built on the PlayCanvas build uses them, or three.js has its own:
200
+
201
+ - `ShadowSystem` (the legacy lights' shadows; `SplatRelight` replaces it)
202
+ - CRT and stained-glass effects, SSAO (`CameraFrame.ssao` is kept so settings carry over, and draws nothing)
203
+ - Compressed `.ply`, environment clip bounds and camera cutaway
204
+ - On environments: the reveal (`DEFAULT_ENV_REVEAL_LOOK` is exported for its values only), shock, `clipDistance`, `splatSizeMax`, `sampleWorldPoints` and `probeGroundDepth`
205
+ - `applyOverlaySplatStyle`, the see-through overlay layer style; an overlay splat from `addOverlaySplat` takes `setOpacity` or a colour hook instead
206
+ - `DamageVariant`, `CharacterMotor`, `WasdController`, orbit / fly controls, `TileGrid`, grid / sky dome / ground plane / gizmos, scene colliders, scene probe, `MeshCharacter`. The controls and helpers have direct three.js equivalents (`OrbitControls`, `GridHelper`, …).
207
+
208
+ ## The game-engine layer
209
+
210
+ Above characters and splat scenes, the PlayCanvas build is a small game engine: a `Scene` that owns the canvas and the loop, relighting, post-processing, physics, VFX. All of it is here, under the same names, so a game written against that build ports by replacing PlayCanvas objects with three.js ones rather than by rewriting its engine calls.
211
+
212
+ ```typescript
213
+ import { Scene, Character, Animation, SplatRelight, TONEMAP_ACES2 } from '@viggle/splat-engine-three/webgpu';
214
+
215
+ const scene = await Scene.create(canvas, {
216
+ backend: 'webgpu', // falls back to WebGL where WebGPU is missing
217
+ fov: 70, maxPixelRatio: 2,
218
+ bgColor: { r: 0.05, g: 0.06, b: 0.08, a: 1 },
219
+ physics: { loadAmmo }, // the game ships Ammo; the engine never bundles it
220
+ });
221
+ const hero = await Character.load(scene, '/assets/hero.vsplat');
222
+ await Animation.loadGlb(scene, '/assets/idle.glb', 'idle');
223
+ hero.playAnimation('idle', { loop: true });
224
+
225
+ const frame = scene.getOrCreateCameraFrame();
226
+ frame.rendering.toneMapping = TONEMAP_ACES2;
227
+ frame.bloom.intensity = 0.03;
185
228
 
186
- - Shadows (`ShadowSystem`)
187
- - Post effects (`PostFX`, pixel-art, CRT, outline, stained glass) and the VFX system
188
- - Ragdoll and the physics joints
189
- - `.spz`, compressed `.ply`, SOG and streamed LOD bundles for environments; environment clip bounds and camera cutaway
190
- - Presets: `DamageVariant`, `BodyShapeVariant`, `CharacterMotor`, `WasdController`, camera controls, `TileGrid`, grid / sky dome / gizmos. The camera controls and helpers have direct three.js equivalents (`OrbitControls`, `GridHelper`, …).
229
+ const relight = SplatRelight.create(scene, { /* sun, sky */ });
230
+ await relight.add(hero);
231
+
232
+ scene.on('update', (dt) => { /* game logic */ });
233
+ scene.start();
234
+ ```
235
+
236
+ `Scene` is a `SplatEngine`, so everything in [The engine-level API](#the-engine-level-api) takes it. It plays GLB clips as the PlayCanvas build 0.3.2 does, keeping the clip's root rotation; see [GLB clips and the root bone](#glb-clips-and-the-root-bone). Where the PlayCanvas build hands out PlayCanvas objects, this one hands out three.js ones:
237
+
238
+ | PlayCanvas build | here |
239
+ |---|---|
240
+ | `scene.app`, `scene.graphicsDevice` | `scene.renderer`, `scene.threeScene` |
241
+ | `scene.cameraEntity` | `scene.camera` (a `PerspectiveCamera`) |
242
+ | `scene.graphicsDevice.setResolution(w, h)` / `.maxPixelRatio` | `scene.setResolution(w, h)` / `scene.maxPixelRatio` |
243
+ | `scene.app.on('update', fn)` | `scene.on('update', fn)` (also `postUpdate`, `preRender`, `postRender`) |
244
+ | `armature.entity`, `splat.entity`, `environment.entity` | `.object3D` |
245
+ | `entity.addComponent('rigidbody' / 'collision', …)` | `scene.physics.addBody(object, { shape, type, mass, … })` |
246
+ | `entity.rigidbody`, `app.systems.rigidbody.raycastFirst` | `scene.physics.getBody(object)`, `scene.physics.raycastFirst` |
247
+ | `gsplat.setWorkBufferModifier({ glsl, wgsl })` with `WORK_BUFFER_MODIFIER_*` | `character.setColorModifier({ glsl, wgsl \| tsl, uniforms })` |
248
+ | `loadGlbFromUrl(app, url, cb)` → container asset | `loadGlbFromUrl(url)` → `GLTF` |
249
+
250
+ The `PhysicsWorld` class comment carries the full rigid-body mapping.
251
+
252
+ ### Colour hooks
253
+
254
+ The PlayCanvas build let a game splice its own code into the engine's splat shader. Here a game hands the engine a function, which runs on every splat after the engine's own colour work - lighting, tint, relight, grade, reveal, opacity:
255
+
256
+ ```typescript
257
+ const fade = { uFade: { value: 1 } };
258
+ character.setColorModifier({
259
+ uniforms: fade,
260
+ glsl: `void modifySplatColor(vec3 center, vec3 modelCenter, vec3 restCenter, uint splatIndex, inout vec4 color) {
261
+ color.a *= uFade;
262
+ }`,
263
+ wgsl: `fn modifySplatColor(center: vec3f, modelCenter: vec3f, restCenter: vec3f, splatIndex: u32,
264
+ color: vec4f, uFade: f32) -> vec4f {
265
+ return vec4f(color.rgb, color.a * uFade);
266
+ }`,
267
+ });
268
+ fade.uFade.value = 0.5; // next frame
269
+ ```
270
+
271
+ `glsl` serves `WebGLRenderer`; `wgsl` (or `tsl`, a TSL builder) serves `WebGPURenderer`. Many hooks in the PlayCanvas games only faded a character, which `setOpacity` now does without one.
272
+
273
+ ### Lighting: legacy lights and `SplatRelight`
274
+
275
+ The two lighting paths are independent. `SunLight` / `SkyLight` / `PointLight` multiply each splat's colour by a factor evaluated at its centre, and are kept exactly as they were. `SplatRelight` is the PlayCanvas build's current lighting: each target gets a voxel proxy, the proxies are lit and shadowed by three.js lights into a screen-space texture, and every splat looks its lighting up there. It costs a proxy render per frame, so give it the player and a few actors, not a crowd. New lighting work happens in `SplatRelight` only.
276
+
277
+ ### GLB clips and the root bone
278
+
279
+ The MetaHuman GLB presets carry a constant 180° yaw on their root bone. Up to 0.1.1 this package pinned the root bone's rotation to bind every frame, which threw that yaw away; the PlayCanvas build 0.3.2 keeps it, so a preset faces the way the clip says. Both behaviours are here, picked by where the character lives:
280
+
281
+ | | root rotation | GLB presets face |
282
+ |---|---|---|
283
+ | `new SplatEngine()`, `SplatEngine.shared`, the loaders (0.1.1 apps) | pinned to bind, as in 0.1.1 | as they always did here |
284
+ | `Scene.create()` (games ported from the PlayCanvas build) | kept, as in PlayCanvas 0.3.2 | turned 180° from the above |
285
+
286
+ Set `legacyRootRotation` to choose: on `SplatEngineOptions` / `CreateSceneOptions`, on `engine.legacyRootRotation`, or on one `character.armature`. Root motion turns with the root, so `consumeRootMotionDelta` follows the same choice. Clips whose root bone carries no rotation - every `.anim`, and GLBs from the pipeline since September 2026 - play the same either way.
287
+
288
+ - The engine's setting is read every frame, so changing it turns the characters already loaded too, except those with a setting of their own. Assigning `null` to `character.armature.legacyRootRotation` makes one follow its engine again.
289
+ - Choose before clips play. Changed mid-clip under root-motion `'apply'`, a character jumps by twice its current pelvis offset.
290
+ - The loaders put characters in `SplatEngine.shared`, which pins the root. An app that also creates a `Scene` gets the two sets of characters facing opposite ways unless it sets one of them to match.
191
291
 
192
292
  ## The engine-level API
193
293
 
@@ -221,9 +321,17 @@ One difference to know when mixing the two: `Character.setPosition` lowers the m
221
321
 
222
322
  ## Differences from the PlayCanvas build
223
323
 
224
- - **No `Scene`.** `Scene.create(canvas)` + `scene.start()` become your own renderer, scene and render loop.
324
+ - **`Scene` is optional.** Applications with their own renderer and loop use `SplatEngine` and the loaders, and call `engine.update(dt)` themselves.
325
+ - **Colour hooks are functions, not shader splices.** See [Colour hooks](#colour-hooks).
326
+ - **`Ragdoll.writePose` places every bone on its body.** The PlayCanvas build up to 0.3.2 reuses a scratch matrix inside a recursion, which puts the spine top, neck and arms 4-18 cm off their bodies; this port has the fix that build is getting next. The bodies simulate the same either way (final pelvis height equal to 1e-4 m).
327
+ - **Relight shadow bias is taken at the proxy.** `shadowBias` and `normalOffsetBias` mean what they mean in PlayCanvas and give the same picture (see [Verification](#verification)), but PlayCanvas's slope-scaled offset is applied where the proxies receive the key light's shadow rather than to every caster as it draws. Meshes of the game's own that receive that shadow get the constant part only. `shadowBiasMode: 'three'` takes the numbers as three.js's `shadow.bias` / `normalBias` instead.
328
+ - **Joints survive a body changing type.** Changing a `RigidBody`'s `type` rebuilds its Ammo body; joints holding it are re-made against the new one. The PlayCanvas build leaves them on the freed body.
329
+ - **`OutlineEffect` shows through walls and `PixelartEffect`'s character mask does not,** as in the PlayCanvas build.
330
+ - **Splats under a `CameraFrame` blend in linear light,** as in the PlayCanvas build; the background is display colour on the canvas and linear inside a frame, also as there.
225
331
  - **Environments always respond to lights.** In the PlayCanvas build an environment only follows `SunLight` / `SkyLight` once a `ShadowSystem` is bound; without one it stays unlit whatever lights exist. Here it follows them from the start.
226
- - **Character bundles decode on the main thread.** There is no worker file to keep track of, so the bundler notes in that build's README do not apply. A bundle decodes in a few milliseconds.
332
+ - **Character bundles decode on the main thread.** There is no worker file to keep track of, so the bundler notes in that build's README do not apply. A bundle decodes in a few milliseconds. Splat scenes (`.spz`, SOG) decode in an inline worker built from a `blob:` URL that needs no file of its own either, and on the main thread where a Content Security Policy blocks it.
333
+ - **Version-4 `.spz` needs `zstddec`,** a dependency of this package that is imported on demand. Bundlers resolve it; with an import map, map `zstddec` too. It loads its WebAssembly through `fetch(data:)`, so a Content Security Policy must allow `connect-src data:` and `script-src 'wasm-unsafe-eval'`.
334
+ - **`loadGlbFromUrl` imports three.js's `GLTFLoader` on first use,** from `three/addons/`. Nothing else in the package needs `three/addons`.
227
335
  - **Under WebGPU, at most 16 point lights and 64 variant groups** are evaluated.
228
336
 
229
337
  ### Depth and draw order
@@ -232,44 +340,194 @@ Splats test against the depth buffer and do not write it. Opaque meshes therefor
232
340
 
233
341
  ## Performance
234
342
 
343
+ For what to change when these numbers are not good enough on a given device, see [Tuning](#tuning).
344
+
235
345
  Mean time per frame, 1920×1080, NVIDIA RTX 3090, Chromium (headless, vsync off), median of five runs. Lower is better. The first two columns are the original PlayCanvas engine on the same scenes, for reference.
236
346
 
237
347
  <!-- BENCH_TABLE -->
238
348
  | Scenario | Splats | PlayCanvas, WebGL | PlayCanvas, WebGPU | this package, WebGL | this package, WebGPU |
239
349
  |---|--:|--:|--:|--:|--:|
240
- | 1 character | 46,983 | 1.22 ms | 11.13 ms | 1.17 ms | **0.76 ms** |
241
- | 8 characters | 356,960 | 14.13 ms | 11.08 ms | 10.29 ms | **3.91 ms** |
242
- | 32 characters | 1,427,840 | 40.94 ms | 31.48 ms | 37.60 ms | **14.84 ms** |
243
- | room, still camera | 1,048,576 | 2.77 ms | 14.47 ms | **1.71 ms** | 1.71 ms |
244
- | room, orbiting camera | 1,048,576 | 3.40 ms | 14.67 ms | **1.85 ms** | 5.10 ms |
245
- | room + 4 characters, orbiting | 1,227,056 | **5.44 ms** | 20.71 ms | 6.43 ms | 7.09 ms |
350
+ | 1 character | 46,983 | 1.48 ms | 13.66 ms | 1.42 ms | **0.96 ms** |
351
+ | 8 characters | 356,960 | 11.37 ms | 12.76 ms | 13.44 ms | **4.18 ms** |
352
+ | 32 characters | 1,427,840 | 40.78 ms | 39.58 ms | 45.78 ms | **15.13 ms** |
353
+ | room, still camera | 1,048,576 | 2.73 ms | 15.54 ms | **1.70 ms** | 2.07 ms |
354
+ | room, orbiting camera | 1,048,576 | 3.39 ms | 15.54 ms | **1.86 ms** | 5.28 ms |
355
+ | room + 4 characters, orbiting | 1,227,056 | **6.64 ms** | 22.31 ms | 9.76 ms | 7.23 ms |
246
356
  <!-- /BENCH_TABLE -->
247
357
 
248
358
  Reading the table:
249
359
 
250
- - The two WebGL columns do the same work per character - both re-skin every splat centre on the CPU to feed the depth sort - and are equal to within run-to-run noise. The machine was shared while these were measured; the character rows, which are CPU-bound, moved by about ±20% between runs.
251
- - Under WebGPU that work moves to the GPU, which is where the 2.5x on the character rows comes from (3x in a run where the CPU was busier). What remains on the CPU is pose evaluation.
252
- - With a turning camera and nothing animated, WebGL is ahead: it re-sorts a static mesh in a worker and keeps drawing the previous order meanwhile, while WebGPU re-sorts on the GPU inside the frame. The WebGPU order is never a frame behind; the WebGL one can be.
253
- - The PlayCanvas WebGPU column sat on an ~11 ms floor in this harness, which drives that engine one `app.tick()` at a time. That was not investigated and may not reflect how it behaves under its own frame loop.
360
+ - The two WebGL columns do the same work per character - both re-skin every splat centre on the CPU to feed the depth sort - and are equal to within the run-to-run noise of the shared machine these were measured on (roughly ±20% on the character rows).
361
+ - The WebGPU backend moves that work to the GPU, which is where the 3x on the character rows comes from. What remains on the CPU is pose evaluation.
362
+ - With a moving camera and nothing animated, the WebGL backend is ahead: it re-sorts the environment in a worker and keeps drawing the previous order meanwhile, while the WebGPU backend re-sorts on the GPU inside the frame. The WebGPU result is never a frame behind; the WebGL one can be.
363
+ - The PlayCanvas WebGPU column sat on a ~13 ms floor in this harness, which drives that engine one `app.tick()` at a time. That was not investigated and may not reflect how it behaves under its own frame loop.
254
364
 
255
365
  Regenerate with `npm run bench -- --backend <webgl|webgpu|webgpu-managed|pc-webgl|pc-webgpu>`, then `node scripts/readme-tables.mjs`.
256
366
 
367
+ ## Tuning
368
+
369
+ A splat frame is bound by one of two things, and that decides which knobs do anything:
370
+
371
+ | Bound by | When | What moves it |
372
+ |---|---|---|
373
+ | **Fragments** (GPU) | WebGPU; anything static; a character filling the screen | `quadAlphaCutoff` |
374
+ | **Splats** (main thread) | WebGL with animated characters - every centre is re-skinned each frame to feed the CPU sort | `minOpacity`, `pruneRatio`, the distance throttles |
375
+
376
+ Measured on 32 animated characters under WebGL: 26.5 ms of main thread per frame, of which 23.7 ms is skinning and 2.8 ms the sort. `node ab/profile-stages.mjs` prints this split for any scene.
377
+
378
+ Settings are module-level, on `SplatQuality`, read per frame (or per decode, where stated). Two ship non-zero.
379
+
380
+ ### `quadAlphaCutoff` — default `8 / 255`
381
+
382
+ Sizes each splat's quad to the radius its own opacity reaches, instead of the worst case. Fewer blended fragments; harder splat edges, visible first on hair, fabric and faces. **Takes effect next frame**, reversible, safe to drive from a frame-rate governor. Clamped to `[0, 1]`.
383
+
384
+ | Value | |
385
+ |---|---|
386
+ | `1 / 255` | Identical to the behaviour before this knob existed. A reference, not a setting. |
387
+ | `8 / 255` | **Default.** Also what the Unity build ships. |
388
+ | `12 / 255` | One step down. |
389
+ | `16 / 255` | **Low-end, and the floor.** |
390
+ | above `16 / 255` | Don't. More performance is there, but every silhouette hardens; spend it on `pruneRatio`, pixel ratio or a distance LOD instead. |
391
+
392
+ Cost on a face filling a 760px frame, against `1 / 255`: `8/255` 40.7 dB / 3.1% of pixels off by >8; `12/255` 36.8 dB / 7.8%; `16/255` 34.3 dB / 11.2%. Frame time where fragments bind, against `1 / 255`: `8/255` -29%, `16/255` -42%.
393
+
394
+ ### `minOpacity` — default `0.05`, hard cap `0.1`
395
+
396
+ Drops splats whose peak opacity is below the threshold. Saves memory, skinning, sorting and rasterisation together, where `quadAlphaCutoff` saves rasterisation alone.
397
+
398
+ - **Applied during the decode of a character bundle.** Set it before `load()`; changing it later needs a reload.
399
+ - **Does not touch `.ply` scenes** - same scope as the Unity build. `0.05` removes 8.7% of the test character but 41.8% of the 1M-splat test room. `pruneSplats` is exported for scenes.
400
+ - **Changes `Splat.numSplats`.** A `setSplatGroups` array must be built from the loaded splats, not from the file. An array authored offline against the file cannot be truncated to fit - its indices no longer line up.
401
+ - **Values above `0.1` are clamped**, with one console warning. Enforced because every increment buys frame time while the cost arrives gradually and everywhere, so nothing tells a tuning pass to stop.
402
+
403
+ | Value | Cost on a face filling the frame | Splats kept |
404
+ |---|---|---|
405
+ | `0` | none | 100% |
406
+ | `1 / 255` | pixel-identical | 98% |
407
+ | `0.05` | max 20/255, 0.94% of pixels off by >8 | 91% |
408
+ | `0.1` (cap) | max 45/255, 9.3% of pixels off by >8 | 83% |
409
+
410
+ ### The rest
411
+
412
+ ```ts
413
+ SplatQuality.pruneRatio = 0.3; // 0..1, decode-time, characters only: drop the weakest
414
+ // share of every pruneVoxelSize cell by opacity x footprint
415
+ SplatQuality.pruneVoxelSize = 0.04; // metres; the cell that quota is per
416
+ SplatQuality.screenSizeCull = 0; // pixels; drop splats smaller than this. For distant crowds
417
+ SplatQuality.depthOcclusion = true; // scene geometry hides splats. Correctness, not performance:
418
+ // this renderer gets the hardware depth test for free
419
+ SplatQuality.passTimings = false; // then read SplatQuality.timings after each render
420
+ ```
421
+
422
+ `pruneRatio` ranks inside each cell, not globally: a face is many faint splats where a jacket is few strong ones, so a global rank deletes the face first.
423
+
424
+ ### Distance throttles, per character
425
+
426
+ ```ts
427
+ SplatEngine.shared.camera = camera; // all three measure distance from it; without it they no-op
428
+
429
+ character.setSplatCountLod({ nearDist: 4, farDist: 16, farFraction: 0.25 });
430
+ character.armature.setSortLod({ nearDist: 5, farDist: 15, nearStride: 2, farStride: 4 });
431
+ character.armature.setAnimationLod({ nearDist: 12, farDist: 24, nearStride: 2, farStride: 4 });
432
+ ```
433
+
434
+ All off until called. `nearStride` applies between `nearDist` and `farDist`, `farStride` beyond `farDist` - **set both**, or the band most of a crowd is standing in keeps its previous value.
435
+
436
+ `setSplatCountLod` is `pruneRatio` made dynamic: nothing is discarded, and the fraction skinned, sorted and drawn follows camera distance, by the same per-cell importance. WebGL backend only - that is the one paying per splat on the CPU.
437
+
438
+ ### Per device
439
+
440
+ Pixel ratio first; it is not in this package and it is larger than everything below it. A phone reports `devicePixelRatio` 3, which is nine times the fragments.
441
+
442
+ ```ts
443
+ renderer.setPixelRatio(Math.min(window.devicePixelRatio, 1.5));
444
+ ```
445
+
446
+ | Tier | `quadAlphaCutoff` | `minOpacity` | `pruneRatio` | Pixel ratio | Also |
447
+ |---|---|---|---|---|---|
448
+ | Desktop / flagship | `8 / 255` | `0.05` | `0` | ≤ 2 | — |
449
+ | Mid-range phone | `12 / 255` | `0.05` | `0` | ≤ 1.5 | — |
450
+ | Low-end phone | `16 / 255` | `0.05` | `0.3` | ≤ 1.5 | `setSplatCountLod({ nearDist: 3, farDist: 12, farFraction: 0.25 })` |
451
+ | Very low-end, or a crowd | `16 / 255` | `0.05` | `0.5` | 1 | plus `setSortLod` / `setAnimationLod` |
452
+
453
+ On WebGL with several animated characters the cutoff column does nothing; spend the budget to its right.
454
+
455
+ ### Measured
456
+
457
+ 1920×1080, Apple M5 Pro, headless Chromium, vsync off. Baseline is **every knob off**, including the two that ship on, so the `DEFAULT` rows are what the defaults themselves cost and buy. `~` is inside that column's noise floor.
458
+
459
+ <!-- QUALITY_TABLE -->
460
+ | Setting | Splats | PSNR | Worst pixel | WebGL, 2 close | WebGL, 2 close, GPU only |
461
+ |---|--:|--:|--:|--:|--:|
462
+ | `DEFAULT cutoff 8/255` | - | 53.4 dB | 31/255 | ~ | -22% |
463
+ | `DEFAULT 8/255 + minOp 0.05` | 78,004 | 53.0 dB | 31/255 | -10% | -22% |
464
+ | `cutoff 12/255` | - | 48.5 dB | 47/255 | ~ | -24% |
465
+ | `cutoff 16/255` | - | 45.3 dB | 63/255 | ~ | -29% |
466
+ | `cutoff 16 + minOp 0.05` | 78,004 | 45.3 dB | 63/255 | -12% | -30% |
467
+ | `cutoff 24/255` | - | 40.8 dB | 98/255 | ~ | -34% |
468
+ | `cutoff 32/255` | - | 37.5 dB | 144/255 | ~ | -36% |
469
+ | `minOpacity 1/255` | 87,262 | ∞ | 0/255 | ~ | ~ |
470
+ | `minOpacity 0.05` | 78,004 | 61.7 dB | 14/255 | -11% | ~ |
471
+ | `prune 0.3` | 64,755 | 43.9 dB | 174/255 | -23% | -8% |
472
+ | `prune 0.5` | 45,952 | 37.8 dB | 187/255 | -42% | -20% |
473
+ | `screenSizeCull 1px` | - | ∞ | 0/255 | ~ | +10% |
474
+ | `screenSizeCull 2px` | - | 100.8 dB | 4/255 | ~ | ~ |
475
+ | `cutoff 16 + prune 0.3` | 64,755 | 40.3 dB | 179/255 | -22% | -36% |
476
+ | `cutoff 16 + prune 0.3 + minOp 0.05` | 56,824 | 40.2 dB | 179/255 | -31% | -36% |
477
+ | `countLod 0.5` | - | 35.2 dB | 190/255 | -43% | -17% |
478
+ | `countLod 0.3` | - | 31.1 dB | 196/255 | -41% | -35% |
479
+ | `countLod 0.3 + cutoff 16` | - | 30.4 dB | 201/255 | -57% | -47% |
480
+ | `sortLod stride 2` | - | 48.2 dB | 56/255 | -24% | ~ |
481
+ | `sortLod stride 4` | - | 48.2 dB | 56/255 | -24% | ~ |
482
+ | `animLod stride 2` | - | ∞ | 0/255 | -38% | ~ |
483
+
484
+ Noise floor per column: WebGL, 2 close ±9%, WebGL, 2 close, GPU only ±6%. `~` is a result inside it. Splats are per scene where a setting changes the count, `-` where it does not.
485
+ <!-- /QUALITY_TABLE -->
486
+
487
+ `screenSizeCull` culls nothing in these scenes (frames are bit-identical) yet reads +10% in one column: a single run can still mislead. The throttles read the same because two characters cannot separate skipping half the frames from skipping three quarters; on 32 characters, per-frame main-thread ms:
488
+
489
+ | | frame | update | skin | sort |
490
+ |---|--:|--:|--:|--:|
491
+ | baseline | 29.9 | 26.5 | 23.7 | 2.8 |
492
+ | `sortLod` stride 2 | 16.5 | 14.6 | 11.9 | 1.4 |
493
+ | `sortLod` stride 4 | 9.9 | 8.8 | 6.1 | 0.7 |
494
+ | `countLod 0.3` | 12.2 | 10.1 | 7.3 | 1.7 |
495
+ | `prune 0.5` | 16.7 | 14.7 | 11.9 | 1.4 |
496
+
497
+ With skinning throttled away the floor is pose evaluation, a couple of ms per 32 characters.
498
+
499
+ ```bash
500
+ npm run build
501
+ node ab/run-quality-ab.mjs --backend webgl --scenario fill-2 # [--animate 0] for GPU alone
502
+ node ab/profile-stages.mjs --scenario crowd-32 # which stage a setting cut
503
+ node ab/quality-shots.mjs # contact sheets to judge by eye
504
+ node scripts/readme-tables.mjs # rewrite the table above
505
+ ```
506
+
507
+ Scenarios: `fill-2`, `crowd-16`, `crowd-32`, `room`, `room-4`.
508
+
509
+ ### Not ported
510
+
511
+ `RenderScale`, `LdrRenderTarget`, `FitTargetToCharacters`, `FitCompositeOnly` act on an offscreen splat target. This package draws straight into the camera's target - the mode the Unity build measured as its fastest - so they have nothing to act on. For a lower splat resolution, render the whole frame smaller.
512
+
513
+ `SplitComputeAndDraw` (batching every splat's compute ahead of all draws, worth 11.6% on a Mali-G57) was ported and removed: `WebGPURenderer` already submits each compute call in its own command buffer ahead of the render pass, so there is no interleaving to undo, and it measured 6-18% slower.
514
+
257
515
  ## Verification
258
516
 
259
517
  `ab/` holds an A/B suite that drives the PlayCanvas build and this package through the same cases - both characters, every supplied clip, crossfades, layers, root motion, transforms, tint, grade, lights, bone stretch, variant masks, and the splat scene - and compares:
260
518
 
261
- - **Bone matrices**, numerically. They are bit-identical to the PlayCanvas build in every case.
519
+ - **Bone matrices**, numerically. Against the current PlayCanvas build (0.3.2, `--ref current`) they are bit-identical in every case. Against the build this port began from (the default), GLB clips move by up to 4 mm, because 0.3.x reads their keys directly rather than through matrices.
262
520
  - **Rendered frames**, per pixel. See the table below; the PlayCanvas build's own WebGL and WebGPU renderers differ from each other by about as much as this package differs from either.
263
521
 
264
522
  The suite runs this package through the three.js-style API by default, and can run it through the engine-level API instead (`--api engine`); both pass. What has no counterpart in the PlayCanvas build - loaders and the `LoadingManager`, events, time in seconds, `clone`, `dispose` - is covered by `ab/check-api.mjs`.
265
523
 
266
524
  <!-- AB_TABLE -->
267
- | Compared with the PlayCanvas build (WebGL) | Cases | Bone matrices, max difference | PSNR, median | PSNR, worst | Pixels off by more than 8/255, worst case |
525
+ | Compared with the PlayCanvas build this port began from (WebGL) | Cases | Bone matrices, max difference | PSNR, median | PSNR, worst | Pixels off by more than 8/255, worst case |
268
526
  |---|--:|--:|--:|--:|--:|
269
- | WebGL backend, characters | 66 | 0 | 55.5 dB | 45.7 dB | 0.050% |
270
- | WebGL backend, environment | 10 | 0 | 44.1 dB | 42.6 dB | 0.040% |
271
- | WebGPU backend, characters | 66 | 0 | 55.6 dB | 45.7 dB | 0.048% |
272
- | WebGPU backend, environment | 10 | 0 | 44.1 dB | 42.6 dB | 0.041% |
527
+ | WebGL backend, characters | 68 | 1.9 mm | 58.7 dB | 40.0 dB | 1.238% |
528
+ | WebGL backend, environment | 10 | < 0.01 mm | 55.8 dB | 49.2 dB | 0.227% |
529
+ | WebGPU backend, characters | 68 | 1.9 mm | 58.8 dB | 39.9 dB | 1.241% |
530
+ | WebGPU backend, environment | 10 | < 0.01 mm | 56.1 dB | 49.1 dB | 0.234% |
273
531
  <!-- /AB_TABLE -->
274
532
 
275
533
  ```bash
@@ -279,10 +537,25 @@ npm run ab -- --port webgpu # WebGPU
279
537
  npm run ab -- --api engine # the engine-level API instead
280
538
  node ab/check-api.mjs # the three.js-style API's own contract
281
539
  node ab/check-stability.mjs # still frames must be bit-stable
282
- node ab/check-consumer.mjs <dir> # pack, install into a Vite + TypeScript project, build, run
540
+ node ab/check-prune.mjs # the load-time prune keeps every column in lockstep
541
+ node ab/check-animation.mjs # a playing clip must actually reach the screen
542
+
543
+ npm install --prefix ab/ref-pc # the current PlayCanvas build, once
544
+ npm run ab -- --ref current # against it: poses, and the newer splat effects
545
+ node ab/check-scene.mjs # the Scene facade
546
+ node ab/check-fixes.mjs # one check per fix from the 0.2.0 review
547
+ node ab/run-relight.mjs # SplatRelight vs PlayCanvas
548
+ node ab/run-postfx-check.mjs # CameraFrame, PostFX, pixel-art, outline vs PlayCanvas
549
+ node ab/check-physics.mjs # rigid bodies, events, raycasts, ragdoll (Ammo from test-assets/ammo/)
550
+ node ab/check-env.mjs # .spz / SOG / LOD bundles vs PlayCanvas
551
+ node ab/run-vfx.mjs # VFX and presets vs PlayCanvas
283
552
  ```
284
553
 
285
- `check-consumer.mjs` takes a scratch project that depends on `three`, `vite` and `typescript` and has the README's quick start as its source; it verifies the published `exports`, the type declarations under `strict`, and that a minified production build still runs under both renderers.
554
+ `--ref` picks the PlayCanvas build: `start` (the default) is the version this port began from, which still has the legacy lights; `current` is 0.3.2, which no longer does. Against `current` - run with `legacyRootRotation` off, as a `Scene` has it - bone matrices are bit-identical in every case and frames score 49-63 dB (median 59.5), the newer effects (opacity, multiply tint, reveal, cut, colour hooks) included. Against `start`, with a `SplatEngine`'s default of pinning the root, the table above holds; see [GLB clips and the root bone](#glb-clips-and-the-root-bone).
555
+
556
+ `node ab/check-fixes.mjs` holds one check per fix from the 0.2.0 review: the root-rotation defaults, cut bounds, sprite disposal, WebGPU buffer reuse, relight ignoring `scene.environment`, LOD manifest validation, the fetch interceptor, decoding without a worker, and the shape of `dist`.
557
+
558
+ The module checks, against the PlayCanvas reference where it has a counterpart, both backends: relight 54-62 dB on the lit frames of the character and stage cases and 39-40 dB in the room (`chamber`), with PlayCanvas's own default bias reproduced at 36 dB; post-processing 34-48 dB; `.spz` / SOG scenes 41-64 dB and streamed LOD bundles 33-45 dB; VFX and the reveal 32-88 dB (WebGPU blends in linear light, which sets the low end); ragdoll final pelvis height equal to 1e-4 m.
286
559
 
287
560
  The suite needs a GPU-backed headless Chromium (`npx playwright install chromium`).
288
561