@driftengine/core 4.9.0 → 4.11.0

package/dist/render/shaders/tangentFrame.js

@@ -40,11 +40,24 @@ export const TANGENT_FRAME_GLSL = `mat3 tangentFrame(vec3 n, vec3 worldPos, vec2
    * side and nothing else.
    *
    * The UV determinant flips with them, so folding its sign back in restores the invariance the
-   * solve always had. Measured before and after on demo/dev/normal.html: the derived panel stood
+   * solve always had — through the orientation below, which flips with them too. Measured before and after on demo/dev/normal.html: the derived panel stood
    * 86 of 255 rms from the attribute panel on WebGPU and 8.8 on WebGL2; with this they agree.
    */
-  float det = duv1.x * duv2.y - duv2.x * duv1.y;
-  float handed = det < 0.0 ? -1.0 : 1.0;
+  /*
+   * **And the mapping's own handedness, which the determinant alone does not carry.** The closed
+   * form is the determinant times \`Pv × n\` and \`−Pu × n\`, which are \`Pu\` and \`Pv\` where the
+   * coordinates are right-handed about the normal and their negations where they are mirrored: a
+   * mirrored mapping came out turned half a circle, its normal map lit from the far side. The sign
+   * that puts both back is the determinant's times the mapping's handedness, and that product is
+   * the surface's orientation on screen, \`dp1 × dp2 = det · (Pu × Pv)\`, against the normal. It
+   * flips with \`dFdy\` as the determinant does, so the two backends stay agreed, and it equals the
+   * determinant's sign wherever a mapping is not mirrored. Found by a projection laying \`u\` along
+   * x and \`v\` along z on ground facing up, which is mirrored: on demo/dev/worldUv.html a normal
+   * map leaning along +u read 74.8 derived against 110.8 from the tangent attribute, the light
+   * from the side it leans toward, and 110.8 both after. Every published scene and the four panels
+   * of demo/dev/normal.html, none of them mirrored and derived, are unchanged to the pixel.
+   */
+  float handed = dot(cross(dp1, dp2), n) < 0.0 ? -1.0 : 1.0;
   /* One scale for both axes, so a stretched UV layout does not shear the frame it produces. */
   float invmax = inversesqrt(max(max(dot(dt, dt), dot(db, db)), 1e-12)) * handed;
   vec3 derivedT = dt * invmax;

package/dist/render/shaders/vertexChannel.d.ts

@@ -18,6 +18,13 @@
  * 4.1 KB across five, so a `#if` here would buy nothing measurable and cost a variant axis.
  */
 export declare const CHANNEL_ATTRIBUTE = "\nlayout(location = 13) in vec4 aChannel;\n\n/*\n * The frame's wind, already converted by `resolveScatterDeform` \u2014 a normalised direction, metres\n * of bend, a gust amplitude and a scaled clock.\n *\n * **The same numbers the scatter batch reads, and that is the rule rather than an economy.** A\n * second conversion here would be a second wind however identical its inputs, and the failure is\n * not localised: it shows up as a scene that does not cohere, a canopy leaning one way while the\n * grass beneath it leans another, with no single element looking wrong. See \"One wind, sampled\n * once\" in AGENTS.md.\n */\nuniform vec2 uWindDirection;\nuniform float uWindSpeed;\nuniform float uWindGust;\nuniform float uWindTime;\n/* Spatial frequency of the travelling gust, per metre. */\nuniform vec2 uWindSpatialPhase;\n";
