@driftengine/core 4.10.0 → 4.11.1

package/dist/render/vertexPacking.d.ts

@@ -0,0 +1,48 @@
+import type { MeshData } from '@driftengine/drft';
+/**
+ * How each of a mesh's vertex attributes travels to the device, decided once from its data and
+ * bound by each backend: as floats, as sixteen-bit fixed point, or as one value every vertex
+ * shares.
+ *
+ * **Only what reads back as it went, or near enough that no picture can tell.** One value every
+ * vertex shares is exact, and is a constant rather than a stream: a colour or an emissive naming
+ * no difference between vertices costs nothing a vertex, where both were always stored per vertex.
+ * A unit direction — a normal, a tangent and its handedness — in sixteen-bit signed fixed point is
+ * within 1/32767 a component, a few thousandths of a degree: measured against floats, 12 pixels of
+ * 921,600 moved in one published scene, by 2 of 255 on average, and none in the other eight.
+ * Colours and skin weights inside [0, 1] in sixteen-bit unsigned fixed point are within 1/65535. A
+ * textured vertex with a tangent frame, white and not glowing, goes from 64 bytes to 36 on WebGPU.
+ *
+ * **What it gives up.** Eight-bit normals would save four bytes more and are not taken: a normal in
+ * steps of 1/127 can band a highlight. **Texture coordinates stay floats**, in any range: a
+ * coordinate on a tile's far edge rounds past it in sixteen-bit fixed point, by 1/131,070, and a
+ * pixel there samples the neighbouring tile of an atlas — measured as 29 pixels moved by 62 of 255
+ * in the voxel scene, every one at a face's edge — and a half float, which steps by a 2048th near
+ * 1.0, is worse. A dynamic mesh's normals stay floats, because each rewrite would have to be packed
+ * on the CPU. What would make this wrong is a value outside its range, which the range check sends
+ * to floats rather than clamping, or a shader reading an attribute as something other than the
+ * value it carries.
+ */
+/** Floats; sixteen-bit fixed point, signed or not; or one value for every vertex. */
+export type AttributePacking = 'float' | 'snorm16' | 'unorm16' | 'constant';
+/** The attributes this decides for. Every other one travels as floats. */
+export declare const PACKED_ATTRIBUTES: readonly ['normals', 'tangents', 'colors', 'emissive', 'weights', 'weights2'];
+export type PackedAttribute = (typeof PACKED_ATTRIBUTES)[number];
+export type VertexPacking = Readonly<Record<PackedAttribute, AttributePacking>>;
+/** The choice for this mesh. `dynamic` is a mesh whose positions and normals are rewritten. */
+export declare function vertexPackingOf(data: MeshData, dynamic: boolean): VertexPacking;
+/**
+ * What 1 is in each fixed point, the values WebGPU's `snorm16` and `unorm16` and WebGL2's
+ * normalised `SHORT` and `UNSIGNED_SHORT` divide by. A value is stored rounded to nearest, so 1, 0
+ * and -1 come back exactly.
+ */
+export declare const SNORM16_ONE = 32767;
+export declare const UNORM16_ONE = 65535;
+/** One value in the fixed point whose 1 is `one`, rounded to nearest: the only place it is. */
+export declare function toFixed16(value: number, one: number): number;
+/** An attribute's values in its fixed point, tightly, for a backend reading separate arrays. */
+export declare function fixedArray(values: Float32Array, packing: 'snorm16' | 'unorm16'): Int16Array | Uint16Array;
+/** How `name` travels under this packing: floats for an attribute it does not decide for. */
+export declare function packingFor(packing: VertexPacking, name: string): AttributePacking;
+/** The value every vertex shares, for an attribute packed as `'constant'`. */
+export declare function sharedValue(values: Float32Array, width: number): number[];

package/dist/render/vertexPacking.js

