@driftengine/core 3.61.0

package/dist/environment/celestialClock.js

@@ -0,0 +1,262 @@
+/**
+ * Allocation-free wall-clock sampling for a procedural sun, moon and clouds.
+ *
+ * **Two models, and a caller chooses by whether it names a place.** Without a `CelestialSite` this
+ * is what it has always been: a sun swung through a fixed arc, peaking at the same altitude every
+ * day of every year wherever the world is meant to be. With one, it is the standard solar-position
+ * arithmetic — a declination from the day of the year, an hour angle from the clock, and an
+ * altitude and azimuth from those and the latitude.
+ *
+ * **The simplified model is kept rather than replaced**, and that is the engine's ordinary rule
+ * rather than a soft touch: every world authored against this engine has its lighting tuned against
+ * that arc, and a model that silently moved the sun would move every shadow, every exposure and
+ * every night in every consumer at once. A caller that passes no site gets the same numbers it got
+ * before, bit for bit, which `celestialClock.test.ts` asserts against literals rather than against
+ * a second implementation.
+ *
+ * **What the simplified model gives up, said plainly, because a consumer worked it out for
+ * themselves first:** no latitude, so the sun reaches 66° at noon on the equator and at the pole
+ * alike; no season, so the arc is the same in December as in June; an azimuth that sweeps a whole
+ * turn in a day where a real one swings through rather less; and a moon pinned exactly opposite the
+ * sun, which contradicts the phase reported beside it — a crescent that rises at midnight. All four
+ * are fixed by naming a site.
+ *
+ * **A site can also name its clock, and until 2026-09-03 nothing could.** The hour was read off the
+ * timestamp through the *host machine's* time zone, so one argument put the sun in four places on
+ * four machines — solar noon at 12:00 under `TZ=UTC`, 10:00 in Rome, 16:00 in New York, 03:00 in
+ * Tokyo — and the only way to say an hour was to build a timestamp whose host offset cancelled the
+ * one being added. `longitudeDeg` and `utcOffsetHours` are the way to say it instead: either one
+ * makes the timestamp a UTC instant and the engine derives the site's own hour, so the sky is a
+ * function of the arguments alone. It was found by a player in Italy watching the sun set before
+ * six, which is what the workaround cost when the host disagreed with the world.
+ */
+import { TAU, smoothstep } from '../math/scalar.js';
+const MS_PER_DAY = 86_400_000;
+/** One hour, for shifting an instant into a site's own zone. */
+const MS_PER_HOUR = 3_600_000;
+/**
+ * How high the sun climbs at noon in the model that knows no latitude: 1.15 radians, 66 degrees.
+ *
+ * Unused by the sited model, which derives the altitude instead, and kept because every world
+ * authored before 2026-08-27 is tuned against it.
+ */
+const MAX_ELEVATION = 1.15;
+/** Earth's axial tilt, and the default a site takes when it names none. */
+const OBLIQUITY_DEG = 23.44;
+/** Days in the year the declination is derived against. */
+const YEAR_DAYS = 365;
+const DEG = Math.PI / 180;
+const LUNAR_CYCLE_DAYS = 29.530_588_67;
+const NEW_MOON_EPOCH_MS = Date.UTC(2000, 0, 6, 18, 14);
+const TWILIGHT = 0.12;
+/**
+ * Reused because `celestialStateAt` runs every frame; `new Date` would allocate.
+ *
+ * It holds the caller's timestamp verbatim when the site names no zone, and the same instant
+ * shifted into the site's zone when it does — so the UTC getters read that site's wall clock.
+ */
+const scratchDate = new Date(0);
+export function createCelestialState() {
+    return {
+        sunDir: [0, 1, 0],
+        moonDir: [0, -1, 0],
+        dayFactor: 1,
+        nightFactor: 0,
+        moonPhase: 0,
+    };
+}
+/** Visible fraction: new at 0/1, quarters at 0.25/0.75, full at 0.5. */
+export function moonIllumination(phase) {
+    return 0.5 - Math.cos(phase * TAU) * 0.5;
+}
+/**
+ * Convert a timestamp and an authored azimuth into sky state.
+ *
+ * The caller decides where the timestamp comes from and must keep it out of a deterministic
+ * simulation if wall time should not affect gameplay.
+ *
+ * `sunAzimuth` is **where the world's north points**, as an angle in the xz plane from +x toward
+ * +z. It was an arbitrary offset in the model that knows no latitude and it means the same thing
+ * there; with a site it becomes load-bearing, because the sun's own azimuth is then derived and
+ * this is what relates it to the world's axes.
+ *
+ * **`site` is what turns the simplified model into the sited one**, and omitting it is not a
+ * degraded mode — it is the model every world here was authored against. See the header.
+ *
+ * **Which hour the timestamp names depends on whether the site states a zone**, and that is the
+ * one thing to get right before anything else here matters:
+ *
+ * - **A site naming `longitudeDeg` or `utcOffsetHours`** makes `whenMs` a plain **UTC instant** —
+ *   `Date.now()`, or `Date.UTC(…)` for an hour chosen outright — and the engine derives that
+ *   site's own hour from it. The answer is then a function of the arguments and of nothing else,
+ *   which is the only form that gives every machine the same sky.
+ * - **A site naming neither, or no site at all**, reads the hour off the timestamp through the
+ *   **host machine's** time zone, which is what this function has always done. Every world
+ *   authored against it is tuned that way, so it is kept exactly: the same argument gives the same
+ *   numbers, bit for bit. But the same argument on another machine gives another hour, so a caller
+ *   in this form must build the timestamp from local parts — `new Date(y, m, d, h)` — for the
+ *   host's offset to cancel rather than be added.
+ *
+ * **`moonPhase` is the reason the first form is worth taking even where the sun already looks
+ * right.** It comes from the timestamp's absolute value rather than from the hour, so the
+ * build-it-from-local-parts trick that steadies the sun leaves the moon drifting by the host's
+ * offset — a fiftieth of a lunar cycle across the world, invisible and still not a fact about the
+ * world.
+ *
+ * **The equation of time stays the caller's**, and it is the last correction left: a real sun runs
+ * up to about a quarter of an hour ahead of or behind mean time across the year, from the Earth's
+ * eccentricity and its tilt. The zone and the meridian are the engine's as soon as a site states
+ * them; this one is not, because it is a property of the planet's orbit rather than of the place,
+ * and a world with an obliquity of its own has an equation of time of its own. A caller measuring
+ * a shadow against an almanac applies it to the timestamp; a caller lighting a world does not care.
+ */
+export function celestialStateAt(whenMs, sunAzimuth, out, site) {
+    const cycles = (whenMs - NEW_MOON_EPOCH_MS) / MS_PER_DAY / LUNAR_CYCLE_DAYS;
+    const phase = cycles - Math.floor(cycles);
+    out.moonPhase = phase;
+    if (site === undefined) {
+        scratchDate.setTime(whenMs);
+        simplified(hostHours(scratchDate), sunAzimuth, out);
+    }
+    else {
+        /*
+         * The zone, or nothing.
+         *
+         * A longitude alone implies its own offset, so a site that gives one and not the other still
+         * describes a consistent clock: `undefined` here means the site named neither, which is the
+         * one case that falls back to the host's.
+         */
+        const meridianDeg = site.longitudeDeg;
+        const offsetHours = site.utcOffsetHours ?? (meridianDeg === undefined ? undefined : meridianDeg / 15);
+        if (offsetHours === undefined) {
+            scratchDate.setTime(whenMs);
+            sited(hostHours(scratchDate), site.dayOfYear ?? hostDayOfYear(scratchDate), sunAzimuth, phase, site, out);
+        }
+        else {
+            /*
+             * Shifted into the site's zone, so the UTC getters read its wall clock; the meridian then
+             * carries that clock the rest of the way to solar time, which is where the hour angle is
+             * measured from. That correction is zero for a place at the centre of its zone and up to
+             * half an hour at its edges. It can push the hour past midnight either way and nothing needs
+             * it wrapped: an hour angle is an angle, and the calendar day is the site's rather than the
+             * sun's.
+             */
+            scratchDate.setTime(whenMs + offsetHours * MS_PER_HOUR);
+            const solar = utcHours(scratchDate) + (meridianDeg ?? offsetHours * 15) / 15 - offsetHours;
+            sited(solar, site.dayOfYear ?? utcDayOfYear(scratchDate), sunAzimuth, phase, site, out);
+        }
+    }
+    out.dayFactor = smoothstep(-TWILIGHT, TWILIGHT, out.sunDir[1]);
+    out.nightFactor = 1 - out.dayFactor;
+}
+/**
+ * The model that knows no latitude, unchanged since it was written.
+ *
+ * A sine of the day's fraction scaled to a fixed peak, an azimuth sweeping a whole turn, and a moon
+ * pinned exactly opposite. Every number a world authored before 2026-08-27 was tuned against.
+ */
+function simplified(hours, sunAzimuth, out) {
+    const fraction = hours / 24;
+    const elevation = Math.sin((fraction - 0.25) * TAU) * MAX_ELEVATION;
+    const azimuth = sunAzimuth + (fraction - 0.25) * TAU;
+    const cosElevation = Math.cos(elevation);
+    const sx = cosElevation * Math.cos(azimuth);
+    const sy = Math.sin(elevation);
+    const sz = cosElevation * Math.sin(azimuth);
+    out.sunDir[0] = sx;
+    out.sunDir[1] = sy;
+    out.sunDir[2] = sz;
+    out.moonDir[0] = -sx;
+    out.moonDir[1] = -sy;
+    out.moonDir[2] = -sz;
+}
+/**
+ * The sited model: a declination, an hour angle, and the two spherical formulas over them.
+ *
+ * **Standard solar-position arithmetic and deliberately the plain form of it.** The declination is
+ * Cooper's equation, `ε · sin(2π (284 + N) / 365)`, which is within about half a degree of the
+ * truth all year; the altitude and azimuth are the spherical law of cosines and its companion. A
+ * more accurate model exists — the equation of centre, nutation, refraction — and buys a fraction
+ * of a degree for a sky nobody is navigating by.
+ *
+ * **The moon follows its phase rather than the sun's opposite**, which is what makes the position
+ * and the phase agree at last. The phase *is* the elongation: at new moon the moon shares the sun's
+ * ecliptic longitude and its hour angle, so it is up in the daytime and invisible; at full it is
+ * half a turn away in both, so it rises as the sun sets. Its own five-degree orbital inclination is
+ * ignored, which is what makes this a line rather than a page and costs the moon up to five degrees
+ * of altitude.
+ *
+ * **It takes an hour and a day rather than a `Date`**, because which clock those came off is the
+ * caller's question and settled before this is reached — see `celestialStateAt`. The model itself
+ * has no time zone in it at all.
+ */
+function sited(hours, day, northAzimuth, phase, site, out) {
+    const latitude = Math.max(-90, Math.min(90, site.latitudeDeg)) * DEG;
+    const obliquity = (site.obliquityDeg ?? OBLIQUITY_DEG) * DEG;
+    /* Ecliptic longitude measured from the point that puts the solstices where they belong. */
+    const sunLongitude = (TAU * (284 + day)) / YEAR_DAYS;
+    const sunHourAngle = (hours - 12) * (Math.PI / 12);
+    place(latitude, Math.asin(Math.sin(obliquity) * Math.sin(sunLongitude)), sunHourAngle, northAzimuth, out.sunDir);
+    /*
+     * The moon, a phase's worth of longitude ahead of the sun and the same amount behind in hour
+     * angle — because an hour angle is the sky turning westward and a longitude is the moon crawling
+     * eastward through it.
+     */
+    const moonLongitude = sunLongitude + phase * TAU;
+    place(latitude, Math.asin(Math.sin(obliquity) * Math.sin(moonLongitude)), sunHourAngle - phase * TAU, northAzimuth, out.moonDir);
+}
+/**
+ * A declination and an hour angle at a latitude, into a world-space direction.
+ *
+ * `sin(alt) = sin φ sin δ + cos φ cos δ cos H` is the altitude; the azimuth is the `atan2` form,
+ * which needs no quadrant test and is stable at the poles where the cosine form divides by nearly
+ * nothing. It comes out measured from **south**, so half a turn puts it on north, and the world's
+ * own north then rotates the whole sky into place.
+ */
+function place(latitude, declination, hourAngle, northAzimuth, out) {
+    const sinLat = Math.sin(latitude);
+    const cosLat = Math.cos(latitude);
+    const sinDec = Math.sin(declination);
+    const cosDec = Math.cos(declination);
+    const sinAlt = sinLat * sinDec + cosLat * cosDec * Math.cos(hourAngle);
+    const altitude = Math.asin(Math.max(-1, Math.min(1, sinAlt)));
+    const fromSouth = Math.atan2(Math.sin(hourAngle) * cosDec, Math.cos(hourAngle) * cosDec * sinLat - sinDec * cosLat);
+    const azimuth = northAzimuth + fromSouth + Math.PI;
+    const cosAltitude = Math.cos(altitude);
+    out[0] = cosAltitude * Math.cos(azimuth);
+    out[1] = Math.sin(altitude);
+    out[2] = cosAltitude * Math.sin(azimuth);
+}
+/** The hour, with its minutes and seconds, off the host machine's own clock. */
+function hostHours(date) {
+    return date.getHours() + date.getMinutes() / 60 + date.getSeconds() / 3600;
+}
+/** The same, off an instant already shifted into the site's zone. See `scratchDate`. */
+function utcHours(date) {
+    return date.getUTCHours() + date.getUTCMinutes() / 60 + date.getUTCSeconds() / 3600;
+}
+/**
+ * Which day of the year a host-local date falls on, 1 to 366.
+ *
+ * From the date's own month and day rather than a difference of timestamps, because a difference
+ * across a daylight-saving boundary is an hour short and lands on the previous day for an hour of
+ * every spring.
+ */
+function hostDayOfYear(date) {
+    const start = Date.UTC(date.getFullYear(), 0, 1);
+    const here = Date.UTC(date.getFullYear(), date.getMonth(), date.getDate());
+    return Math.round((here - start) / MS_PER_DAY) + 1;
+}
+/**
+ * The same for an instant already shifted into the site's zone, read through the UTC getters.
+ *
+ * A separate four lines rather than a flag, because the pair is the whole difference between the
+ * two clocks this function can be asked about and folding them together hides it. No daylight
+ * saving to step around here: the shift was a constant, so the difference of timestamps would
+ * have done — it is written this way to read beside its neighbour.
+ */
+function utcDayOfYear(date) {
+    const start = Date.UTC(date.getUTCFullYear(), 0, 1);
+    const here = Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+    return Math.round((here - start) / MS_PER_DAY) + 1;
+}

