@viggle/splat-engine-three 0.2.0 → 0.4.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 +29 -0
- package/README.md +42 -3
- package/dist/chunks/{chunk-BHNNSHJG.js → chunk-SASRTGRD.js} +1095 -71
- package/dist/chunks/chunk-SASRTGRD.js.map +7 -0
- package/dist/index.js +15 -1
- package/dist/types/character.d.ts +3 -1
- package/dist/types/index.d.ts +5 -3
- package/dist/types/math.d.ts +191 -13
- package/dist/types/physics/ammo.d.ts +7 -0
- package/dist/types/physics/index.d.ts +2 -2
- package/dist/types/physics/joints.d.ts +49 -0
- package/dist/types/physics/physics-world.d.ts +2 -1
- package/dist/types/relight/splat-relight.d.ts +19 -0
- package/dist/types/scene.d.ts +57 -7
- 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/webgpu.js +76 -28
- package/dist/webgpu.js.map +3 -3
- package/package.json +1 -1
- package/dist/chunks/chunk-BHNNSHJG.js.map +0 -7
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,34 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.4.0
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- **`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".
|
|
10
|
+
- `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.
|
|
11
|
+
|
|
12
|
+
## 0.3.0
|
|
13
|
+
|
|
14
|
+
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.
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
|
|
18
|
+
- **`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.
|
|
19
|
+
- **`Scene.once(event, fn)`**; `off(event, fn)` cancels it.
|
|
20
|
+
- **`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.
|
|
21
|
+
- **`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.
|
|
22
|
+
- **`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.
|
|
23
|
+
- **`setPlayCanvasLightColor`**, the conversion `SplatRelight` applies to its own lights, for lights a game sets itself.
|
|
24
|
+
- **`buildSourceBoneRemap`** and **`evictExpired`** (the old name of `indexAssetCache`), exported as in the PlayCanvas build.
|
|
25
|
+
- `ab/check-gaps.mjs`, with `ab/check-math.mjs`, checks all of the above on both backends and the math against PlayCanvas.
|
|
26
|
+
|
|
27
|
+
### Changed
|
|
28
|
+
|
|
29
|
+
- **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.
|
|
30
|
+
- The loop steps 0 rather than a negative time if the clock it is given goes backwards.
|
|
31
|
+
|
|
3
32
|
## 0.2.0
|
|
4
33
|
|
|
5
34
|
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.
|
package/README.md
CHANGED
|
@@ -240,7 +240,10 @@ scene.start();
|
|
|
240
240
|
| `scene.app`, `scene.graphicsDevice` | `scene.renderer`, `scene.threeScene` |
|
|
241
241
|
| `scene.cameraEntity` | `scene.camera` (a `PerspectiveCamera`) |
|
|
242
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
|
|
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)) |
|
|
244
247
|
| `armature.entity`, `splat.entity`, `environment.entity` | `.object3D` |
|
|
245
248
|
| `entity.addComponent('rigidbody' / 'collision', …)` | `scene.physics.addBody(object, { shape, type, mass, … })` |
|
|
246
249
|
| `entity.rigidbody`, `app.systems.rigidbody.raycastFirst` | `scene.physics.getBody(object)`, `scene.physics.raycastFirst` |
|
|
@@ -249,6 +252,23 @@ scene.start();
|
|
|
249
252
|
|
|
250
253
|
The `PhysicsWorld` class comment carries the full rigid-body mapping.
|
|
251
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
|
+
|
|
252
272
|
### Colour hooks
|
|
253
273
|
|
|
254
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:
|
|
@@ -274,6 +294,8 @@ fade.uFade.value = 0.5; // next frame
|
|
|
274
294
|
|
|
275
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.
|
|
276
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
|
+
|
|
277
299
|
### GLB clips and the root bone
|
|
278
300
|
|
|
279
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:
|
|
@@ -326,6 +348,8 @@ One difference to know when mixing the two: `Character.setPosition` lowers the m
|
|
|
326
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).
|
|
327
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.
|
|
328
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).
|
|
329
353
|
- **`OutlineEffect` shows through walls and `PixelartEffect`'s character mask does not,** as in the PlayCanvas build.
|
|
330
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.
|
|
331
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.
|
|
@@ -336,7 +360,17 @@ One difference to know when mixing the two: `Character.setPosition` lowers the m
|
|
|
336
360
|
|
|
337
361
|
### Depth and draw order
|
|
338
362
|
|
|
339
|
-
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.
|
|
363
|
+
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.
|
|
364
|
+
|
|
365
|
+
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:
|
|
366
|
+
|
|
367
|
+
```ts
|
|
368
|
+
SplatQuality.depthWriteAlpha = 0.15; // or per object: environment.splat.depthWriteAlpha = 0.15
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
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.
|
|
372
|
+
|
|
373
|
+
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.
|
|
340
374
|
|
|
341
375
|
## Performance
|
|
342
376
|
|
|
@@ -416,6 +450,8 @@ SplatQuality.pruneVoxelSize = 0.04; // metres; the cell that quota is per
|
|
|
416
450
|
SplatQuality.screenSizeCull = 0; // pixels; drop splats smaller than this. For distant crowds
|
|
417
451
|
SplatQuality.depthOcclusion = true; // scene geometry hides splats. Correctness, not performance:
|
|
418
452
|
// this renderer gets the hardware depth test for free
|
|
453
|
+
SplatQuality.depthWriteAlpha = 0; // splat objects hide one another where they overlap; see
|
|
454
|
+
// Depth and draw order. Costs a second draw per object
|
|
419
455
|
SplatQuality.passTimings = false; // then read SplatQuality.timings after each render
|
|
420
456
|
```
|
|
421
457
|
|
|
@@ -544,6 +580,8 @@ npm install --prefix ab/ref-pc # the current PlayCanvas build, once
|
|
|
544
580
|
npm run ab -- --ref current # against it: poses, and the newer splat effects
|
|
545
581
|
node ab/check-scene.mjs # the Scene facade
|
|
546
582
|
node ab/check-fixes.mjs # one check per fix from the 0.2.0 review
|
|
583
|
+
node ab/check-gaps.mjs # time scale, update order, point-to-point joints, exported math vs PlayCanvas
|
|
584
|
+
node ab/check-depth-write.mjs # depthWriteAlpha: what hides what, overrides, overlays, teardown
|
|
547
585
|
node ab/run-relight.mjs # SplatRelight vs PlayCanvas
|
|
548
586
|
node ab/run-postfx-check.mjs # CameraFrame, PostFX, pixel-art, outline vs PlayCanvas
|
|
549
587
|
node ab/check-physics.mjs # rigid bodies, events, raycasts, ragdoll (Ammo from test-assets/ammo/)
|
|
@@ -553,7 +591,8 @@ node ab/run-vfx.mjs # VFX and presets vs PlayCanvas
|
|
|
553
591
|
|
|
554
592
|
`--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
593
|
|
|
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`.
|
|
594
|
+
`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.
|
|
595
|
+
`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.
|
|
557
596
|
|
|
558
597
|
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.
|
|
559
598
|
|