pelican-engine 0.3.13 → 0.3.15

package/docs/npm/GAME-AUTHOR.md

@@ -137,12 +137,28 @@ 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`.
 
+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
+particles and updates their transforms as the rope moves. `radius` defaults to
+the particle collision radius (or 0.025); `radialSegments` defaults to 8 and
+accepts 3–32. `castShadow` and `receiveShadow` default to true. A collapsed
+zero-length segment has no visible surface. `ctx.ropes.visuals()` returns
+detached descriptions, not renderer objects. Visual configuration is included
+in the rope snapshot and is disposed with the owning content.
+
+This is segmented geometry with overlapping caps, not a continuous deformable
+tube. Large ropes may be expensive. Raster, ray-traced modes, GPU resource
+lifecycle and snapshot restoration have not been runtime validated.
+
 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 and radius, steps the rope, and applies the resulting normal projection
-impulse to the body. That impulse changes body velocity; displacement responds on
-the next body step. Bindings require live dynamic non-trigger spheres and unique
+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
@@ -150,13 +166,15 @@ 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 delayed sampled coupling and
-is not a complete physics solver: body velocity/effective mass, friction,
-continuous collision and coupled substeps are not included. It has not been
-runtime or snapshot validated.
+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. Contacts from unbound manual colliders do not
 automatically act on a rigid body.
@@ -174,9 +192,8 @@ 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, 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
+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
 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.13",
+  "version": "0.3.15",
   "milestone": "M3",
   "stage": "advanced-rendering-development",
   "license": "MIT",

package/lib/physics/index.js

@@ -813,7 +813,13 @@ function createPlugin(context) {
         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.`);
-        return { center: tuple(b.collider.translation()), radius: b.collider.radius() };
+        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,
@@ -823,16 +829,23 @@ function createPlugin(context) {
             sampleSphere: sampleRopeSphere,
             applySphereReactions(reactions) {
                 alive();
-                if (history.length + reactions.length > limit)
-                    fail("TC_PHYSICS_HISTORY_LIMIT", "Rope reactions exceed physics history capacity; start a new scene.");
                 const seen = new Set();
-                const actions = reactions.map(({ entity, impulse }) => {
+                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);
-                    return { kind: "impulseAtPoint", id: entity, value: tuple(vec(impulse, "rope reaction")), point: sample.center };
-                });
+                    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);

package/lib/renderer/browser.js

@@ -1,5 +1,6 @@
 import * as THREE from "three/webgpu";
 import { prepareGameplay } from "./gameplay.js";
+import { createRopeVisualOwner } from "./rope-visuals.js";
 import { GPUTracer } from "./pathtrace.js";
 import { SurfaceTracer } from "./surface-tracer.js";
 import { createRenderSettingsDriver, resolveRenderSettings, } from "../runtime/render-settings.js";
@@ -134,6 +135,11 @@ const recoveryEvents = [];
 const gameObjects = new Map();
 const gameRoot = new THREE.Group();
 scene.add(gameRoot);
+const ropeVisuals = createRopeVisualOwner();
+scene.add(ropeVisuals.root);
+let ropeVisualRevision = 0, renderedRopeVisualRevision = 0;
+const clearRopeVisuals = () => { if (ropeVisuals.clear())
+    ropeVisualRevision++; };
 let authoredCamera = { position: [0, 3.4, 7], target: [0, 0.9, 0] };
 let authoredLights = [];
 let compiledIR = null;
@@ -352,8 +358,10 @@ function createEntityView(entity, materials) {
     return node;
 }
 function syncRuntime() {
-    if (!runtime)
-        return;
+    if (!runtime) {
+        clearRopeVisuals();
+        return ropeVisualRevision !== renderedRopeVisualRevision;
+    }
     transforms.clear();
     componentState.clear();
     const records = runtime.world.records();
@@ -428,6 +436,13 @@ function syncRuntime() {
             if (light)
                 authoredLights.push({ definition: entity.light, object: light });
         }
+    if (gameplay) {
+        if (ropeVisuals.sync(runtime.facade.ropes.visuals(), gameMaterials))
+            ropeVisualRevision++;
+    }
+    else
+        clearRopeVisuals();
+    return ropeVisualRevision !== renderedRopeVisualRevision;
 }
 let simulation;
 const simulationGroup = new THREE.Group();
