@driftengine/core 4.11.0 → 4.11.1

package/dist/render/surfaceLayers.d.ts

@@ -1,7 +1,8 @@
 /**
- * A material blended from layers by a mask: `SurfaceMaterial.layers`, and the two vectors
- * `shaders/flat/layered.ts` reads it from.
+ * A material blended from layers by a mask: `SurfaceMaterial.layers`, the four vectors
+ * `shaders/flat/layered.ts` reads it from, and the decisions both backends take about it.
  */
+import type { SurfaceProjection } from './surfaceProjection.ts';
 /** The most layers a material blends: a base and one for each of the mask's four channels. */
 export declare const MAX_SURFACE_LAYERS = 5;
 /**
@@ -10,30 +11,97 @@ export declare const MAX_SURFACE_LAYERS = 5;
  * **Layer `i` is layer `i` of the material's arrays**: `albedo`, `normal` and `orm` each an array
  * whose layers are the material's layers in order, read at the mesh's coordinates times
  * `repeats[i]`, so rock can repeat forty times across a cliff while the moss on it repeats three.
- * **The mask** is read at the mesh's own coordinates and lays each layer over those before it: red
- * lays layer 1 over the base, green layer 2 over that, blue layer 3, alpha layer 4. Its layer 0 is
- * read, from where a shading model's map goes, which is why a layered material carries no
- * `modelMap`. `emissiveLayer` gives the material's emissive map to one layer, glowing where that
- * layer shows and nowhere it is covered; absent, the map glows as on any material.
+ * Where the material has a `projection`, the layers are read at the world's horizontal position
+ * instead, so a repeat is so many a metre (with the projection's own scale at 1). **The mask** is
+ * read at the mesh's own coordinates and lays each layer over those before it: red lays layer 1
+ * over the base, green layer 2 over that, blue layer 3, alpha layer 4. `emissiveLayer` gives the
+ * material's emissive map to one layer, glowing where that layer shows and nowhere it is covered;
+ * absent, the map glows as on any material.
+ *
+ * **Maps beyond the layers ride the material's own arrays, after its layers**, so they take no
+ * texture binding of their own — the lit stage has none to spare: a mask the ORM array carries
+ * (`mask: 'orm'`) is the ORM array's layer just past the layers, an `addMask` the one after that,
+ * and `meshNormal` the normal array's layer just past the layers. Each shares its array's size and
+ * format, so a four-channel mask wants an array that stores four.
  *
  * **What it gives up**: every layer's maps are read wherever any shows, three reads a layer, so five
  * layers are fifteen reads where one material is three; layers share an array's size and format; a
- * cutout reads the base layer's alpha; and the mask is sampled linear, so it is uploaded as data
+ * cutout reads the base layer's alpha; a mask read where a model's map goes leaves no room for one,
+ * so a lightmapped surface carries its mask in its ORM array or its vertices; a triplanar projection
+ * lays layers on the horizontal plane alone; and a mask is sampled linear, so it is uploaded as data
  * (`colorSpace: 'linear'`).
  */
 export interface SurfaceLayers<Texture> {
-    /** The weights, red to alpha laying layers 1 to 4, read at the mesh's coordinates. */
-    readonly mask: Texture;
+    /**
+     * Where the weights come from, red to alpha laying layers 1 to 4: a map read where a shading
+     * model's map goes; `'orm'`, the ORM array's layer just past the layers; or `'vertex'`, the
+     * vertex colour's red, green and blue, which then weights the layers instead of tinting them.
+     */
+    readonly mask: Texture | 'orm' | 'vertex';
     /** Each layer's repeats across the mesh's coordinates, base first: one to five of them. */
     readonly repeats: readonly number[];
     /** The layer the emissive map glows on, 0 to 4. Absent: everywhere, as on any material. */
     readonly emissiveLayer?: number;
+    /**
+     * How the layers combine. `'over'`, the default, lays each over the ones before it by its
+     * channel. `'sum'` mixes the base toward the sum of each layer times its channel, by the channels'
+     * sum held to 1: two layers at half each are both half there, where laying over would let the
+     * second cover half of the first.
+     */
+    readonly blend?: 'over' | 'sum';
+    /**
+     * A second mask added to one layer's weight, read where the layers are (the world, under a
+     * `projection`) times `repeat`, its red times `intensity`: sand drifting into the gravel's layer at
+     * a scale of its own. The ORM array's layer after the layers and any mask it carries.
+     */
+    readonly addMask?: {
+        readonly layer: number;
+        readonly repeat: number;
+        readonly intensity: number;
+    };
+    /**
+     * One layer weighted by how much the surface faces up rather than by its mask channel:
+     * `saturate(bias + sharpness × (up / 2 + 1/2))`, `up` the world normal's upward share before any
+     * normal map. Snow on the tops of rocks, moss on a ledge.
+     */
+    readonly facing?: {
+        readonly layer: number;
+        readonly bias: number;
+        readonly sharpness: number;
+    };
+    /**
+     * A normal map read at the mesh's own coordinates and tangents, the normal array's layer just past
+     * the layers, under the layers' blended normal: the large shapes of a rock or a cliff, which a
+     * layer repeating forty times across it cannot carry.
+     */
+    readonly meshNormal?: boolean;
 }
