pelican-engine 0.3.16 → 0.3.18

package/lib/simulation/cloth.js

@@ -0,0 +1,327 @@
+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, gravity = readVec(input.gravity ?? [0, -9.81, 0], "gravity");
+    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, triangles, constraints }, positions, anchors);
+}
+export class ClothSolver {
+    config;
+    positions;
+    anchors;
+    tickValue = 0;
+    disposed = false;
+    velocities;
+    forces;
+    colliders = [];
+    contacts = [];
+    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]);
+    }
+    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, 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.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();
+        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 });
+                    }
+                }
+            }
+            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.tickValue++;
+    }
+    inspect() {
+        if (this.disposed)
+            return { tick: this.tickValue, simulatedSeconds: this.tickValue * this.config.fixedDt, disposed: true, positions: [], velocities: [], triangles: [], anchors: [], contacts: [], 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,
+            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 })), 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 };
+    }
+    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 ||
+            !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.tickValue = input.tick;
+    }
+    dispose() { if (this.disposed)
+        return; this.disposed = true; this.positions = []; this.velocities = []; this.forces = []; this.colliders = []; this.contacts = []; this.anchors.clear(); }
+}

package/lib/simulation/rope-plugin.js

@@ -4,7 +4,7 @@ import { createRope } from "./rope.js";
 import { createRopeBodyCoupling, VirtualRopeSphere } from "./rope-body-coupling.js";
 const fail = (code, detail) => { throw new Error(`TC_ROPE_${code}: ${detail}`); };
 const validId = (id) => typeof id === "string" && id.trim() === id && id.length > 0 && id.length <= 128;
