pelican-engine 0.3.13 → 0.3.14

package/AGENTS.md

@@ -140,9 +140,11 @@ 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 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 +152,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.

package/distribution.json

@@ -1,12 +1,12 @@
 {
   "format": "pelican.npm-distribution",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "files": {
-    "AGENTS.md": "8609edbd3ff882cc12a448b44f064a0241295e06d2b51f2dc674a92d1d7c4e1f",
+    "AGENTS.md": "4e031adeec0446317141f17c9f04c8d6c03f7339f00e27687331dd8051a4c807",
     "CONTRIBUTING.md": "0ffad5d841d90f319fc50a75b81d3c0ad6dab8d5d9bec2846c65c7f8358d5a50",
     "docs/AI-WORKFLOW.md": "aa992686df93f791795f6f3fce01713d812eea6a1b9556f07411ac5847278efa",
-    "docs/api/index.json": "3cd876657860e0b3f1f3d0c0c6d348c7ffaf3fe894cf8ba50eedb6c42f026b8e",
-    "docs/api/REFERENCE.md": "4e45c32451506aff95f94dda37b8c685400ddfb92245adf13ae92f576d42e2da",
+    "docs/api/index.json": "31ea1aa6c3531cdd2df129ae10fed54f666be4cb69c005c556690339f7b9a420",
+    "docs/api/REFERENCE.md": "ba657a3fb169e0f6c6e77ab1233cfb94125daf6ce4914ec0e960e4b1bf07d884",
     "docs/ARCHITECTURE.md": "3184b73592d466390e7793b1cf39bbb80d6052b523fba7e7cb377b5207074627",
     "docs/assets/pelican-mark.svg": "407b10cd7e292ea83cf5dba4046fb2f01c7d566a14014c55deda3a2984562b4d",
     "docs/CAPABILITIES.md": "92950817497d8c63db07830db96dc93c877befa8d038320feed1ae1f1a053cb1",
@@ -14,14 +14,14 @@
     "docs/GETTING-STARTED.md": "5519ebe4e513e8ae4517c04948ee9dc70bcb1e3d04a65d468a6537c838502663",
     "docs/GRAPHICS-GUIDE.md": "e3d0f7df6189ca3f88d81af5ffaf393f5d6bf39b9e66167bb2f64b39194b514c",
     "docs/npm/DISTRIBUTION.md": "ff25e039921a85ba253c27608c77ed614a036117d7a04f908a78d1e3ed3f19ef",
-    "docs/npm/GAME-AUTHOR.md": "8609edbd3ff882cc12a448b44f064a0241295e06d2b51f2dc674a92d1d7c4e1f",
+    "docs/npm/GAME-AUTHOR.md": "4e031adeec0446317141f17c9f04c8d6c03f7339f00e27687331dd8051a4c807",
     "docs/PELICAN-MIGRATION.md": "c5d6ab8e5186f4d36720a0a01d1a7e4157a5d386c5400e2db99571a7d10a1e49",
     "docs/PHYSICS-LIFECYCLE-ISSUE.md": "cc78917462de4e7e9b68e77c742192ce213b4be5b516d2ba943251fff46977ac",
     "docs/RENDER-BACKENDS.md": "d981ea94742a835d028db37d536fb7fba05102e37bc6274a37baf74f5034b954",
     "docs/ROADMAP.md": "29ac1c54f36064e23c17cfe7f549d6860889257a57d1227e322958aa9c281568",
-    "docs/STATUS.md": "bb0d0e62fb501d7a9dcedc68edb4d1cc37010aa44a174ee07b2d8d0608e05222",
+    "docs/STATUS.md": "75dc60834515914a7177198a01f7bbdd7a6437feac62cf555657dde7823b0a95",
     "docs/THIRD-PARTY-NOTICES.md": "58f9b72e2b4dfaaaf2a4c08b9bde9ecef3d2b7e7d65fccd782ed54f39fa76fdc",
-    "engine.manifest.json": "d2f94f6527b46bc681e3fe9e921f4833fac7bcf12b238217fe84835d2bfa0f88",
+    "engine.manifest.json": "e6b474c204d00972619b80f4157c57b4d748e89913fa5455583c961e11dcf875",
     "lib/assets/audio.js": "6facdce4e053afd172af5b9407569b035169844ea17b49f93f8b67f72b78895f",
     "lib/assets/errors.js": "70572678655c6e53179d31920d71f29882d373a0e12d560220bb0fc2cd74f2cc",
     "lib/assets/glb.js": "b808479a36299c154db97f50c16863a3b5a2c61f725e66bf01d01a5f62a288a5",
@@ -51,7 +51,7 @@
     "lib/experiments/world/types.js": "8e609bb71c20b858c77f0e9f90bb1319db8477b13f9f965f1a1e18524bf50881",
     "lib/experiments/world/world.js": "e335a96b1a2b217b69077f8e4b01aed7fd54b87e39bd5ac4138555d27ad9afe1",
     "lib/navigation/index.js": "5ee447333ff2152b1f08b34a68e16dd058448b0a4d2f8b3eae0fb8e76f52a1a9",
-    "lib/physics/index.js": "714bb1d2a7b9eef0776af2623f0964d3b19a220824a8e26a0ec24327c2c2436d",
+    "lib/physics/index.js": "d2f61506b26078c75ac12ea73a6ee17c62b833145dfe950fd66835659ede30b3",
     "lib/protocol/index.js": "875c9f7ba4e67adc182aa177bc5017da0907ff9c584ba523021a219b26e38c89",
     "lib/renderer/acceleration.js": "50ccafc9bc5b463470a23cffbdff8dc1a29a77bada44d21caf1eb0c3f9de2c65",
     "lib/renderer/browser.js": "0ef885517bef24b12a68e898d274643f5a8ee164d1956c27dc470a9a6c5a431e",
@@ -123,10 +123,11 @@
     "lib/runtime/world.js": "c43621fbaca8bd2b0d6477a96e60e895312f0f7b1eb97614b6e4f9b716129ea1",
     "lib/schema/index.js": "594429eecb4494c4af2f3d04537be3211f2c9297a1fc555bbba5d028d8627965",
     "lib/sdk/graph-values.js": "a58c00f127cb82aba5fd2824981942844e06d9a59a88a05e35d1d3df2fc7ed2f",
-    "lib/sdk/index.d.ts": "78196f514e088a9b0fe0f6dbf4bda544fe238a4e8dd7d1835588a9efdfadafe6",
-    "lib/sdk/index.js": "1176ce3b3d208919f7fe0db5f1b945928e4e52ad70932bcb9347e28584e67c4d",
-    "lib/simulation/rope-plugin.js": "4f098bb4da706969a7b35fd4143b8a55a025222d52a759ecdaa7d3390ab0e4f1",
-    "lib/simulation/rope.js": "0304f637696364dcc21c21f1f274cf2ba9c7dd2276073322071ba5f238fe34c1",
+    "lib/sdk/index.d.ts": "f8b095dc14e5a0804a0ba5e102f144c8775f4f4e0194ce2a24ff5bd7904c425c",
+    "lib/sdk/index.js": "3d70f1320a1739e255b461724b91d1a1fa3caeeba17a4d162155727d96f8026a",
+    "lib/simulation/rope-body-coupling.js": "70694b73d17c79f223803a51fbf4a4dae551b717cd29bbea1fa38386ac98d621",
+    "lib/simulation/rope-plugin.js": "050b64e82d196087aafe47047b3849e22fe8af362e3a7436dc0299c7a470d385",
+    "lib/simulation/rope.js": "ae653f44a8edaf206ba5a0cfe8d5bf5ebe7d3fc97714368c5b97e4f870a6ec9f",
     "lib/tools/api-index.js": "6aedc153a0ce8eaf18239b0368a76a8ae8e4397bd8e6cdf571889bc39265be5d",
     "lib/tools/browser-session.js": "1fa7f78d4752d8a59a55dc2283b4d42cd1df230f0d5a5dc80c6d78ade45b4cdb",
     "lib/tools/cli.js": "ad5e915f046cc2e6bf612edd1a88cc33758b1d2b0ce2f057be50e0a2c4770062",
@@ -197,7 +198,7 @@
     "licenses/undici-types/LICENSE": "a6db8096b2707bc0102d256917d4d33f298ba36d8c3f25de067a2b5bb379db27",
     "licenses/uniq/LICENSE": "e67aed7df22dc8031e4fcf5338fe91cb33e3817e5c58a99a2a2802eea9069791",
     "licenses/vite/LICENSE.md": "a22152baa1aef74402443008e767e7c689a524c0909d19b0431d97f5ab066a13",
-    "package.json": "fb9075ef4dec1793d1b5c1752a93a4fb855e9f0bdc98fbe90c4abe3a68893492",
+    "package.json": "d5874a4eba7869c56faef55c73a9b107eb209b6d3850f25943452e8fcfd83525",
     "README.md": "ff25e039921a85ba253c27608c77ed614a036117d7a04f908a78d1e3ed3f19ef",
     "web/index.html": "d89d6a5b5be3beae3627a8ed506ac308b165d264fb8696be3afd79fcca2f26ee"
   }

package/docs/STATUS.md

@@ -2,7 +2,7 @@
 
 ## 版本与发布
 
-- 当前版本为 `0.3.13`，包、锁文件、引擎、SDK、编译器和示例中的版本保持一致。下一项功能完成后统一递增并推送；相同版本不能重复发布。
+- 当前版本为 `0.3.14`，包、锁文件、引擎、SDK、编译器和示例中的版本保持一致。下一项功能完成后统一递增并推送；相同版本不能重复发布。
 - 推送主线会通过 GitHub Actions 和 npm 可信发布更新 `latest`；GitHub Release 用于记录里程碑。历史版本和旧标签保持原样，不代表当前源码通过。
 - 当前按用户要求仅允许编译和构建，不运行测试、浏览器、GPU、性能或其他验证。普通版本号不意味着运行行为、硬件或完整引擎已验收。
 
@@ -13,7 +13,7 @@
 - 刚体首步前删除存在已知缺陷；历史候选存在旧快照兼容及危险历史回放风险，不得通过修改夹具或在主进程回放危险历史掩盖。有关背景与原始证据保留在历史任务文档中。
 - 正交网格导航新增批量障碍更新接口；它只处理单个网格的阻挡状态，不等于世界流送、实体变换或物理联动。该增量尚未进行运行行为验证。
 - CPU 粒子绳索已接入 `ctx.ropes` 和 Host 快照，支持手动或自动固定步进。显式绑定的动态非触发球体可在物理阶段后被采样，并接收绳索投影产生的反冲量；其他采样球体/平面仍为单向。尚无绳索网格渲染、完整双向求解、绳段/自碰撞或撕裂。该增量尚未进行运行行为或快照兼容验证。
-- 接触反冲量可手动映射到其他刚体；球体绑定的自动反应仍是延迟采样，不含刚体有效质量、速度反馈、摩擦或连续碰撞，不代表完整双向耦合。接口和示例尚未执行运行或快照验证。
+- 动态球体绑定的接触响应已纳入刚体接触点速度、有效逆质量和转动惯量；绳索阶段使用虚拟状态、按绳索顺序求解并延迟提交冲量。真实刚体位移在下一物理步更新，仍无全局耦合子步、摩擦、恢复系数或连续碰撞，不代表完整双向物理。稳定性、守恒、运行和快照兼容尚未验证。
 - 布料、绳索、软体、流体、连续世界、导航、动画、音频和其他首发能力仍需按各自依赖完成，不能把独立候选或局部实现写成整项完成。
 
 ## 单线接续

package/docs/api/REFERENCE.md

@@ -1,4 +1,4 @@
-# pelican 0.3.13 API 索引
+# pelican 0.3.14 API 索引
 
 Installed declarations: `lib/sdk/index.d.ts` (relative to the package root).
 The signatures below come from the same public SDK source as repository games.
@@ -11,7 +11,7 @@ Source-file paths and line numbers are build-time provenance only; TypeScript so
 来源：`packages/sdk/src/index.ts:2`
 
 ```ts
-SDK_VERSION = "0.3.13"
+SDK_VERSION = "0.3.14"
 ```
 
 ## Vec2
@@ -308,7 +308,7 @@ export interface RopeDefinition {
 ```ts
 export interface RopeContact {
   tick: number; 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/docs/api/index.json

@@ -1,14 +1,14 @@
 {
   "format": "pelican.api-index",
   "version": 1,
-  "engineVersion": "0.3.13",
+  "engineVersion": "0.3.14",
   "entry": "pelican-engine",
   "source": "packages/sdk/src/index.ts",
   "symbols": [
     {
       "name": "SDK_VERSION",
       "kind": "constant",
-      "signature": "SDK_VERSION = \"0.3.13\"",
+      "signature": "SDK_VERSION = \"0.3.14\"",
       "line": 2
     },
     {
@@ -232,7 +232,7 @@
     {
       "name": "RopeContact",
       "kind": "InterfaceDeclaration",
-      "signature": "export interface RopeContact {\n  tick: number; particle: number; colliderId: string; penetration: number;\n  /** Opposite of particle projection impulses, N·s; absent in older snapshots. */\n  reactionImpulse?: Vec3;\n  /** Angular impulse about the world origin; absent in older snapshots. */\n  reactionAngularImpulse?: Vec3;\n}",
+      "signature": "export interface RopeContact {\n  tick: number; particle: number; colliderId: string; penetration: number;\n  /** Opposite of particle contact impulses, N·s; absent in older snapshots. */\n  reactionImpulse?: Vec3;\n  /** Angular impulse about the world origin; absent in older snapshots. */\n  reactionAngularImpulse?: Vec3;\n}",
       "line": 147,
       "fields": [
         "tick",

package/docs/npm/GAME-AUTHOR.md

@@ -140,9 +140,11 @@ 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 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 +152,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.

package/engine.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "pelican-engine",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "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/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.14";
 export type Vec2 = readonly [number, number];
 export type Vec3 = readonly [number, number, number];
 export type Vec4 = readonly [number, number, number, number];
@@ -148,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.13";
+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,6 +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) {
@@ -93,7 +94,7 @@ function validateWorldBindings(entries, context, world) {
                 fail("SNAPSHOT", `Bound body '${binding.entity}' must exist as a dynamic, non-trigger sphere in the restored world.`);
         }
 }
-/** Position-based sphere reactions are delayed and do not yet solve body effective mass. */
+/** 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))
@@ -170,7 +171,7 @@ export const createRopePlugin = (context) => {
             alive();
             ensureRefs();
             const committed = [];
-            const reactions = new Map();
+            const bodies = new Map();
             try {
                 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);
@@ -191,33 +192,27 @@ export const createRopePlugin = (context) => {
                         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 => {
-                            const sphere = bridge.sampleSphere(binding.entity);
-                            return { kind: "sphere", id: binding.id, center: [...sphere.center], radius: sphere.radius };
+                            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]);
                     }
-                    const state = entry.solver.step();
-                    const byCollider = new Map(live.map(binding => [binding.id, binding.entity]));
-                    for (const contact of state.contacts) {
-                        const entity = byCollider.get(contact.colliderId), impulse = contact.reactionImpulse;
-                        if (!entity || !impulse)
-                            continue;
-                        const total = reactions.get(entity) ?? [0, 0, 0];
-                        for (let k = 0; k < 3; k++)
-                            total[k] += impulse[k];
-                        if (!total.every(Number.isFinite))
-                            fail("NUMERIC", `Reaction for '${entity}' exceeded finite bounds.`);
-                        reactions.set(entity, total);
-                    }
+                    entry.solver.step(1, coupled.size ? createRopeBodyCoupling(coupled) : undefined);
                 }
-                const batch = [...reactions].filter(([, impulse]) => impulse.some(value => value !== 0))
-                    .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
-                    .map(([entity, impulse]) => ({ entity, impulse }));
+                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);
             }

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}`;

package/package.json

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