+/**
+ * The same, for the lit stage, whose wind lives in its view block: the frame's and not the draw's,
+ * so a draw's own block does not change when the wind does. See `hoistUniformBlock` in
+ * `scripts/wgsl/transform.mjs`. Text otherwise identical, so WebGL2 runs the same program it always
+ * has; the depth stage keeps the unmarked chunk, having no view block.
+ */
+export declare const LIT_CHANNEL_ATTRIBUTE = "\nlayout(location = 13) in vec4 aChannel;\n\n/*\n * The frame's wind, already converted by `resolveScatterDeform` \u2014 a normalised direction, metres\n * of bend, a gust amplitude and a scaled clock.\n *\n * **The same numbers the scatter batch reads, and that is the rule rather than an economy.** A\n * second conversion here would be a second wind however identical its inputs, and the failure is\n * not localised: it shows up as a scene that does not cohere, a canopy leaning one way while the\n * grass beneath it leans another, with no single element looking wrong. See \"One wind, sampled\n * once\" in AGENTS.md.\n */\nuniform vec2 uWindDirection; // wgsl:view\nuniform float uWindSpeed; // wgsl:view\nuniform float uWindGust; // wgsl:view\nuniform float uWindTime; // wgsl:view\n/* Spatial frequency of the travelling gust, per metre. */\nuniform vec2 uWindSpatialPhase; // wgsl:view\n";
 /**
  * Where the wind puts a vertex, given how much of it that vertex takes.
  *

package/dist/render/shaders/vertexChannel.js

@@ -37,6 +37,32 @@ uniform float uWindTime;
 /* Spatial frequency of the travelling gust, per metre. */
 uniform vec2 uWindSpatialPhase;
 `;
+/**
+ * The same, for the lit stage, whose wind lives in its view block: the frame's and not the draw's,
+ * so a draw's own block does not change when the wind does. See `hoistUniformBlock` in
+ * `scripts/wgsl/transform.mjs`. Text otherwise identical, so WebGL2 runs the same program it always
+ * has; the depth stage keeps the unmarked chunk, having no view block.
+ */
+export const LIT_CHANNEL_ATTRIBUTE = `
+layout(location = 13) in vec4 aChannel;
+
+/*
+ * The frame's wind, already converted by \`resolveScatterDeform\` — a normalised direction, metres
+ * of bend, a gust amplitude and a scaled clock.
+ *
+ * **The same numbers the scatter batch reads, and that is the rule rather than an economy.** A
+ * second conversion here would be a second wind however identical its inputs, and the failure is
+ * not localised: it shows up as a scene that does not cohere, a canopy leaning one way while the
+ * grass beneath it leans another, with no single element looking wrong. See "One wind, sampled
+ * once" in AGENTS.md.
+ */
+uniform vec2 uWindDirection; // wgsl:view
+uniform float uWindSpeed; // wgsl:view
+uniform float uWindGust; // wgsl:view
+uniform float uWindTime; // wgsl:view
+/* Spatial frequency of the travelling gust, per metre. */
+uniform vec2 uWindSpatialPhase; // wgsl:view
+`;
 /**
  * Where the wind puts a vertex, given how much of it that vertex takes.
  *

package/dist/render/skinnedClothRun.d.ts

@@ -22,5 +22,33 @@ export interface SkinnedClothSolver {
     reset(): void;
     dispose(): void;
 }
+/** Garments a renderer solves together, from `createSkinnedClothSet`, each named by its index. */
+export interface SkinnedClothSet {
+    /** Each garment's particles, in the order its set-up was given: what `setCloth` draws it by. */
+    readonly particles: readonly ClothParticlesHandle[];
+    /** Where the set runs: on the device, or on the CPU beneath a backend without compute. */
+    readonly runsOn: 'device' | 'cpu';
+    /**
+     * Garment `g`'s rig for the next `step`: each joint's global matrix, model space, sixteen floats a
+     * joint, and the model matrix. A garment not posed in a frame steps toward its last pose.
+     */
+    setPose(g: number, globals: Float32Array, model: Float32Array): void;
+    /** The air garment `g` drags toward from its next step: the frame's sample of the one wind. */
+    setWind(g: number, x: number, y: number, z: number): void;
+    /** Garment `g` back to its skinned pose, settled, as a teleport resets it. */
+    reset(g: number): void;
+    /**
+     * `dt` seconds for every garment, run as whole fixed steps; each garment's particles at its
+     * `alpha` are then what the frame draws. **Once a frame, before the draws**, as a solver's `step`.
+     */
+    step(dt: number): void;
+    dispose(): void;
+}
 /** A garment for `renderer`, from a set-up checked by name. */
 export declare function createSkinnedCloth(renderer: RendererApi, setup: SkinnedClothSetup): SkinnedClothSolver;
+/**
+ * Garments for `renderer` stepped together, from set-ups checked by name: one pass, one submit and
+ * one garment's dispatches a step on the device, whatever the count. They must agree on `step`,
+ * `substeps`, `iterations` and `maxSteps`, and are refused by the first they disagree on.
+ */
+export declare function createSkinnedClothSet(renderer: RendererApi, setups: readonly SkinnedClothSetup[]): SkinnedClothSet;

package/dist/render/skinnedClothRun.js

@@ -11,74 +11,142 @@
  * millisecond a frame on the main thread, and 4,500 are twenty — a garment that size wants the
  * device. The device solver ran 4,500 particles in 0.65 ms a frame, most of it the dispatches
  * rather than the particles (`demo/dev/skinnedCloth.html?bench=1`).
+ *
+ * **Several garments step as one with `createSkinnedClothSet`**: one pass, one submit and one
+ * garment's dispatches a step for all of them, where a garment each was a pass, a submit and its
+ * own dispatches each. They must share a step, substeps, iterations and most steps a frame.
  */
 import { SkinnedCloth } from '@driftengine/physics';
 import { computeHostOf } from './backend/webgpu/computeHost.js';
-import { GpuSkinnedCloth } from './backend/webgpu/gpuSkinnedCloth.js';
+import { GpuClothSet } from './backend/webgpu/gpuClothSet.js';
 /** A garment for `renderer`, from a set-up checked by name. */
 export function createSkinnedCloth(renderer, setup) {
     const host = computeHostOf(renderer);
-    return host === null ? new CpuCloth(renderer, setup) : new DeviceCloth(host, setup);
+    const set = host === null ? new CpuClothSet(renderer, [setup]) : new DeviceClothSet(host, [setup]);
+    return new OneGarment(set);
+}
+/** A set of one, as a solver: what `createSkinnedCloth` hands back. */
+class OneGarment {
+    set;
+    particles;
+    runsOn;
+    constructor(set) {
+        this.set = set;
+        this.particles = set.particles[0];
+        this.runsOn = set.runsOn;
+    }
+    step(globals, model, dt) {
+        this.set.setPose(0, globals, model);
+        this.set.step(dt);
+    }
+    setWind(x, y, z) {
+        this.set.setWind(0, x, y, z);
+    }
+    reset() {
+        this.set.reset(0);
+    }
+    dispose() {
+        this.set.dispose();
+    }
+    /** The particles where the last step left them: the parity check's door. */
+    read() {
+        return this.set.read(0);
+    }
 }
-class DeviceCloth {
+/**
+ * Garments for `renderer` stepped together, from set-ups checked by name: one pass, one submit and
+ * one garment's dispatches a step on the device, whatever the count. They must agree on `step`,
+ * `substeps`, `iterations` and `maxSteps`, and are refused by the first they disagree on.
+ */
+export function createSkinnedClothSet(renderer, setups) {
+    const host = computeHostOf(renderer);
+    return host === null ? new CpuClothSet(renderer, setups) : new DeviceClothSet(host, setups);
+}
+class DeviceClothSet {
     host;
     runsOn = 'device';
     particles;
-    cloth;
-    constructor(host, setup) {
+    set;
+    constructor(host, setups) {
         this.host = host;
-        this.cloth = new GpuSkinnedCloth(host.device(), setup);
-        this.particles = this.cloth.particles;
+        this.set = new GpuClothSet(host.device(), setups);
+        const particles = [];
+        for (let g = 0; g < this.set.size; g++)
+            particles.push(this.set.particles(g));
+        this.particles = particles;
     }
-    step(globals, model, dt) {
+    setPose(g, globals, model) {
         if (this.host.lost())
             return;
-        this.cloth.advance(globals, model, dt, this.host.changeFrame());
+        this.set.setPose(g, globals, model);
     }
-    setWind(x, y, z) {
-        this.cloth.setWind(x, y, z);
+    setWind(g, x, y, z) {
+        this.set.setWind(g, x, y, z);
     }
-    reset() {
+    reset(g) {
+        if (this.host.lost())
+            return;
+        this.set.reset(g);
+    }
+    step(dt) {
         if (this.host.lost())
             return;
-        this.cloth.reset();
+        this.set.step(dt, this.host.changeFrame());
     }
     /** Its buffers at once — its work is submitted — and its textures with the frame's. */
     dispose() {
-        this.cloth.dispose();
-        this.host.retire(this.cloth.particles.textures);
+        this.set.dispose();
+        for (let g = 0; g < this.set.size; g++)
+            this.host.retire(this.set.particles(g).textures);
     }
-    /** The particles where the last step left them: the parity check's door, waits on the device. */
-    read() {
-        return this.cloth.read();
+    /** Garment `g`'s particles where its last step left them: the parity check's, waits on the device. */
+    read(g) {
+        return this.set.read(g);
     }
 }
-class CpuCloth {
+class CpuClothSet {
     renderer;
     runsOn = 'cpu';
     particles;
-    cloth;
-    /** The frame's particles at `alpha`, before they go up. */
+    cloths;
+    /** Each garment's particles at `alpha`, before they go up. */
     staging;
-    constructor(renderer, setup) {
+    constructor(renderer, setups) {
         this.renderer = renderer;
-        this.cloth = new SkinnedCloth(setup);
-        this.particles = renderer.createClothParticles(this.cloth.count);
-        this.staging = new Float32Array(this.cloth.count * 3);
+        this.cloths = setups.map((setup) => new SkinnedCloth(setup));
+        this.particles = this.cloths.map((cloth) => renderer.createClothParticles(cloth.count));
+        this.staging = this.cloths.map((cloth) => new Float32Array(cloth.count * 3));
     }
-    step(globals, model, dt) {
-        this.cloth.setPose(globals, model);
-        this.cloth.advance(dt);
-        this.cloth.interpolate(this.cloth.alpha, this.staging);
-        this.renderer.updateClothParticles(this.particles, this.staging);
+    setPose(g, globals, model) {
+        this.at(g).setPose(globals, model);
     }
-    setWind(x, y, z) {
-        this.cloth.setWind(x, y, z);
+    setWind(g, x, y, z) {
+        this.at(g).setWind(x, y, z);
     }
-    reset() {
-        this.cloth.reset();
+    reset(g) {
+        this.at(g).reset();
+    }
+    step(dt) {
+        for (let g = 0; g < this.cloths.length; g++) {
+            const cloth = this.cloths[g];
+            const staging = this.staging[g];
+            cloth.advance(dt);
+            cloth.interpolate(cloth.alpha, staging);
+            this.renderer.updateClothParticles(this.particles[g], staging);
+        }
     }
     dispose() {
-        this.renderer.disposeClothParticles(this.particles);
+        for (const particles of this.particles)
+            this.renderer.disposeClothParticles(particles);
+    }
+    /** Garment `g`'s particles where its last step left them, as the device set reads its own. */
+    read(g) {
+        return Promise.resolve(new Float32Array(this.at(g).positions));
+    }
+    at(g) {
+        const cloth = this.cloths[g];
+        if (cloth === undefined)
+            throw new Error(`skinned cloth set: no garment ${g}`);
+        return cloth;
     }
 }

package/dist/render/staticDraws.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Draws that do not change between frames, captured once from an enumeration and replayed into any
+ * colour pass: what `createStaticDraws` keeps, and the one rule both backends replay it by.
+ *
+ * **Captured, not referenced.** An enumeration is a closure over the caller's state, written to
+ * allocate nothing, so it hands a sink its scratch: the matrix it fills for every entry and the
+ * count it rewrites for the next batch. A list kept across frames copies both when it is made, so
+ * what it draws is what the enumeration said then. Meshes, batches and materials are held by
+ * reference: they are the caller's, and disposing one a list still holds is the caller's error.
+ *
+ * **Rigid meshes and instanced batches only.** A skinned mesh is posed every frame and a scatter
+ * batch bends with every frame's wind, so neither can be kept, and both are refused by name rather
+ * than captured in the pose they happened to have. A caller draws them each frame as it always has.
+ *
+ * What a backend does with the list is its own: WebGL2 replays the entries every frame through
+ * the scene-caster path, and WebGPU records them once into a render bundle per view. See
+ * `RendererApi.createStaticDraws` for what a caller is promised, which is the same on both.
+ */
+import type { InstancedHandle, MeshHandle } from './backend/api.ts';
+import type { MeshInstances } from './instances.ts';
+import type { SceneCasterMaterial, ShadowCasterSink, ShadowCasters } from './shadowCasters.ts';
+/** A list from `createStaticDraws`. Opaque but for its size. */
+export interface StaticDrawsHandle {
+    /** How many entries it holds: meshes and batches, a batch counting once. */
+    readonly draws: number;
+}
+/** One captured entry. */
+export type StaticEntry = {
+    readonly kind: 'mesh';
+    readonly mesh: MeshHandle;
+    readonly model: Float32Array;
+    readonly material: SceneCasterMaterial;
+} | {
+    readonly kind: 'instanced';
+    readonly batch: InstancedHandle;
+    readonly data: MeshInstances;
+    readonly material: SceneCasterMaterial;
+};
+/** What both backends hold: the entries, and whether the list has been disposed. */
+export interface StaticDrawsList extends StaticDrawsHandle {
+    readonly entries: readonly StaticEntry[];
+    disposed: boolean;
+}
+/** Enumerate `casters` once into a list. Allocates: it runs when the list is made, not per frame. */
+export declare function captureStaticDraws(casters: ShadowCasters): StaticDrawsList;
+/** Hand every entry to `sink`, in the order it was captured. */
+export declare function replayStaticDraws(list: StaticDrawsList, sink: ShadowCasterSink): void;

package/dist/render/staticDraws.js

@@ -0,0 +1,43 @@
+/** Enumerate `casters` once into a list. Allocates: it runs when the list is made, not per frame. */
+export function captureStaticDraws(casters) {
+    const entries = [];
+    const sink = {
+        mesh: (mesh, model, material) => {
+            entries.push({
+                kind: 'mesh',
+                mesh,
+                model: new Float32Array(model),
+                material: material ?? null,
+            });
+        },
+        instanced: (batch, data, material) => {
+            /* The batch's placements are on the device already; the count is the caller's scratch. */
+            entries.push({ kind: 'instanced', batch, data: { ...data }, material: material ?? null });
+        },
+        skinnedMesh: () => {
+            throw new Error('createStaticDraws: a skinned mesh is posed every frame, so a list kept across frames ' +
+                'cannot hold one. Draw it each frame, with drawMesh or drawSceneCasters.');
+        },
+        scatter: () => {
+            throw new Error('createStaticDraws: a scatter batch bends with every frame’s wind, so a list kept across ' +
+                'frames cannot hold one. Draw it each frame with drawScatter.');
+        },
+    };
+    casters(sink);
+    return {
+        entries,
+        get draws() {
+            return entries.length;
+        },
+        disposed: false,
+    };
+}
+/** Hand every entry to `sink`, in the order it was captured. */
+export function replayStaticDraws(list, sink) {
+    for (const entry of list.entries) {
+        if (entry.kind === 'mesh')
+            sink.mesh(entry.mesh, entry.model, entry.material);
+        else
+            sink.instanced?.(entry.batch, entry.data, entry.material);
+    }
+}

package/dist/render/surfaceLayers.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 declare 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.
+ * **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.
+ *
+ * **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
+ * (`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;
+    /** 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;
+}
+/** Floats `packSurfaceLayers` writes: two vectors. */
+export declare const LAYER_FLOATS = 8;
+/**
+ * `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.
+ */
+export declare function packSurfaceLayers<Texture>(layers: SurfaceLayers<Texture> | null | undefined, out: Float32Array): void;