package/dist/geometry/decal.d.ts

@@ -0,0 +1,61 @@
+import type { MeshData } from '../render/mesh.ts';
+import type { Vec3 } from '../math/color.ts';
+/**
+ * A decal, as the receiving surface's own geometry clipped to a box and lifted off it.
+ *
+ * **A forward renderer cannot write a decal cheaply into a G-buffer, because there is no G-buffer**,
+ * and that is the fact every decal design here has to start from. What a forward renderer *can* do
+ * is the older technique, and it is the better-looking one: take the triangles the projector box
+ * covers, clip them to it, and draw that. The decal is then made of the surface, so it follows
+ * every curve and every bump exactly, which a projector re-drawing a quad cannot.
+ *
+ * **What it replaces, in a consumer's own words.** Their road patches are strips of geometry lifted
+ * two millimetres above the carriageway: it works, it is a draw call per patch for something that
+ * exists only to sit on top of something else, and it does not follow a curved surface. Puddles
+ * after a storm, oil stains and skid marks were all waiting on the same row. This is one mesh for
+ * as many marks as you project into it, and it is the road's own shape.
+ *
+ * **Built once, not per frame.** A decal is authored or placed by an event — a tyre locks, a barrel
+ * leaks — and then it is scenery. That is what makes clipping on the CPU the right cost: it happens
+ * at the moment the mark is made, and every frame afterwards it is one more mesh in the batch.
+ *
+ * **Its limits, stated rather than discovered.** It is a *static* decal: the receiving mesh is
+ * sampled as it is, so a decal on something that later deforms rides the old shape. It reads
+ * positions and normals and nothing else, so the mark takes its own colour rather than tinting what
+ * is underneath. And a projector box covering a hundred thousand triangles clips a hundred thousand
+ * triangles, so a caller marking a large world hands in the piece of it they mean.
+ */
+export interface DecalOptions {
+    /** Middle of the projector box, world space. */
+    readonly center: Vec3;
+    /** Half-size across, up, and along the projection. The third is how deep the box reaches. */
+    readonly halfExtents: Vec3;
+    /**
+     * The direction the decal is projected *along* — for a mark on the ground, straight down.
+     *
+     * A surface is marked when it faces back along this. Need not be normalised.
+     */
+    readonly forward: Vec3;
+    /** Which way is up in the decal's own image, so a mark can be turned. Need not be normalised. */
+    readonly up: Vec3;
+    readonly color?: Vec3;
+    /**
+     * How far the decal is lifted off the surface, metres. Two millimetres by default.
+     *
+     * **Not a depth-bias setting in disguise.** The lift is along each vertex's own normal, so it
+     * survives a surface that curves away under it where a constant depth offset would not, and it is
+     * small enough to be invisible at a metre and large enough to beat a 24-bit depth buffer at fifty.
+     */
+    readonly offsetM?: number;
+    /**
+     * How far from facing the projector a surface may be turned and still be marked, as a cosine.
+     *
+     * The reason this is not zero: a triangle exactly edge-on to the projector clips to a sliver of
+     * zero area that still costs six vertices, and one a hair past edge-on produces a mark stretched
+     * along a wall it was never aimed at. 0.1 keeps everything within about 84° of facing.
+     */
+    readonly facingCos?: number;
+    readonly emissive?: number;
+    readonly specular?: number;
+}
+export declare function projectDecal(target: MeshData, options: DecalOptions): MeshData;

