@viggle/splat-engine-three 0.3.0 → 0.5.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 +18 -0
- package/README.md +22 -4
- package/dist/chunks/{chunk-2GKWT24B.js → chunk-NNGE5LDC.js} +486 -45
- package/dist/chunks/chunk-NNGE5LDC.js.map +7 -0
- package/dist/index.js +3 -1
- package/dist/types/character.d.ts +3 -1
- package/dist/types/environment.d.ts +3 -2
- package/dist/types/index.d.ts +1 -0
- package/dist/types/loader/environment/compressed-ply.d.ts +40 -0
- package/dist/types/loader/environment/ply.d.ts +3 -0
- package/dist/types/loader/shared/asset-loader.d.ts +3 -2
- package/dist/types/loader/shared/sog.d.ts +5 -0
- package/dist/types/splat/backend.d.ts +10 -1
- package/dist/types/splat/quality.d.ts +45 -0
- package/dist/types/splat/splat-mesh.d.ts +14 -1
- package/dist/types/splat/splat.d.ts +6 -0
- package/dist/types/splat/webgl/shaders.d.ts +1 -1
- package/dist/types/splat/webgl/splat-mesh.d.ts +1 -0
- package/dist/types/splat/webgpu/splat-mesh.d.ts +1 -0
- package/dist/types/three/loaders.d.ts +4 -2
- package/dist/types/three/sog-loader.d.ts +50 -0
- package/dist/webgpu.js +64 -28
- package/dist/webgpu.js.map +3 -3
- package/package.json +1 -1
- package/dist/chunks/chunk-2GKWT24B.js.map +0 -7
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.5.0
|
|
4
|
+
|
|
5
|
+
Splat-scene loading level with `@viggle/splat-engine` 0.3.2. Additions only; nothing an existing app calls changes behaviour.
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- **`.compressed.ply`** - PlayCanvas's quantised PLY, as SuperSplat and splat-transform write it - reads everywhere a `.ply` does: `SplatPLYLoader`, `Environment.load`, `loadSplatAsset`, `loadSplatSource`, `decodeSplatFile` and `parseGaussianPly`. The layout is told by the header, so a renamed file reads too. Decoded with the arithmetic of PlayCanvas's `GSplatCompressedData.decompress`, and bit-identical to it on 12- and 18-float chunk layouts, with and without an `sh` element (which is skipped, as `f_rest_*` is for the float PLY).
|
|
10
|
+
- **`SplatSOGLoader`**, a `THREE.Loader` for SOG scenes: a `.sog` bundle, or an unbundled `meta.json` whose images it fetches from beside it. Every file goes through a `FileLoader`, so the `LoadingManager`, `setPath`, request headers and credentials mode apply to the images too. Same splats as `loadSplatSource`.
|
|
11
|
+
|
|
12
|
+
## 0.4.0
|
|
13
|
+
|
|
14
|
+
Splat objects can hide one another where they overlap. The setting is off by default; with it off, every frame draws exactly as in 0.3.0.
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
|
|
18
|
+
- **`SplatQuality.depthWriteAlpha`** and the per-object **`Splat.depthWriteAlpha`**, so splat objects hide one another where they overlap: a held weapon and the hand holding it, two fighters, a character behind a prop. Each splat object follows its colour draw with a depth-only draw of its solid parts, and the objects drawn after it depth-test against that. Off (`0`) by default. At `0.15`, a staff held in a hand scores 42-48 dB against the PlayCanvas build, up from 31-33 dB. An object that overlaps nothing draws exactly as before. An environment drawn first hides a character behind it too, which the PlayCanvas build's environment layer does not (`environment.splat.depthWriteAlpha = 0` keeps that). Costs a second draw per splat object, and `Character.addOverlaySplat` copies opt out. See the README's "Depth and draw order".
|
|
19
|
+
- `ab/check-depth-write.mjs`, and `overlap/` cases in the A/B suite (a procedural staff through the actor's hand, `ab/staff-ply.mjs`); `run-ab.mjs --depth-write <alpha>` runs the whole suite with it on.
|
|
20
|
+
|
|
3
21
|
## 0.3.0
|
|
4
22
|
|
|
5
23
|
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.
|
package/README.md
CHANGED
|
@@ -56,13 +56,17 @@ Get character `.vsplat` files and animation `.glb` files from https://viggle.ai/
|
|
|
56
56
|
|
|
57
57
|
### Loaders
|
|
58
58
|
|
|
59
|
-
All
|
|
59
|
+
All of them extend `THREE.Loader`, so `load` / `loadAsync`, `setPath`, `setRequestHeader`, `setWithCredentials` and a `LoadingManager` work as usual. Each also has `parseAsync(arrayBuffer)` for bytes you already hold.
|
|
60
60
|
|
|
61
61
|
| Loader | Reads | Gives you |
|
|
62
62
|
|---|---|---|
|
|
63
63
|
| `VSplatLoader` | `.vsplat` character bundles | `SplatCharacter` |
|
|
64
64
|
| `SplatClipLoader` | MetaHuman-rig `.glb` animations | `SplatClip` |
|
|
65
|
-
| `SplatPLYLoader` |
|
|
65
|
+
| `SplatPLYLoader` | 3D Gaussian Splatting `.ply`, uncompressed or PlayCanvas's `.compressed.ply` | `SplatMesh` |
|
|
66
|
+
| `SplatSPZLoader` | `.spz` (versions 1-4) | `SplatMesh` |
|
|
67
|
+
| `SplatSOGLoader` | SOG: a `.sog` bundle, or an unbundled `meta.json` (its images are fetched from beside it) | `SplatMesh` |
|
|
68
|
+
|
|
69
|
+
Streamed LOD bundles (`lod-meta.json`) pick their detail level from the engine's camera every frame, so they load through [`Environment.loadLodBundle`](#the-game-engine-layer) rather than a loader.
|
|
66
70
|
|
|
67
71
|
### `SplatCharacter`
|
|
68
72
|
|
|
@@ -180,7 +184,7 @@ Ported, and checked against the PlayCanvas build by the A/B suite (see [Verifica
|
|
|
180
184
|
- Characters - loading `.vsplat` bundles, position / rotation / scale, tint (mix and multiply), colour grade, opacity, the feet-to-head reveal, cut pieces, colour hooks
|
|
181
185
|
- Animation - GLB clips, crossfade, layers with bone masks, root motion
|
|
182
186
|
- Rig - pose evaluation, bone-length scaling (`setBoneStretch`, stretching and shrinking)
|
|
183
|
-
- Splat scenes - `.ply
|
|
187
|
+
- Splat scenes - `.ply` (uncompressed and `.compressed.ply`), `.spz` (versions 1-4), SOG, and streamed LOD bundles (`Environment.loadLodBundle`)
|
|
184
188
|
- `SunLight`, `SkyLight`, `PointLight` (against the version this port started from; the current PlayCanvas build has removed them)
|
|
185
189
|
- `SplatRelight` - characters and environments lit through voxel proxies, with sun shadows and point lights
|
|
186
190
|
- `Scene`, `CameraFrame` (tone mapping, bloom, grading, vignette), `PostFX` and `BaseCapturingPass`, `PixelartEffect`, `OutlineEffect`
|
|
@@ -360,7 +364,17 @@ One difference to know when mixing the two: `Character.setPosition` lowers the m
|
|
|
360
364
|
|
|
361
365
|
### Depth and draw order
|
|
362
366
|
|
|
363
|
-
Splats test against the depth buffer and do not write it. Opaque meshes therefore occlude them correctly with no extra setup, but two splat objects are layered by draw order alone, not by depth. Static meshes from `SplatPLYLoader` draw first (`renderOrder = -1`), so characters always composite on top of the scene they stand in - the same layering the PlayCanvas build uses. A character that walks behind a wall of the splat scene is still drawn over it.
|
|
367
|
+
Splats test against the depth buffer and, by default, do not write it. Opaque meshes therefore occlude them correctly with no extra setup, but two splat objects are layered by draw order alone, not by depth: each is sorted and drawn on its own, and whichever draws second paints over the other across the whole overlap. Static meshes from `SplatPLYLoader` and `Environment` draw first (`renderOrder = -1`), so characters always composite on top of the scene they stand in - the same layering the PlayCanvas build uses for its environment layer. A character that walks behind a wall of the splat scene is still drawn over it.
|
|
368
|
+
|
|
369
|
+
The PlayCanvas build sorts all the splats on one layer together, so a held weapon on the characters' layer, or two characters, interleave splat by splat there. Here `SplatQuality.depthWriteAlpha` stands in for that:
|
|
370
|
+
|
|
371
|
+
```ts
|
|
372
|
+
SplatQuality.depthWriteAlpha = 0.15; // or per object: environment.splat.depthWriteAlpha = 0.15
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
Each splat object then follows its colour draw with a depth-only draw of its solid parts (single-splat fragments at or above that alpha), and objects drawn after it depth-test against them: a weapon is hidden where it passes behind the fingers and still drawn where it passes in front. An object never tests against its own depth, so one that overlaps nothing draws exactly as before. Where the earlier object is faint the later one still paints over it, and where it is just above the alpha it hides the later one outright, so the edge of an overlap is harder than in the PlayCanvas build. Against that build, a staff held in a hand scores 31-33 dB plain and 42-48 dB with `0.15` (the A/B suite's `overlap/` cases). The alpha is taken after `setOpacity`, so a character fading out keeps hiding what is behind it until its opacity drops below the setting; opt its splats out for the fade. The vertex work, which under WebGL includes the skinning, is paid twice. `Character.addOverlaySplat` copies never write depth.
|
|
376
|
+
|
|
377
|
+
An environment draws first, so with depth writes on it also hides a character where the scene is in front of it - the prop the character stands behind, a wall it walks past. The PlayCanvas build's environment layer never does; set `environment.splat.depthWriteAlpha = 0` on a stage to keep that. A streamed LOD bundle is one splat at every level and keeps its own setting across level switches; it draws the same with depth writes on (`check-env`'s LOD cases, frame for frame). With the setting off (the default) every frame is the same as before it existed, and with it on every A/B case with one splat object is too; only the cases with a character inside the stage change.
|
|
364
378
|
|
|
365
379
|
## Performance
|
|
366
380
|
|
|
@@ -440,6 +454,8 @@ SplatQuality.pruneVoxelSize = 0.04; // metres; the cell that quota is per
|
|
|
440
454
|
SplatQuality.screenSizeCull = 0; // pixels; drop splats smaller than this. For distant crowds
|
|
441
455
|
SplatQuality.depthOcclusion = true; // scene geometry hides splats. Correctness, not performance:
|
|
442
456
|
// this renderer gets the hardware depth test for free
|
|
457
|
+
SplatQuality.depthWriteAlpha = 0; // splat objects hide one another where they overlap; see
|
|
458
|
+
// Depth and draw order. Costs a second draw per object
|
|
443
459
|
SplatQuality.passTimings = false; // then read SplatQuality.timings after each render
|
|
444
460
|
```
|
|
445
461
|
|
|
@@ -569,6 +585,7 @@ npm run ab -- --ref current # against it: poses, and the newer splat effect
|
|
|
569
585
|
node ab/check-scene.mjs # the Scene facade
|
|
570
586
|
node ab/check-fixes.mjs # one check per fix from the 0.2.0 review
|
|
571
587
|
node ab/check-gaps.mjs # time scale, update order, point-to-point joints, exported math vs PlayCanvas
|
|
588
|
+
node ab/check-depth-write.mjs # depthWriteAlpha: what hides what, overrides, overlays, teardown
|
|
572
589
|
node ab/run-relight.mjs # SplatRelight vs PlayCanvas
|
|
573
590
|
node ab/run-postfx-check.mjs # CameraFrame, PostFX, pixel-art, outline vs PlayCanvas
|
|
574
591
|
node ab/check-physics.mjs # rigid bodies, events, raycasts, ragdoll (Ammo from test-assets/ammo/)
|
|
@@ -579,6 +596,7 @@ node ab/run-vfx.mjs # VFX and presets vs PlayCanvas
|
|
|
579
596
|
`--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
597
|
|
|
581
598
|
`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.
|
|
599
|
+
`node ab/check-depth-write.mjs` checks `depthWriteAlpha` on both backends: which of two crossing splats hides the other with it off, on, overridden per object and with the draw order swapped, one preparation per frame, `clone`, overlay copies, teardown while on, and switching it off. The suite's `overlap/` cases hold a staff in the actor's hand from four sides: 31-33 dB against the PlayCanvas build plain, 42-48 dB at `0.15`, on either backend.
|
|
582
600
|
|
|
583
601
|
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
602
|
|