-/** Floats `packSurfaceLayers` writes: two vectors. */
-export declare const LAYER_FLOATS = 8;
+/** Floats `packSurfaceLayers` writes: four vectors. */
+export declare const LAYER_FLOATS = 16;
 /**
- * `layers` into `out`: the five repeats (1 for a layer not given), then how many layers there are
- * and which one glows (−1 for none); zeros, no layers, where there are none. A repeat that is not a
- * positive number is 1, so a layer is never laid at a scale that collapses it to a point.
+ * `layers` into `out`, four vectors. The first five floats are the repeats (1 for a layer not
+ * given), then how many layers there are, which one glows (−1 for none) and where the mask comes
+ * from (0 a map, 1 the ORM array, 2 the vertex colour). Then the blend (0 over, 1 sum), whether a
+ * mesh normal is laid under the layers, the added mask's layer (−1 for none) and repeat; its
+ * intensity; and the facing layer (−1 for none), its bias and its sharpness. Zeros, no layers, where
+ * there are none.
+ *
+ * A repeat that is not a positive number is 1, so a layer is never laid at a scale that collapses it
+ * to a point; a glow, an added mask or a facing layer naming a layer there is not is none, and the
+ * base, which no channel lays, is not one an added mask or the facing can name.
  */
 export declare function packSurfaceLayers<Texture>(layers: SurfaceLayers<Texture> | null | undefined, out: Float32Array): void;
+/** The texture a layered material's mask is, where it is one rather than another array or the vertices. */
+export declare function layerMaskMap<Texture>(layers: SurfaceLayers<Texture> | null | undefined): Texture | null;
+/**
+ * Whether a material's layers can be drawn beside its `modelMap`: always, unless the mask is a map,
+ * which is read where a model's map goes and so cannot share the slot with one — a lightmap's page
+ * among them. The backends draw such a material as one layer and say so once.
+ */
+export declare function layersFitBeside<Texture>(layers: SurfaceLayers<Texture>, modelMap: Texture | null | undefined): boolean;
+/**
+ * The projection a layered material is drawn with: a triplanar one is laid on the horizontal plane,
+ * at its own scale, since every layer's maps read three times over would be forty-five reads a pixel.
+ * Anything else as it was. Whether to say so is the caller's.
+ */
+export declare function layeredProjection<Texture>(projection: SurfaceProjection | null | undefined, layers: SurfaceLayers<Texture> | null | undefined): SurfaceProjection | null;

package/dist/render/surfaceLayers.js

@@ -1,26 +1,82 @@
-/**
- * A material blended from layers by a mask: `SurfaceMaterial.layers`, and the two vectors
- * `shaders/flat/layered.ts` reads it from.
- */
 /** The most layers a material blends: a base and one for each of the mask's four channels. */
 export const MAX_SURFACE_LAYERS = 5;