@@ -0,0 +1,68 @@
+/** The attributes this decides for. Every other one travels as floats. */
+export const PACKED_ATTRIBUTES = [
+    'normals',
+    'tangents',
+    'colors',
+    'emissive',
+    'weights',
+    'weights2',
+];
+/** The choice for this mesh. `dynamic` is a mesh whose positions and normals are rewritten. */
+export function vertexPackingOf(data, dynamic) {
+    return {
+        normals: dynamic ? 'float' : fixedOrFloat(data.normals, -1),
+        tangents: fixedOrFloat(data.tangents, -1),
+        colors: shared(data.colors, 3) ? 'constant' : fixedOrFloat(data.colors, 0),
+        emissive: shared(data.emissive, 1) ? 'constant' : 'float',
+        weights: fixedOrFloat(data.weights, 0),
+        weights2: fixedOrFloat(data.weights2, 0),
+    };
+}
+/**
+ * What 1 is in each fixed point, the values WebGPU's `snorm16` and `unorm16` and WebGL2's
+ * normalised `SHORT` and `UNSIGNED_SHORT` divide by. A value is stored rounded to nearest, so 1, 0
+ * and -1 come back exactly.
+ */
+export const SNORM16_ONE = 32767;
+export const UNORM16_ONE = 65535;
+/** One value in the fixed point whose 1 is `one`, rounded to nearest: the only place it is. */
+export function toFixed16(value, one) {
+    return Math.round(value * one);
+}
+/** An attribute's values in its fixed point, tightly, for a backend reading separate arrays. */
+export function fixedArray(values, packing) {
+    const out = packing === 'snorm16' ? new Int16Array(values.length) : new Uint16Array(values.length);
+    const one = packing === 'snorm16' ? SNORM16_ONE : UNORM16_ONE;
+    for (let at = 0; at < values.length; at++)
+        out[at] = toFixed16(values[at], one);
+    return out;
+}
+/** How `name` travels under this packing: floats for an attribute it does not decide for. */
+export function packingFor(packing, name) {
+    return packing[name] ?? 'float';
+}
+/** The value every vertex shares, for an attribute packed as `'constant'`. */
+export function sharedValue(values, width) {
+    return Array.from(values.subarray(0, width));
+}
+/** Fixed point where every value lies in [low, 1]; floats otherwise, and for a NaN. */
+function fixedOrFloat(values, low) {
+    if (values === undefined)
+        return 'float';
+    for (let at = 0; at < values.length; at++) {
+        const value = values[at];
+        if (!(value >= low && value <= 1))
+            return 'float';
+    }
+    return low < 0 ? 'snorm16' : 'unorm16';
+}
+/** Whether every vertex holds the first vertex's value. Not for a mesh of none. */
+function shared(values, width) {
+    if (values.length < width)
+        return false;
+    for (let at = width; at < values.length; at++) {
+        if (values[at] !== values[at % width])
+            return false;
+    }
+    return true;
+}

package/dist/ui/splash.d.ts

@@ -49,8 +49,9 @@ export declare const SPLASH_FADE_MS = 420;
 /**
  * When the badge gives the screen to the game. Two conditions and a cap, each for a named failure.
  *
- *   - **The game has painted.** Swapping before that shows the empty canvas the badge exists to
- *     cover.
+ *   - **The game has painted**, and every promise it asked the badge to wait for has settled
+ *     (`holdSplash`). Swapping before that shows the empty canvas, or the half-loaded first screen,
+ *     the badge exists to cover.
  *   - **The minimum has passed.** A badge that vanishes the instant a fast machine paints is a
  *     flicker, and the machines that boot fastest are the ones a developer tests on.
  *   - **The cap overrides both**, and is checked first so that a minimum longer than the cap
@@ -75,7 +76,46 @@ export interface MountedSplash {
     present(): void;
     /** Take it down now, whatever the clock says. Idempotent. */
     release(): void;
+    /** Keep it up until `until` settles as well, under `capMs`. False once it has left. */
+    holdUntil(until: PromiseLike<unknown>, capMs?: number): boolean;
 }
