pelican-engine 0.3.15 → 0.3.17

package/docs/npm/GAME-AUTHOR.md

@@ -137,6 +137,31 @@ all earlier automatic ropes from that phase; the host tick may still have other
 partial changes and must be recovered from a known-good checkpoint. The source
 checkout includes `examples/rope-particles`.
 
+New ropes resolve discrete sphere overlaps along segment interiors as well as at
+particles. Corrections are distributed to movable endpoints; a segment with two
+fixed anchors cannot move. `ctx.ropes.inspect(id).segmentContacts` reports the
+segment index, closest-point fraction and reaction impulses. Set
+`segmentCollisions: false` to retain particle-only behavior. Historical rope
+solver snapshots without this field retain particle-only behavior when migrated;
+`inspect(id).segmentCollisions` reports the active mode. Normal Host snapshot
+engine-version restrictions still apply. Plane contacts use particle endpoints.
+The segment index names its first particle; `fraction` runs toward the next.
+Work increases with segment, sphere, substep and iteration counts. This does not
+provide continuous collision detection; the segment solver and snapshot migration
+have not been runtime validated.
+
+New ropes also resolve discrete self-contact between non-adjacent segments using
+sweep-and-prune and endpoint projection. `inspect(id).selfContacts` reports
+segment indices, closest-point fractions and maximum overlap; `selfCollisions`
+reports the active mode. Set `selfCollisions: false` to disable it. Adjacent
+segments and collisions between separate ropes are not handled. Immovable anchored
+endpoints stay fixed, and contacts introduced by corrections can wait until the
+next iteration. Dense overlap can approach quadratic work. Snapshots from before
+this feature retain the disabled mode when migrated; Host engine-version rules
+still apply. This is unverified discrete contact, not a guarantee against
+penetration, continuous collision, friction or full rope physics. The source
+checkout includes `examples/rope-self`.
+
 For optional visual presentation, declare a material in `defineGame({ materials:
 [...] })` and create the rope with `visual: { material: "your-material-id" }`.
 The renderer draws capped cylindrical instances between consecutive simulated
@@ -181,8 +206,8 @@ automatically act on a rigid body.
 For an explicitly mapped dynamic body, game code can read its actual world center
 of mass via `ctx.physics.centerOfMass(id)`, apply the linear impulse, and apply
 `reactionAngularImpulse - centerOfMass × reactionImpulse` as torque impulse.
-Apply each contact at most once for its `tick`; repeated `inspect` calls return
-the same contacts. The source checkout's `examples/rope-reaction` uses the
+For manual coupling, include both `contacts` and `segmentContacts` and apply each
+contact at most once for its `tick`; repeated `inspect` calls return the same contacts. The source checkout's `examples/rope-reaction` uses the
 automatic binding instead.
 
 This sampled, manually applied reaction is delayed and uses positional correction,
@@ -193,7 +218,7 @@ checkpoint. It must not be represented as complete two-way rigid-body interactio
 
 This is an unverified development-stage increment, not complete rope physics:
 the optional segmented visual does not provide a continuous deformable rope mesh,
-general rigid-body coupling, segment or self collision, or tearing. Plane normals must be unit length; `offset` is the signed
+general rigid-body coupling, continuous collision, cross-rope collision, or tearing. Plane normals must be unit length; `offset` is the signed
 normal distance from the origin. Host intervals must be between 1/1000 and
 1/30 seconds inclusive.
 

package/engine.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "pelican-engine",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "milestone": "M3",
   "stage": "advanced-rendering-development",
   "license": "MIT",

package/lib/sdk/index.d.ts

@@ -1,5 +1,5 @@
 /** Pelican Engine public API. No renderer or GPU implementation types escape this module. */
-export declare const SDK_VERSION = "0.3.15";
+export declare const SDK_VERSION = "0.3.17";
 export type Vec2 = readonly [number, number];
 export type Vec3 = readonly [number, number, number];
 export type Vec4 = readonly [number, number, number, number];