-function createEntry(input, fixedDt, materials, restoredSegmentMode) {
+function createEntry(input, fixedDt, materials, restoredSegmentMode, restoredSelfMode) {
     const definition = cloneSerializable(input);
     if (!definition || !validId(definition.id))
         return fail("ID", "Expected a nonempty id of at most 128 characters.");
@@ -12,6 +12,10 @@ function createEntry(input, fixedDt, materials, restoredSegmentMode) {
         return fail("AUTO_STEP", "autoStep must be a boolean.");
     if (definition.segmentCollisions !== undefined && typeof definition.segmentCollisions !== "boolean")
         return fail("SEGMENT_COLLISION", "segmentCollisions must be a boolean.");
+    if (definition.selfCollisions !== undefined && typeof definition.selfCollisions !== "boolean")
+        return fail("SELF_COLLISION", "selfCollisions must be a boolean.");
+    if (restoredSelfMode !== undefined && definition.selfCollisions !== undefined && definition.selfCollisions !== restoredSelfMode)
+        return fail("SNAPSHOT", "Self collision configuration does not match the saved solver.");
     if (restoredSegmentMode !== undefined && definition.segmentCollisions !== undefined && definition.segmentCollisions !== restoredSegmentMode)
         return fail("SNAPSHOT", "Segment collision configuration does not match the saved solver.");
     if (definition.fixedDt !== undefined && definition.fixedDt !== fixedDt)
@@ -44,7 +48,8 @@ function createEntry(input, fixedDt, materials, restoredSegmentMode) {
             entities.add(binding.entity);
         }
     }
-    const solver = createRope({ ...definition, fixedDt, ...(restoredSegmentMode === undefined ? {} : { segmentCollisions: restoredSegmentMode }) });
+    const solver = createRope({ ...definition, fixedDt, ...(restoredSegmentMode === undefined ? {} : { segmentCollisions: restoredSegmentMode }),
+        ...(restoredSelfMode === undefined ? {} : { selfCollisions: restoredSelfMode }) });
     return { definition, solver, bodyRefs: new Map(), staleBodies: new Set() };
 }
 function disposeEntries(entries) {
@@ -63,8 +68,11 @@ function parseSnapshot(value, fixedDt, materials) {
             const savedSegmentMode = item.state?.config?.segmentCollisions;
             if (savedSegmentMode !== undefined && typeof savedSegmentMode !== "boolean")
                 fail("SNAPSHOT", "Invalid segment collision configuration.");
-            // Snapshots made before segment contacts represent particle-only behavior.
-            const entry = createEntry(item.definition, fixedDt, materials, savedSegmentMode ?? false);
+            const savedSelfMode = item.state?.config?.selfCollisions;
+            if (savedSelfMode !== undefined && typeof savedSelfMode !== "boolean")
+                fail("SNAPSHOT", "Invalid self collision configuration.");
+            // Missing flags in historical snapshots preserve their original disabled modes.
+            const entry = createEntry(item.definition, fixedDt, materials, savedSegmentMode ?? false, savedSelfMode ?? false);
             if (entries.has(entry.definition.id)) {
                 entry.solver.dispose();
                 fail("SNAPSHOT", "Duplicate rope id.");

package/lib/simulation/rope-self-collision.js

@@ -0,0 +1,102 @@
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+const clamp = (value) => Math.max(0, Math.min(1, value));
+const fail = (message) => { throw new Error(`ROPE_NUMERIC: ${message}`); };
+/** Closest points of finite line segments; handles collapsed and near-parallel links. */
+function closest(a, b, c, d) {
+    const u = sub(b, a), v = sub(d, c), w = sub(a, c);
+    const uu = dot(u, u), vv = dot(v, v), uv = dot(u, v), uw = dot(u, w), vw = dot(v, w);
+    let first = 0, second = 0;
+    if (uu <= 1e-24 && vv <= 1e-24) { /* both points */ }
+    else if (uu <= 1e-24)
+        second = clamp(vw / vv);
+    else if (vv <= 1e-24)
+        first = clamp(-uw / uu);
+    else {
+        const denominator = uu * vv - uv * uv;
+        if (denominator > 1e-12 * uu * vv)
+            first = clamp((uv * vw - uw * vv) / denominator);
+        second = (uv * first + vw) / vv;
+        if (second < 0) {
+            second = 0;
+            first = clamp(-uw / uu);
+        }
+        else if (second > 1) {
+            second = 1;
+            first = clamp((uv - uw) / uu);
+        }
+    }
+    const firstPoint = [a[0] + u[0] * first, a[1] + u[1] * first, a[2] + u[2] * first];
+    const secondPoint = [c[0] + v[0] * second, c[1] + v[1] * second, c[2] + v[2] * second];
+    if (![first, second, ...firstPoint, ...secondPoint].every(Number.isFinite))
+        fail("self-contact closest point is not finite");
+    return { first, second, firstPoint, secondPoint };
+}
+function fallbackNormal(firstDirection, secondDirection) {
+    let normal = cross(firstDirection, secondDirection), magnitude = Math.hypot(...normal);
+    if (magnitude < 1e-12) {
+        const direction = dot(firstDirection, firstDirection) >= dot(secondDirection, secondDirection) ? firstDirection : secondDirection;
+        const [x, y, z] = direction.map(Math.abs);
+        const axis = x <= y && x <= z ? [1, 0, 0] : y <= z ? [0, 1, 0] : [0, 0, 1];
+        normal = cross(direction, axis);
+        magnitude = Math.hypot(...normal);
+    }
+    return magnitude < 1e-12 ? [1, 0, 0] : [normal[0] / magnitude, normal[1] / magnitude, normal[2] / magnitude];
+}
+/** Sweep-and-prune broadphase followed by discrete capsule-segment projection.
+ * Bounds are rebuilt each iteration; contacts created by a correction may wait for the next pass.
+ * Adjacent segments are excluded. The caller owns rollback for these temporary positions. */
+export function resolveRopeSelfCollisions(positions, anchors, radius, tick, contacts) {
+    if (positions.some(point => point.some(value => !Number.isFinite(value) || Math.abs(value) > 1e6)))
+        fail("particle position exceeded finite bounds before self-contact");
+    const bounds = [];
+    for (let index = 0; index < positions.length - 1; index++) {
+        const a = positions[index], b = positions[index + 1];
+        bounds.push({ index, minX: Math.min(a[0], b[0]) - radius, maxX: Math.max(a[0], b[0]) + radius,
+            minY: Math.min(a[1], b[1]) - radius, maxY: Math.max(a[1], b[1]) + radius,
+            minZ: Math.min(a[2], b[2]) - radius, maxZ: Math.max(a[2], b[2]) + radius });
+    }
+    bounds.sort((a, b) => a.minX - b.minX || a.index - b.index);
+    for (let left = 0; left < bounds.length; left++) {
+        const x = bounds[left];
+        for (let right = left + 1; right < bounds.length && bounds[right].minX <= x.maxX; right++) {
+            const y = bounds[right];
+            if (Math.abs(x.index - y.index) <= 1 || x.minY > y.maxY || y.minY > x.maxY || x.minZ > y.maxZ || y.minZ > x.maxZ)
+                continue;
+            const firstSegment = Math.min(x.index, y.index), secondSegment = Math.max(x.index, y.index);
+            const a = positions[firstSegment], b = positions[firstSegment + 1], c = positions[secondSegment], d = positions[secondSegment + 1];
+            const contact = closest(a, b, c, d), delta = sub(contact.firstPoint, contact.secondPoint), distance = Math.hypot(...delta);
+            const penetration = 2 * radius - distance;
+            if (!Number.isFinite(penetration))
+                fail("self-contact penetration is not finite");
+            if (penetration <= 0)
+                continue;
+            const normal = distance < 1e-12 ? fallbackNormal(sub(b, a), sub(d, c)) : [delta[0] / distance, delta[1] / distance, delta[2] / distance];
+            const indices = [firstSegment, firstSegment + 1, secondSegment, secondSegment + 1];
+            const gradients = [1 - contact.first, contact.first, -(1 - contact.second), -contact.second]
+                .map((weight, index) => anchors.has(indices[index]) ? 0 : weight);
+            const weight = gradients.reduce((sum, value) => sum + value * value, 0);
+            if (weight === 0)
+                continue; // four immovable endpoints cannot be projected
+            const magnitude = penetration / weight;
+            if (!Number.isFinite(magnitude))
+                fail("self-contact projection exceeded finite bounds");
+            for (let i = 0; i < 4; i++)
+                for (let axis = 0; axis < 3; axis++) {
+                    const value = positions[indices[i]][axis] + normal[axis] * magnitude * gradients[i];
+                    if (!Number.isFinite(value) || Math.abs(value) > 1e6)
+                        fail("self-contact correction exceeded finite bounds");
+                    positions[indices[i]][axis] = value;
+                }
+            const key = `${firstSegment}:${secondSegment}`, existing = contacts.get(key);
+            if (existing) {
+                existing.penetration = Math.max(existing.penetration, penetration);
+                existing.firstFraction = contact.first;
+                existing.secondFraction = contact.second;
+            }
+            else
+                contacts.set(key, { tick, firstSegment, secondSegment, firstFraction: contact.first, secondFraction: contact.second, penetration });
+        }
+    }
+}

package/lib/simulation/rope.js

@@ -1,3 +1,4 @@
+import { resolveRopeSelfCollisions } from "./rope-self-collision.js";
 export class RopeError extends Error {
     code;
     constructor(code, message) {
@@ -74,6 +75,9 @@ export function createRope(options) {
     if (options.segmentCollisions !== undefined && typeof options.segmentCollisions !== "boolean")
         fail("ROPE_INPUT", "segmentCollisions must be boolean");
     const segmentCollisions = options.segmentCollisions ?? true;
+    if (options.selfCollisions !== undefined && typeof options.selfCollisions !== "boolean")
+        fail("ROPE_INPUT", "selfCollisions must be boolean");
+    const selfCollisions = options.selfCollisions ?? true;
     const fixedDt = positive(options.fixedDt ?? 1 / 60, "fixedDt");
     if (fixedDt < 1 / 1000 || fixedDt > 1 / 30)
         fail("ROPE_INPUT", "fixedDt must be in [1/1000, 1/30]");
@@ -88,7 +92,7 @@ export function createRope(options) {
     const anchors = readAnchors(options.anchors ?? [{ index: 0, position: positions[0] }], positions.length);
     for (const [i, p] of anchors)
         positions[i] = copy(p);
-    return new RopeSolver({ mass, radius, fixedDt, substeps, iterations, damping, gravity, restLengths, segmentCollisions }, positions, anchors);
+    return new RopeSolver({ mass, radius, fixedDt, substeps, iterations, damping, gravity, restLengths, segmentCollisions, selfCollisions }, positions, anchors);
 }
 export class RopeSolver {
     config;
@@ -101,6 +105,7 @@ export class RopeSolver {
     colliders = [];
     contacts = [];
     segmentContacts = [];
+    selfContacts = [];
     constructor(config, positions, anchors) {
         this.config = config;
         this.positions = positions;
@@ -163,6 +168,7 @@ export class RopeSolver {
             forces: this.forces,
             contacts: this.contacts,
             segmentContacts: this.segmentContacts,
+            selfContacts: this.selfContacts,
             tick: this.tickValue,
         };
         try {
@@ -175,6 +181,7 @@ export class RopeSolver {
             this.forces = before.forces;
             this.contacts = before.contacts;
             this.segmentContacts = before.segmentContacts;
+            this.selfContacts = before.selfContacts;
             this.tickValue = before.tick;
             throw error;
         }
@@ -187,6 +194,7 @@ export class RopeSolver {
         const positions = this.positions.map(copy), velocities = this.velocities.map(copy);
         const contacts = new Map();
         const segmentContacts = new Map();
+        const selfContacts = new Map();
         const spheres = this.config.segmentCollisions ? this.colliders.filter((collider) => collider.kind === "sphere") : [];
         for (let sub = 0; sub < substeps; sub++) {
             const previous = positions.map(copy);
@@ -357,6 +365,8 @@ export class RopeSolver {
                             segmentContacts.set(key, { tick: this.tickValue + 1, segment: j, colliderId: collider.id, fraction, penetration: depth, reactionImpulse: reaction, reactionAngularImpulse: moment });
                     }
                 }
+                if (this.config.selfCollisions && positions.length >= 4)
+                    resolveRopeSelfCollisions(positions, this.anchors, radius, this.tickValue + 1, selfContacts);
             }
             for (let i = 0; i < positions.length; i++) {
                 if (this.anchors.has(i))
@@ -372,22 +382,23 @@ export class RopeSolver {
         this.forces = positions.map(() => [0, 0, 0]);
         this.contacts = [...contacts.values()];
         this.segmentContacts = [...segmentContacts.values()];
+        this.selfContacts = [...selfContacts.values()];
         this.tickValue++;
     }
     /** Detached positions for renderer synchronization without copying contact state. */
     particlePositions() { this.alive(); return this.positions.map(copy); }
     inspect() {
         if (this.disposedValue)
-            return { tick: this.tickValue, simulatedSeconds: this.tickValue * this.config.fixedDt, disposed: true, segmentCollisions: this.config.segmentCollisions, positions: [], velocities: [], anchors: [], contacts: [], segmentContacts: [], maxDistanceError: 0, resources: { particles: 0, constraints: 0, anchors: 0, colliders: 0 } };
+            return { tick: this.tickValue, simulatedSeconds: this.tickValue * this.config.fixedDt, disposed: true, segmentCollisions: this.config.segmentCollisions, selfCollisions: this.config.selfCollisions, positions: [], velocities: [], anchors: [], contacts: [], segmentContacts: [], selfContacts: [], maxDistanceError: 0, resources: { particles: 0, constraints: 0, anchors: 0, colliders: 0 } };
         const maxDistanceError = Math.max(0, ...this.config.restLengths.map((d, i) => {
             const a = this.positions[i], b = this.positions[i + 1];
             return Math.abs(Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]) - d);
         }));
         return {
-            tick: this.tickValue, simulatedSeconds: this.tickValue * this.config.fixedDt, disposed: false, segmentCollisions: this.config.segmentCollisions,
+            tick: this.tickValue, simulatedSeconds: this.tickValue * this.config.fixedDt, disposed: false, segmentCollisions: this.config.segmentCollisions, selfCollisions: this.config.selfCollisions,
             positions: this.positions.map(copy), velocities: this.velocities.map(copy),
             anchors: [...this.anchors].map(([index, position]) => ({ index, position: copy(position) })).sort((a, b) => a.index - b.index),
-            contacts: this.contacts.map(copyContact), segmentContacts: this.segmentContacts.map(copySegmentContact), maxDistanceError,
+            contacts: this.contacts.map(copyContact), segmentContacts: this.segmentContacts.map(copySegmentContact), selfContacts: this.selfContacts.map(contact => ({ ...contact })), maxDistanceError,
             resources: { particles: this.positions.length, constraints: this.config.restLengths.length, anchors: this.anchors.size, colliders: this.colliders.length },
         };
     }
@@ -398,7 +409,7 @@ export class RopeSolver {
             format: "pelican-rope-cpu", version: 1, tick: this.tickValue,
             config: { ...this.config, gravity: copy(this.config.gravity), restLengths: [...this.config.restLengths] },
             positions: state.positions, velocities: state.velocities, anchors: state.anchors,
-            forces: this.forces.map(copy), colliders: readColliders(this.colliders), contacts: state.contacts, segmentContacts: state.segmentContacts,
+            forces: this.forces.map(copy), colliders: readColliders(this.colliders), contacts: state.contacts, segmentContacts: state.segmentContacts, selfContacts: state.selfContacts,
         };
     }
     /** Accepts a JSON-round-tripped snapshot only from the same rope configuration. Atomic on failure. */
@@ -411,6 +422,7 @@ export class RopeSolver {
         if (!c || c.mass !== this.config.mass || c.radius !== this.config.radius || c.fixedDt !== this.config.fixedDt ||
             c.substeps !== this.config.substeps || c.iterations !== this.config.iterations || c.damping !== this.config.damping ||
             (c.segmentCollisions !== undefined && typeof c.segmentCollisions !== "boolean") || (c.segmentCollisions ?? false) !== this.config.segmentCollisions ||
+            (c.selfCollisions !== undefined && typeof c.selfCollisions !== "boolean") || (c.selfCollisions ?? false) !== this.config.selfCollisions ||
             !vec(c.gravity) || c.gravity.some((v, i) => v !== this.config.gravity[i]) ||
             !Array.isArray(c.restLengths) || c.restLengths.length !== this.config.restLengths.length ||
             c.restLengths.some((v, i) => v !== this.config.restLengths[i]))
@@ -448,6 +460,23 @@ export class RopeSolver {
                 fail("ROPE_SNAPSHOT", "duplicate segment contact");
             segmentKeys.add(key);
         }
+        const self = input.selfContacts === undefined ? [] : input.selfContacts;
+        const maxSelfContacts = Math.max(0, (count - 2) * (count - 3) / 2);
+        if (!Array.isArray(self) || self.length > maxSelfContacts || (!this.config.selfCollisions && self.length > 0) ||
+            self.some(contact => !contact || contact.tick !== input.tick ||
+                !Number.isSafeInteger(contact.firstSegment) || !Number.isSafeInteger(contact.secondSegment) ||
+                contact.firstSegment < 0 || contact.secondSegment >= count - 1 || contact.secondSegment - contact.firstSegment <= 1 ||
+                typeof contact.firstFraction !== "number" || !Number.isFinite(contact.firstFraction) || contact.firstFraction < 0 || contact.firstFraction > 1 ||
+                typeof contact.secondFraction !== "number" || !Number.isFinite(contact.secondFraction) || contact.secondFraction < 0 || contact.secondFraction > 1 ||
+                typeof contact.penetration !== "number" || !Number.isFinite(contact.penetration) || contact.penetration <= 0))
+            fail("ROPE_SNAPSHOT", "invalid self contact state");
+        const selfKeys = new Set();
+        for (const contact of self) {
+            const key = `${contact.firstSegment}:${contact.secondSegment}`;
+            if (selfKeys.has(key))
+                fail("ROPE_SNAPSHOT", "duplicate self contact");
+            selfKeys.add(key);
+        }
         this.positions = input.positions.map(copy);
         this.velocities = input.velocities.map(copy);
         this.forces = input.forces.map(copy);
@@ -455,6 +484,7 @@ export class RopeSolver {
         this.colliders = colliders;
         this.contacts = input.contacts.map(copyContact);
         this.segmentContacts = segments.map(copySegmentContact);
+        this.selfContacts = self.map(contact => ({ ...contact }));
         this.tickValue = input.tick;
     }
     dispose() {
@@ -467,6 +497,7 @@ export class RopeSolver {
         this.colliders = [];
         this.contacts = [];
         this.segmentContacts = [];
+        this.selfContacts = [];
         this.anchors.clear();
     }
 }

package/package.json

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