+/**
+ * What a badge waits for besides the clock: the game's first frame, and every promise the game asked
+ * it to wait for (`holdSplash`), under the cap the game named, the longest of several, or the engine's.
+ *
+ * **A hold settles whichever way its promise does.** A load that failed must not pin the logo: the
+ * game is shown, broken and visible, which is the cap's own argument. Pure apart from the promises,
+ * so the rule is testable in Node.
+ */
+export declare class SplashState {
+    /** Whether a frame of the game has reached the screen. */
+    painted: boolean;
+    private pending;
+    /** The longest cap a hold has named, or 0 for none. */
+    private asked;
+    /** The longest the badge may stay: the cap a hold named, the longest of several, or the engine's. */
+    get capMs(): number;
+    /** Wait for `until` too, under `capMs` where it names one; `settled` once it has. */
+    hold(until: PromiseLike<unknown>, capMs: number | undefined, settled: () => void): void;
+    /** Painted, with every hold settled: what `splashDecision` calls the content being ready. */
+    get ready(): boolean;
+}
+/**
+ * Keep the engine's badge up until `until` settles, as well as until the game's first frame: a game
+ * whose first screen loads for longer than that frame — a stage, figures and their pictures on a
+ * first visit — is seen whole rather than loading. **`capMs` is the game's own ceiling** on the
+ * badge in place of the engine's twenty seconds, longer for a slow first visit or shorter, so a load
+ * that never settles is still shown in the end; the longest of several holds' wins, and the minimum
+ * hold is unchanged.
+ *
+ * **Frames run while the game loads behind the plate**, since a load may need them, and are held
+ * once it has settled, for whatever is left of the minimum, as they are after a first frame with no
+ * hold. Returns whether there was a badge to hold: none in a packaged build, whose shell shows its
+ * own until the first frame, nor where `splash: false` or `?splash=0` turned it off.
+ */
+export declare function holdSplash(until: PromiseLike<unknown>, options?: {
+    capMs?: number;
+}): boolean;
 /**
  * Put the badge up, and hand back the two verbs that take it down.
  *

package/dist/ui/splash.js

@@ -80,8 +80,9 @@ export const SPLASH_FADE_MS = 420;
 /**
  * When the badge gives the screen to the game. Two conditions and a cap, each for a named failure.
  *
- *   - **The game has painted.** Swapping before that shows the empty canvas the badge exists to
- *     cover.
+ *   - **The game has painted**, and every promise it asked the badge to wait for has settled
+ *     (`holdSplash`). Swapping before that shows the empty canvas, or the half-loaded first screen,
+ *     the badge exists to cover.
  *   - **The minimum has passed.** A badge that vanishes the instant a fast machine paints is a
  *     flicker, and the machines that boot fastest are the ones a developer tests on.
  *   - **The cap overrides both**, and is checked first so that a minimum longer than the cap
@@ -99,6 +100,58 @@ export function splashDecision(elapsedMs, minMs, contentReady, capMs = SPLASH_HA
         return 'hold';
     return elapsedMs >= minMs ? 'swap' : 'hold';
 }
+/**
+ * What a badge waits for besides the clock: the game's first frame, and every promise the game asked
+ * it to wait for (`holdSplash`), under the cap the game named, the longest of several, or the engine's.
+ *
+ * **A hold settles whichever way its promise does.** A load that failed must not pin the logo: the
+ * game is shown, broken and visible, which is the cap's own argument. Pure apart from the promises,
+ * so the rule is testable in Node.
+ */
+export class SplashState {
+    /** Whether a frame of the game has reached the screen. */
+    painted = false;
+    pending = 0;
+    /** The longest cap a hold has named, or 0 for none. */
+    asked = 0;
+    /** The longest the badge may stay: the cap a hold named, the longest of several, or the engine's. */
+    get capMs() {
+        return this.asked > 0 ? this.asked : SPLASH_HARD_CAP_MS;
+    }
+    /** Wait for `until` too, under `capMs` where it names one; `settled` once it has. */
+    hold(until, capMs, settled) {
+        this.pending += 1;
+        if (capMs !== undefined && Number.isFinite(capMs) && capMs > this.asked)
+            this.asked = capMs;
+        const done = () => {
+            this.pending -= 1;
+            settled();
+        };
+        Promise.resolve(until).then(done, done);
+    }
+    /** Painted, with every hold settled: what `splashDecision` calls the content being ready. */
+    get ready() {
+        return this.painted && this.pending === 0;
+    }
+}
+/** The badge on the page, which `holdSplash` holds. One screen, so one badge: see `bootGate.ts`. */
+let mounted = null;
+/**
+ * Keep the engine's badge up until `until` settles, as well as until the game's first frame: a game
+ * whose first screen loads for longer than that frame — a stage, figures and their pictures on a
+ * first visit — is seen whole rather than loading. **`capMs` is the game's own ceiling** on the
+ * badge in place of the engine's twenty seconds, longer for a slow first visit or shorter, so a load
+ * that never settles is still shown in the end; the longest of several holds' wins, and the minimum
+ * hold is unchanged.
+ *
+ * **Frames run while the game loads behind the plate**, since a load may need them, and are held
+ * once it has settled, for whatever is left of the minimum, as they are after a first frame with no
+ * hold. Returns whether there was a badge to hold: none in a packaged build, whose shell shows its
+ * own until the first frame, nor where `splash: false` or `?splash=0` turned it off.
+ */
+export function holdSplash(until, options = {}) {
+    return mounted?.holdUntil(until, options.capMs) ?? false;
+}
 /**
  * The badge markup. One constant string, interpolated into nothing.
  *
@@ -228,17 +281,18 @@ export function mountSplash(options = {}) {
                the document and already styled; nothing here needs to be undone. */
         }
     }
