pelican-engine 0.3.12 → 0.3.14

package/AGENTS.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/distribution.json

@@ -1,12 +1,12 @@
 {
   "format": "pelican.npm-distribution",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "files": {
-    "AGENTS.md": "3dabfa6d929c2a64fb70e64ad7588c921ace5a8c6f664c0e9e3c6211727e4d57",
+    "AGENTS.md": "4e031adeec0446317141f17c9f04c8d6c03f7339f00e27687331dd8051a4c807",
     "CONTRIBUTING.md": "0ffad5d841d90f319fc50a75b81d3c0ad6dab8d5d9bec2846c65c7f8358d5a50",
     "docs/AI-WORKFLOW.md": "aa992686df93f791795f6f3fce01713d812eea6a1b9556f07411ac5847278efa",
-    "docs/api/index.json": "5af157ee6b03d4d9cb4e26b53540bf92105f20d9d56a443383a39d185f2bced0",
-    "docs/api/REFERENCE.md": "7cc71bcb17be6a914602101bcd3a4e353c026fdab12d4bc35d869caaef8f787c",
+    "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": "3dabfa6d929c2a64fb70e64ad7588c921ace5a8c6f664c0e9e3c6211727e4d57",
+    "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": "41d6801a0e201ec0cbfdd6ef9cc957ab3a2d5416bf1ca505b51c8f552b67fd6d",
+    "docs/STATUS.md": "75dc60834515914a7177198a01f7bbdd7a6437feac62cf555657dde7823b0a95",
     "docs/THIRD-PARTY-NOTICES.md": "58f9b72e2b4dfaaaf2a4c08b9bde9ecef3d2b7e7d65fccd782ed54f39fa76fdc",
-    "engine.manifest.json": "38fbebb2e3fdfe5d036276ad98245ecbf2924c68dbf47a4410c17c393a400b7f",
+    "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": "19eeab8b07a3fd25b5369e162a8f82ae9509341f928f21806cd5ecfd3058df5b",
+    "lib/physics/index.js": "d2f61506b26078c75ac12ea73a6ee17c62b833145dfe950fd66835659ede30b3",
     "lib/protocol/index.js": "875c9f7ba4e67adc182aa177bc5017da0907ff9c584ba523021a219b26e38c89",
     "lib/renderer/acceleration.js": "50ccafc9bc5b463470a23cffbdff8dc1a29a77bada44d21caf1eb0c3f9de2c65",
     "lib/renderer/browser.js": "0ef885517bef24b12a68e898d274643f5a8ee164d1956c27dc470a9a6c5a431e",
@@ -104,7 +104,7 @@
     "lib/runtime/error.js": "544d52d5426c53266c902e7b5afda1ea76a84ac12b6027879aed647423acbbad",
     "lib/runtime/events.js": "e1d8fd5005be19d7a26d51023b97245318bce4b777748562d5e453b10f0faefe",
     "lib/runtime/game-services.js": "a026966789aca4c45a5303950f7bc757cc6c12f223cbeaba13f6d514cac8575b",
-    "lib/runtime/host.js": "e9b4e0028d80549114d9b2f92cd01500403a1c381d6fc295175ee1e33cd7bed7",
+    "lib/runtime/host.js": "b4012d63dc2a5ffb9a32840801848f590e842e8eee5f2ec4f5f1ffb718e7477c",
     "lib/runtime/material-parameters.js": "c535afa5ff3d92f399da142a45f22541598e374b6a8e4051a65f8f20dd8fb970",
     "lib/runtime/plugins.js": "8e609bb71c20b858c77f0e9f90bb1319db8477b13f9f965f1a1e18524bf50881",
     "lib/runtime/postprocess-contract.js": "8e609bb71c20b858c77f0e9f90bb1319db8477b13f9f965f1a1e18524bf50881",
@@ -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": "ecf2c08cdfe4f9bf0b184dfe9dbdcc1104b1c32936edf8217f168df2adf17d75",
-    "lib/sdk/index.js": "7945cabb4824d88987ae450eeb36edaa3c4681fc589b0a6efeace1d1b8113c0b",
-    "lib/simulation/rope-plugin.js": "6c1eef7109d8838c1a41400698998ff511c24a22c30cacb4c2c5ec0d02e1034b",
-    "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": "de6c6a5791dd6e0e31247c595beb9b325b0e85a489c5fcf0e6f2a6a02bc36092",
+    "package.json": "d5874a4eba7869c56faef55c73a9b107eb209b6d3850f25943452e8fcfd83525",
     "README.md": "ff25e039921a85ba253c27608c77ed614a036117d7a04f908a78d1e3ed3f19ef",
     "web/index.html": "d89d6a5b5be3beae3627a8ed506ac308b165d264fb8696be3afd79fcca2f26ee"
   }

package/docs/STATUS.md

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