@@ -104,7 +104,7 @@ export interface SystemContext extends EngineFacade {
     readonly ropes: RopeService;
 }
 /** CPU particles with sampled sphere/plane collisions. Explicit body bindings apply delayed
- * contact impulses to dynamic spheres; there is no full rigid-body coupling or segment/self collision. */
+ * contact impulses to dynamic spheres; there is no full rigid-body coupling. */
 export type RopeCollider = {
     kind: "sphere";
     id: string;
@@ -151,6 +151,10 @@ export interface RopeDefinition {
     autoStep?: boolean;
     /** Automatically sample and react to existing dynamic, non-trigger sphere bodies. Requires autoStep. */
     bodyColliders?: readonly RopeBodyCollider[];
+    /** Resolve sphere contacts on segment interiors; defaults to true for new ropes. */
+    segmentCollisions?: boolean;
+    /** Resolve discrete non-adjacent segment self contacts; defaults to true for new ropes. */
+    selfCollisions?: boolean;
     /** Optional segmented presentation using an already-declared material id. */
     visual?: RopeVisualOptions;
     substeps?: number;
@@ -173,10 +177,36 @@ export interface RopeContact {
     /** Angular impulse about the world origin; absent in older snapshots. */
     reactionAngularImpulse?: Vec3;
 }
+/** Contact between an interior rope segment and a sampled sphere. */
+export interface RopeSegmentContact {
+    tick: number;
+    /** Zero-based index of the first endpoint; the second is segment + 1. */
+    segment: number;
+    colliderId: string;
+    /** Last closest-point fraction from the first endpoint toward the second. */
+    fraction: number;
+    penetration: number;
+    reactionImpulse?: Vec3;
+    reactionAngularImpulse?: Vec3;
+}
+/** Discrete self-contact between two non-adjacent rope segments. */
+export interface RopeSelfContact {
+    tick: number;
+    /** Zero-based first endpoint of each non-adjacent segment, ordered ascending. */
+    firstSegment: number;
+    secondSegment: number;
+    /** Last closest-point fractions along the respective segments. */
+    firstFraction: number;
+    secondFraction: number;
+    /** Maximum observed overlap in metres during this tick. */
+    penetration: number;
+}
 export interface RopeState {
     tick: number;
     simulatedSeconds: number;
     disposed: boolean;
+    segmentCollisions: boolean;
+    selfCollisions: boolean;
     positions: Vec3[];
     velocities: Vec3[];
     anchors: {
@@ -184,6 +214,8 @@ export interface RopeState {
         position: Vec3;
     }[];
     contacts: RopeContact[];
+    segmentContacts: RopeSegmentContact[];
+    selfContacts: RopeSelfContact[];
     maxDistanceError: number;
     resources: {
         particles: number;

package/lib/sdk/index.js

@@ -1,5 +1,5 @@
 /** Pelican Engine public API. No renderer or GPU implementation types escape this module. */
-export const SDK_VERSION = "0.3.15";
+export const SDK_VERSION = "0.3.17";
 export const SYSTEM_PHASES = [
     "input",
     "prePhysics",

package/lib/simulation/rope-plugin.js

@@ -4,12 +4,20 @@ 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) {
+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.");
     if (definition.autoStep !== undefined && typeof definition.autoStep !== "boolean")
         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)
         return fail("FIXED_DT", "Rope fixedDt must exactly match the host fixedDt.");
     if (fixedDt < 1 / 1000 || fixedDt > 1 / 30)
@@ -40,7 +48,8 @@ function createEntry(input, fixedDt, materials) {
             entities.add(binding.entity);
         }
     }
-    const solver = createRope({ ...definition, fixedDt });
+    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) {
@@ -56,7 +65,14 @@ function parseSnapshot(value, fixedDt, materials) {
         for (const item of value.ropes) {
             if (!item || typeof item !== "object")
                 fail("SNAPSHOT", "Invalid rope entry.");
-            const entry = createEntry(item.definition, fixedDt, materials);
+            const savedSegmentMode = item.state?.config?.segmentCollisions;
+            if (savedSegmentMode !== undefined && typeof savedSegmentMode !== "boolean")
+                fail("SNAPSHOT", "Invalid segment collision configuration.");
+            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) {
@@ -18,6 +19,11 @@ const copyContact = (contact) => {
         ...(reactionAngularImpulse === undefined ? {} : { reactionAngularImpulse: copy(reactionAngularImpulse) }),
     };
 };
+const copySegmentContact = (contact) => {
+    const { reactionImpulse, reactionAngularImpulse, ...rest } = contact;
+    return { ...rest, ...(reactionImpulse === undefined ? {} : { reactionImpulse: copy(reactionImpulse) }),
+        ...(reactionAngularImpulse === undefined ? {} : { reactionAngularImpulse: copy(reactionAngularImpulse) }) };
+};
 const length = (v) => Math.hypot(v[0], v[1], v[2]);
 const validVec = (v, name) => vec(v) ? copy(v) : fail("ROPE_INPUT", `${name} must be a finite 3D vector (|component| <= 1e6)`);
 const positive = (v, name) => typeof v === "number" && Number.isFinite(v) && v > 0 && v <= 1e6 ? v : fail("ROPE_INPUT", `${name} must be positive and <= 1e6`);
@@ -66,6 +72,12 @@ export function createRope(options) {
     const positions = options.points.map((p, i) => validVec(p, `points[${i}]`));
     const mass = positive(options.mass, "mass");
     const radius = positive(options.radius ?? 0.025, "radius");
+    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]");
@@ -80,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 }, positions, anchors);
+    return new RopeSolver({ mass, radius, fixedDt, substeps, iterations, damping, gravity, restLengths, segmentCollisions, selfCollisions }, positions, anchors);
 }
 export class RopeSolver {
     config;
@@ -92,6 +104,8 @@ export class RopeSolver {
     forces;
     colliders = [];
     contacts = [];
+    segmentContacts = [];
+    selfContacts = [];
     constructor(config, positions, anchors) {
         this.config = config;
         this.positions = positions;
@@ -106,6 +120,7 @@ export class RopeSolver {
         this.alive();
         this.colliders = readColliders(input);
         this.contacts = [];
+        this.segmentContacts = [];
     }
     /** Pins or moves a particle; new anchor position takes effect immediately. */
     setAnchor(index, position) {
@@ -152,6 +167,8 @@ export class RopeSolver {
             velocities: this.velocities,
             forces: this.forces,
             contacts: this.contacts,
+            segmentContacts: this.segmentContacts,
+            selfContacts: this.selfContacts,
             tick: this.tickValue,
         };
         try {
@@ -163,6 +180,8 @@ export class RopeSolver {
             this.velocities = before.velocities;
             this.forces = before.forces;
             this.contacts = before.contacts;
+            this.segmentContacts = before.segmentContacts;
+            this.selfContacts = before.selfContacts;
             this.tickValue = before.tick;
             throw error;
         }
@@ -174,6 +193,9 @@ export class RopeSolver {
         // Work on copies; numeric failures must never leave half a tick applied.
         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);
             for (let i = 0; i < positions.length; i++) {
@@ -269,6 +291,82 @@ export class RopeSolver {
                             contacts.set(key, { tick: this.tickValue + 1, particle: i, colliderId: c.id, penetration: depth, reactionImpulse: reaction, reactionAngularImpulse: moment });
                     }
                 }
+                // Resolve interior segment/sphere overlaps after particle contacts. Endpoint
+                // overlaps are already handled by the particle pass above.
+                for (let j = 0; j < restLengths.length; j++) {
+                    const a = positions[j], b = positions[j + 1];
+                    for (const collider of spheres) {
+                        const dynamic = coupling?.sphere(collider.id);
+                        const center = dynamic?.center ?? collider.center, colliderRadius = dynamic?.radius ?? collider.radius;
+                        const direction = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
+                        const squared = direction[0] * direction[0] + direction[1] * direction[1] + direction[2] * direction[2];
+                        if (squared < 1e-24)
+                            continue; // collapsed segment is covered by particle contacts
+                        const fraction = Math.max(0, Math.min(1, ((center[0] - a[0]) * direction[0] + (center[1] - a[1]) * direction[1] + (center[2] - a[2]) * direction[2]) / squared));
+                        if (fraction <= 0 || fraction >= 1)
+                            continue;
+                        const closest = [a[0] + direction[0] * fraction, a[1] + direction[1] * fraction, a[2] + direction[2] * fraction];
+                        const delta = [closest[0] - center[0], closest[1] - center[1], closest[2] - center[2]];
+                        const distance = length(delta), depth = colliderRadius + radius - distance;
+                        if (depth <= 0)
+                            continue;
+                        let normal;
+                        if (distance >= 1e-12)
+                            normal = [delta[0] / distance, delta[1] / distance, delta[2] / distance];
+                        else {
+                            // Choose a deterministic perpendicular if the sphere center lies exactly on the segment.
+                            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];
+                            const perpendicular = [direction[1] * axis[2] - direction[2] * axis[1], direction[2] * axis[0] - direction[0] * axis[2], direction[0] * axis[1] - direction[1] * axis[0]];
+                            const magnitude = length(perpendicular);
+                            normal = [perpendicular[0] / magnitude, perpendicular[1] / magnitude, perpendicular[2] / magnitude];
+                        }
+                        const first = this.anchors.has(j) ? 0 : 1 - fraction, second = this.anchors.has(j + 1) ? 0 : fraction;
+                        const inverseWeight = first * first + second * second;
+                        if (inverseWeight === 0)
+                            continue; // two authoritative anchors cannot move
+                        const contactMass = mass / inverseWeight;
+                        if (!Number.isFinite(contactMass) || contactMass <= 0)
+                            fail("ROPE_NUMERIC", "segment contact mass exceeded finite bounds");
+                        const previousPoint = [0, 1, 2].map(k => previous[j][k] * (1 - fraction) + previous[j + 1][k] * fraction);
+                        let correction, reaction, moment;
+                        if (dynamic && coupling) {
+                            const resolved = coupling.resolve(collider.id, normal, depth, closest, previousPoint, contactMass, h);
+                            correction = resolved.correction;
+                            reaction = resolved.reactionImpulse;
+                            moment = resolved.reactionAngularImpulse;
+                        }
+                        else {
+                            correction = [normal[0] * depth, normal[1] * depth, normal[2] * depth];
+                            const magnitude = -contactMass * depth / h;
+                            reaction = [normal[0] * magnitude, normal[1] * magnitude, normal[2] * magnitude];
+                            const point = [center[0] + normal[0] * colliderRadius, center[1] + normal[1] * colliderRadius, center[2] + normal[2] * colliderRadius];
+                            moment = [point[1] * reaction[2] - point[2] * reaction[1], point[2] * reaction[0] - point[0] * reaction[2], point[0] * reaction[1] - point[1] * reaction[0]];
+                        }
+                        if (!finiteVector(correction) || !finiteVector(reaction) || !finiteVector(moment))
+                            fail("ROPE_NUMERIC", "segment contact exceeded finite bounds");
+                        // Gradients of the closest point distribute correction to movable endpoints.
+                        for (let k = 0; k < 3; k++) {
+                            a[k] += correction[k] * first / inverseWeight;
+                            b[k] += correction[k] * second / inverseWeight;
+                        }
+                        const key = `${j}:${collider.id}`, existing = segmentContacts.get(key);
+                        if (existing) {
+                            existing.penetration = Math.max(existing.penetration, depth);
+                            existing.fraction = fraction;
+                            for (let k = 0; k < 3; k++) {
+                                existing.reactionImpulse[k] += reaction[k];
+                                existing.reactionAngularImpulse[k] += moment[k];
+                            }
+                            if (!finiteVector(existing.reactionImpulse) || !finiteVector(existing.reactionAngularImpulse))
+                                fail("ROPE_NUMERIC", "segment reaction accumulation exceeded finite bounds");
+                        }
+                        else
+                            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))
@@ -283,22 +381,24 @@ export class RopeSolver {
         this.velocities = velocities;
         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, positions: [], velocities: [], anchors: [], contacts: [], 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,
+            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), 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 },
         };
     }
@@ -309,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,
+            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. */
@@ -321,6 +421,8 @@ export class RopeSolver {
         const c = input.config;
         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]))
@@ -341,12 +443,48 @@ export class RopeSolver {
                 (contact.reactionImpulse === undefined) !== (contact.reactionAngularImpulse === undefined) ||
                 (contact.reactionImpulse !== undefined && (!finiteVector(contact.reactionImpulse) || !finiteVector(contact.reactionAngularImpulse)))))
             fail("ROPE_SNAPSHOT", "invalid contact state");