-    let painted = false;
+    const state = new SplashState();
     let leaving = false;
     let timer = null;
     /*
-     * **Freeze the game the moment it has proved it can draw.**
+     * **Freeze the game the moment it has proved it can draw and has loaded.**
      *
-     * `painted` is the first `endFrame`, and everything after it until the plate leaves is time the
-     * game would otherwise spend running behind an opaque screen. `bootGate` is read by `startLoop`
+     * Ready is the first `endFrame` with every hold settled (`SplashState`), and everything after it
+     * until the plate leaves is time the game would otherwise spend running behind an opaque screen.
+     * Before it, frames run: a load the game is holding the badge for may need them. `bootGate` is read by `startLoop`
      * and named by neither of them; see its own comment for why the state is shared that way.
      */
-    const openGate = holdFrames(() => painted && !leaving);
+    const openGate = holdFrames(() => state.ready && !leaving);
     const remove = () => {
         /* Leaving the top layer is what `hidePopover` is for. `remove()` alone takes the element out
            of the document, and an element removed while shown is not a state worth relying on. */
@@ -256,6 +310,8 @@ export function mountSplash(options = {}) {
         if (leaving)
             return;
         leaving = true;
+        if (mounted === badge)
+            mounted = null;
         /* Before the fade, not after it: the game resumes as the plate becomes transparent, so what
            shows through is a running frame rather than the still one it was frozen on. */
         openGate();
@@ -278,23 +334,32 @@ export function mountSplash(options = {}) {
         if (leaving)
             return;
         const elapsed = performance.now() - started;
-        if (splashDecision(elapsed, minMs, painted) === 'swap') {
+        if (splashDecision(elapsed, minMs, state.ready, state.capMs) === 'swap') {
             release();
             return;
         }
         if (timer !== null)
             clearTimeout(timer);
-        const next = painted ? minMs - elapsed : SPLASH_HARD_CAP_MS - elapsed;
+        const next = state.ready ? minMs - elapsed : state.capMs - elapsed;
         timer = setTimeout(settle, Math.max(0, next));
     };
-    settle();
-    return {
+    const badge = {
         present() {
-            if (painted || leaving)
+            if (state.painted || leaving)
                 return;
-            painted = true;
+            state.painted = true;
             settle();
         },
         release,
+        holdUntil(until, capMs) {
+            if (leaving)
+                return false;
+            state.hold(until, capMs, settle);
+            settle();
+            return true;
+        },
     };
+    mounted = badge;
+    settle();
+    return badge;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.10.0",
+  "version": "4.11.1",
   "description": "The runtime of DriftEngine, a WebGPU game engine with a WebGL2 fallback: renderer, loop, input, cameras, scene graph and physics",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.10.0",
-    "@driftengine/physics": "4.10.0",
+    "@driftengine/drft": "4.11.1",
+    "@driftengine/physics": "4.11.1",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -67,8 +67,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.10.0",
-    "@driftengine/network": "4.10.0",
-    "@driftengine/texture": "4.10.0"
+    "@driftengine/nav": "4.11.1",
+    "@driftengine/network": "4.11.1",
+    "@driftengine/texture": "4.11.1"
   }
 }

package/src/index.ts

@@ -481,6 +481,7 @@ export type {
   LineHandle,
   MeshHandle,
   MeshOptions,
+  PrepareOptions,
   RenderBackend,
   RendererApi,
   ParticleHandle,
@@ -539,8 +540,8 @@ export type { LightmapPage, LightmapRegion } from './render/lightmap.ts';
  * A skinned cloth solved where the renderer can: compute on WebGPU, the CPU under WebGL2. A function
  * rather than a renderer method so only a game that imports it carries the solver.
  */
-export { createSkinnedCloth } from './render/skinnedClothRun.ts';
-export type { SkinnedClothSolver } from './render/skinnedClothRun.ts';
+export { createSkinnedCloth, createSkinnedClothSet } from './render/skinnedClothRun.ts';
+export type { SkinnedClothSet, SkinnedClothSolver } from './render/skinnedClothRun.ts';
 
 /**
  * What a frame asked of a backend, against the ceilings that backend imposes.
@@ -652,6 +653,7 @@ export type {
   DirectionalShadowDepthLayers,
   GlassShadows,
   OutputTransform,
+  PipelineCompile,
   RenderQuality,
   RenderQualityOptions,
   ShadowFilterTaps,
@@ -663,6 +665,7 @@ export { MAX_POINT_LIGHTS, SURFACE_TEXTURE_UNIT } from './render/lightBudget.ts'
 export { MAX_CLUSTERED_LIGHTS } from './render/clusteredLights.ts';
 export { SurfaceTexture } from './render/surfaceTexture.ts';
 export type { SurfaceMaterial, SurfaceTextureOptions } from './render/surfaceTexture.ts';
+export type { SurfaceProjection } from './render/surfaceProjection.ts';
 /*
  * Compressed textures — BC, ETC2 and EAC, ASTC: the source `createSurfaceTexture` takes as blocks,
  * the one question to ask before handing one over — whether this device takes its format
@@ -991,6 +994,7 @@ export {
   SPLASH_HARD_CAP_MS,
   SPLASH_MIN_MS,
   forcedSplash,
+  holdSplash,
   mountSplash,
   splashDecision,
   splashWanted,

package/src/render/ambientOcclusionPass.ts

@@ -113,7 +113,8 @@ export class AmbientOcclusionPass {
    * by, or null if this pass could not run, which the caller must read as "no occlusion"
    * rather than as black.
    *
-   * `invProjection` is column-major, as `gl-matrix` produces it.
+   * `invProjection` is column-major, as `gl-matrix` produces it. `fade` is `uFade`, where the
+   * occlusion fades out with distance (`occlusionFade.ts`).
    */
   run(
     depth: WebGLTexture,
@@ -122,6 +123,7 @@ export class AmbientOcclusionPass {
     radius: number,
     projScale: Float32Array,
     invProjection: Float32Array,
+    fade: Float32Array,
   ): WebGLTexture | null {
     if (!this.ensureSize(width, height)) return null;
     const { gl } = this;
@@ -142,6 +144,7 @@ export class AmbientOcclusionPass {
     gl.uniform1i(this.estimateUniforms['uDepth'] ?? null, 0);
     gl.uniform2fv(this.estimateUniforms['uProjScale'] ?? null, projScale);
     gl.uniform1f(this.estimateUniforms['uRadius'] ?? null, radius);
+    gl.uniform2fv(this.estimateUniforms['uFade'] ?? null, fade);
     gl.uniformMatrix4fv(this.estimateUniforms['uInvProjection'] ?? null, false, invProjection);
     gl.drawArrays(gl.TRIANGLES, 0, 3);
 

package/src/render/backend/api.ts

@@ -235,6 +235,15 @@ export interface SurfaceTextureHandle {
  * `WebGLBuffer` in a private field, so no WebGPU object can satisfy it however identical its
  * shape. It is not meant to be read; it is meant to be enforced.
  */
+/** Which of a draw's pipelines `prepareMesh` and `prepareInstanced` compile beside the opaque ones. */
+export interface PrepareOptions {
+  /**
+   * The blended ones too, for a draw made with `drawTranslucentMesh` or `drawTranslucentInstanced`.
+   * Off by default: an opaque surface would pay a compile it never draws with.
+   */
+  readonly translucent?: boolean;
+}
+
 /** What a mesh needs to be told at creation that its geometry cannot say. */
 export interface MeshOptions {
   /**
@@ -312,6 +321,8 @@ export type RendererApi = Omit<
   | 'disposeSurfaceTexture'
   | 'setSurfaceTexture'
   | 'setMaterial'
+  | 'prepareMesh'
+  | 'prepareInstanced'
   | 'setSurfaceOverlay'
   | 'createClothBinding'
   | 'createClothParticles'
@@ -455,6 +466,26 @@ export type RendererApi = Omit<
    * setter each — and `setSurfaceTexture` is now a wrapper over it.
    */
   setMaterial(material: SurfaceMaterial<SurfaceTextureHandle> | null): void;
+  /**
+   * Compile, off the main thread, every pipeline a draw of `mesh` in `material` takes that making
+   * the mesh did not — a two-sided, cut-out or shaded-by-a-model variant, a material's lit switches,
+   * a skin's halves — so the first frame that draws it waits on none; `ready()` resolves once they
+   * have. For `pipelineCompile: 'skip'` above all, where a draw whose pipeline is new is left out
+   * until it lands: a figure brought on screen whole rather than without its face for a few frames.
+   * A rigged mesh is prepared as drawn with a palette, and one with targets both with weights and
+   * without. Call it between frames: it sets `material` to read it and leaves none set after.
+   */
+  prepareMesh(
+    mesh: MeshHandle,
+    material: SurfaceMaterial<SurfaceTextureHandle> | null,
+    options?: PrepareOptions,
+  ): void;
+  /** `prepareMesh` for an instanced batch drawn in `material`, its own pipelines being its own. */
+  prepareInstanced(
+    batch: InstancedHandle,
+    material: SurfaceMaterial<SurfaceTextureHandle> | null,
+    options?: PrepareOptions,
+  ): void;
 
   /**
    * A 3D text object: one string, drawn as instanced glyph cubes over the scene.