-/** Floats `packSurfaceLayers` writes: two vectors. */
-export const LAYER_FLOATS = 8;
+/** Floats `packSurfaceLayers` writes: four vectors. */
+export const LAYER_FLOATS = 16;
+/** Where the mask is read, as the fourth float of the second vector carries it. */
+const MASK_SOURCE = { map: 0, orm: 1, vertex: 2 };
 /**
- * `layers` into `out`: the five repeats (1 for a layer not given), then how many layers there are
- * and which one glows (−1 for none); zeros, no layers, where there are none. A repeat that is not a
- * positive number is 1, so a layer is never laid at a scale that collapses it to a point.
+ * `layers` into `out`, four vectors. The first five floats are the repeats (1 for a layer not
+ * given), then how many layers there are, which one glows (−1 for none) and where the mask comes
+ * from (0 a map, 1 the ORM array, 2 the vertex colour). Then the blend (0 over, 1 sum), whether a
+ * mesh normal is laid under the layers, the added mask's layer (−1 for none) and repeat; its
+ * intensity; and the facing layer (−1 for none), its bias and its sharpness. Zeros, no layers, where
+ * there are none.
+ *
+ * A repeat that is not a positive number is 1, so a layer is never laid at a scale that collapses it
+ * to a point; a glow, an added mask or a facing layer naming a layer there is not is none, and the
+ * base, which no channel lays, is not one an added mask or the facing can name.
  */
 export function packSurfaceLayers(layers, out) {
     out.fill(0);
     if (layers === null || layers === undefined || layers.repeats.length === 0)
         return;
     const count = Math.min(layers.repeats.length, MAX_SURFACE_LAYERS);
-    for (let i = 0; i < MAX_SURFACE_LAYERS; i++) {
-        const repeat = i < count ? layers.repeats[i] : 1;
-        out[i] = Number.isFinite(repeat) && repeat > 0 ? repeat : 1;
-    }
+    for (let i = 0; i < MAX_SURFACE_LAYERS; i++)
+        out[i] = positive(i < count ? layers.repeats[i] : 1);
     out[5] = count;
     const glow = layers.emissiveLayer;
     out[6] = glow !== undefined && Number.isInteger(glow) && glow >= 0 && glow < count ? glow : -1;
+    out[7] =
+        layers.mask === 'orm'
+            ? MASK_SOURCE.orm
+            : layers.mask === 'vertex'
+                ? MASK_SOURCE.vertex
+                : MASK_SOURCE.map;
+    out[8] = layers.blend === 'sum' ? 1 : 0;
+    out[9] = layers.meshNormal === true ? 1 : 0;
+    const added = layers.addMask;
+    const addLayer = laidLayer(added?.layer, count);
+    out[10] = addLayer;
+    out[11] = addLayer < 0 ? 0 : positive(added?.repeat);
+    out[12] = addLayer < 0 ? 0 : finite(added?.intensity);
+    const facing = layers.facing;
+    const faceLayer = laidLayer(facing?.layer, count);
+    out[13] = faceLayer;
+    out[14] = faceLayer < 0 ? 0 : finite(facing?.bias);
+    out[15] = faceLayer < 0 ? 0 : finite(facing?.sharpness);
+}
+/** The texture a layered material's mask is, where it is one rather than another array or the vertices. */
+export function layerMaskMap(layers) {
+    const mask = layers?.mask;
+    return mask === undefined || mask === 'orm' || mask === 'vertex' ? null : mask;
+}
+/**
+ * Whether a material's layers can be drawn beside its `modelMap`: always, unless the mask is a map,
+ * which is read where a model's map goes and so cannot share the slot with one — a lightmap's page
+ * among them. The backends draw such a material as one layer and say so once.
+ */
+export function layersFitBeside(layers, modelMap) {
+    return modelMap === null || modelMap === undefined || layerMaskMap(layers) === null;
+}
+/**
+ * The projection a layered material is drawn with: a triplanar one is laid on the horizontal plane,
+ * at its own scale, since every layer's maps read three times over would be forty-five reads a pixel.
+ * Anything else as it was. Whether to say so is the caller's.
+ */
+export function layeredProjection(projection, layers) {
+    if (projection === null || projection === undefined)
+        return null;
+    if (layers === null || layers === undefined || projection.kind !== 'triplanar')
+        return projection;
+    return { kind: 'planar', scale: projection.scale };
+}
+/** A layer an added mask or the facing may name: one a channel lays, 1 to `count − 1`, or −1. */
+function laidLayer(layer, count) {
+    return layer !== undefined && Number.isInteger(layer) && layer >= 1 && layer < count ? layer : -1;
+}
+function positive(value) {
+    return value !== undefined && Number.isFinite(value) && value > 0 ? value : 1;
+}
+function finite(value) {
+    return value !== undefined && Number.isFinite(value) ? value : 0;
 }