+        const segments = input.segmentContacts === undefined ? [] : input.segmentContacts;
+        if (!Array.isArray(segments) || segments.length > (count - 1) * colliders.length || (!this.config.segmentCollisions && segments.length > 0) ||
+            segments.some(contact => !contact || contact.tick !== input.tick ||
+                !Number.isSafeInteger(contact.segment) || contact.segment < 0 || contact.segment >= count - 1 ||
+                !colliders.some(collider => collider.id === contact.colliderId && collider.kind === "sphere") ||
+                typeof contact.fraction !== "number" || !Number.isFinite(contact.fraction) || contact.fraction <= 0 || contact.fraction >= 1 ||
+                typeof contact.penetration !== "number" || !Number.isFinite(contact.penetration) || contact.penetration <= 0 ||
+                (contact.reactionImpulse === undefined) !== (contact.reactionAngularImpulse === undefined) ||
+                (contact.reactionImpulse !== undefined && (!finiteVector(contact.reactionImpulse) || !finiteVector(contact.reactionAngularImpulse)))))
+            fail("ROPE_SNAPSHOT", "invalid segment contact state");
+        const segmentKeys = new Set();
+        for (const contact of segments) {
+            const key = `${contact.segment}:${contact.colliderId}`;
+            if (segmentKeys.has(key))
+                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);
         this.anchors = anchors;
         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() {
@@ -358,6 +496,8 @@ export class RopeSolver {
         this.forces = [];
         this.colliders = [];
         this.contacts = [];
+        this.segmentContacts = [];
+        this.selfContacts = [];
         this.anchors.clear();
     }
 }

package/package.json

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