@@ -720,6 +735,7 @@ async function loadGame(sceneId, saved, loadSlot) {
         contentScope = nextScope;
         gameMaterials = nextMaterials;
         committed = true;
+        clearRopeVisuals();
         if (nextRoot.children.length)
             gameRoot.add(...nextRoot.children);
         gameObjects.clear();
@@ -950,7 +966,9 @@ async function drawFrame(accumulate = false, changed = true) {
         throw new Error("TC_BROWSER_DISPOSED");
     await computeControl?.flush();
     const start = performance.now();
-    syncRuntime();
+    const ropeChanged = syncRuntime();
+    const ropeRevision = ropeVisualRevision;
+    changed = changed || ropeChanged;
     animate();
     renderBufferBridge?.update();
     renderTextureBridge?.update();
@@ -1030,6 +1048,7 @@ async function drawFrame(accumulate = false, changed = true) {
             triangles: triangleCount,
             faulted: terminalFault,
         });
+        renderedRopeVisualRevision = ropeRevision;
         return;
     }
     if (changed) {
@@ -1082,6 +1101,7 @@ async function drawFrame(accumulate = false, changed = true) {
         triangles: triangleCount,
         faulted: terminalFault,
     });
+    renderedRopeVisualRevision = ropeRevision;
 }
 async function applyInput(key) {
     if (!probeEnabled) {
@@ -1327,6 +1347,7 @@ async function disposeBrowser() {
     clean(() => simulation?.dispose());
     clean(() => world?.dispose());
     clean(() => resourceManager.dispose());
+    clean(() => ropeVisuals.dispose());
     clean(() => releaseObject(scene, true, gameMaterials.values()));
     clean(() => pendingSurface?.abort());
     clean(() => tracer?.dispose());

package/lib/renderer/geometry.js

@@ -18,22 +18,32 @@ export function extractTriangles(scene) {
             new THREE.Vector3(),
             new THREE.Vector3(),
         ];
-        for (let i = 0; i < count; i += 3) {
-            for (let k = 0; k < 3; k++)
-                object
-                    .getVertexPosition(geometry.index?.getX(i + k) ?? i + k, points[k])
-                    .applyMatrix4(object.matrixWorld);
-            const color = material.color ?? new THREE.Color(0.6, 0.6, 0.6);
-            triangles.push({
-                a: points[0].toArray(),
-                b: points[1].toArray(),
-                c: points[2].toArray(),
-                color: color.toArray(),
-                emission: material.emissiveIntensity && material.emissive?.getHex()
-                    ? material.emissiveIntensity
-                    : 0,
-                roughness: material.roughness ?? 0.8,
-            });
+        const instanced = object instanceof THREE.InstancedMesh ? object : undefined;
+        const instance = new THREE.Matrix4(), transform = new THREE.Matrix4();
+        for (let slot = 0; slot < (instanced?.count ?? 1); slot++) {
+            if (instanced) {
+                instanced.getMatrixAt(slot, instance);
+                transform.multiplyMatrices(object.matrixWorld, instance);
+            }
+            else
+                transform.copy(object.matrixWorld);
+            for (let i = 0; i < count; i += 3) {
+                for (let k = 0; k < 3; k++)
+                    object
+                        .getVertexPosition(geometry.index?.getX(i + k) ?? i + k, points[k])
+                        .applyMatrix4(transform);
+                const color = material.color ?? new THREE.Color(0.6, 0.6, 0.6);
+                triangles.push({
+                    a: points[0].toArray(),
+                    b: points[1].toArray(),
+                    c: points[2].toArray(),
+                    color: color.toArray(),
+                    emission: material.emissiveIntensity && material.emissive?.getHex()
+                        ? material.emissiveIntensity
+                        : 0,
+                    roughness: material.roughness ?? 0.8,
+                });
+            }
         }
     });
     return triangles;

package/lib/renderer/rope-visuals.js

@@ -0,0 +1,122 @@
+import * as THREE from "three/webgpu";
+/** Presentation owns its instance buffers and geometries; scene materials remain borrowed. */
+export function createRopeVisualOwner() {
+    const root = new THREE.Group();
+    root.name = "pelican-rope-visuals";
+    const views = new Map();
+    let disposed = false;
+    const remove = (view) => { view.mesh.removeFromParent(); view.mesh.dispose(); view.geometry.dispose(); };
+    const clear = () => { const changed = views.size > 0; for (const view of views.values())
+        remove(view); views.clear(); return changed; };
+    const signature = (state) => JSON.stringify([state.material, state.radius, state.radialSegments, state.castShadow, state.receiveShadow, state.positions.length]);
+    const create = (state, material) => {
+        let geometry;
+        let mesh;
+        try {
+            geometry = new THREE.CylinderGeometry(state.radius, state.radius, 1, state.radialSegments, 1, false);
+            const uv = geometry.getAttribute("uv");
+            if (uv)
+                geometry.setAttribute("uv1", uv.clone());
+            mesh = new THREE.InstancedMesh(geometry, material, state.positions.length - 1);
+            mesh.name = `rope:${state.id}`;
+            mesh.castShadow = state.castShadow;
+            mesh.receiveShadow = state.receiveShadow;
+            mesh.count = 0;
+            mesh.visible = false;
+            mesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+            return { mesh, geometry, signature: signature(state), positions: [] };
+        }
+        catch (error) {
+            mesh?.dispose();
+            geometry?.dispose();
+            throw error;
+        }
+    };
+    const matrices = (state) => {
+        const data = new Float32Array((state.positions.length - 1) * 16);
+        const axis = new THREE.Vector3(0, 1, 0), direction = new THREE.Vector3();
+        const position = new THREE.Vector3(), scale = new THREE.Vector3(), rotation = new THREE.Quaternion();
+        const matrix = new THREE.Matrix4();
+        let count = 0;
+        for (let index = 0; index < state.positions.length - 1; index++) {
+            const a = state.positions[index], b = state.positions[index + 1];
+            direction.set(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
+            const length = direction.length();
+            // A collapsed segment has no surface; never submit a singular instance transform.
+            if (length === 0)
+                continue;
+            if (!Number.isFinite(length) || Math.fround(length) === 0)
+                throw new Error(`TC_ROPE_VISUAL_NUMERIC: Segment ${index} of '${state.id}' has an unrepresentable length.`);
+            position.set((a[0] + b[0]) / 2, (a[1] + b[1]) / 2, (a[2] + b[2]) / 2);
+            rotation.setFromUnitVectors(axis, direction.multiplyScalar(1 / length));
+            scale.set(1, length, 1);
+            matrix.compose(position, rotation, scale);
+            for (const value of matrix.elements)
+                if (!Number.isFinite(value) || !Number.isFinite(Math.fround(value)))
+                    throw new Error(`TC_ROPE_VISUAL_NUMERIC: Segment ${index} of '${state.id}' has a non-finite transform.`);
+            data.set(matrix.elements, count++ * 16);
+        }
+        return { data, count };
+    };
+    const sync = (states, materials) => {
+        if (disposed)
+            throw new Error("TC_ROPE_VISUAL_DISPOSED: Create a new presentation owner.");
+        const staged = new Map();
+        const created = [];
+        try {
+            for (const state of states) {
+                if (staged.has(state.id))
+                    throw new Error(`TC_ROPE_VISUAL_ID: Duplicate rope '${state.id}'.`);
+                const material = materials.get(state.material);
+                if (!material)
+                    throw new Error(`TC_ROPE_VISUAL_MATERIAL: Material '${state.material}' is not declared.`);
+                if (!Array.isArray(state.positions) || state.positions.length < 2 || state.positions.length > 4096 ||
+                    state.positions.some(point => !Array.isArray(point) || point.length !== 3 || !point.every(Number.isFinite)))
+                    throw new Error(`TC_ROPE_VISUAL_POSITION: Rope '${state.id}' requires finite particle positions.`);
+                if (!Number.isFinite(state.radius) || state.radius <= 0 || Math.fround(state.radius) === 0 ||
+                    !Number.isInteger(state.radialSegments) || state.radialSegments < 3 || state.radialSegments > 32)
+                    throw new Error(`TC_ROPE_VISUAL_SHAPE: Rope '${state.id}' has an invalid radius or radial segment count.`);
+                const old = views.get(state.id), same = old && old.signature === signature(state) && old.mesh.material === material;
+                const view = same ? old : create(state, material);
+                if (!same)
+                    created.push(view);
+                const positions = state.positions.flatMap(point => [...point]);
+                const changed = !same || positions.length !== view.positions.length || positions.some((value, index) => value !== view.positions[index]);
+                const update = changed ? matrices(state) : undefined;
+                staged.set(state.id, { view, created: !same, positions, ...(update ? { matrices: update.data, count: update.count } : {}) });
+            }
+        }
+        catch (error) {
+            for (const view of created)
+                remove(view);
+            throw error;
+        }
+        let changed = false;
+        for (const [id, view] of views)
+            if (!staged.has(id) || staged.get(id).view !== view) {
+                remove(view);
+                changed = true;
+            }
+        views.clear();
+        for (const [id, item] of staged) {
+            if (item.created) {
+                root.add(item.view.mesh);
+                changed = true;
+            }
+            if (item.matrices) {
+                item.view.mesh.instanceMatrix.array.set(item.matrices);
+                item.view.mesh.count = item.count;
+                item.view.mesh.visible = item.count > 0;
+                item.view.mesh.instanceMatrix.needsUpdate = true;
+                if (item.count > 0)
+                    item.view.mesh.computeBoundingSphere();
+                item.view.positions = item.positions;
+                changed = true;
+            }
+            views.set(id, item.view);
+        }
+        return changed;
+    };
+    return { root, sync, clear, dispose() { if (disposed)
+            return; clear(); root.removeFromParent(); disposed = true; } };
+}

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.13";
+export declare const SDK_VERSION = "0.3.15";
 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. Explicit body bindings apply a delayed
- * projection reaction to dynamic spheres; no full rigid-body coupling, segment/self collision or rope rendering. */
+/** 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. */
 export type RopeCollider = {
     kind: "sphere";
     id: string;
@@ -121,6 +121,24 @@ export interface RopeBodyCollider {
     readonly id: string;
     readonly entity: string;
 }
+/** Optional renderer-owned cylindrical segments following simulated particle positions. */
+export interface RopeVisualOptions {
+    material: string;
+    radius?: number;
+    radialSegments?: number;
+    castShadow?: boolean;
+    receiveShadow?: boolean;
+}
+/** Detached presentation state; native renderer objects are not exposed. */
+export interface RopeVisualState {
+    id: string;
+    material: string;
+    radius: number;
+    radialSegments: number;
+    castShadow: boolean;
+    receiveShadow: boolean;
+    positions: Vec3[];
+}
 export interface RopeDefinition {
     id: string;
     points: readonly Vec3[];
@@ -133,6 +151,8 @@ export interface RopeDefinition {
     autoStep?: boolean;
     /** Automatically sample and react to existing dynamic, non-trigger sphere bodies. Requires autoStep. */
     bodyColliders?: readonly RopeBodyCollider[];
+    /** Optional segmented presentation using an already-declared material id. */
+    visual?: RopeVisualOptions;
     substeps?: number;
     iterations?: number;
     damping?: number;
@@ -148,7 +168,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;
@@ -177,6 +197,8 @@ export interface RopeService {
     /** Explicit ticks for manual ropes only. Auto-stepped ropes reject this call. A failed batch leaves the rope unchanged. */
     step(id: string, ticks?: number): RopeState;
     inspect(id: string): RopeState;
+    /** Detached visual descriptions, sorted by rope id; empty when no visuals are requested. */
+    visuals(): readonly RopeVisualState[];
     setColliders(id: string, colliders: readonly RopeCollider[]): void;
     setAnchor(id: string, index: number, position: Vec3): void;
     releaseAnchor(id: string, index: number): void;

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.13";
+export const SDK_VERSION = "0.3.15";
 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);
+        },
+    };
+}