pelican-engine 0.3.12 → 0.3.14

package/docs/npm/GAME-AUTHOR.md

@@ -137,15 +137,39 @@ 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`.
 
+To bind a rope to existing dynamic sphere bodies, create it with `autoStep: true`
+and `bodyColliders: [{ id: "rope-collider-id", entity: "body-id" }]`. After the
+rigid-body physics phase, the host samples each bound sphere's actual collider
+center, radius, velocity and effective inverse mass/inertia, then steps the rope
+and applies the resulting normal contact impulse to the body. At detected overlaps,
+particle and virtual body corrections share effective mass and address closing
+normal velocity; contacts are not predicted before overlap.
+The actual body's displacement responds on the next body step. Bindings require live dynamic non-trigger spheres and unique
+collider ids and body entities within each rope. Do not use a bound collider id
+in `setColliders`; its manual planes and spheres remain separate. A destroyed body
+is unbound at the next automatic step, and a new entity with the same id is not
+implicitly rebound. Bindings are saved with Host snapshots.
+
+Do not manually apply the same contact's reaction when using a body binding: the
+host already applies it. A native failure can still leave the host tick partially
+changed, so restore a known-good checkpoint. This is an approximate split-step
+solver: virtual positions use a first-order update and the real body moves on its
+next step. Ropes are processed sequentially, without globally coupled substeps;
+friction, restitution and continuous collision are not included. Penetration
+correction can inject energy; stability, conservation, runtime and snapshot
+compatibility have not been validated.
+
 For each latest-tick contact, `reactionImpulse` and `reactionAngularImpulse`
-report the opposite impulse produced by the particle's position projections,
+report the opposite impulse produced by the particle's contact response,
 and its moment about the world origin. These optional fields are absent when
-restoring older contact snapshots. They do not automatically act on a rigid body.
+restoring older contact snapshots. Contacts from unbound manual colliders do not
+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 has an illustrative `examples/rope-reaction`.
+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,
 not a coupled contact solver: it omits body velocity/effective mass, friction and
@@ -154,7 +178,7 @@ operations and is not transactional if a tick fails; recover from a known-good
 checkpoint. It must not be represented as complete two-way rigid-body interaction.
 
 This is an unverified development-stage increment, not complete rope physics:
-there is no built-in rope mesh, automatic rigid-body reaction, segment or self collision,
+there is no built-in rope mesh, general rigid-body coupling, segment or self collision,
 or tearing. Moving entities to particle positions is not a rope renderer or
 coupled physics. Plane normals must be unit length; `offset` is the signed
 normal distance from the origin. Host intervals must be between 1/1000 and

package/engine.manifest.json

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

package/lib/physics/index.js

@@ -809,10 +809,48 @@ function createPlugin(context) {
             };
         },
     };
+    const sampleRopeSphere = (id) => {
+        const b = get(id);
+        if (b.type !== "dynamic" || b.definition.rigidBody?.collider.shape !== "sphere" || b.collider.isSensor())
+            fail("TC_PHYSICS_ROPE_BODY", `Rope body '${id}' must be a live dynamic, non-trigger sphere.`);
+        const inertia = b.body.effectiveWorldInvInertia();
+        return {
+            center: tuple(b.collider.translation()), radius: b.collider.radius(),
+            centerOfMass: tuple(b.body.worldCom()), linearVelocity: tuple(b.body.linvel()),
+            angularVelocity: tuple(b.body.angvel()), inverseMass: tuple(b.body.effectiveInvMass()),
+            inverseInertia: [inertia.m11, inertia.m12, inertia.m13, inertia.m22, inertia.m23, inertia.m33],
+        };
+    };
     return {
         id: pluginId,
         version: "3",
         services: { physics },
+        ropePhysicsBridge: {
+            sampleSphere: sampleRopeSphere,
+            applySphereReactions(reactions) {
+                alive();
+                const seen = new Set();
+                const actions = [];
+                for (const { entity, impulse, moment } of reactions) {
+                    if (seen.has(entity))
+                        fail("TC_PHYSICS_ROPE_BODY", `Duplicate rope reaction body '${entity}'.`);
+                    seen.add(entity);
+                    const sample = sampleRopeSphere(entity), j = tuple(vec(impulse, "rope reaction"));
+                    const m = tuple(vec(moment, "rope reaction moment")), c = sample.centerOfMass;
+                    const torque = [m[0] - (c[1] * j[2] - c[2] * j[1]), m[1] - (c[2] * j[0] - c[0] * j[2]), m[2] - (c[0] * j[1] - c[1] * j[0])];
+                    vec(torque, "rope reaction torque");
+                    if (j.some(value => value !== 0))
+                        actions.push({ kind: "impulse", id: entity, value: j });
+                    if (torque.some(value => value !== 0))
+                        actions.push({ kind: "torqueImpulse", id: entity, value: torque });
+                }
+                if (history.length + actions.length > limit)
+                    fail("TC_PHYSICS_HISTORY_LIMIT", "Rope reactions exceed physics history capacity; start a new scene.");
+                // Validation precedes mutation; a native error can still leave a partial batch.
+                for (const action of actions)
+                    record(action);
+            },
+        },
         systems: [
             {
                 id: pluginId,

package/lib/runtime/host.js

@@ -105,6 +105,7 @@ export class RuntimeHost {
             for (const factory of options.plugins ?? []) {
                 const plugin = factory({
                     fixedDt: this.fixedDt,
+                    getRopePhysicsBridge: () => this.plugins.find((plugin) => plugin.id === "$engine.physics")?.ropePhysicsBridge,
                     world: this.world,
                     scene: this.scene,
                     events: (type) => this.scheduler.events(type),

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.12";
+export declare const SDK_VERSION = "0.3.14";
 export type Vec2 = readonly [number, number];
 export type Vec3 = readonly [number, number, number];
 export type Vec4 = readonly [number, number, number, number];
@@ -103,8 +103,8 @@ export interface SystemContext extends EngineFacade {
     readonly navigation: NavigationService;
     readonly ropes: RopeService;
 }
-/** CPU particles with sampled sphere/plane collisions. Collision only moves rope particles;
- * no automatic rigid-body reaction, segment/self collision, rendering or complete physics. */
+/** CPU particles with sampled sphere/plane collisions. Explicit body bindings apply a delayed
+ * projection reaction to dynamic spheres; no full rigid-body coupling, segment/self collision or rope rendering. */
 export type RopeCollider = {
     kind: "sphere";
     id: string;
@@ -116,6 +116,11 @@ export type RopeCollider = {
     normal: Vec3;
     offset: number;
 };
+/** Explicit connection between a sampled rope collider id and a dynamic sphere body. */
+export interface RopeBodyCollider {
+    readonly id: string;
+    readonly entity: string;
+}
 export interface RopeDefinition {
     id: string;
     points: readonly Vec3[];
@@ -126,6 +131,8 @@ export interface RopeDefinition {
     fixedDt?: number;
     /** When true, step once after each physics phase; defaults to false (manual stepping). */
     autoStep?: boolean;
+    /** Automatically sample and react to existing dynamic, non-trigger sphere bodies. Requires autoStep. */
+    bodyColliders?: readonly RopeBodyCollider[];
     substeps?: number;
     iterations?: number;
     damping?: number;
@@ -141,7 +148,7 @@ export interface RopeContact {
     particle: number;
     colliderId: string;
     penetration: number;
-    /** Opposite of particle projection impulses, N·s; absent in older snapshots. */
+    /** Opposite of particle contact impulses, N·s; absent in older snapshots. */
     reactionImpulse?: Vec3;
     /** Angular impulse about the world origin; absent in older snapshots. */
     reactionAngularImpulse?: Vec3;

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.12";
+export const SDK_VERSION = "0.3.14";
 export const SYSTEM_PHASES = [
     "input",
     "prePhysics",

package/lib/simulation/rope-body-coupling.js

@@ -0,0 +1,107 @@
+const error = (message) => { throw new Error(`TC_ROPE_BODY_NUMERIC: ${message}`); };
+const vector = (value, label) => {
+    if (!Array.isArray(value) || value.length !== 3 || !value.every(Number.isFinite))
+        return error(`${label} must be a finite 3D vector.`);
+    return [value[0], value[1], value[2]];
+};
+const add = (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 scale = (a, value) => [a[0] * value, a[1] * value, a[2] * value];
+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 dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const multiply = (m, v) => [m[0] * v[0] + m[1] * v[1] + m[2] * v[2], m[1] * v[0] + m[3] * v[1] + m[4] * v[2], m[2] * v[0] + m[4] * v[1] + m[5] * v[2]];
+/** Mutable per-host-tick approximation. Native rigid bodies remain untouched until commit. */
+export class VirtualRopeSphere {
+    center;
+    radius;
+    centerOfMass;
+    linearVelocity;
+    angularVelocity;
+    inverseMass;
+    inverseInertia;
+    impulse = [0, 0, 0];
+    moment = [0, 0, 0];
+    constructor(sample) {
+        this.center = vector(sample.center, "sphere center");
+        this.centerOfMass = vector(sample.centerOfMass, "center of mass");
+        this.linearVelocity = vector(sample.linearVelocity, "linear velocity");
+        this.angularVelocity = vector(sample.angularVelocity, "angular velocity");
+        this.inverseMass = vector(sample.inverseMass, "inverse mass");
+        if (this.inverseMass.some(value => value < 0))
+            error("inverse mass cannot be negative.");
+        if (!Array.isArray(sample.inverseInertia) || sample.inverseInertia.length !== 6 || !sample.inverseInertia.every(Number.isFinite))
+            throw new Error("TC_ROPE_BODY_NUMERIC: world inverse inertia must have six finite elements.");
+        this.inverseInertia = [...sample.inverseInertia];
+        if (this.inverseInertia[0] < 0 || this.inverseInertia[3] < 0 || this.inverseInertia[5] < 0)
+            error("world inverse inertia diagonal cannot be negative.");
+        if (!Number.isFinite(sample.radius) || sample.radius <= 0 || sample.radius > 1e6)
+            error("sphere radius is outside (0, 1e6].");
+        this.radius = sample.radius;
+    }
+    point(normal) { return add(this.center, scale(normal, this.radius)); }
+    pointVelocity(point) { return add(this.linearVelocity, cross(this.angularVelocity, sub(point, this.centerOfMass))); }
+    inverseEffectiveMass(point, normal) {
+        const rCrossN = cross(sub(point, this.centerOfMass), normal);
+        const linear = normal[0] * normal[0] * this.inverseMass[0] + normal[1] * normal[1] * this.inverseMass[1] + normal[2] * normal[2] * this.inverseMass[2];
+        const angular = dot(rCrossN, multiply(this.inverseInertia, rCrossN));
+        const result = linear + angular;
+        if (!Number.isFinite(result) || result < -1e-8)
+            return error("invalid effective inverse mass.");
+        return Math.max(0, result);
+    }
+    apply(impulse, point, dt) {
+        const r = sub(point, this.centerOfMass);
+        const deltaLinear = [this.inverseMass[0] * impulse[0], this.inverseMass[1] * impulse[1], this.inverseMass[2] * impulse[2]];
+        const deltaAngular = multiply(this.inverseInertia, cross(r, impulse));
+        const relativeCenter = sub(this.center, this.centerOfMass);
+        const translation = scale(deltaLinear, dt);
+        // First-order virtual transform update; the actual rigid body moves on its next physics step.
+        this.center = vector(add(add(this.center, translation), cross(scale(deltaAngular, dt), relativeCenter)), "virtual sphere center");
+        this.centerOfMass = vector(add(this.centerOfMass, translation), "virtual center of mass");
+        this.linearVelocity = vector(add(this.linearVelocity, deltaLinear), "virtual linear velocity");
+        this.angularVelocity = vector(add(this.angularVelocity, deltaAngular), "virtual angular velocity");
+        this.impulse = vector(add(this.impulse, impulse), "accumulated impulse");
+        this.moment = vector(add(this.moment, cross(point, impulse)), "accumulated moment");
+    }
+    resolve(normal, depth, position, previous, mass, dt) {
+        const invParticle = 1 / mass;
+        if (!Number.isFinite(invParticle) || invParticle <= 0 || !Number.isFinite(dt) || dt <= 0)
+            return error("particle mass and substep must be finite and positive.");
+        // n·M⁻¹n + (r×n)·I⁻¹(r×n) accounts for translation, rotation and locked axes.
+        const firstPoint = this.point(normal), denominator = invParticle + this.inverseEffectiveMass(firstPoint, normal);
+        if (!Number.isFinite(denominator) || denominator <= 0)
+            return error("contact inverse mass must be positive and finite.");
+        // Position projection is shared between particle and body by effective inverse mass.
+        const positionImpulse = depth / (dt * denominator);
+        const firstImpulse = scale(normal, -positionImpulse);
+        let correction = scale(normal, positionImpulse * invParticle * dt);
+        let reactionImpulse = firstImpulse, reactionAngularImpulse = cross(firstPoint, firstImpulse);
+        this.apply(firstImpulse, firstPoint, dt);
+        // Remove remaining closing normal velocity using the virtual body's updated velocity.
+        const secondPoint = this.point(normal);
+        const particleVelocity = scale(sub(add(position, correction), previous), 1 / dt);
+        const relativeNormal = dot(sub(particleVelocity, this.pointVelocity(secondPoint)), normal);
+        const velocityDenominator = invParticle + this.inverseEffectiveMass(secondPoint, normal);
+        if (!Number.isFinite(relativeNormal) || !Number.isFinite(velocityDenominator) || velocityDenominator <= 0)
+            return error("contact velocity or inverse mass is not finite.");
+        if (relativeNormal < 0) {
+            const velocityImpulse = -relativeNormal / velocityDenominator;
+            const secondImpulse = scale(normal, -velocityImpulse);
+            correction = add(correction, scale(normal, velocityImpulse * invParticle * dt));
+            reactionImpulse = add(reactionImpulse, secondImpulse);
+            reactionAngularImpulse = add(reactionAngularImpulse, cross(secondPoint, secondImpulse));
+            this.apply(secondImpulse, secondPoint, dt);
+        }
+        return { correction: vector(correction, "particle correction"), reactionImpulse: vector(reactionImpulse, "reaction impulse"), reactionAngularImpulse: vector(reactionAngularImpulse, "reaction moment") };
+    }
+    reaction() { return { impulse: vector(this.impulse, "reaction impulse"), moment: vector(this.moment, "reaction moment") }; }
+}
+export function createRopeBodyCoupling(bodies) {
+    return {
+        sphere(id) { const body = bodies.get(id); return body ? { center: body.center, radius: body.radius } : undefined; },
+        resolve(id, normal, depth, position, previous, mass, dt) {
+            const body = bodies.get(id) ?? error(`Missing virtual sphere '${id}'.`);
+            return body.resolve(normal, depth, position, previous, mass, dt);
+        },
+    };
+}

package/lib/simulation/rope-plugin.js

@@ -1,5 +1,7 @@
+import { resolveEntityDefinition } from "../runtime/prefabs.js";
 import { cloneSerializable } from "../runtime/random.js";
 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) {
@@ -12,8 +14,21 @@ function createEntry(input, fixedDt) {
         return fail("FIXED_DT", "Rope fixedDt must exactly match the host fixedDt.");
     if (fixedDt < 1 / 1000 || fixedDt > 1 / 30)
         return fail("FIXED_DT", "Host fixedDt must be within [1/1000, 1/30] seconds for ropes.");
+    if (definition.bodyColliders !== undefined) {
+        if (!Array.isArray(definition.bodyColliders) || definition.bodyColliders.length > 64)
+            return fail("BODY_COLLIDER", "bodyColliders must contain at most 64 bindings.");
+        if (definition.bodyColliders.length && !definition.autoStep)
+            return fail("BODY_COLLIDER", "Body bindings require autoStep: true.");
+        const ids = new Set(), entities = new Set();
+        for (const binding of definition.bodyColliders) {
+            if (!binding || typeof binding !== "object" || !validId(binding.id) || !validId(binding.entity) || ids.has(binding.id) || entities.has(binding.entity))
+                return fail("BODY_COLLIDER", "Each binding requires a unique nonempty collider id and body entity.");
+            ids.add(binding.id);
+            entities.add(binding.entity);
+        }
+    }
     const solver = createRope({ ...definition, fixedDt });
-    return { definition, solver };
+    return { definition, solver, bodyRefs: new Map(), staleBodies: new Set() };
 }
 function disposeEntries(entries) {
     for (const { solver } of entries.values())
@@ -34,6 +49,11 @@ function parseSnapshot(value, fixedDt) {
                 fail("SNAPSHOT", "Duplicate rope id.");
             }
             entries.set(entry.definition.id, entry);
+            const stale = item.staleBodyColliders === undefined ? [] : item.staleBodyColliders;
+            const bound = new Set((entry.definition.bodyColliders ?? []).map(binding => binding.id));
+            if (!Array.isArray(stale) || stale.some(id => typeof id !== "string" || !bound.has(id)) || new Set(stale).size !== stale.length)
+                fail("SNAPSHOT", "Invalid stale body collider list.");
+            entry.staleBodies = new Set(stale);
             entry.solver.restore(item.state);
         }
         return entries;
@@ -43,17 +63,60 @@ function parseSnapshot(value, fixedDt) {
         throw error;
     }
 }
-/** CPU rope ownership; optional host-scheduled stepping remains independent from Rapier. */
-export const createRopePlugin = ({ fixedDt }) => {
+function bridgeFor(context) {
+    return context.getRopePhysicsBridge?.() ?? fail("BODY_COLLIDER", "Body colliders require the physics plugin and a live dynamic sphere.");
+}
+function resolveRefs(entry, context, checkPhysics) {
+    const refs = new Map();
+    const specs = entry.definition.bodyColliders ?? [];
+    const bridge = checkPhysics && specs.length ? bridgeFor(context) : undefined;
+    for (const spec of specs) {
+        if (entry.staleBodies.has(spec.id))
+            continue;
+        if (!context.world.isAlive(spec.entity))
+            fail("BODY_COLLIDER", `Body '${spec.entity}' is not a live entity.`);
+        if (bridge)
+            bridge.sampleSphere(spec.entity);
+        refs.set(spec.id, context.world.resolve(spec.entity));
+    }
+    return refs;
+}
+function validateWorldBindings(entries, context, world) {
+    const records = new Map(world.entities.map(record => [record.id, record]));
+    for (const entry of entries.values())
+        for (const binding of entry.definition.bodyColliders ?? []) {
+            if (entry.staleBodies.has(binding.id))
+                continue;
+            const record = records.get(binding.entity);
+            const definition = record && resolveEntityDefinition(context.scene, record);
+            const body = definition?.rigidBody;
+            if (!record || !body || body.type !== "dynamic" || body.collider.shape !== "sphere" || body.trigger)
+                fail("SNAPSHOT", `Bound body '${binding.entity}' must exist as a dynamic, non-trigger sphere in the restored world.`);
+        }
+}
+/** Split-step sphere contact uses virtual mass/velocity state; native commit is deferred. */
+export const createRopePlugin = (context) => {
+    const { fixedDt } = context;
     if (typeof fixedDt !== "number" || !Number.isFinite(fixedDt))
         return fail("FIXED_DT", "RuntimeHost must provide a finite fixed interval.");
     const hostDt = fixedDt;
     let entries = new Map();
-    let disposed = false;
+    let disposed = false, pendingRefs = false;
     const alive = () => { if (disposed)
         fail("DISPOSED", "Rope service is disposed."); };
+    // Host replay restores plugin data before it replaces the World. Resolve handles
+    // lazily at the first use, after that World replacement has completed.
+    const ensureRefs = () => {
+        if (!pendingRefs)
+            return;
+        const staged = [...entries.values()].map(entry => ({ entry, refs: resolveRefs(entry, context, false) }));
+        for (const { entry, refs } of staged)
+            entry.bodyRefs = refs;
+        pendingRefs = false;
+    };
     const get = (id) => {
         alive();
+        ensureRefs();
         if (!validId(id))
             return fail("ID", "Expected a nonempty rope id.");
         return entries.get(id) ?? fail("MISSING", `Rope '${id}' does not exist.`);
@@ -61,6 +124,7 @@ export const createRopePlugin = ({ fixedDt }) => {
     const service = {
         create(definition) {
             alive();
+            ensureRefs();
             if (!definition || !validId(definition.id))
                 return fail("ID", "Expected a nonempty rope id.");
             if (entries.has(definition.id))
@@ -68,7 +132,14 @@ export const createRopePlugin = ({ fixedDt }) => {
             if (entries.size >= 256)
                 return fail("CAPACITY", "At most 256 ropes per host.");
             const entry = createEntry(definition, hostDt);
-            entries.set(entry.definition.id, entry);
+            try {
+                entry.bodyRefs = resolveRefs(entry, context, true);
+                entries.set(entry.definition.id, entry);
+            }
+            catch (error) {
+                entry.solver.dispose();
+                throw error;
+            }
         },
         step(id, ticks) {
             const entry = get(id);
@@ -77,7 +148,17 @@ export const createRopePlugin = ({ fixedDt }) => {
             return entry.solver.step(ticks);
         },
         inspect(id) { return get(id).solver.inspect(); },
-        setColliders(id, colliders) { get(id).solver.setColliders(cloneSerializable(colliders)); },
+        setColliders(id, colliders) {
+            const entry = get(id);
+            if (Array.isArray(colliders)) {
+                const bound = new Set((entry.definition.bodyColliders ?? []).map(item => item.id));
+                if (colliders.length + bound.size > 4096)
+                    return fail("BODY_COLLIDER", "Manual and bound colliders together may not exceed 4096.");
+                if (colliders.some(collider => collider && bound.has(collider.id)))
+                    return fail("BODY_COLLIDER", "Manual collider ids must not conflict with body bindings.");
+            }
+            entry.solver.setColliders(cloneSerializable(colliders));
+        },
         setAnchor(id, index, position) { get(id).solver.setAnchor(index, cloneSerializable(position)); },
         releaseAnchor(id, index) { get(id).solver.releaseAnchor(index); },
         applyForce(id, index, force) { get(id).solver.applyForce(index, cloneSerializable(force)); },
@@ -88,22 +169,61 @@ export const createRopePlugin = ({ fixedDt }) => {
         id: "$engine.ropes", version: "1", services: { ropes: service },
         afterPhysics() {
             alive();
+            ensureRefs();
             const committed = [];
+            const bodies = new Map();
             try {
-                // Stable ordering also makes failure and recording behavior independent of insertion order.
                 const automatic = [...entries.values()].filter(entry => entry.definition.autoStep)
                     .sort((a, b) => a.definition.id < b.definition.id ? -1 : a.definition.id > b.definition.id ? 1 : 0);
-                for (const { solver } of automatic) {
-                    const snapshot = solver.snapshot();
-                    solver.step(); // A failed solver step rolls itself back.
-                    committed.push({ solver, snapshot });
+                for (const entry of automatic) {
+                    const snapshot = entry.solver.snapshot();
+                    committed.push({ entry, snapshot, definition: entry.definition, refs: entry.bodyRefs, stale: entry.staleBodies });
+                    const previous = entry.definition.bodyColliders ?? [];
+                    const live = [];
+                    for (const binding of previous) {
+                        const ref = entry.bodyRefs.get(binding.id);
+                        if (!ref && !entry.staleBodies.has(binding.id))
+                            fail("BODY_COLLIDER", `Missing live handle for '${binding.id}'; restore a known-good checkpoint.`);
+                        if (ref && context.world.isAlive(ref))
+                            live.push(binding);
+                    }
+                    if (live.length !== previous.length) {
+                        entry.definition = { ...entry.definition, bodyColliders: live };
+                        entry.bodyRefs = new Map(live.map(binding => [binding.id, entry.bodyRefs.get(binding.id)]));
+                        entry.staleBodies = new Set();
+                    }
+                    const coupled = new Map();
+                    if (previous.length) {
+                        const boundIds = new Set(previous.map(item => item.id));
+                        const manual = snapshot.colliders.filter(collider => !boundIds.has(collider.id));
+                        const bridge = live.length ? bridgeFor(context) : undefined;
+                        const sampled = live.map(binding => {
+                            let body = bodies.get(binding.entity);
+                            if (!body) {
+                                body = new VirtualRopeSphere(bridge.sampleSphere(binding.entity));
+                                bodies.set(binding.entity, body);
+                            }
+                            coupled.set(binding.id, body);
+                            return { kind: "sphere", id: binding.id, center: [...body.center], radius: body.radius };
+                        });
+                        entry.solver.setColliders([...manual, ...sampled]);
+                    }
+                    entry.solver.step(1, coupled.size ? createRopeBodyCoupling(coupled) : undefined);
                 }
+                const batch = [...bodies].map(([entity, body]) => ({ entity, ...body.reaction() }))
+                    .filter(item => item.impulse.some(value => value !== 0) || item.moment.some(value => value !== 0))
+                    .sort((a, b) => a.entity < b.entity ? -1 : a.entity > b.entity ? 1 : 0);
+                if (batch.length)
+                    bridgeFor(context).applySphereReactions(batch);
             }
             catch (error) {
                 const failures = [];
-                for (const { solver, snapshot } of committed.reverse()) {
+                for (const item of committed.reverse()) {
+                    item.entry.definition = item.definition;
+                    item.entry.bodyRefs = item.refs;
+                    item.entry.staleBodies = item.stale;
                     try {
-                        solver.restore(snapshot);
+                        item.entry.solver.restore(item.snapshot);
                     }
                     catch (rollbackError) {
                         failures.push(String(rollbackError));
@@ -115,9 +235,56 @@ export const createRopePlugin = ({ fixedDt }) => {
             }
         },
         legacySnapshot: () => ({ version: 1, ropes: [] }),
-        snapshot: () => ({ version: 1, ropes: [...entries.values()].sort((a, b) => a.definition.id < b.definition.id ? -1 : a.definition.id > b.definition.id ? 1 : 0).map(({ definition, solver }) => ({ definition: cloneSerializable(definition), state: solver.snapshot() })) }),
+        snapshot: () => {
+            alive();
+            ensureRefs();
+            return { version: 1, ropes: [...entries.values()].sort((a, b) => a.definition.id < b.definition.id ? -1 : a.definition.id > b.definition.id ? 1 : 0).map(entry => {
+                    const stale = (entry.definition.bodyColliders ?? []).filter(binding => {
+                        const ref = entry.bodyRefs.get(binding.id);
+                        if (!ref && !entry.staleBodies.has(binding.id))
+                            return fail("SNAPSHOT", `Missing handle for '${binding.id}'.`);
+                        return !ref || !context.world.isAlive(ref);
+                    }).map(binding => binding.id);
+                    return { definition: cloneSerializable(entry.definition), state: entry.solver.snapshot(), ...(stale.length ? { staleBodyColliders: stale } : {}) };
+                }) };
+        },
         validateSnapshot(value) { const staged = parseSnapshot(value, hostDt); disposeEntries(staged); },
-        restore(value) { alive(); const staged = parseSnapshot(value, hostDt); disposeEntries(entries); entries = staged; },
+        validateWorld(value, world) {
+            const staged = parseSnapshot(value, hostDt);
+            try {
+                validateWorldBindings(staged, context, world);
+            }
+            finally {
+                disposeEntries(staged);
+            }
+        },
+        validatePeers(value, peers) {
+            const staged = parseSnapshot(value, hostDt);
+            try {
+                const bindings = [...staged.values()].flatMap(entry => (entry.definition.bodyColliders ?? []).filter(binding => !entry.staleBodies.has(binding.id)));
+                if (!bindings.length)
+                    return;
+                const physics = peers["$engine.physics"]?.payload;
+                if (!physics || !Array.isArray(physics.bindings) || !Array.isArray(physics.entities))
+                    return fail("SNAPSHOT", "Body-bound ropes require a matching physics snapshot.");
+                const bodyStates = physics.entities, bodyIds = physics.bindings;
+                for (const binding of bindings) {
+                    const found = bodyStates.find(item => item && typeof item === "object" && item.id === binding.entity && item.type === "dynamic");
+                    if (!found || !bodyIds.includes(binding.entity))
+                        fail("SNAPSHOT", `Bound body '${binding.entity}' is missing from physics state.`);
+                }
+            }
+            finally {
+                disposeEntries(staged);
+            }
+        },
+        restore(value) {
+            alive();
+            const staged = parseSnapshot(value, hostDt);
+            disposeEntries(entries);
+            entries = staged;
+            pendingRefs = true;
+        },
         dispose() { if (disposed)
             return; disposed = true; disposeEntries(entries); },
     };

package/lib/simulation/rope.js

@@ -140,8 +140,10 @@ export class RopeSolver {
         this.forces[i] = next;
     }
     /** Exactly N fixed ticks; a failed batch restores the state before the first tick. */
-    step(steps = 1) {
+    step(steps = 1, coupling) {
         this.alive();
+        if (coupling && steps !== 1)
+            fail("ROPE_INPUT", "coupled stepping requires exactly one tick");
         if (!Number.isSafeInteger(steps) || steps < 1 || steps > 1000 || this.tickValue + steps > Number.MAX_SAFE_INTEGER)
             fail("ROPE_INPUT", "steps must be an integer in [1,1000] without tick overflow");
         // stepOne replaces these arrays rather than mutating the prior committed state.
@@ -154,7 +156,7 @@ export class RopeSolver {
         };
         try {
             for (let s = 0; s < steps; s++)
-                this.stepOne();
+                this.stepOne(coupling);
         }
         catch (error) {
             this.positions = before.positions;
@@ -166,7 +168,7 @@ export class RopeSolver {
         }
         return this.inspect();
     }
-    stepOne() {
+    stepOne(coupling) {
         const { fixedDt, substeps, iterations, mass, gravity, damping, restLengths, radius } = this.config;
         const h = fixedDt / substeps, decay = Math.exp(-damping * h);
         // Work on copies; numeric failures must never leave half a tick applied.
@@ -215,29 +217,41 @@ export class RopeSolver {
                     for (const c of this.colliders) {
                         let depth = 0;
                         let normal;
+                        const dynamic = c.kind === "sphere" ? coupling?.sphere(c.id) : undefined;
                         if (c.kind === "plane") {
                             depth = c.offset + radius - (p[0] * c.normal[0] + p[1] * c.normal[1] + p[2] * c.normal[2]);
                             normal = c.normal;
                         }
                         else {
-                            const delta = [p[0] - c.center[0], p[1] - c.center[1], p[2] - c.center[2]];
+                            const center = dynamic?.center ?? c.center, colliderRadius = dynamic?.radius ?? c.radius;
+                            const delta = [p[0] - center[0], p[1] - center[1], p[2] - center[2]];
                             const distance = length(delta);
-                            depth = c.radius + radius - distance;
+                            depth = colliderRadius + radius - distance;
                             normal = distance < 1e-12 ? [1, 0, 0] : [delta[0] / distance, delta[1] / distance, delta[2] / distance];
                         }
                         if (depth <= 0)
                             continue;
-                        for (let k = 0; k < 3; k++)
-                            p[k] += normal[k] * depth;
-                        // Each positional projection changes the particle's velocity by depth / h.
-                        // Report its equal-and-opposite impulse and moment on the sampled surface;
-                        // the collider itself remains an immutable input and is not moved here.
-                        const magnitude = -mass * depth / h;
-                        const reaction = [normal[0] * magnitude, normal[1] * magnitude, normal[2] * magnitude];
-                        const point = c.kind === "sphere"
-                            ? [c.center[0] + normal[0] * c.radius, c.center[1] + normal[1] * c.radius, c.center[2] + normal[2] * c.radius]
-                            : [p[0] - normal[0] * radius, p[1] - normal[1] * radius, p[2] - normal[2] * radius];
-                        const 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]];
+                        let reaction, moment;
+                        if (dynamic && coupling) {
+                            const result = coupling.resolve(c.id, normal, depth, p, previous[i], mass, h);
+                            if (!finiteVector(result.correction) || !finiteVector(result.reactionImpulse) || !finiteVector(result.reactionAngularImpulse))
+                                fail("ROPE_NUMERIC", "coupled contact exceeded finite numeric bounds");
+                            for (let k = 0; k < 3; k++)
+                                p[k] += result.correction[k];
+                            reaction = result.reactionImpulse;
+                            moment = result.reactionAngularImpulse;
+                        }
+                        else {
+                            for (let k = 0; k < 3; k++)
+                                p[k] += normal[k] * depth;
+                            // A manually sampled collider remains immovable; expose its projection reaction.
+                            const magnitude = -mass * depth / h;
+                            reaction = [normal[0] * magnitude, normal[1] * magnitude, normal[2] * magnitude];
+                            const point = c.kind === "sphere"
+                                ? [c.center[0] + normal[0] * c.radius, c.center[1] + normal[1] * c.radius, c.center[2] + normal[2] * c.radius]
+                                : [p[0] - normal[0] * radius, p[1] - normal[1] * radius, p[2] - normal[2] * radius];
+                            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(reaction) || !finiteVector(moment))
                             fail("ROPE_NUMERIC", "contact reaction exceeded finite numeric bounds");
                         const key = `${i}:${c.id}`;