pelican-engine 0.3.15 → 0.3.16

package/docs/npm/GAME-AUTHOR.md

@@ -137,6 +137,19 @@ 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 or self collision, and the segment solver
+and snapshot migration have not been runtime validated.
+
 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 +194,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 +206,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, self 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.16",
   "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.16";
 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 or self collision. */
 export type RopeCollider = {
     kind: "sphere";
     id: string;
@@ -151,6 +151,8 @@ 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;
     /** Optional segmented presentation using an already-declared material id. */
     visual?: RopeVisualOptions;
     substeps?: number;
@@ -173,10 +175,23 @@ 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;
+}
 export interface RopeState {
     tick: number;
     simulatedSeconds: number;
     disposed: boolean;
+    segmentCollisions: boolean;
     positions: Vec3[];
     velocities: Vec3[];
     anchors: {
@@ -184,6 +199,7 @@ export interface RopeState {
         position: Vec3;
     }[];
     contacts: RopeContact[];
+    segmentContacts: RopeSegmentContact[];
     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.16";
 export const SYSTEM_PHASES = [
     "input",
     "prePhysics",

package/lib/simulation/rope-plugin.js

@@ -4,12 +4,16 @@ 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) {
     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 (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 +44,7 @@ function createEntry(input, fixedDt, materials) {
             entities.add(binding.entity);
         }
     }
-    const solver = createRope({ ...definition, fixedDt });
+    const solver = createRope({ ...definition, fixedDt, ...(restoredSegmentMode === undefined ? {} : { segmentCollisions: restoredSegmentMode }) });
     return { definition, solver, bodyRefs: new Map(), staleBodies: new Set() };
 }
 function disposeEntries(entries) {
@@ -56,7 +60,11 @@ 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.");
+            // Snapshots made before segment contacts represent particle-only behavior.
+            const entry = createEntry(item.definition, fixedDt, materials, savedSegmentMode ?? false);
             if (entries.has(entry.definition.id)) {
                 entry.solver.dispose();
                 fail("SNAPSHOT", "Duplicate rope id.");

package/lib/simulation/rope.js

@@ -18,6 +18,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 +71,9 @@ 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;
     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 +88,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 }, positions, anchors);
 }
 export class RopeSolver {
     config;
@@ -92,6 +100,7 @@ export class RopeSolver {
     forces;
     colliders = [];
     contacts = [];
+    segmentContacts = [];
     constructor(config, positions, anchors) {
         this.config = config;
         this.positions = positions;
@@ -106,6 +115,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 +162,7 @@ export class RopeSolver {
             velocities: this.velocities,
             forces: this.forces,
             contacts: this.contacts,
+            segmentContacts: this.segmentContacts,
             tick: this.tickValue,
         };
         try {
@@ -163,6 +174,7 @@ export class RopeSolver {
             this.velocities = before.velocities;
             this.forces = before.forces;
             this.contacts = before.contacts;
+            this.segmentContacts = before.segmentContacts;
             this.tickValue = before.tick;
             throw error;
         }
@@ -174,6 +186,8 @@ 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 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 +283,80 @@ 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 });
+                    }
+                }
             }
             for (let i = 0; i < positions.length; i++) {
                 if (this.anchors.has(i))
@@ -283,22 +371,23 @@ export class RopeSolver {
         this.velocities = velocities;
         this.forces = positions.map(() => [0, 0, 0]);
         this.contacts = [...contacts.values()];
+        this.segmentContacts = [...segmentContacts.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, positions: [], velocities: [], anchors: [], contacts: [], segmentContacts: [], 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,
             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), maxDistanceError,
             resources: { particles: this.positions.length, constraints: this.config.restLengths.length, anchors: this.anchors.size, colliders: this.colliders.length },
         };
     }
@@ -309,7 +398,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,
         };
     }
     /** Accepts a JSON-round-tripped snapshot only from the same rope configuration. Atomic on failure. */
@@ -321,6 +410,7 @@ 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 ||
             !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 +431,30 @@ 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);
+        }
         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.tickValue = input.tick;
     }
     dispose() {
@@ -358,6 +466,7 @@ export class RopeSolver {
         this.forces = [];
         this.colliders = [];
         this.contacts = [];
+        this.segmentContacts = [];
         this.anchors.clear();
     }
 }

package/package.json

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