@driftengine/core 4.10.0 → 4.11.1

package/src/render/surfaceLayers.ts

@@ -0,0 +1,176 @@
+/**
+ * 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 const MAX_SURFACE_LAYERS = 5;
+
+/**
+ * Up to five layers, each its own colour, normal and roughness at its own repeat, blended by a mask.
+ *
+ * **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.
+ * 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; 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> {
+  /**
+   * 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: 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 } as const;
+
+/**
+ * `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<Texture>(
+  layers: SurfaceLayers<Texture> | null | undefined,
+  out: Float32Array,
+): void {
+  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++) 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<Texture>(
+  layers: SurfaceLayers<Texture> | null | undefined,
+): Texture | null {
+  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<Texture>(
+  layers: SurfaceLayers<Texture>,
+  modelMap: Texture | null | undefined,
+): boolean {
+  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<Texture>(
+  projection: SurfaceProjection | null | undefined,
+  layers: SurfaceLayers<Texture> | null | undefined,
+): SurfaceProjection | null {
+  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: number | undefined, count: number): number {
+  return layer !== undefined && Number.isInteger(layer) && layer >= 1 && layer < count ? layer : -1;
+}
+
+function positive(value: number | undefined): number {
+  return value !== undefined && Number.isFinite(value) && value > 0 ? value : 1;
+}
+
+function finite(value: number | undefined): number {
+  return value !== undefined && Number.isFinite(value) ? value : 0;
+}

package/src/render/surfaceOverlay.ts

@@ -29,12 +29,24 @@ export interface OverlayRegion {
  * raised to a contrast, times a noise laid in screen space, a slow pulse and a mask, in a colour.
  * Added to what the surface emits, and not gated on the night as emission is: it is a glow the
  * surface wears, not light it gives off.
+ *
+ * **Or, with `mode: 'blend'`, a colour the surface is pulled toward**, lit like the rest of it: the
+ * base colour mixed toward the rim's by the edge times `alpha`, before any light reads it, so the
+ * rim is bright where light falls and dark where none does. The colour is `colour` times
+ * `intensity`, each channel held at 1 as a base colour is, so a colour of 8 red is a red of 1 and
+ * not a glow; `alpha` is the weight, which may pass 1 to saturate the edge sooner.
  */
 export interface SurfaceRim {
   readonly colour: Vec3;
-  /** How bright, 0 for none. Multiplied with `alpha`. */
+  /**
+   * How bright, 0 for none, multiplied with `alpha`. Where the rim blends it scales `colour`
+   * instead, so 0 there is a rim of black, and `alpha` alone says how much: 0 for none.
+   */
   readonly intensity: number;
+  /** The rim's weight, 1 unless given. */
   readonly alpha?: number;
+  /** `'add'`, the default, lays the rim on as glow; `'blend'` pulls the base colour toward it, lit. */
+  readonly mode?: 'add' | 'blend';
   /** The edge's exponent: larger keeps the rim nearer the silhouette. 1.5 unless given. */
   readonly falloff?: number;
   /**
@@ -122,10 +134,11 @@ function region(out: Float32Array, at: number, r: OverlayRegion | undefined | nu
  * no overlay. A region with a zero scale is an image not given, and its term reads as none — a
  * noise of 1, a mask of 0, no wrinkle — and every region is one without `maps`. Fifteen vectors:
  *
- * - 0: rim colour, rim strength (intensity times alpha; 0 is no rim)
+ * - 0: rim colour, rim strength (intensity times alpha; 0 is no rim). A blending rim: the colour
+ *   times intensity, each channel held at 1, and the alpha alone
  * - 1: falloff, upward lean, contrast, mask weight
  * - 2: the rim's noise region; 3: its scroll along x and y, its tiling, the pulse's rate
- * - 4: the pulse's low and high (1 and 1 where none)
+ * - 4: the pulse's low and high (1 and 1 where none), and the mode: 0 adds, 1 blends
  * - 5: the rim's mask region
  * - 6: the dissolve's noise region (a zero scale is no dissolve); 7: its tiling, threshold, edge
  * - 8: the edge's light and its strength; 9: the laid-over colour and its amount
@@ -138,10 +151,14 @@ export function packSurfaceOverlay(overlay: SurfaceOverlay | null, out: Float32A
   const images = overlay.maps !== undefined;
   const rim = overlay.rim;
   if (rim !== undefined) {
-    out[0] = finite(rim.colour[0], 0);
-    out[1] = finite(rim.colour[1], 0);
-    out[2] = finite(rim.colour[2], 0);
-    out[3] = Math.max(0, finite(rim.intensity, 0) * finite(rim.alpha, 1));
+    const blend = rim.mode === 'blend';
+    const scale = blend ? finite(rim.intensity, 0) : 1;
+    for (let c = 0; c < 3; c++) {
+      const channel = finite(rim.colour[c], 0) * scale;
+      out[c] = blend ? Math.min(Math.max(channel, 0), 1) : channel;
+    }
+    out[3] = Math.max(0, (blend ? 1 : finite(rim.intensity, 0)) * finite(rim.alpha, 1));
+    out[18] = blend ? 1 : 0;
     out[4] = Math.max(0, finite(rim.falloff, 1.5));
     out[5] = Math.max(0, finite(rim.upward, 0.4));
     out[6] = Math.max(0, finite(rim.contrast, 1));

package/src/render/surfaceProjection.ts

@@ -0,0 +1,57 @@
+/**
+ * A material's maps placed by where a point is in the world: `SurfaceMaterial.projection`, and the
+ * one vector `shaders/flat/worldUv.ts` reads it from.
+ */
+
+/**
+ * Texture coordinates from the world rather than from the mesh.
+ *
+ * **`'planar'`** lays the maps across the two horizontal axes, `x` and `z`: ground whose mesh
+ * carries flat coordinates, or none worth reading, shows its texture at `scale` repeats a metre.
+ * **`'triplanar'`** reads each map on the three planes across `x`, `y` and `z` and blends them by
+ * how squarely the surface faces each, the normal's components raised to `sharpness`, so walls and
+ * rock wear a texture without stretching. See `worldUv.ts` for the normal map's blend.
+ *
+ * **What it gives up**: the world's coordinates do not move with a mesh, so a moving mesh slides
+ * under its texture; triplanar reads every map three times; and the material's `uScale`, `vScale`
+ * and offsets, which are the mesh's coordinates', do not apply.
+ */
+export interface SurfaceProjection {
+  readonly kind: 'planar' | 'triplanar';
+  /** Repeats a metre: 2 lays a texture every half metre. */
+  readonly scale: number;
+  /** How sharply triplanar's planes meet: the exponent on the normal. 4 unless given. */
+  readonly sharpness?: number;
+}
+
+/** Floats `packSurfaceProjection` writes: one vector. */
+export const PROJECTION_FLOATS = 4;
+
+/**
+ * `projection` into `out`: its kind (0 none, 1 planar, 2 triplanar), its repeats a metre and its
+ * sharpness; zeros for none. A scale that is not finite and above zero projects nothing, so a
+ * material is never drawn at a scale that collapses its texture to a point.
+ */
+export function packSurfaceProjection(
+  projection: SurfaceProjection | null | undefined,
+  out: Float32Array,
+): void {
+  out.fill(0);
+  if (projection === null || projection === undefined) return;
+  const scale = projection.scale;
+  if (!Number.isFinite(scale) || scale <= 0) return;
+  out[0] = projection.kind === 'triplanar' ? 2 : 1;
+  out[1] = scale;
+  const sharpness = projection.sharpness ?? 4;
+  out[2] = Number.isFinite(sharpness) ? Math.min(Math.max(sharpness, 1), 64) : 4;
+}
+
+/** Whether a material projects its maps at all. */
+export function projects(projection: SurfaceProjection | null | undefined): boolean {
+  return (
+    projection !== null &&
+    projection !== undefined &&
+    Number.isFinite(projection.scale) &&
+    projection.scale > 0
+  );
+}

package/src/render/surfaceTexture.ts

@@ -8,6 +8,8 @@
  * array samples exactly as a 2D texture does. A mesh names its layer per vertex (`MeshData.layers`),
  * so a merged block wearing forty facades is one draw.
  */
+import type { SurfaceLayers } from './surfaceLayers.ts';
+import type { SurfaceProjection } from './surfaceProjection.ts';
 import type { SurfaceModel } from './surfaceModel.ts';
 import { layerSize, refuseArrayUpdate, sourceSize } from './textureSource.ts';
 import {
@@ -213,6 +215,43 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
    * and an 8-bit frame clips the brighter peak without `hdrScene`.
    */
   physicalSpecular?: boolean;
+  /**
+   * Texture coordinates from where a point is in the world rather than from the mesh: `'planar'`
+   * across the horizontal axes for ground, `'triplanar'` on three planes for walls and rock, at so
+   * many repeats a metre. Absent, the mesh's, as every material's were. **A lit switch**, compiled in
+   * the first time a material asks, so a scene that never asks pays nothing. See
+   * `surfaceProjection.ts` for what it gives up.
+   */
+  projection?: SurfaceProjection | null;
+  /**
+   * How much light from behind a thin surface lets through, 0 to 1: a banner lit from behind, a
+   * leaf against the sun, a lampshade. The light falling on the far side — the sun, lamps, area
+   * lights, DriftLight — reaches the eye through the surface, coloured by its own colour; a metal
+   * lets none through. 0, the default, is every material as it was. Two-sided or not: a one-sided
+   * surface seen from its front shows the light behind it as well.
+   *
+   * **What it gives up**: a thin surface, not a volume, so a thick one lets through as much as a
+   * sheet; the light behind is not blurred by the surface; and none of it on glass, which lets
+   * 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 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;
 }
 
 export interface SurfaceTextureOptions {

package/src/render/transmission.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 function resolveTransmission(material: Transmission | null, out: Float32Array): void {
+  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/src/render/vertexPacking.ts

@@ -0,0 +1,109 @@
+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 const PACKED_ATTRIBUTES = [
+  'normals',
+  'tangents',
+  'colors',
+  'emissive',
+  'weights',
+  'weights2',
+] as const;
+
+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 function vertexPackingOf(data: MeshData, dynamic: boolean): VertexPacking {
+  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: number, one: number): number {
+  return Math.round(value * one);
+}
+
+/** An attribute's values in its fixed point, tightly, for a backend reading separate arrays. */
+export function fixedArray(
+  values: Float32Array,
+  packing: 'snorm16' | 'unorm16',
+): Int16Array | Uint16Array {
+  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] as number, one);
+  return out;
+}
+
+/** How `name` travels under this packing: floats for an attribute it does not decide for. */
+export function packingFor(packing: VertexPacking, name: string): AttributePacking {
+  return (packing as Readonly<Record<string, AttributePacking>>)[name] ?? 'float';
+}
+
+/** The value every vertex shares, for an attribute packed as `'constant'`. */
+export function sharedValue(values: Float32Array, width: number): number[] {
+  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: Float32Array | undefined, low: -1 | 0): AttributePacking {
+  if (values === undefined) return 'float';
+  for (let at = 0; at < values.length; at++) {
+    const value = values[at] as number;
+    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: Float32Array, width: number): boolean {
+  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/src/ui/splash.ts

@@ -101,8 +101,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
@@ -138,6 +139,65 @@ 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 class SplashState {
+  /** Whether a frame of the game has reached the screen. */
+  painted = false;
+  private pending = 0;
+  /** The longest cap a hold has named, or 0 for none. */
+  private asked = 0;
+
+  /** The longest the badge may stay: the cap a hold named, the longest of several, or the engine's. */
+  get capMs(): number {
+    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: PromiseLike<unknown>, capMs: number | undefined, settled: () => void): void {
+    this.pending += 1;
+    if (capMs !== undefined && Number.isFinite(capMs) && capMs > this.asked) this.asked = capMs;
+    const done = (): void => {
+      this.pending -= 1;
+      settled();
+    };
+    Promise.resolve(until).then(done, done);
+  }
+
+  /** Painted, with every hold settled: what `splashDecision` calls the content being ready. */
+  get ready(): boolean {
+    return this.painted && this.pending === 0;
+  }
+}
+
+/** The badge on the page, which `holdSplash` holds. One screen, so one badge: see `bootGate.ts`. */
+let mounted: MountedSplash | null = 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: PromiseLike<unknown>, options: { capMs?: number } = {}): boolean {
+  return mounted?.holdUntil(until, options.capMs) ?? false;
 }
 
 /**
@@ -275,18 +335,19 @@ export function mountSplash(options: SplashOptions = {}): MountedSplash | null {
     }
   }
 
-  let painted = false;
+  const state = new SplashState();
   let leaving = false;
   let timer: ReturnType<typeof setTimeout> | null = 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 = (): void => {
     /* Leaving the top layer is what `hidePopover` is for. `remove()` alone takes the element out
@@ -304,6 +365,7 @@ export function mountSplash(options: SplashOptions = {}): MountedSplash | null {
   const release = (): void => {
     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();
@@ -325,23 +387,30 @@ export function mountSplash(options: SplashOptions = {}): MountedSplash | null {
   const settle = (): void => {
     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: MountedSplash = {
     present(): void {
-      if (painted || leaving) return;
-      painted = true;
+      if (state.painted || leaving) return;
+      state.painted = true;
       settle();
     },
     release,
+    holdUntil(until: PromiseLike<unknown>, capMs?: number): boolean {
+      if (leaving) return false;
+      state.hold(until, capMs, settle);
+      settle();
+      return true;
+    },
   };
+  mounted = badge;
+  settle();
+  return badge;
 }