pelican-engine 0.0.0-stage → 0.3.1

package/lib/experiments/simulation/solver.js

@@ -0,0 +1,346 @@
+import { accumulate, add, copy, cross, dot, fail, isVec3, length, mul, sub, volume, } from "./math.js";
+import { allPoints, makeScene, resolveOptions } from "./scenes.js";
+const REST_DENSITY = 1;
+const SMOOTHING_LENGTH = 0.34;
+const PRESSURE_STIFFNESS = 12;
+const VISCOSITY = 0.025;
+const LOWER = [-1.35, -1.05, -1.1];
+const UPPER = [1.35, 1.65, 1.1];
+/** Pure synchronous CPU reference solver; intentionally small O(n²) fluid neighbor search. */
+export function createSimulation(kind, options = {}) {
+    let state = makeScene(kind, resolveOptions(kind, options));
+    let disposed = false;
+    let solverWallMs = 0, measuredSteps = 0, maxStepMs = 0;
+    const alive = () => {
+        if (disposed)
+            fail("SIM_DISPOSED", "Create a new simulation before stepping, restoring, or reading geometry.");
+    };
+    function fluidData() {
+        const h2 = SMOOTHING_LENGTH ** 2;
+        const poly6 = 315 / (64 * Math.PI * SMOOTHING_LENGTH ** 9);
+        const density = state.particles.map((p) => {
+            let rho = 0;
+            for (const q of state.particles) {
+                const delta = sub(p.position, q.position), r2 = dot(delta, delta);
+                if (r2 < h2)
+                    rho += (1 / q.inverseMass) * poly6 * (h2 - r2) ** 3;
+            }
+            return rho;
+        });
+        // Weakly compressible SPH: compressive pressure only, free-surface tension omitted.
+        const pressure = density.map((rho) => PRESSURE_STIFFNESS * Math.max(0, rho - REST_DENSITY));
+        return { density, pressure };
+    }
+    function sphAccelerations() {
+        const points = state.particles;
+        const { density, pressure } = fluidData();
+        const forces = points.map(() => [0, 0, 0]);
+        const kernel = 45 / (Math.PI * SMOOTHING_LENGTH ** 6);
+        for (let i = 0; i < points.length; i++)
+            for (let j = i + 1; j < points.length; j++) {
+                const delta = sub(points[i].position, points[j].position), r = length(delta);
+                if (r >= SMOOTHING_LENGTH || r < 1e-10)
+                    continue;
+                const mi = 1 / points[i].inverseMass, mj = 1 / points[j].inverseMass;
+                const d = SMOOTHING_LENGTH - r;
+                const pressureForce = mul(delta, (mi *
+                    mj *
+                    (pressure[i] / density[i] ** 2 + pressure[j] / density[j] ** 2) *
+                    kernel *
+                    d ** 2) /
+                    r);
+                const viscousForce = mul(sub(points[j].velocity, points[i].velocity), ((VISCOSITY * mi * mj) / (density[i] * density[j])) * kernel * d);
+                const force = add(pressureForce, viscousForce);
+                // Equal-and-opposite pair forces; total internal momentum is conserved before damping/walls.
+                accumulate(forces[i], force);
+                accumulate(forces[j], force, -1);
+            }
+        return forces.map((f, i) => mul(f, points[i].inverseMass));
+    }
+    function solveDistances(h, lambdas) {
+        for (let i = 0; i < state.distances.length; i++) {
+            const c = state.distances[i], a = state.particles[c.a], b = state.particles[c.b];
+            const delta = sub(a.position, b.position), r = length(delta);
+            if (r < 1e-12)
+                continue;
+            const alpha = c.compliance / (h * h), denom = a.inverseMass + b.inverseMass + alpha;
+            if (denom === 0)
+                continue;
+            const dl = (-(r - c.restLength) - alpha * lambdas[i]) / denom;
+            lambdas[i] += dl;
+            accumulate(a.position, delta, (a.inverseMass * dl) / r);
+            accumulate(b.position, delta, (-b.inverseMass * dl) / r);
+        }
+    }
+    function solveVolumes(h, lambdas) {
+        for (let i = 0; i < state.volumes.length; i++) {
+            const c = state.volumes[i], p = c.indices.map((index) => state.particles[index]);
+            const [a, b, d, e] = p.map((point) => point.position);
+            const g1 = mul(cross(sub(d, a), sub(e, a)), 1 / 6);
+            const g2 = mul(cross(sub(e, a), sub(b, a)), 1 / 6);
+            const g3 = mul(cross(sub(b, a), sub(d, a)), 1 / 6);
+            const gradients = [mul(add(add(g1, g2), g3), -1), g1, g2, g3];
+            const alpha = c.compliance / (h * h);
+            const denom = p.reduce((sum, point, k) => sum + point.inverseMass * dot(gradients[k], gradients[k]), alpha);
+            if (denom < 1e-20)
+                continue;
+            const dl = (-(volume(a, b, d, e) - c.restVolume) - alpha * lambdas[i]) / denom;
+            lambdas[i] += dl;
+            for (let k = 0; k < 4; k++)
+                accumulate(p[k].position, gradients[k], p[k].inverseMass * dl);
+        }
+    }
+    function solveContacts(h) {
+        if (!state.options.contacts)
+            return;
+        for (const body of state.bodies)
+            for (const p of state.particles) {
+                if (p.inverseMass === 0)
+                    continue;
+                const delta = sub(p.position, body.position), r = length(delta), penetration = body.radius + p.radius - r;
+                if (penetration <= 0)
+                    continue;
+                const normal = r > 1e-12 ? mul(delta, 1 / r) : [1, 0, 0];
+                const bodyWeight = state.options.twoWayCoupling ? body.inverseMass : 0;
+                const weight = p.inverseMass + bodyWeight;
+                accumulate(p.position, normal, (penetration * p.inverseMass) / weight);
+                accumulate(body.position, normal, (-penetration * bodyWeight) / weight);
+                state.counters.contactCount++;
+                state.counters.maxContactCorrection = Math.max(state.counters.maxContactCorrection, penetration);
+                if (bodyWeight > 0) {
+                    const impulse = mul(normal, -penetration / (weight * h));
+                    accumulate(state.counters.reactionImpulse, impulse);
+                    state.counters.absoluteReactionImpulse += length(impulse);
+                }
+            }
+    }
+    function constrainWalls(p) {
+        if (p.inverseMass === 0)
+            return;
+        for (let k = 0; k < 3; k++)
+            p.position[k] = Math.max(LOWER[k] + p.radius, Math.min(UPPER[k] - p.radius, p.position[k]));
+    }
+    function substep(h) {
+        const points = allPoints(state), oldPositions = points.map((p) => [...p.position]);
+        const fluid = kind === "fluid" ? sphAccelerations() : null;
+        for (let i = 0; i < points.length; i++) {
+            const p = points[i];
+            if (p.inverseMass === 0)
+                continue;
+            accumulate(p.velocity, state.options.gravity, h);
+            if (fluid && i >= state.bodies.length)
+                accumulate(p.velocity, fluid[i - state.bodies.length], h);
+            // Explicitly dissipative reference model, not an energy-conserving integrator.
+            p.velocity = mul(p.velocity, Math.exp(-(i < state.bodies.length ? 0.12 : 0.25) * h));
+            accumulate(p.position, p.velocity, h);
+        }
+        const distanceLambdas = new Float64Array(state.distances.length);
+        const volumeLambdas = new Float64Array(state.volumes.length);
+        for (let iteration = 0; iteration < state.options.iterations; iteration++) {
+            solveDistances(h, distanceLambdas);
+            solveVolumes(h, volumeLambdas);
+            solveContacts(h);
+            for (const p of points)
+                constrainWalls(p);
+        }
+        for (let i = 0; i < points.length; i++) {
+            const p = points[i];
+            if (p.inverseMass === 0)
+                continue;
+            p.velocity = mul(sub(p.position, oldPositions[i]), 1 / h);
+            state.counters.maxObservedSpeed = Math.max(state.counters.maxObservedSpeed, length(p.velocity));
+        }
+        if (points.some((p) => !isVec3(p.position) || !isVec3(p.velocity)))
+            fail("SIM_NONFINITE", `Non-finite state at tick ${state.tick}; capture the last valid snapshot and reduce the timestep or impulse.`);
+    }
+    function inspect() {
+        const points = allPoints(state);
+        let maxDistanceRelativeError = 0, maxVolumeRelativeError = 0, minSignedVolumeRatio = null;
+        for (const c of state.distances)
+            maxDistanceRelativeError = Math.max(maxDistanceRelativeError, Math.abs(length(sub(state.particles[c.a].position, state.particles[c.b].position)) - c.restLength) / c.restLength);
+        for (const c of state.volumes) {
+            const v = volume(...c.indices.map((i) => state.particles[i].position));
+            const ratio = v / c.restVolume;
+            maxVolumeRelativeError = Math.max(maxVolumeRelativeError, Math.abs(ratio - 1));
+            minSignedVolumeRatio = Math.min(minSignedVolumeRatio ?? Infinity, ratio);
+        }
+        const bounds = state.particles.length
+            ? {
+                min: [0, 1, 2].map((k) => Math.min(...state.particles.map((p) => p.position[k]))),
+                max: [0, 1, 2].map((k) => Math.max(...state.particles.map((p) => p.position[k]))),
+            }
+            : null;
+        let kineticEnergy = 0, maxSpeed = 0;
+        const momentum = [0, 0, 0];
+        for (const p of points) {
+            maxSpeed = Math.max(maxSpeed, length(p.velocity));
+            if (p.inverseMass > 0) {
+                kineticEnergy += dot(p.velocity, p.velocity) / (2 * p.inverseMass);
+                accumulate(momentum, p.velocity, 1 / p.inverseMass);
+            }
+        }
+        const f = kind === "fluid" && !disposed ? fluidData() : null;
+        return {
+            kind,
+            tick: state.tick,
+            simulatedSeconds: state.tick * state.options.fixedDt,
+            disposed,
+            finite: points.every((p) => isVec3(p.position) && isVec3(p.velocity)),
+            resources: {
+                bodies: state.bodies.length,
+                particles: state.particles.length,
+                constraints: state.distances.length + state.volumes.length,
+                triangles: state.triangles.length,
+            },
+            bodies: copy(state.bodies),
+            particleBounds: bounds,
+            maxDistanceRelativeError,
+            maxVolumeRelativeError,
+            minSignedVolumeRatio,
+            maxSpeed,
+            kineticEnergy,
+            momentum,
+            contacts: copy(state.counters),
+            fluid: f
+                ? {
+                    method: "WCSPH",
+                    restDensity: REST_DENSITY,
+                    minDensity: Math.min(...f.density),
+                    maxDensity: Math.max(...f.density),
+                    maxPressure: Math.max(...f.pressure),
+                }
+                : null,
+            timing: {
+                solverWallMs,
+                measuredSteps,
+                meanStepMs: measuredSteps ? solverWallMs / measuredSteps : 0,
+                maxStepMs,
+            },
+        };
+    }
+    return {
+        kind,
+        step(steps = 1) {
+            alive();
+            if (!Number.isInteger(steps) || steps < 0 || steps > 10000)
+                fail("SIM_STEPS", "steps must be an integer in [0,10000].");
+            for (let frame = 0; frame < steps; frame++) {
+                const start = performance.now();
+                for (let j = 0; j < state.options.substeps; j++)
+                    substep(state.options.fixedDt / state.options.substeps);
+                state.tick++;
+                const elapsed = performance.now() - start;
+                solverWallMs += elapsed;
+                measuredSteps++;
+                maxStepMs = Math.max(maxStepMs, elapsed);
+            }
+            return inspect();
+        },
+        snapshot() {
+            alive();
+            return copy(state);
+        },
+        restore(snapshot) {
+            alive();
+            state = validateSnapshot(snapshot, kind);
+            solverWallMs = 0;
+            measuredSteps = 0;
+            maxStepMs = 0;
+        },
+        inspect,
+        getRenderState() {
+            alive();
+            const renderPoint = (p) => ({
+                id: p.id,
+                position: [...p.position],
+                radius: p.radius,
+            });
+            return {
+                kind,
+                tick: state.tick,
+                bodies: state.bodies.map(renderPoint),
+                particles: state.particles.map(renderPoint),
+                links: state.distances.map((c) => [c.a, c.b]),
+                triangles: state.triangles.map((t) => [...t]),
+            };
+        },
+        applyImpulse(id, impulse) {
+            alive();
+            if (!isVec3(impulse) || impulse.some((x) => Math.abs(x) > 100))
+                fail("SIM_IMPULSE", "impulse must contain three finite components in [-100,100].");
+            const p = allPoints(state).find((point) => point.id === id);
+            if (!p)
+                fail("SIM_ENTITY", `Unknown body or particle id: ${id}`);
+            if (p.inverseMass === 0)
+                fail("SIM_PINNED", `Cannot apply an impulse to fixed anchor ${id}.`);
+            accumulate(p.velocity, impulse, p.inverseMass);
+        },
+        dispose() {
+            if (disposed)
+                return;
+            state.bodies.length = 0;
+            state.particles.length = 0;
+            state.distances.length = 0;
+            state.volumes.length = 0;
+            state.triangles.length = 0;
+            disposed = true;
+        },
+    };
+}
+/** Restore accepts only this prototype's fixed topology; validates before replacing live state. */
+function validateSnapshot(input, kind) {
+    try {
+        if (!input ||
+            input.format !== "pelican-m0-simulation" ||
+            input.version !== 1 ||
+            input.kind !== kind)
+            throw new Error("format, version, or kind mismatch");
+        if (!input.options ||
+            !isVec3(input.options.gravity) ||
+            !isVec3(input.options.bodyPosition) ||
+            !isVec3(input.options.bodyVelocity))
+            throw new Error("invalid options");
+        const expected = makeScene(kind, resolveOptions(kind, input.options));
+        if (!Number.isSafeInteger(input.tick) || input.tick < 0)
+            throw new Error("invalid tick");
+        for (const key of ["bodies", "particles"]) {
+            if (!Array.isArray(input[key]) ||
+                input[key].length !== expected[key].length)
+                throw new Error(`invalid ${key} count`);
+            input[key].forEach((p, i) => {
+                const reference = expected[key][i];
+                if (p.id !== reference.id ||
+                    p.inverseMass !== reference.inverseMass ||
+                    p.radius !== reference.radius ||
+                    !isVec3(p.position) ||
+                    !isVec3(p.velocity))
+                    throw new Error(`invalid ${key}[${i}]`);
+                if (p.inverseMass === 0 &&
+                    (JSON.stringify(p.position) !== JSON.stringify(reference.position) ||
+                        length(p.velocity) !== 0))
+                    throw new Error("anchor changed");
+            });
+        }
+        for (const key of ["distances", "volumes", "triangles"])
+            if (JSON.stringify(input[key]) !== JSON.stringify(expected[key]))
+                throw new Error(`invalid ${key} topology`);
+        const c = input.counters;
+        if (!c ||
+            !Number.isSafeInteger(c.contactCount) ||
+            c.contactCount < 0 ||
+            !isVec3(c.reactionImpulse))
+            throw new Error("invalid contact counters");
+        for (const n of [
+            c.absoluteReactionImpulse,
+            c.maxContactCorrection,
+            c.maxObservedSpeed,
+        ])
+            if (!Number.isFinite(n) || n < 0)
+                throw new Error("invalid counters");
+        // Validate the original before JSON copying, so NaN / Infinity cannot silently become null.
+        return copy({ ...input, options: expected.options });
+    }
+    catch (error) {
+        fail("SIM_SNAPSHOT", `Snapshot rejected without changing live state: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/lib/experiments/simulation/types.js

@@ -0,0 +1 @@
+export {};

package/lib/experiments/world/adapters.js

@@ -0,0 +1,30 @@
+import { clone } from "./geometry.js";
+/** Reference consumers prepare real derived data, then swap one reference synchronously. */
+export function createConsumer(name, initial, build) {
+    let current = initial;
+    return {
+        name,
+        read: () => current,
+        prepare(t) {
+            let prepared = build(t);
+            const previous = current;
+            return {
+                commit() {
+                    if (prepared === undefined)
+                        throw new Error("WORLD_PREPARED: preparation was discarded");
+                    current = prepared;
+                },
+                rollback() {
+                    current = previous;
+                    prepared = undefined;
+                },
+                discard() {
+                    prepared = undefined;
+                },
+            };
+        },
+        dispose() {
+            current = clone(initial);
+        },
+    };
+}

package/lib/experiments/world/geometry.js

@@ -0,0 +1,180 @@
+export const clone = (v) => JSON.parse(JSON.stringify(v));
+export const key = (c) => `${c[0]}:${c[1]}`;
+export const chunkId = (c) => `chunk:${key(c)}`;
+export function fail(code, message) {
+    throw new Error(`${code}: ${message}`);
+}
+export const vector = (v, length) => Array.isArray(v) &&
+    v.length === length &&
+    v.every((n) => typeof n === "number" && Number.isFinite(n));
+export const coordValid = (v) => vector(v, 2) && v.every((n) => Number.isSafeInteger(n) && Math.abs(n) <= 1e9);
+export function inside(c, config) {
+    return c.every((n, i) => n >= config.bounds.min[i] && n <= config.bounds.max[i]);
+}
+export function assertCoord(c, config) {
+    if (!coordValid(c) || !inside(c, config))
+        fail("WORLD_COORD", "Expected an integer chunk coordinate inside configured bounds.");
+}
+export function assertOrigin(o, config) {
+    if (!o ||
+        !coordValid(o.chunk) ||
+        !vector(o.offset, 3) ||
+        o.offset.some((n) => Math.abs(n) > config.chunkSize))
+        fail("WORLD_ORIGIN", "Expected a chunk coordinate and finite local offset within one chunk size.");
+}
+export function vertexKey(c, x, z, n) {
+    return key([c[0] * n + x, c[1] * n + z]);
+}
+export function baseHeight(gx, gz, seed) {
+    let h = Math.imul(gx | 0, 73856093) ^ Math.imul(gz | 0, 19349663) ^ seed;
+    h = Math.imul(h ^ (h >>> 16), 0x45d9f3b);
+    h = Math.imul(h ^ (h >>> 16), 0x45d9f3b);
+    h ^= h >>> 16;
+    return ((h >>> 0) / 4294967295 - 0.5) * 0.12;
+}
+export function buildChunk(c, version, config, edits) {
+    const n = config.cellsPerChunk, heights = [];
+    for (let z = 0; z <= n; z++)
+        for (let x = 0; x <= n; x++)
+            heights.push(edits.get(vertexKey(c, x, z, n)) ??
+                baseHeight(c[0] * n + x, c[1] * n + z, config.seed));
+    return { id: chunkId(c), coord: [...c], version, heights };
+}
+export function affectedChunks(vertex, config) {
+    const n = config.cellsPerChunk;
+    const candidates = (v) => v % n === 0 ? [v / n - 1, v / n] : [Math.floor(v / n)];
+    const result = [];
+    for (const x of candidates(vertex[0]))
+        for (const z of candidates(vertex[1]))
+            if (inside([x, z], config))
+                result.push([x, z]);
+    return result;
+}
+export function localPoint(point, origin, config) {
+    return [
+        (point.chunk[0] - origin.chunk[0]) * config.chunkSize +
+            point.local[0] -
+            origin.offset[0],
+        point.local[1] - origin.offset[1],
+        (point.chunk[1] - origin.chunk[1]) * config.chunkSize +
+            point.local[2] -
+            origin.offset[2],
+    ];
+}
+export function normalizePoint(point, config) {
+    const dx = Math.floor(point.local[0] / config.chunkSize), dz = Math.floor(point.local[2] / config.chunkSize);
+    return {
+        chunk: [point.chunk[0] + dx, point.chunk[1] + dz],
+        local: [
+            point.local[0] - dx * config.chunkSize,
+            point.local[1],
+            point.local[2] - dz * config.chunkSize,
+        ],
+    };
+}
+export function heightAt(heights, n, x, z) {
+    const ix = Math.min(n - 1, Math.max(0, Math.floor(x))), iz = Math.min(n - 1, Math.max(0, Math.floor(z)));
+    const fx = x - ix, fz = z - iz, a = iz * (n + 1) + ix;
+    const ha = heights[a], hb = heights[a + 1], hc = heights[a + n + 1], hd = heights[a + n + 2];
+    return fx + fz <= 1
+        ? ha + (hb - ha) * fx + (hc - ha) * fz
+        : hd + (hc - hd) * (1 - fx) + (hb - hd) * (1 - fz);
+}
+export function renderBuild(t) {
+    const n = t.config.cellsPerChunk, step = t.config.chunkSize / n;
+    return {
+        epoch: t.epoch,
+        origin: clone(t.origin),
+        chunks: t.chunks.map((c) => {
+            const positions = [], indices = [];
+            for (let z = 0; z <= n; z++)
+                for (let x = 0; x <= n; x++)
+                    positions.push(...localPoint({
+                        chunk: c.coord,
+                        local: [x * step, c.heights[z * (n + 1) + x], z * step],
+                    }, t.origin, t.config));
+            for (let z = 0; z < n; z++)
+                for (let x = 0; x < n; x++) {
+                    const a = z * (n + 1) + x;
+                    indices.push(a, a + n + 1, a + 1, a + 1, a + n + 1, a + n + 2);
+                }
+            return {
+                id: c.id,
+                coord: [...c.coord],
+                version: c.version,
+                positions,
+                indices,
+            };
+        }),
+    };
+}
+export function collisionBuild(t) {
+    return {
+        epoch: t.epoch,
+        origin: clone(t.origin),
+        chunks: t.chunks.map((c) => ({
+            id: c.id,
+            coord: [...c.coord],
+            version: c.version,
+            heights: [...c.heights],
+            cells: t.config.cellsPerChunk,
+            cellSize: t.config.chunkSize / t.config.cellsPerChunk,
+            offset: localPoint({ chunk: c.coord, local: [0, 0, 0] }, t.origin, t.config),
+        })),
+    };
+}
+export const navId = (a) => `${chunkId(a.chunk)}/cell:${a.cell[0]}:${a.cell[1]}`;
+export function navBuild(t) {
+    const n = t.config.cellsPerChunk, step = t.config.chunkSize / n;
+    const result = {
+        epoch: t.epoch,
+        origin: clone(t.origin),
+        versions: t.chunks.map((c) => ({ id: c.id, version: c.version })),
+        nodes: [],
+        blockedCells: 0,
+    };
+    const grid = new Map();
+    for (const c of t.chunks)
+        for (let z = 0; z < n; z++)
+            for (let x = 0; x < n; x++) {
+                const a = z * (n + 1) + x, hs = [
+                    c.heights[a],
+                    c.heights[a + 1],
+                    c.heights[a + n + 1],
+                    c.heights[a + n + 2],
+                ];
+                if (Math.max(...hs) - Math.min(...hs) > t.config.navMaxStep) {
+                    result.blockedCells++;
+                    continue;
+                }
+                const height = heightAt(c.heights, n, x + 0.5, z + 0.5);
+                const node = {
+                    id: navId({ chunk: c.coord, cell: [x, z] }),
+                    coord: [...c.coord],
+                    cell: [x, z],
+                    height,
+                    position: localPoint({
+                        chunk: c.coord,
+                        local: [(x + 0.5) * step, height, (z + 0.5) * step],
+                    }, t.origin, t.config),
+                    neighbors: [],
+                };
+                result.nodes.push(node);
+                grid.set(key([c.coord[0] * n + x, c.coord[1] * n + z]), node);
+            }
+    for (const node of result.nodes)
+        for (const [dx, dz] of [
+            [1, 0],
+            [-1, 0],
+            [0, 1],
+            [0, -1],
+        ]) {
+            const other = grid.get(key([
+                node.coord[0] * n + node.cell[0] + dx,
+                node.coord[1] * n + node.cell[1] + dz,
+            ]));
+            if (other && Math.abs(other.height - node.height) <= t.config.navMaxStep)
+                node.neighbors.push(other.id);
+        }
+    return result;
+}

package/lib/experiments/world/index.js

@@ -0,0 +1,2 @@
+export { createWorldProbe } from "./world.js";
+export { runWorldProbe } from "./probe.js";