package/dist/render/surfaceTexture.d.ts

@@ -218,12 +218,21 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
      * light through by its own rule (`TranslucentMeshOptions.glass`).
      */
     diffuseTransmission?: number;
+    /**
+     * The colour the light from behind takes through the surface, linear, in place of its own colour:
+     * a banner whose cloth glows a flat red behind a printed face, a leaf whose veins are not what the
+     * light through it shows. Absent, the surface's colour, as `diffuseTransmission` has always used.
+     * Each component is held at zero or above. Read only where `diffuseTransmission` lets light through.
+     */
+    transmissionColor?: readonly [number, number, number] | null;
     /**
      * Up to five layers blended by a mask, each at its own repeat: `albedo`, `normal` and `orm` arrays
-     * whose layers are the material's, and a mask laying each over the ones before it. Absent, the
-     * material is one layer, as every material was. **A lit switch**, compiled in the first time a
-     * material asks. The mask is read where `modelMap` goes, so a material carries one or the other.
-     * See `surfaceLayers.ts` for what it gives up.
+     * whose layers are the material's, and a mask laying each over the ones before it or summing them,
+     * from a map, the ORM array or the vertex colour; under a `projection` the layers are placed by the
+     * world. Absent, the material is one layer, as every material was. **A lit switch**, compiled in the
+     * first time a material asks. A mask that is a map is read where `modelMap` goes, so such a
+     * material carries one or the other; a lightmapped one keeps its mask in its ORM array or its
+     * vertices. See `surfaceLayers.ts` for the rest and what it gives up.
      */
     layers?: SurfaceLayers<Texture> | null;
 }

package/dist/render/transmission.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A thin surface's light from behind as the lit stage reads it: `SurfaceMaterial.diffuseTransmission`
+ * and `transmissionColor` into the four lanes of the glass tint an opaque material leaves unused.
+ *
+ * **The colour rides lanes glass owns**, because the lit stage's uniform rows are spent
+ * (`flat/preamble.ts`): a pane writes its own tint there for its draw, so whatever binds a pane
+ * puts this back after it, or the next draw of the material lets light through in the pane's colour.
+ * **−1 in the colour lanes means "the albedo"**, which is what a material naming no colour has
+ * always let through, so a scene that names none draws to the bit as it did.
+ */
+/** What a material lets through from behind and in which colour, as the glass tint carries it. */
+export interface Transmission {
+    readonly diffuseTransmission?: number;
+    readonly transmissionColor?: readonly [number, number, number] | null;
+}
+/**
+ * `material` into `out`: the colour, or −1 three times where it names none, then the amount held
+ * to 0..1. A colour component below zero is held at zero, so a mistyped colour lets no light
+ * through rather than reading as "the albedo".
+ */
+export declare function resolveTransmission(material: Transmission | null, out: Float32Array): void;

package/dist/render/transmission.js

@@ -0,0 +1,21 @@
+/**
+ * A thin surface's light from behind as the lit stage reads it: `SurfaceMaterial.diffuseTransmission`
+ * and `transmissionColor` into the four lanes of the glass tint an opaque material leaves unused.
+ *
+ * **The colour rides lanes glass owns**, because the lit stage's uniform rows are spent
+ * (`flat/preamble.ts`): a pane writes its own tint there for its draw, so whatever binds a pane
+ * puts this back after it, or the next draw of the material lets light through in the pane's colour.
+ * **−1 in the colour lanes means "the albedo"**, which is what a material naming no colour has
+ * always let through, so a scene that names none draws to the bit as it did.
+ */
+/**
+ * `material` into `out`: the colour, or −1 three times where it names none, then the amount held
+ * to 0..1. A colour component below zero is held at zero, so a mistyped colour lets no light
+ * through rather than reading as "the albedo".
+ */
+export function resolveTransmission(material, out) {
+    const colour = material?.transmissionColor ?? null;
+    for (let i = 0; i < 3; i++)
+        out[i] = colour === null ? -1 : Math.max(colour[i] ?? 0, 0) || 0;
+    out[3] = Math.min(Math.max(material?.diffuseTransmission ?? 0, 0), 1) || 0;
+}

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.11.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.11.0",
-    "@driftengine/physics": "4.11.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.11.0",
-    "@driftengine/network": "4.11.0",
-    "@driftengine/texture": "4.11.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,
@@ -993,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.