package/dist/render/surfaceLayers.js

@@ -0,0 +1,26 @@
+/**
+ * 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;
+/**
+ * `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.
+ */
+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;
+    }
+    out[5] = count;
+    const glow = layers.emissiveLayer;
+    out[6] = glow !== undefined && Number.isInteger(glow) && glow >= 0 && glow < count ? glow : -1;
+}

package/dist/render/surfaceOverlay.d.ts

@@ -27,12 +27,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;
     /**
@@ -118,10 +130,11 @@ export declare const OVERLAY_FLOATS: number;
  * 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

package/dist/render/surfaceOverlay.js

@@ -14,10 +14,11 @@ function region(out, at, r) {
  * 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
@@ -31,10 +32,14 @@ export function packSurfaceOverlay(overlay, out) {
     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/dist/render/surfaceProjection.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 declare 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 declare function packSurfaceProjection(projection: SurfaceProjection | null | undefined, out: Float32Array): void;
+/** Whether a material projects its maps at all. */
+export declare function projects(projection: SurfaceProjection | null | undefined): boolean;

package/dist/render/surfaceProjection.js

@@ -0,0 +1,30 @@
+/**
+ * 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.
+ */
+/** 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, out) {
+    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) {
+    return (projection !== null &&
+        projection !== undefined &&
+        Number.isFinite(projection.scale) &&
+        projection.scale > 0);
+}