@viggle/splat-engine-three 0.1.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +58 -0
- package/README.md +158 -20
- package/dist/chunks/chunk-2GKWT24B.js +23182 -0
- package/dist/chunks/chunk-2GKWT24B.js.map +7 -0
- package/dist/index.js +235 -3
- package/dist/types/anim/animation-conversion.d.ts +2 -2
- package/dist/types/anim/keyframe-splines.d.ts +17 -41
- package/dist/types/animation.d.ts +84 -28
- package/dist/types/armature.d.ts +280 -2
- package/dist/types/character.d.ts +120 -2
- package/dist/types/effects/index.d.ts +12 -0
- package/dist/types/effects/outlines/outline-effect.d.ts +98 -0
- package/dist/types/effects/outlines/outline-shaders.d.ts +14 -0
- package/dist/types/effects/pixelart/pixelart-effect.d.ts +152 -0
- package/dist/types/effects/pixelart/pixelart-shaders.d.ts +31 -0
- package/dist/types/effects/postfx/base-capturing-pass.d.ts +109 -0
- package/dist/types/effects/postfx/camera-frame.d.ts +103 -0
- package/dist/types/effects/postfx/frame-renderer.d.ts +32 -0
- package/dist/types/effects/postfx/frame-shaders.d.ts +19 -0
- package/dist/types/effects/postfx/mask.d.ts +44 -0
- package/dist/types/effects/postfx/postfx.d.ts +144 -0
- package/dist/types/effects/postfx/program.d.ts +74 -0
- package/dist/types/effects/postfx/uniforms.d.ts +24 -0
- package/dist/types/effects/postfx/webgl-program.d.ts +6 -0
- package/dist/types/effects/postfx/webgpu-program.d.ts +3 -0
- package/dist/types/effects/vfx/data-types.d.ts +100 -0
- package/dist/types/effects/vfx/index.d.ts +37 -0
- package/dist/types/effects/vfx/json-vfx-prefab.d.ts +94 -0
- package/dist/types/effects/vfx/layer-renderer.d.ts +118 -0
- package/dist/types/effects/vfx/layers/mesh.d.ts +124 -0
- package/dist/types/effects/vfx/layers/particle.d.ts +90 -0
- package/dist/types/effects/vfx/layers/shader.d.ts +130 -0
- package/dist/types/effects/vfx/layers/shared.d.ts +40 -0
- package/dist/types/effects/vfx/layers/sprite.d.ts +45 -0
- package/dist/types/effects/vfx/pool.d.ts +51 -0
- package/dist/types/effects/vfx/prefab.d.ts +48 -0
- package/dist/types/effects/vfx/prewarm.d.ts +17 -0
- package/dist/types/effects/vfx/stage.d.ts +115 -0
- package/dist/types/effects/vfx/webgpu-register.d.ts +2 -0
- package/dist/types/effects/webgpu-register.d.ts +2 -0
- package/dist/types/engine.d.ts +18 -0
- package/dist/types/environment.d.ts +96 -8
- package/dist/types/index.d.ts +35 -6
- package/dist/types/loader/animation/animation-glb.d.ts +4 -4
- package/dist/types/loader/character/load.d.ts +6 -1
- package/dist/types/loader/environment/lod-bundle.d.ts +123 -0
- package/dist/types/loader/environment/spz-decode.d.ts +88 -0
- package/dist/types/loader/environment/spz.d.ts +28 -0
- package/dist/types/loader/shared/asset-fetch.d.ts +11 -0
- package/dist/types/loader/shared/asset-loader.d.ts +86 -0
- package/dist/types/loader/shared/bin-cache.d.ts +41 -14
- package/dist/types/loader/shared/decode-worker.d.ts +27 -0
- package/dist/types/loader/shared/glb.d.ts +30 -0
- package/dist/types/loader/shared/inflate.d.ts +9 -0
- package/dist/types/loader/shared/pack-splats-task.d.ts +17 -0
- package/dist/types/loader/shared/sog-decode.d.ts +81 -0
- package/dist/types/loader/shared/sog.d.ts +17 -0
- package/dist/types/math.d.ts +198 -13
- package/dist/types/physics/ammo.d.ts +217 -0
- package/dist/types/physics/index.d.ts +11 -0
- package/dist/types/physics/joints.d.ts +206 -0
- package/dist/types/physics/physics-world.d.ts +194 -0
- package/dist/types/physics/rigid-body.d.ts +361 -0
- package/dist/types/presets/camera/camera-preset.d.ts +43 -0
- package/dist/types/presets/camera/third-person-camera.d.ts +63 -0
- package/dist/types/presets/character/body-shape.d.ts +109 -0
- package/dist/types/presets/character/character-reveal.d.ts +90 -0
- package/dist/types/presets/character/socket-loadout.d.ts +61 -0
- package/dist/types/presets/index.d.ts +13 -0
- package/dist/types/presets/vfx/mesh-flash.d.ts +51 -0
- package/dist/types/presets/visual/bone-overlay.d.ts +57 -0
- package/dist/types/proxy/environment-input.d.ts +30 -0
- package/dist/types/proxy/environment-source.d.ts +39 -0
- package/dist/types/proxy/proxy-debug.d.ts +106 -0
- package/dist/types/proxy/splat-source.d.ts +42 -0
- package/dist/types/proxy/voxelizer.d.ts +383 -0
- package/dist/types/relight/backend.d.ts +101 -0
- package/dist/types/relight/index.d.ts +6 -0
- package/dist/types/relight/relight-pass.d.ts +367 -0
- package/dist/types/relight/relight-placeholder.d.ts +2 -0
- package/dist/types/relight/relight-shaders.d.ts +4 -0
- package/dist/types/relight/shadow-bias.d.ts +26 -0
- package/dist/types/relight/splat-relight.d.ts +760 -0
- package/dist/types/relight/webgl-backend.d.ts +3 -0
- package/dist/types/relight/webgpu/backend.d.ts +3 -0
- package/dist/types/relight/webgpu-register.d.ts +2 -0
- package/dist/types/scene.d.ts +291 -0
- package/dist/types/skeletal/animation-player.d.ts +31 -3
- package/dist/types/skeletal/body-parts.d.ts +55 -0
- package/dist/types/skeletal/ragdoll-config.d.ts +115 -0
- package/dist/types/skeletal/ragdoll.d.ts +283 -0
- package/dist/types/skeletal/skeleton.d.ts +9 -2
- package/dist/types/splat/backend.d.ts +2 -0
- package/dist/types/splat/color-modifier.d.ts +78 -0
- package/dist/types/splat/cut-groups.d.ts +27 -0
- package/dist/types/splat/relight-binding.d.ts +39 -0
- package/dist/types/splat/reveal-bake.d.ts +43 -0
- package/dist/types/splat/reveal-look.d.ts +64 -0
- package/dist/types/splat/splat-mesh.d.ts +1 -0
- package/dist/types/splat/splat.d.ts +154 -0
- package/dist/types/splat/webgl/shaders.d.ts +5 -1
- package/dist/types/splat/webgl/splat-mesh.d.ts +4 -0
- package/dist/types/splat/webgpu/radix-sort.d.ts +3 -0
- package/dist/types/splat/webgpu/splat-mesh.d.ts +23 -0
- package/dist/types/three/splat-character.d.ts +28 -0
- package/dist/types/three/spz-loader.d.ts +35 -0
- package/dist/types/types.d.ts +6 -0
- package/dist/webgpu.js +1137 -154
- package/dist/webgpu.js.map +4 -4
- package/package.json +6 -2
- package/dist/chunks/chunk-WN5WBKM4.js +0 -8606
- package/dist/chunks/chunk-WN5WBKM4.js.map +0 -7
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.3.0
|
|
4
|
+
|
|
5
|
+
What games remade from the PlayCanvas build need beyond 0.2.0. Every addition is new API or an opt-in; nothing an existing app calls changes behaviour.
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- **`Scene.timeScale` and `Scene.maxDeltaTime`**, PlayCanvas's `app.timeScale` / `app.maxDeltaTime`: the loop clamps each step to `maxDeltaTime` (default 0.1 s, as before), then scales it by `timeScale` (default 1) for physics, characters and listeners. `0` pauses while drawing. A hand-called `tick(dt)` is unaffected.
|
|
10
|
+
- **`Scene.once(event, fn)`**; `off(event, fn)` cancels it.
|
|
11
|
+
- **`CreateSceneOptions.updateOrder`.** `'characters-first'`, the default, is 0.2.0's order: every character, then the `'update'` listeners. `'registration'` runs characters and listeners in the order they were added, as the PlayCanvas build does, so a listener added before a character sets a pose that is drawn the same frame.
|
|
12
|
+
- **`Vec3`, `Quat`, `Mat4`** exported: the math types `getBoneWorldMatrix`, `Pose` and the rig hand out, now with all of PlayCanvas 2.23's methods for each (degrees, `transformPoint`, `setFromAxisAngle`, `getEulerAngles`, statics like `Vec3.UP`), bit-identical to PlayCanvas's. The methods the rig already used are unchanged; `normalize`, `conjugate`, `mulScalar` and `invert` gain PlayCanvas's optional `src` argument.
|
|
13
|
+
- **`createPointToPointJoint`**: a point on one body held on a point of another, or at a point in the world, with `setPivotB` to move it and an optional `breakImpulse`. Tied to its bodies like the other joints (removed with them, re-made when one changes type). The PlayCanvas build has no such helper.
|
|
14
|
+
- **`setPlayCanvasLightColor`**, the conversion `SplatRelight` applies to its own lights, for lights a game sets itself.
|
|
15
|
+
- **`buildSourceBoneRemap`** and **`evictExpired`** (the old name of `indexAssetCache`), exported as in the PlayCanvas build.
|
|
16
|
+
- `ab/check-gaps.mjs`, with `ab/check-math.mjs`, checks all of the above on both backends and the math against PlayCanvas.
|
|
17
|
+
|
|
18
|
+
### Changed
|
|
19
|
+
|
|
20
|
+
- **Bundle size.** The math methods are class methods, which do not tree-shake: every app grows by 9 KB minified (2.7 KB gzipped). Loaders-only 227.7 → 236.7 KB, engine layer 246.7 → 255.7 KB, measured as for 0.2.0 against 0.2.0 as published.
|
|
21
|
+
- The loop steps 0 rather than a negative time if the clock it is given goes backwards.
|
|
22
|
+
|
|
23
|
+
## 0.2.0
|
|
24
|
+
|
|
25
|
+
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.
|
|
26
|
+
|
|
27
|
+
### Changed
|
|
28
|
+
|
|
29
|
+
- **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:
|
|
30
|
+
- 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.
|
|
31
|
+
- 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.
|
|
32
|
+
- **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.
|
|
33
|
+
- **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.
|
|
34
|
+
|
|
35
|
+
### Added
|
|
36
|
+
|
|
37
|
+
- **`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.
|
|
38
|
+
- **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`.
|
|
39
|
+
- **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`.
|
|
40
|
+
- **`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.
|
|
41
|
+
- **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`.
|
|
42
|
+
- **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.
|
|
43
|
+
- **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'`.
|
|
44
|
+
- **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).
|
|
45
|
+
- **Character**: `fetchParsed` / `buildFromLoadResults`, `disableAutoUpdate` / `enableAutoUpdate`, `addOverlaySplat` / `removeOverlaySplat`, `setLayers`.
|
|
46
|
+
- **Armature**: `poseModifier`, `rootOffsetProvider`, `driveNodes`, `tickLayers`, `prepareReveal`, `legacyRootRotation`.
|
|
47
|
+
- **Animation**: `Animation.load` options for clips converted from FBX (`referenceFrameMode`, `referenceBaseAnimation`, `rigidBones`), `prefetch`, crossfade `continueSource` / `easing`.
|
|
48
|
+
- **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.
|
|
49
|
+
- **Exports** `UPPER_BODY_BONE_NAMES`, `LOWER_BODY_BONE_NAMES`, `resolveBoneIndices`, `computeBoneStretch`, the body-part helpers.
|
|
50
|
+
- **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.
|
|
51
|
+
|
|
52
|
+
### Differs from the PlayCanvas build
|
|
53
|
+
|
|
54
|
+
- `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.
|
|
55
|
+
- 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.
|
|
56
|
+
- `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.
|
|
57
|
+
- `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.
|
|
58
|
+
- 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
|
|
|
@@ -177,11 +177,15 @@ That setting applies to the whole renderer: other materials in the scene are the
|
|
|
177
177
|
|
|
178
178
|
Ported, and checked against the PlayCanvas build by the A/B suite (see [Verification](#verification)):
|
|
179
179
|
|
|
180
|
-
- 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
|
|
181
181
|
- Animation - GLB clips, crossfade, layers with bone masks, root motion
|
|
182
|
-
- Rig - pose evaluation, bone-length scaling (`setBoneStretch
|
|
183
|
-
- Splat scenes -
|
|
184
|
-
- `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
|
|
185
189
|
- Render options - anti-aliasing, sub-pixel culling, per-group visibility (`setSplatGroups` / `setVariantMask`)
|
|
186
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.
|
|
187
191
|
|
|
@@ -192,13 +196,120 @@ Ported from the same source, but not exercised by the suite for want of test ass
|
|
|
192
196
|
- Multi-level character LOD (`Character.load([...])`, `addLodLevel`, `setRenderLod`) and variant splats (`addVariantSplat`)
|
|
193
197
|
- Animation LOD and sort LOD
|
|
194
198
|
|
|
195
|
-
Not ported:
|
|
199
|
+
Not ported, because no game built on the PlayCanvas build uses them, or three.js has its own:
|
|
196
200
|
|
|
197
|
-
-
|
|
198
|
-
-
|
|
199
|
-
-
|
|
200
|
-
-
|
|
201
|
-
-
|
|
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;
|
|
228
|
+
|
|
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`; see [Update order](#update-order)) |
|
|
244
|
+
| `scene.app.once('frameend', fn)` | `scene.once('postRender', fn)` |
|
|
245
|
+
| `scene.app.timeScale`, `scene.app.maxDeltaTime` | `scene.timeScale`, `scene.maxDeltaTime` |
|
|
246
|
+
| `pc.Vec3`, `pc.Quat`, `pc.Mat4` | `Vec3`, `Quat`, `Mat4` from this package (see [Math](#math)) |
|
|
247
|
+
| `armature.entity`, `splat.entity`, `environment.entity` | `.object3D` |
|
|
248
|
+
| `entity.addComponent('rigidbody' / 'collision', …)` | `scene.physics.addBody(object, { shape, type, mass, … })` |
|
|
249
|
+
| `entity.rigidbody`, `app.systems.rigidbody.raycastFirst` | `scene.physics.getBody(object)`, `scene.physics.raycastFirst` |
|
|
250
|
+
| `gsplat.setWorkBufferModifier({ glsl, wgsl })` with `WORK_BUFFER_MODIFIER_*` | `character.setColorModifier({ glsl, wgsl \| tsl, uniforms })` |
|
|
251
|
+
| `loadGlbFromUrl(app, url, cb)` → container asset | `loadGlbFromUrl(url)` → `GLTF` |
|
|
252
|
+
|
|
253
|
+
The `PhysicsWorld` class comment carries the full rigid-body mapping.
|
|
254
|
+
|
|
255
|
+
### Update order
|
|
256
|
+
|
|
257
|
+
By default a frame runs physics, then every character, then the `'update'` listeners, so a listener reads the pose drawn this frame. The PlayCanvas build makes each character an `app.on('update')` handler of its own instead, so characters and listeners run in the order they were added: a listener added before a character runs before it, and a pose it sets (a scrubbed clip, a gun placed on a hand) is drawn the same frame. A game ported from that build that relies on this passes `updateOrder: 'registration'` to `Scene.create`:
|
|
258
|
+
|
|
259
|
+
```typescript
|
|
260
|
+
const scene = await Scene.create(canvas, { updateOrder: 'registration' });
|
|
261
|
+
scene.on('update', drive); // before any character: runs first
|
|
262
|
+
const hero = await Character.load(scene, url);
|
|
263
|
+
scene.on('update', followHand); // after the hero: reads its pose for this frame
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
`timeScale` and `maxDeltaTime` work as PlayCanvas's: the loop clamps each frame's step to `maxDeltaTime` (default 0.1 s), then multiplies it by `timeScale` (default 1) for physics, the characters and every listener. `timeScale = 0` pauses the game while it keeps drawing. A `scene.tick(dt)` called by hand takes `dt` as given.
|
|
267
|
+
|
|
268
|
+
### Math
|
|
269
|
+
|
|
270
|
+
The rig works in PlayCanvas's own math types, ported with their formulas, so `getBoneWorldMatrix`, `Pose` and `armature.skeleton` hand out `Mat4`, `Vec3` and `Quat` rather than three.js types. The package exports them with all of PlayCanvas 2.23's methods for each (angles in degrees, `lerp(a, b, t)`, `transformPoint`, `setFromAxisAngle`, …), checked against PlayCanvas by `ab/check-math.mjs`, so game code that used `pc.Vec3` and friends keeps its maths by changing an import. `Mat4.data` has the layout of `THREE.Matrix4.elements`: `new Matrix4().fromArray(m.data)` crosses over.
|
|
271
|
+
|
|
272
|
+
### Colour hooks
|
|
273
|
+
|
|
274
|
+
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:
|
|
275
|
+
|
|
276
|
+
```typescript
|
|
277
|
+
const fade = { uFade: { value: 1 } };
|
|
278
|
+
character.setColorModifier({
|
|
279
|
+
uniforms: fade,
|
|
280
|
+
glsl: `void modifySplatColor(vec3 center, vec3 modelCenter, vec3 restCenter, uint splatIndex, inout vec4 color) {
|
|
281
|
+
color.a *= uFade;
|
|
282
|
+
}`,
|
|
283
|
+
wgsl: `fn modifySplatColor(center: vec3f, modelCenter: vec3f, restCenter: vec3f, splatIndex: u32,
|
|
284
|
+
color: vec4f, uFade: f32) -> vec4f {
|
|
285
|
+
return vec4f(color.rgb, color.a * uFade);
|
|
286
|
+
}`,
|
|
287
|
+
});
|
|
288
|
+
fade.uFade.value = 0.5; // next frame
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
`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.
|
|
292
|
+
|
|
293
|
+
### Lighting: legacy lights and `SplatRelight`
|
|
294
|
+
|
|
295
|
+
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.
|
|
296
|
+
|
|
297
|
+
A three.js light given a PlayCanvas light's `color` and `intensity` delivers a different colour: PlayCanvas linearizes the colour and, below intensity 1, the colour times the intensity. `setPlayCanvasLightColor(light, color, intensity)` gives a three.js light the PlayCanvas result; `SplatRelight` uses it for its own lights, and a game that sets the lights it passes to `relight.addLight` by hand, a flicker or a fade say, calls it on every change.
|
|
298
|
+
|
|
299
|
+
### GLB clips and the root bone
|
|
300
|
+
|
|
301
|
+
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:
|
|
302
|
+
|
|
303
|
+
| | root rotation | GLB presets face |
|
|
304
|
+
|---|---|---|
|
|
305
|
+
| `new SplatEngine()`, `SplatEngine.shared`, the loaders (0.1.1 apps) | pinned to bind, as in 0.1.1 | as they always did here |
|
|
306
|
+
| `Scene.create()` (games ported from the PlayCanvas build) | kept, as in PlayCanvas 0.3.2 | turned 180° from the above |
|
|
307
|
+
|
|
308
|
+
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.
|
|
309
|
+
|
|
310
|
+
- 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.
|
|
311
|
+
- Choose before clips play. Changed mid-clip under root-motion `'apply'`, a character jumps by twice its current pelvis offset.
|
|
312
|
+
- 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.
|
|
202
313
|
|
|
203
314
|
## The engine-level API
|
|
204
315
|
|
|
@@ -232,9 +343,19 @@ One difference to know when mixing the two: `Character.setPosition` lowers the m
|
|
|
232
343
|
|
|
233
344
|
## Differences from the PlayCanvas build
|
|
234
345
|
|
|
235
|
-
-
|
|
346
|
+
- **`Scene` is optional.** Applications with their own renderer and loop use `SplatEngine` and the loaders, and call `engine.update(dt)` themselves.
|
|
347
|
+
- **Colour hooks are functions, not shader splices.** See [Colour hooks](#colour-hooks).
|
|
348
|
+
- **`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).
|
|
349
|
+
- **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.
|
|
350
|
+
- **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.
|
|
351
|
+
- **`createPointToPointJoint`** joins a point on one body to a point on another, or holds it at a point in the world (`setPivotB` moves that point, to drag a body by it). The PlayCanvas build has no such helper; its games build `btPoint2PointConstraint` on Ammo themselves.
|
|
352
|
+
- **`'update'` listeners run after the characters** unless the scene is created with `updateOrder: 'registration'`; see [Update order](#update-order).
|
|
353
|
+
- **`OutlineEffect` shows through walls and `PixelartEffect`'s character mask does not,** as in the PlayCanvas build.
|
|
354
|
+
- **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.
|
|
236
355
|
- **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.
|
|
237
|
-
- **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.
|
|
356
|
+
- **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.
|
|
357
|
+
- **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'`.
|
|
358
|
+
- **`loadGlbFromUrl` imports three.js's `GLTFLoader` on first use,** from `three/addons/`. Nothing else in the package needs `three/addons`.
|
|
238
359
|
- **Under WebGPU, at most 16 point lights and 64 variant groups** are evaluated.
|
|
239
360
|
|
|
240
361
|
### Depth and draw order
|
|
@@ -419,18 +540,18 @@ Scenarios: `fill-2`, `crowd-16`, `crowd-32`, `room`, `room-4`.
|
|
|
419
540
|
|
|
420
541
|
`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:
|
|
421
542
|
|
|
422
|
-
- **Bone matrices**, numerically.
|
|
543
|
+
- **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.
|
|
423
544
|
- **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.
|
|
424
545
|
|
|
425
546
|
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`.
|
|
426
547
|
|
|
427
548
|
<!-- AB_TABLE -->
|
|
428
|
-
| Compared with the PlayCanvas build (WebGL) | Cases | Bone matrices, max difference | PSNR, median | PSNR, worst | Pixels off by more than 8/255, worst case |
|
|
549
|
+
| 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 |
|
|
429
550
|
|---|--:|--:|--:|--:|--:|
|
|
430
|
-
| WebGL backend, characters |
|
|
431
|
-
| WebGL backend, environment | 10 | 0 |
|
|
432
|
-
| WebGPU backend, characters |
|
|
433
|
-
| WebGPU backend, environment | 10 | 0 |
|
|
551
|
+
| WebGL backend, characters | 68 | 1.9 mm | 58.7 dB | 40.0 dB | 1.238% |
|
|
552
|
+
| WebGL backend, environment | 10 | < 0.01 mm | 55.8 dB | 49.2 dB | 0.227% |
|
|
553
|
+
| WebGPU backend, characters | 68 | 1.9 mm | 58.8 dB | 39.9 dB | 1.241% |
|
|
554
|
+
| WebGPU backend, environment | 10 | < 0.01 mm | 56.1 dB | 49.1 dB | 0.234% |
|
|
434
555
|
<!-- /AB_TABLE -->
|
|
435
556
|
|
|
436
557
|
```bash
|
|
@@ -442,8 +563,25 @@ node ab/check-api.mjs # the three.js-style API's own contract
|
|
|
442
563
|
node ab/check-stability.mjs # still frames must be bit-stable
|
|
443
564
|
node ab/check-prune.mjs # the load-time prune keeps every column in lockstep
|
|
444
565
|
node ab/check-animation.mjs # a playing clip must actually reach the screen
|
|
566
|
+
|
|
567
|
+
npm install --prefix ab/ref-pc # the current PlayCanvas build, once
|
|
568
|
+
npm run ab -- --ref current # against it: poses, and the newer splat effects
|
|
569
|
+
node ab/check-scene.mjs # the Scene facade
|
|
570
|
+
node ab/check-fixes.mjs # one check per fix from the 0.2.0 review
|
|
571
|
+
node ab/check-gaps.mjs # time scale, update order, point-to-point joints, exported math vs PlayCanvas
|
|
572
|
+
node ab/run-relight.mjs # SplatRelight vs PlayCanvas
|
|
573
|
+
node ab/run-postfx-check.mjs # CameraFrame, PostFX, pixel-art, outline vs PlayCanvas
|
|
574
|
+
node ab/check-physics.mjs # rigid bodies, events, raycasts, ragdoll (Ammo from test-assets/ammo/)
|
|
575
|
+
node ab/check-env.mjs # .spz / SOG / LOD bundles vs PlayCanvas
|
|
576
|
+
node ab/run-vfx.mjs # VFX and presets vs PlayCanvas
|
|
445
577
|
```
|
|
446
578
|
|
|
579
|
+
`--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).
|
|
580
|
+
|
|
581
|
+
`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`. `node ab/check-gaps.mjs` checks what was added for games remade from the PlayCanvas build: `timeScale` / `maxDeltaTime` / `once`, both update orders, point-to-point joints (pinned, chained, rebuilt, broken), the exported helpers, and every `Vec3` / `Quat` / `Mat4` method bit for bit against PlayCanvas 2.23.3.
|
|
582
|
+
|
|
583
|
+
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.
|
|
584
|
+
|
|
447
585
|
The suite needs a GPU-backed headless Chromium (`npx playwright install chromium`).
|
|
448
586
|
|
|
449
587
|
## Licence
|