pelican-engine 0.3.13 → 0.3.15

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

@@ -1,12 +1,12 @@
 {
   "format": "pelican.npm-distribution",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "files": {
-    "AGENTS.md": "8609edbd3ff882cc12a448b44f064a0241295e06d2b51f2dc674a92d1d7c4e1f",
+    "AGENTS.md": "e12abbd5320cd6823a1689c5d76a260b1e9f2293f6d9c871ec11ed0c497bcd3e",
     "CONTRIBUTING.md": "0ffad5d841d90f319fc50a75b81d3c0ad6dab8d5d9bec2846c65c7f8358d5a50",
     "docs/AI-WORKFLOW.md": "aa992686df93f791795f6f3fce01713d812eea6a1b9556f07411ac5847278efa",
-    "docs/api/index.json": "3cd876657860e0b3f1f3d0c0c6d348c7ffaf3fe894cf8ba50eedb6c42f026b8e",
-    "docs/api/REFERENCE.md": "4e45c32451506aff95f94dda37b8c685400ddfb92245adf13ae92f576d42e2da",
+    "docs/api/index.json": "72cb96387ddbb933920a3589457e585cf16335ac13a95868b1306ff606818136",
+    "docs/api/REFERENCE.md": "af4f340f6209272eceb6136942642f2c5f090db3fe15666ec31dc1c12ac71c46",
     "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": "e12abbd5320cd6823a1689c5d76a260b1e9f2293f6d9c871ec11ed0c497bcd3e",
     "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": "cd0ff5eb4bdcad4ef9d040f91f1239827e25e47e12d36e68a82f7f230e0b27f9",
     "docs/THIRD-PARTY-NOTICES.md": "58f9b72e2b4dfaaaf2a4c08b9bde9ecef3d2b7e7d65fccd782ed54f39fa76fdc",
-    "engine.manifest.json": "d2f94f6527b46bc681e3fe9e921f4833fac7bcf12b238217fe84835d2bfa0f88",
+    "engine.manifest.json": "57443c5c26e312da99a6d224eaec66e964282cdfbffb167d76d0b4242ade0a69",
     "lib/assets/audio.js": "6facdce4e053afd172af5b9407569b035169844ea17b49f93f8b67f72b78895f",
     "lib/assets/errors.js": "70572678655c6e53179d31920d71f29882d373a0e12d560220bb0fc2cd74f2cc",
     "lib/assets/glb.js": "b808479a36299c154db97f50c16863a3b5a2c61f725e66bf01d01a5f62a288a5",
@@ -51,10 +51,10 @@
     "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",
+    "lib/renderer/browser.js": "46e7fd62b7751f3168c171459641dcccfefe9888b60945062b999998d842a672",
     "lib/renderer/bsdf.js": "d6d3cd69dadb418dfb794367ac8158ef242799e248b13f4f88edeeb67ee08c69",
     "lib/renderer/checkpoint.js": "7d6b0447b924eb260aa6a8724d17ad69e2949186b2f639dff5f6bbea388f8c62",
     "lib/renderer/compute-executor.js": "7a9d199a1ab4f56fc99c50f82760e18169a905e63a8fa24011fb86c03e8c890a",
@@ -67,7 +67,7 @@
     "lib/renderer/environment-importance.js": "b192af1173eb8235ab3f8cbe34fe7de92fe35bf970c214d7d3a122a5c77006d9",
     "lib/renderer/environment.js": "e7eff454f49e969f188d58e936cb41c217413902af5de4d9fefa3212c3394692",
     "lib/renderer/gameplay.js": "e77b116413339af97d1e24f59b77035eeea8297ddc29963bbe21173c10077673",
-    "lib/renderer/geometry.js": "262674d0b8c45f71a937ef5f8fde023287e14f985bd80ffcf11aa778523ba4bc",
+    "lib/renderer/geometry.js": "8f331cb3547751a70099d80441b146e5a66072c94e23cc9f5716694d0efa1019",
     "lib/renderer/graph-expressions.js": "3cc20d472f3894976b6c8e503b915c3eaf12de9c6d93bae45edb12b0f7e0dc4e",
     "lib/renderer/graph-tsl.js": "d698d22fd2977aabd3f7331e8f3d46d8cbf80695ea503b9326cff470859e84b4",
     "lib/renderer/graph.js": "1d5e9afff7d4f43c26c0bb82f3b6cb475a75af2750101114f0d7b03193bccfa7",
@@ -82,6 +82,7 @@
     "lib/renderer/postprocess.js": "bac52cbec8449b66e35c6ff0b80486b062a7d7d52961b9ae5073b3fb9f24622a",
     "lib/renderer/render-buffers.js": "db61cb80f691616b45ddb98231805469d54c12237497f6e4c709c1affc23cbf9",
     "lib/renderer/render-textures.js": "fe98d2657701350eaeb731c2158db22e44e9a8a308f92e661f780f66fa46428c",
+    "lib/renderer/rope-visuals.js": "4bceb1c55ffc7283b24136e126c07e7e28fb631a2f4cb3afd619b1eab6db80fa",
     "lib/renderer/startup.js": "2e4f8de3362358aad23504304219533f8ef25825abb3bb702bc960e2cfa79a1d",
     "lib/renderer/surface-capture.js": "847edf8c764a4e8b586bee9a441013ba362875e83a957c65ad51433ae623e59f",
     "lib/renderer/surface-gpu.js": "0db76e8873999c6b5ee3da0456e4b60d5df8d5154886a29bc0895782fdd9036b",
@@ -123,10 +124,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": "6108606fb38dae6c044e34d7589baa205bec472b2eff1181f1df278c21deb56f",
+    "lib/sdk/index.js": "950429d5fdcd8e8ad7dfee727c859d127d4f26f45ac0065bbcb938629a3784af",
+    "lib/simulation/rope-body-coupling.js": "70694b73d17c79f223803a51fbf4a4dae551b717cd29bbea1fa38386ac98d621",
+    "lib/simulation/rope-plugin.js": "000f2d74d8ec95eeb27baf556d1d97ead80babbe212eaf5a3117f2a65e81694c",
+    "lib/simulation/rope.js": "1a9dff898d43d9e9a39f0be4ece5a17761cf8aae4a287de9da4b95d26235d441",
     "lib/tools/api-index.js": "6aedc153a0ce8eaf18239b0368a76a8ae8e4397bd8e6cdf571889bc39265be5d",
     "lib/tools/browser-session.js": "1fa7f78d4752d8a59a55dc2283b4d42cd1df230f0d5a5dc80c6d78ade45b4cdb",
     "lib/tools/cli.js": "ad5e915f046cc2e6bf612edd1a88cc33758b1d2b0ce2f057be50e0a2c4770062",
@@ -197,7 +199,7 @@
     "licenses/undici-types/LICENSE": "a6db8096b2707bc0102d256917d4d33f298ba36d8c3f25de067a2b5bb379db27",
     "licenses/uniq/LICENSE": "e67aed7df22dc8031e4fcf5338fe91cb33e3817e5c58a99a2a2802eea9069791",
     "licenses/vite/LICENSE.md": "a22152baa1aef74402443008e767e7c689a524c0909d19b0431d97f5ab066a13",
-    "package.json": "fb9075ef4dec1793d1b5c1752a93a4fb855e9f0bdc98fbe90c4abe3a68893492",
+    "package.json": "c2ee39a9767bcaac74cc5f3d10ad1617ae5078b332dde7f709a4dde6952c0e79",
     "README.md": "ff25e039921a85ba253c27608c77ed614a036117d7a04f908a78d1e3ed3f19ef",
     "web/index.html": "d89d6a5b5be3beae3627a8ed506ac308b165d264fb8696be3afd79fcca2f26ee"
   }

package/docs/STATUS.md

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