package/dist/geometry/decal.js

@@ -0,0 +1,178 @@
+/** Room for one clipped polygon: six planes can each add a vertex to a triangle. */
+const MAX_POLYGON = 12;
+/** Position in box space and normal in world space, per vertex, in both ping-pong buffers. */
+const A = new Float64Array(MAX_POLYGON * 6);
+const B = new Float64Array(MAX_POLYGON * 6);
+export function projectDecal(target, options) {
+    const half = options.halfExtents;
+    const hx = half[0];
+    const hy = half[1];
+    const hz = half[2];
+    if (!(hx > 0 && hy > 0 && hz > 0)) {
+        throw new Error(`projectDecal: halfExtents must be positive, got ${hx}, ${hy}, ${hz}`);
+    }
+    /* The box's own basis. `forward` is the projection axis and `right` closes the frame. */
+    const f = unit(options.forward);
+    let u = unit(options.up);
+    const r = cross(u, f);
+    const rLength = Math.hypot(r[0], r[1], r[2]);
+    if (rLength === 0) {
+        throw new Error('projectDecal: up is parallel to forward, so the box has no orientation');
+    }
+    r[0] /= rLength;
+    r[1] /= rLength;
+    r[2] /= rLength;
+    /* Re-derived so the frame is orthonormal even where the caller's up was not perpendicular. */
+    u = cross(f, r);
+    const facingCos = options.facingCos ?? 0.1;
+    const offsetM = options.offsetM ?? 0.002;
+    const colour = options.color ?? [1, 1, 1];
+    const emissive = options.emissive ?? 0;
+    const specular = options.specular ?? 0;
+    const centre = options.center;
+    const positions = [];
+    const normals = [];
+    const colors = [];
+    const emissives = [];
+    const speculars = [];
+    const uvs = [];
+    const indices = [];
+    const triangles = target.indices.length / 3;
+    for (let t = 0; t < triangles; t++) {
+        const i0 = target.indices[t * 3] ?? 0;
+        const i1 = target.indices[t * 3 + 1] ?? 0;
+        const i2 = target.indices[t * 3 + 2] ?? 0;
+        /*
+         * The *geometric* normal decides whether the triangle is marked, not the shaded one. A smooth
+         * sphere's vertex normals fan out around a triangle, so a facing test on any one of them turns
+         * a decal on and off along an edge nobody can see; the plane the triangle actually lies in is
+         * the thing the projector either sees or does not.
+         */
+        const nx = geoNormal(target, i0, i1, i2, 0);
+        const ny = geoNormal(target, i0, i1, i2, 1);
+        const nz = geoNormal(target, i0, i1, i2, 2);
+        const facing = -(nx * f[0] + ny * f[1] + nz * f[2]);
+        if (facing < facingCos)
+            continue;
+        let count = 3;
+        for (let corner = 0; corner < 3; corner++) {
+            const v = corner === 0 ? i0 : corner === 1 ? i1 : i2;
+            const px = (target.positions[v * 3] ?? 0) - centre[0];
+            const py = (target.positions[v * 3 + 1] ?? 0) - centre[1];
+            const pz = (target.positions[v * 3 + 2] ?? 0) - centre[2];
+            A[corner * 6] = px * r[0] + py * r[1] + pz * r[2];
+            A[corner * 6 + 1] = px * u[0] + py * u[1] + pz * u[2];
+            A[corner * 6 + 2] = px * f[0] + py * f[1] + pz * f[2];
+            A[corner * 6 + 3] = target.normals[v * 3] ?? 0;
+            A[corner * 6 + 4] = target.normals[v * 3 + 1] ?? 0;
+            A[corner * 6 + 5] = target.normals[v * 3 + 2] ?? 0;
+        }
+        /* Sutherland–Hodgman against the six faces of the box, in the box's own space where each is a
+           comparison against a constant. */
+        let source = A;
+        let sink = B;
+        for (let axis = 0; axis < 3 && count > 0; axis++) {
+            const limit = axis === 0 ? hx : axis === 1 ? hy : hz;
+            for (const sign of [1, -1]) {
+                count = clip(source, count, sink, axis, sign, limit);
+                const swap = source;
+                source = sink;
+                sink = swap;
+                if (count === 0)
+                    break;
+            }
+        }
+        if (count < 3)
+            continue;
+        const base = positions.length / 3;
+        for (let v = 0; v < count; v++) {
+            const bx = source[v * 6] ?? 0;
+            const by = source[v * 6 + 1] ?? 0;
+            const bz = source[v * 6 + 2] ?? 0;
+            let vnx = source[v * 6 + 3] ?? 0;
+            let vny = source[v * 6 + 4] ?? 0;
+            let vnz = source[v * 6 + 5] ?? 0;
+            /* An interpolated normal is shorter than unit between two that differ. */
+            const length = Math.hypot(vnx, vny, vnz) || 1;
+            vnx /= length;
+            vny /= length;
+            vnz /= length;
+            positions.push(centre[0] + r[0] * bx + u[0] * by + f[0] * bz + vnx * offsetM, centre[1] + r[1] * bx + u[1] * by + f[1] * bz + vny * offsetM, centre[2] + r[2] * bx + u[2] * by + f[2] * bz + vnz * offsetM);
+            normals.push(vnx, vny, vnz);
+            colors.push(colour[0], colour[1], colour[2]);
+            emissives.push(emissive);
+            speculars.push(specular);
+            /* The projection is the mapping: across the box is u, up the box is v. */
+            uvs.push(bx / (hx * 2) + 0.5, by / (hy * 2) + 0.5);
+        }
+        for (let v = 2; v < count; v++)
+            indices.push(base, base + v - 1, base + v);
+    }
+    return {
+        positions: Float32Array.from(positions),
+        normals: Float32Array.from(normals),
+        colors: Float32Array.from(colors),
+        emissive: Float32Array.from(emissives),
+        specular: Float32Array.from(speculars),
+        uvs: Float32Array.from(uvs),
+        indices: Uint32Array.from(indices),
+    };
+}
+/**
+ * Keep the part of the polygon on the inside of one box face, interpolating across the crossings.
+ *
+ * Every attribute is carried through the same `t`, which is what makes a clipped normal the normal
+ * the surface had at that point rather than one of the corners'.
+ */
+function clip(source, count, sink, axis, sign, limit) {
+    let out = 0;
+    for (let i = 0; i < count; i++) {
+        const j = (i + 1) % count;
+        const di = sign * (source[i * 6 + axis] ?? 0) - limit;
+        const dj = sign * (source[j * 6 + axis] ?? 0) - limit;
+        if (di <= 0) {
+            if (out < MAX_POLYGON)
+                copy(source, i, sink, out++);
+        }
+        if (di > 0 !== dj > 0) {
+            const t = di / (di - dj);
+            if (out < MAX_POLYGON) {
+                for (let k = 0; k < 6; k++) {
+                    const a = source[i * 6 + k] ?? 0;
+                    const b = source[j * 6 + k] ?? 0;
+                    sink[out * 6 + k] = a + (b - a) * t;
+                }
+                out++;
+            }
+        }
+    }
+    return out;
+}
+function copy(source, from, sink, to) {
+    for (let k = 0; k < 6; k++)
+        sink[to * 6 + k] = source[from * 6 + k] ?? 0;
+}
+/** One component of the triangle's own plane normal, unit length. */
+function geoNormal(mesh, i0, i1, i2, component) {
+    const ax = mesh.positions[i0 * 3] ?? 0;
+    const ay = mesh.positions[i0 * 3 + 1] ?? 0;
+    const az = mesh.positions[i0 * 3 + 2] ?? 0;
+    const ux = (mesh.positions[i1 * 3] ?? 0) - ax;
+    const uy = (mesh.positions[i1 * 3 + 1] ?? 0) - ay;
+    const uz = (mesh.positions[i1 * 3 + 2] ?? 0) - az;
+    const vx = (mesh.positions[i2 * 3] ?? 0) - ax;
+    const vy = (mesh.positions[i2 * 3 + 1] ?? 0) - ay;
+    const vz = (mesh.positions[i2 * 3 + 2] ?? 0) - az;
+    const nx = uy * vz - uz * vy;
+    const ny = uz * vx - ux * vz;
+    const nz = ux * vy - uy * vx;
+    const length = Math.hypot(nx, ny, nz) || 1;
+    return (component === 0 ? nx : component === 1 ? ny : nz) / length;
+}
+function unit(v) {
+    const length = Math.hypot(v[0], v[1], v[2]) || 1;
+    return [v[0] / length, v[1] / length, v[2] / length];
+}
+function cross(a, b) {
+    return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}

