pelican-engine 0.3.17 → 0.3.19

package/lib/simulation/cloth.js

@@ -0,0 +1,358 @@
+export class ClothError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.name = "ClothError";
+    }
+}
+const fail = (code, message) => { throw new ClothError(code, message); };
+const vec = (input) => Array.isArray(input) && input.length === 3 && input.every(value => typeof value === "number" && Number.isFinite(value) && Math.abs(value) <= 1e6);
+const copy = (value) => [value[0], value[1], value[2]];
+const readVec = (input, label) => vec(input) ? copy(input) : fail("CLOTH_INPUT", `${label} must be a finite 3D vector with component magnitude <= 1e6`);
+const positive = (input, label) => typeof input === "number" && Number.isFinite(input) && input > 0 && input <= 1e6 ? input : fail("CLOTH_INPUT", `${label} must be positive and <= 1e6`);
+const indexOf = (input, count) => Number.isSafeInteger(input) && input >= 0 && input < count ? input : fail("CLOTH_INDEX", "particle index is out of range");
+const distance = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+const tuple = (a) => [a[0], a[1], a[2]];
+function readAnchors(input, count) {
+    if (!Array.isArray(input) || input.length > count)
+        fail("CLOTH_INPUT", "anchors must be an array of unique particle indices");
+    const result = new Map();
+    for (const anchor of input) {
+        if (!anchor || typeof anchor !== "object")
+            fail("CLOTH_INPUT", "invalid anchor");
+        const index = indexOf(anchor.index, count);
+        if (result.has(index))
+            fail("CLOTH_INPUT", "duplicate anchor index");
+        result.set(index, readVec(anchor.position, "anchor position"));
+    }
+    return result;
+}
+function readColliders(input) {
+    if (!Array.isArray(input) || input.length > 4096)
+        fail("CLOTH_INPUT", "colliders must be an array of at most 4096 items");
+    const ids = new Set();
+    return input.map(collider => {
+        if (!collider || typeof collider !== "object" || typeof collider.id !== "string" || !collider.id || ids.has(collider.id))
+            fail("CLOTH_INPUT", "collider ids must be unique nonempty strings");
+        ids.add(collider.id);
+        if (collider.kind === "sphere")
+            return { kind: "sphere", id: collider.id, center: readVec(collider.center, "sphere center"), radius: positive(collider.radius, "sphere radius") };
+        if (collider.kind === "plane") {
+            const normal = readVec(collider.normal, "plane normal"), magnitude = Math.hypot(...normal);
+            if (Math.abs(magnitude - 1) > 1e-6 || typeof collider.offset !== "number" || !Number.isFinite(collider.offset) || Math.abs(collider.offset) > 1e6)
+                fail("CLOTH_INPUT", "plane requires a unit normal and finite offset with magnitude <= 1e6");
+            return { kind: "plane", id: collider.id, normal, offset: collider.offset };
+        }
+        return fail("CLOTH_INPUT", "unsupported collider kind");
+    });
+}
+function topology(points, input, bending) {
+    if (!Array.isArray(input) || input.length < 1 || input.length > 8192)
+        fail("CLOTH_INPUT", "triangles must contain 1..8192 faces");
+    const triangles = [], faces = new Set();
+    const edges = new Map();
+    for (const raw of input) {
+        if (!Array.isArray(raw) || raw.length !== 3)
+            fail("CLOTH_INPUT", "triangle must contain three particle indices");
+        const [a, b, c] = raw.map(value => indexOf(value, points.length));
+        if (a === b || b === c || a === c)
+            fail("CLOTH_INPUT", "triangle indices must be distinct");
+        const key = [a, b, c].sort((x, y) => x - y).join(":");
+        if (faces.has(key))
+            fail("CLOTH_INPUT", "duplicate triangle");
+        faces.add(key);
+        const u = [points[b][0] - points[a][0], points[b][1] - points[a][1], points[b][2] - points[a][2]];
+        const v = [points[c][0] - points[a][0], points[c][1] - points[a][1], points[c][2] - points[a][2]];
+        if (Math.hypot(u[1] * v[2] - u[2] * v[1], u[2] * v[0] - u[0] * v[2], u[0] * v[1] - u[1] * v[0]) <= 1e-10)
+            fail("CLOTH_INPUT", "initial triangle area must be nonzero");
+        triangles.push([a, b, c]);
+        for (const [from, to, opposite] of [[a, b, c], [b, c, a], [c, a, b]]) {
+            const low = Math.min(from, to), high = Math.max(from, to), edgeKey = `${low}:${high}`;
+            const edge = edges.get(edgeKey) ?? { a: low, b: high, opposite: [], directions: [] };
+            edge.opposite.push(opposite);
+            edge.directions.push(from === low ? 1 : -1);
+            if (edge.opposite.length > 2 || (edge.opposite.length === 2 && edge.directions[0] === edge.directions[1]))
+                fail("CLOTH_INPUT", "shared edges require manifold faces with consistent winding");
+            edges.set(edgeKey, edge);
+        }
+    }
+    const constraints = [], seen = new Set();
+    const add = (a, b) => {
+        const low = Math.min(a, b), high = Math.max(a, b), key = `${low}:${high}`;
+        if (seen.has(key))
+            return;
+        const rest = distance(points[low], points[high]);
+        if (!Number.isFinite(rest) || rest <= 1e-8)
+            fail("CLOTH_INPUT", "constraint endpoints must be distinct");
+        seen.add(key);
+        constraints.push([low, high, rest]);
+    };
+    for (const edge of edges.values())
+        add(edge.a, edge.b);
+    if (bending)
+        for (const edge of edges.values())
+            if (edge.opposite.length === 2)
+                add(edge.opposite[0], edge.opposite[1]);
+    return { triangles, constraints };
+}
+export function createCloth(input) {
+    if (!input || typeof input !== "object" || !Array.isArray(input.points) || input.points.length < 3 || input.points.length > 4096)
+        fail("CLOTH_INPUT", "points must contain 3..4096 particles");
+    const positions = input.points.map((point, index) => readVec(point, `points[${index}]`));
+    const mass = positive(input.mass, "mass"), radius = positive(input.radius ?? 0.025, "radius"), fixedDt = positive(input.fixedDt ?? 1 / 60, "fixedDt");
+    if (fixedDt < 1 / 1000 || fixedDt > 1 / 30)
+        fail("CLOTH_INPUT", "fixedDt must be in [1/1000, 1/30]");
+    const substeps = input.substeps ?? 4, iterations = input.iterations ?? 12, damping = input.damping ?? 0.15;
+    if (!Number.isInteger(substeps) || substeps < 1 || substeps > 32 || !Number.isInteger(iterations) || iterations < 1 || iterations > 64)
+        fail("CLOTH_INPUT", "substeps and iterations are outside their supported bounds");
+    if (typeof damping !== "number" || !Number.isFinite(damping) || damping < 0 || damping > 100)
+        fail("CLOTH_INPUT", "damping must be in [0,100]");
+    if (input.bending !== undefined && typeof input.bending !== "boolean")
+        fail("CLOTH_INPUT", "bending must be boolean");
+    const bending = input.bending ?? true, selfCollisions = input.selfCollisions ?? true, gravity = readVec(input.gravity ?? [0, -9.81, 0], "gravity");
+    if (typeof selfCollisions !== "boolean")
+        fail("CLOTH_INPUT", "selfCollisions must be boolean");
+    const { triangles, constraints } = topology(positions, input.triangles, bending);
+    const anchors = readAnchors(input.anchors ?? [], positions.length);
+    for (const [index, point] of anchors)
+        positions[index] = copy(point);
+    return new ClothSolver({ mass, radius, fixedDt, substeps, iterations, damping, gravity, bending, selfCollisions, triangles, constraints }, positions, anchors);
+}
+export class ClothSolver {
+    config;
+    positions;
+    anchors;
+    tickValue = 0;
+    disposed = false;
+    velocities;
+    forces;
+    colliders = [];
+    contacts = [];
+    selfContacts = [];
+    adjacent;
+    constructor(config, positions, anchors) {
+        this.config = config;
+        this.positions = positions;
+        this.anchors = anchors;
+        this.velocities = positions.map(() => [0, 0, 0]);
+        this.forces = positions.map(() => [0, 0, 0]);
+        this.adjacent = new Set(config.triangles.flatMap(([a, b, c]) => [`${Math.min(a, b)}:${Math.max(a, b)}`, `${Math.min(b, c)}:${Math.max(b, c)}`, `${Math.min(c, a)}:${Math.max(c, a)}`]));
+    }
+    alive() { if (this.disposed)
+        fail("CLOTH_DISPOSED", "cloth has been disposed"); }
+    setColliders(input) { this.alive(); this.colliders = readColliders(input); this.contacts = []; }
+    setAnchor(index, position) {
+        this.alive();
+        const i = indexOf(index, this.positions.length), p = readVec(position, "anchor position");
+        this.anchors.set(i, p);
+        this.positions[i] = copy(p);
+        this.velocities[i] = [0, 0, 0];
+        this.forces[i] = [0, 0, 0];
+    }
+    releaseAnchor(index) { this.alive(); this.anchors.delete(indexOf(index, this.positions.length)); }
+    applyForce(index, input) {
+        this.alive();
+        const i = indexOf(index, this.positions.length), force = readVec(input, "force");
+        if (this.anchors.has(i))
+            fail("CLOTH_ANCHORED", "cannot apply force to an anchor");
+        const next = [0, 1, 2].map(axis => this.forces[i][axis] + force[axis]);
+        if (!vec(next))
+            fail("CLOTH_NUMERIC", "force accumulation exceeded bounds");
+        this.forces[i] = next;
+    }
+    applyImpulse(index, input) {
+        this.alive();
+        const i = indexOf(index, this.positions.length), impulse = readVec(input, "impulse");
+        if (this.anchors.has(i))
+            fail("CLOTH_ANCHORED", "cannot apply impulse to an anchor");
+        const next = [0, 1, 2].map(axis => this.velocities[i][axis] + impulse[axis] / this.config.mass);
+        if (!vec(next))
+            fail("CLOTH_NUMERIC", "impulse exceeded bounds");
+        this.velocities[i] = next;
+    }
+    /** A failed batch restores its pre-batch state. */
+    step(steps = 1) {
+        this.alive();
+        if (!Number.isSafeInteger(steps) || steps < 1 || steps > 1000 || this.tickValue + steps > Number.MAX_SAFE_INTEGER)
+            fail("CLOTH_INPUT", "steps must be in [1,1000] without tick overflow");
+        const before = { positions: this.positions, velocities: this.velocities, forces: this.forces, contacts: this.contacts, selfContacts: this.selfContacts, tick: this.tickValue };
+        try {
+            for (let i = 0; i < steps; i++)
+                this.stepOne();
+        }
+        catch (error) {
+            this.positions = before.positions;
+            this.velocities = before.velocities;
+            this.forces = before.forces;
+            this.contacts = before.contacts;
+            this.selfContacts = before.selfContacts;
+            this.tickValue = before.tick;
+            throw error;
+        }
+        return this.inspect();
+    }
+    stepOne() {
+        const { fixedDt, substeps, iterations, mass, gravity, damping, constraints, radius } = this.config;
+        const h = fixedDt / substeps, decay = Math.exp(-damping * h);
+        const positions = this.positions.map(copy), velocities = this.velocities.map(copy), contacts = new Map(), selfContacts = new Map();
+        for (let sub = 0; sub < substeps; sub++) {
+            const previous = positions.map(copy);
+            for (let i = 0; i < positions.length; i++) {
+                const anchor = this.anchors.get(i);
+                if (anchor) {
+                    positions[i] = copy(anchor);
+                    velocities[i] = [0, 0, 0];
+                    continue;
+                }
+                for (let k = 0; k < 3; k++) {
+                    velocities[i][k] = velocities[i][k] * decay + (gravity[k] + this.forces[i][k] / mass) * h;
+                    positions[i][k] += velocities[i][k] * h;
+                }
+            }
+            for (let iter = 0; iter < iterations; iter++) {
+                for (const [i, j, rest] of constraints) {
+                    const a = positions[i], b = positions[j];
+                    let dx = b[0] - a[0], dy = b[1] - a[1], dz = b[2] - a[2], dist = Math.hypot(dx, dy, dz);
+                    if (dist < 1e-12) {
+                        dx = 1e-6;
+                        dy = 0;
+                        dz = 0;
+                        dist = 1e-6;
+                    }
+                    const wa = this.anchors.has(i) ? 0 : 1, wb = this.anchors.has(j) ? 0 : 1;
+                    if (wa + wb === 0)
+                        continue;
+                    const factor = (dist - rest) / (dist * (wa + wb));
+                    for (let k = 0; k < 3; k++) {
+                        const correction = (k === 0 ? dx : k === 1 ? dy : dz) * factor;
+                        a[k] += correction * wa;
+                        b[k] -= correction * wb;
+                    }
+                }
+                for (let i = 0; i < positions.length; i++) {
+                    if (this.anchors.has(i))
+                        continue;
+                    const p = positions[i];
+                    for (const collider of this.colliders) {
+                        let depth, normal;
+                        if (collider.kind === "plane") {
+                            normal = collider.normal;
+                            depth = collider.offset + radius - (p[0] * normal[0] + p[1] * normal[1] + p[2] * normal[2]);
+                        }
+                        else {
+                            const delta = [p[0] - collider.center[0], p[1] - collider.center[1], p[2] - collider.center[2]], length = Math.hypot(...delta);
+                            depth = collider.radius + radius - length;
+                            normal = length < 1e-12 ? [1, 0, 0] : [delta[0] / length, delta[1] / length, delta[2] / length];
+                        }
+                        if (depth <= 0)
+                            continue;
+                        for (let k = 0; k < 3; k++)
+                            p[k] += normal[k] * depth;
+                        const key = `${i}:${collider.id}`, old = contacts.get(key);
+                        if (old)
+                            old.penetration = Math.max(old.penetration, depth);
+                        else
+                            contacts.set(key, { tick: this.tickValue + 1, particle: i, colliderId: collider.id, penetration: depth });
+                    }
+                }
+                if (this.config.selfCollisions)
+                    for (let i = 0; i < positions.length; i++)
+                        for (let j = i + 1; j < positions.length; j++) {
+                            if (this.adjacent.has(`${i}:${j}`))
+                                continue;
+                            const a = positions[i], b = positions[j], dx = a[0] - b[0], dy = a[1] - b[1], dz = a[2] - b[2], length = Math.hypot(dx, dy, dz), depth = 2 * radius - length;
+                            if (depth <= 0)
+                                continue;
+                            const normal = length < 1e-12 ? [1, 0, 0] : [dx / length, dy / length, dz / length];
+                            const wa = this.anchors.has(i) ? 0 : 1, wb = this.anchors.has(j) ? 0 : 1;
+                            if (wa + wb === 0)
+                                continue;
+                            const correction = depth / (wa + wb);
+                            for (let axis = 0; axis < 3; axis++) {
+                                a[axis] += normal[axis] * correction * wa;
+                                b[axis] -= normal[axis] * correction * wb;
+                            }
+                            const key = `${i}:${j}`, old = selfContacts.get(key);
+                            if (old)
+                                old.penetration = Math.max(old.penetration, depth);
+                            else
+                                selfContacts.set(key, { tick: this.tickValue + 1, firstParticle: i, secondParticle: j, penetration: depth });
+                        }
+            }
+            for (let i = 0; i < positions.length; i++) {
+                if (this.anchors.has(i))
+                    continue;
+                for (let k = 0; k < 3; k++)
+                    velocities[i][k] = (positions[i][k] - previous[i][k]) / h;
+                if (!vec(positions[i]) || !vec(velocities[i]))
+                    fail("CLOTH_NUMERIC", "solver exceeded finite state bounds");
+            }
+        }
+        this.positions = positions;
+        this.velocities = velocities;
+        this.forces = positions.map(() => [0, 0, 0]);
+        this.contacts = [...contacts.values()];
+        this.selfContacts = [...selfContacts.values()];
+        this.tickValue++;
+    }
+    inspect() {
+        if (this.disposed)
+            return { tick: this.tickValue, simulatedSeconds: this.tickValue * this.config.fixedDt, disposed: true, selfCollisions: this.config.selfCollisions, positions: [], velocities: [], triangles: [], anchors: [], contacts: [], selfContacts: [], maxDistanceError: 0, resources: { particles: 0, triangles: 0, constraints: 0, anchors: 0, colliders: 0 } };
+        let maxDistanceError = 0;
+        for (const [a, b, rest] of this.config.constraints)
+            maxDistanceError = Math.max(maxDistanceError, Math.abs(distance(this.positions[a], this.positions[b]) - rest));
+        return { tick: this.tickValue, simulatedSeconds: this.tickValue * this.config.fixedDt, disposed: false, selfCollisions: this.config.selfCollisions,
+            positions: this.positions.map(copy), velocities: this.velocities.map(copy), triangles: this.config.triangles.map(tuple),
+            anchors: [...this.anchors].map(([index, position]) => ({ index, position: copy(position) })).sort((a, b) => a.index - b.index),
+            contacts: this.contacts.map(contact => ({ ...contact })), selfContacts: this.selfContacts.map(contact => ({ ...contact })), maxDistanceError,
+            resources: { particles: this.positions.length, triangles: this.config.triangles.length, constraints: this.config.constraints.length, anchors: this.anchors.size, colliders: this.colliders.length } };
+    }
+    snapshot() {
+        this.alive();
+        const state = this.inspect();
+        return { format: "pelican-cloth-cpu", version: 1, tick: this.tickValue,
+            config: { ...this.config, gravity: copy(this.config.gravity), triangles: this.config.triangles.map(tuple), constraints: this.config.constraints.map(tuple) },
+            positions: state.positions, velocities: state.velocities, forces: this.forces.map(copy), anchors: state.anchors, colliders: readColliders(this.colliders), contacts: state.contacts, selfContacts: state.selfContacts };
+    }
+    restore(input) {
+        this.alive();
+        if (!input || typeof input !== "object" || input.format !== "pelican-cloth-cpu" || input.version !== 1 || !Number.isSafeInteger(input.tick) || input.tick < 0)
+            fail("CLOTH_SNAPSHOT", "unsupported snapshot format or tick");
+        const config = input.config, expected = this.config;
+        if (!config || config.mass !== expected.mass || config.radius !== expected.radius || config.fixedDt !== expected.fixedDt || config.substeps !== expected.substeps ||
+            config.iterations !== expected.iterations || config.damping !== expected.damping || config.bending !== expected.bending || (config.selfCollisions ?? false) !== expected.selfCollisions ||
+            !vec(config.gravity) || config.gravity.some((value, i) => value !== expected.gravity[i]) ||
+            !Array.isArray(config.triangles) || JSON.stringify(config.triangles) !== JSON.stringify(expected.triangles) ||
+            !Array.isArray(config.constraints) || JSON.stringify(config.constraints) !== JSON.stringify(expected.constraints))
+            fail("CLOTH_SNAPSHOT", "cloth configuration or topology mismatch");
+        const count = this.positions.length;
+        if (!Array.isArray(input.positions) || !Array.isArray(input.velocities) || !Array.isArray(input.forces) ||
+            [input.positions, input.velocities, input.forces].some(values => values.length !== count || !values.every(vec)))
+            fail("CLOTH_SNAPSHOT", "invalid particle state");
+        const anchors = readAnchors(input.anchors, count);
+        if ([...anchors].some(([i, point]) => point.some((value, k) => value !== input.positions[i][k]) || input.velocities[i].some(value => value !== 0) || input.forces[i].some(value => value !== 0)))
+            fail("CLOTH_SNAPSHOT", "inconsistent anchored particle state");
+        const colliders = readColliders(input.colliders), keys = new Set();
+        if (!Array.isArray(input.contacts) || input.contacts.length > count * colliders.length || input.contacts.some(contact => !contact || contact.tick !== input.tick ||
+            !Number.isSafeInteger(contact.particle) || contact.particle < 0 || contact.particle >= count || !colliders.some(collider => collider.id === contact.colliderId) ||
+            typeof contact.penetration !== "number" || !Number.isFinite(contact.penetration) || contact.penetration <= 0))
+            fail("CLOTH_SNAPSHOT", "invalid contact state");
+        for (const contact of input.contacts) {
+            const key = `${contact.particle}:${contact.colliderId}`;
+            if (keys.has(key))
+                fail("CLOTH_SNAPSHOT", "duplicate contact");
+            keys.add(key);
+        }
+        this.positions = input.positions.map(copy);
+        this.velocities = input.velocities.map(copy);
+        this.forces = input.forces.map(copy);
+        this.anchors = anchors;
+        this.colliders = colliders;
+        this.contacts = input.contacts.map(contact => ({ ...contact }));
+        this.selfContacts = (input.selfContacts ?? []).map(contact => ({ ...contact }));
+        this.tickValue = input.tick;
+    }
+    dispose() { if (this.disposed)
+        return; this.disposed = true; this.positions = []; this.velocities = []; this.forces = []; this.colliders = []; this.contacts = []; this.selfContacts = []; this.anchors.clear(); }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pelican-engine",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "description": "Pelican Engine public SDK and offline development CLI",
   "type": "module",
   "license": "MIT",