package/dist/geometry/filmPatch.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A rounded, feathered patch lying on a swept surface.
+ *
+ * The shape a spill has. Not a rectangle, not a decal, not a box: an irregular
+ * lens that follows the surface's curvature and bank and dissolves at its rim.
+ *
+ * The rim is the whole reason this exists. A patch drawn with a hard edge reads as
+ * a sticker on the world no matter what material it is made of, because a real
+ * puddle is thinnest where it ends — so this emits a *coverage* value per vertex,
+ * 1 through the middle and 0 around the outside, and the film shader turns that
+ * into alpha. Geometry supplies the silhouette; the shader supplies the wetness.
+ *
+ * Textureless and engine-generic: it takes a curve, a window along it, a width and
+ * a seed, and knows nothing about oil, water or what a slick is for.
+ */
+import type { MeshData } from '../render/mesh.ts';
+import type { Spline } from './spline.ts';
+import type { Vec3 } from '../math/color.ts';
+export interface FilmPatchOptions {
+    /** Arc-length window on the curve. */
+    fromM: number;
+    toM: number;
+    /** Lateral centre and half-width, metres from the centreline. */
+    centreM: number;
+    halfWidthM: number;
+    /** Height above the surface. Small: this is a film, not a kerb. */
+    liftM: number;
+    color: Vec3;
+    /**
+     * Shape seed. Two patches with the same window and the same seed are the same
+     * patch, which is what keeps a day's world identical on every device.
+     */
+    seed: number;
+}
+export declare function buildFilmPatch(spline: Spline, options: FilmPatchOptions): MeshData;

package/dist/geometry/filmPatch.js

@@ -0,0 +1,112 @@
+import { createSplineSample } from './spline.js';
+/**
+ * Stations along the patch, and vertices across it.
+ *
+ * Nine across is what a soft rim costs: the outer pair carry zero coverage, so
+ * they contribute silhouette rather than colour, and the falloff needs a couple of
+ * rings inside them or the shoulder becomes a visible band.
+ */
+const MIN_STATIONS = 7;
+const STATION_SPACING_M = 0.7;
+const ACROSS = 9;
+/**
+ * How much the outline wanders, as a fraction of the half-width.
+ *
+ * Enough that no two slicks are the same lens and none of them looks drawn with a
+ * compass; not so much that the patch stops reading as one connected spill.
+ */
+const WOBBLE = 0.28;
+export function buildFilmPatch(spline, options) {
+    const spanM = Math.max(options.toM - options.fromM, 0.1);
+    const stations = Math.max(MIN_STATIONS, Math.ceil(spanM / STATION_SPACING_M) | 1);
+    const vertexCount = stations * ACROSS;
+    const positions = new Float32Array(vertexCount * 3);
+    const normals = new Float32Array(vertexCount * 3);
+    const colors = new Float32Array(vertexCount * 3);
+    const coverage = new Float32Array(vertexCount);
+    const indices = new Uint32Array((stations - 1) * (ACROSS - 1) * 6);
+    const sample = createSplineSample();
+    // Two incommensurable frequencies per axis, so the outline does not repeat
+    // across a long patch, and phases from the seed so each one is its own shape.
+    const phaseA = (options.seed % 1000) * 0.0063;
+    const phaseB = (options.seed % 997) * 0.0157;
+    let v = 0;
+    let i = 0;
+    for (let s = 0; s < stations; s++) {
+        // -1 at the near end, +1 at the far end.
+        const along = (s / (stations - 1)) * 2 - 1;
+        const d = options.fromM + ((along + 1) / 2) * spanM;
+        spline.sampleAt(d, sample);
+        /*
+         * An ellipse, roughened.
+         *
+         * The circular profile is what rounds the ends — a patch whose width is
+         * constant to its last station has square ends however soft its sides are.
+         */
+        const profile = Math.sqrt(Math.max(1 - along * along, 0));
+        /*
+         * The wobble only ever eats *inward*.
+         *
+         * Written first as `1 ± wobble`, which is the obvious form and is wrong: the
+         * half-width then reaches 1.28× what the caller asked for, and a caller like an
+         * oil slick has a physics window that is exactly this band. Ground that looks
+         * wet and grips normally is a lie, and ground that grips nowhere near what is
+         * drawn is worse. Subtracting keeps the silhouette inside the contract by
+         * construction rather than by a tolerance.
+         */
+        const dent = 0.6 * (0.5 + 0.5 * Math.sin(along * 3.7 + phaseA)) +
+            0.4 * (0.5 + 0.5 * Math.sin(along * 8.3 + phaseB));
+        const half = options.halfWidthM * profile * (1 - WOBBLE * dent);
+        for (let a = 0; a < ACROSS; a++) {
+            // -1 at one edge, +1 at the other.
+            const across = (a / (ACROSS - 1)) * 2 - 1;
+            const lateral = options.centreM + across * half;
+            const o = v * 3;
+            positions[o] = sample.x + sample.rightX * lateral + sample.normalX * options.liftM;
+            positions[o + 1] = sample.y + sample.rightY * lateral + sample.normalY * options.liftM;
+            positions[o + 2] = sample.z + sample.rightZ * lateral + sample.normalZ * options.liftM;
+            normals[o] = sample.normalX;
+            normals[o + 1] = sample.normalY;
+            normals[o + 2] = sample.normalZ;
+            colors[o] = options.color[0];
+            colors[o + 1] = options.color[1];
+            colors[o + 2] = options.color[2];
+            /*
+             * Coverage falls off in both directions at once, and multiplying the two is
+             * what keeps the corners honest — a patch feathered only across its width
+             * still ends in two hard lines at the ends.
+             */
+            const acrossFade = 1 - across * across;
+            const alongFade = 1 - along * along;
+            coverage[v] = Math.max(acrossFade, 0) * Math.max(alongFade, 0);
+            v++;
+        }
+        if (s === 0)
+            continue;
+        for (let a = 0; a < ACROSS - 1; a++) {
+            const here = s * ACROSS + a;
+            const back = here - ACROSS;
+            /*
+             * Wound so the patch faces *up*.
+             *
+             * The first version had every triangle facing down — measured, 224 of 224 — which under
+             * back-face culling means the slick was never drawn at all. That cost a whole session
+             * hunting the shader while looking straight at the patch: the shader was fine and the
+             * geometry was inside out.
+             *
+             * The lesson is the same one the ribbon taught, and it is why the test below measures the
+             * cross product of the triangle rather than reading `normals`: the stored normals are the
+             * *surface's*, written by hand and pointing up whatever the winding does, so asking them
+             * whether the winding is right is asking the wrong array.
+             */
+            indices[i] = back;
+            indices[i + 1] = back + 1;
+            indices[i + 2] = here;
+            indices[i + 3] = back + 1;
+            indices[i + 4] = here + 1;
+            indices[i + 5] = here;
+            i += 6;
+        }
+    }
+    return { positions, normals, colors, emissive: coverage, indices };
+}