pelican-engine 0.3.16 → 0.3.18

package/AGENTS.md

@@ -147,8 +147,20 @@ solver snapshots without this field retain particle-only behavior when migrated;
 engine-version restrictions still apply. Plane contacts use particle endpoints.
 The segment index names its first particle; `fraction` runs toward the next.
 Work increases with segment, sphere, substep and iteration counts. This does not
-provide continuous collision detection or self collision, and the segment solver
-and snapshot migration have not been runtime validated.
+provide continuous collision detection; the segment solver and snapshot migration
+have not been runtime validated.
+
+New ropes also resolve discrete self-contact between non-adjacent segments using
+sweep-and-prune and endpoint projection. `inspect(id).selfContacts` reports
+segment indices, closest-point fractions and maximum overlap; `selfCollisions`
+reports the active mode. Set `selfCollisions: false` to disable it. Adjacent
+segments and collisions between separate ropes are not handled. Immovable anchored
+endpoints stay fixed, and contacts introduced by corrections can wait until the
+next iteration. Dense overlap can approach quadratic work. Snapshots from before
+this feature retain the disabled mode when migrated; Host engine-version rules
+still apply. This is unverified discrete contact, not a guarantee against
+penetration, continuous collision, friction or full rope physics. The source
+checkout includes `examples/rope-self`.
 
 For optional visual presentation, declare a material in `defineGame({ materials:
 [...] })` and create the rope with `visual: { material: "your-material-id" }`.
@@ -206,10 +218,32 @@ checkpoint. It must not be represented as complete two-way rigid-body interactio
 
 This is an unverified development-stage increment, not complete rope physics:
 the optional segmented visual does not provide a continuous deformable rope mesh,
-general rigid-body coupling, self collision, or tearing. Plane normals must be unit length; `offset` is the signed
+general rigid-body coupling, continuous collision, cross-rope 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.
 
+### Development-stage triangular cloth
+
+Declare a material in `defineGame({ materials: [...] })`, then use
+`ctx.cloth.create({ id, points, triangles, mass, autoStep: true, visual: {
+material: "material-id" } })`. Triangles reference particle indices and shared
+edges must be manifold with consistent winding. Anchors are explicit; no particles
+are pinned by default. Automatic cloth advances after the physics phase;
+manual cloth uses `ctx.cloth.step`. Use `setAnchor`, `releaseAnchor`, `applyForce`
+(next tick), `applyImpulse`, `setColliders`, `inspect`, and `destroy` to manage it.
+The source checkout includes `examples/cloth-sheet`.
+
+The CPU solver uses edge distance constraints and an optional distance-based
+bending approximation (`bending: true` by default). Sampled planes and spheres
+only move cloth particles; they do not receive reactions. Contacts do not cover
+triangle interiors or edges. There is no self-contact, cloth–rope interaction,
+rigid-body coupling, tearing, friction or continuous collision. The optional
+visual deforms the actual triangle mesh; UVs may be provided per particle or use a
+planar projection. Use a double-sided material when both sides must be visible.
+Collapsed or unrepresentable triangles return `TC_CLOTH_VISUAL_DEGENERATE` rather
+than being silently replaced. Runtime, GPU, performance, stability and snapshot
+compatibility have not been validated; this is not complete cloth physics.
+
 Keyboard bindings use the browser's `KeyboardEvent.key` values, not physical
 `KeyboardEvent.code` values. For example, use `input: { up: ["w", "W", "ArrowUp"],
 restart: ["r", "R"] }`, not `"KeyW"` or `"KeyR"`. Letter case depends on the

package/distribution.json

@@ -1,12 +1,12 @@
 {
   "format": "pelican.npm-distribution",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "files": {
-    "AGENTS.md": "dd3925d893723b32047d2b0fe46a372189873574afab91f2a9ce0f4653845f36",
+    "AGENTS.md": "bd599d76513789d143cc4a4ed41968806f6e2e07d8aeb85f15be89da684bad6b",
     "CONTRIBUTING.md": "0ffad5d841d90f319fc50a75b81d3c0ad6dab8d5d9bec2846c65c7f8358d5a50",
     "docs/AI-WORKFLOW.md": "aa992686df93f791795f6f3fce01713d812eea6a1b9556f07411ac5847278efa",
-    "docs/api/index.json": "daa7ab5af413e24a1de98a6c90eecbab40f983ab3bd7984d85e3356efb82da99",
-    "docs/api/REFERENCE.md": "6eef5cfff041c36b2457c87a77cb3bb8710d02b3aca3063c1d5e516921d87f68",
+    "docs/api/index.json": "d266290335d4f291374dffdd2507896ae56cc06cdb9c325a0412cae6b40b993c",
+    "docs/api/REFERENCE.md": "9d13e6f3637a016056bbaea2b8204052a79100e4873cde9b60abe7920e0571a2",
     "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": "dd3925d893723b32047d2b0fe46a372189873574afab91f2a9ce0f4653845f36",
+    "docs/npm/GAME-AUTHOR.md": "bd599d76513789d143cc4a4ed41968806f6e2e07d8aeb85f15be89da684bad6b",
     "docs/PELICAN-MIGRATION.md": "c5d6ab8e5186f4d36720a0a01d1a7e4157a5d386c5400e2db99571a7d10a1e49",
     "docs/PHYSICS-LIFECYCLE-ISSUE.md": "cc78917462de4e7e9b68e77c742192ce213b4be5b516d2ba943251fff46977ac",
     "docs/RENDER-BACKENDS.md": "d981ea94742a835d028db37d536fb7fba05102e37bc6274a37baf74f5034b954",
     "docs/ROADMAP.md": "29ac1c54f36064e23c17cfe7f549d6860889257a57d1227e322958aa9c281568",
-    "docs/STATUS.md": "363e45b13d7af2134309cdc7622e903224672bcfdfc56fc4495329eaf1409588",
+    "docs/STATUS.md": "d995a70ac23f68145864f80cb7e16a84a724d386f233cad90cdff79ddff9b25a",
     "docs/THIRD-PARTY-NOTICES.md": "58f9b72e2b4dfaaaf2a4c08b9bde9ecef3d2b7e7d65fccd782ed54f39fa76fdc",
-    "engine.manifest.json": "07aeec81ff664b6f34a1b2435879d19fa59ff4db92bf5053c5aabd2a94300a0a",
+    "engine.manifest.json": "9467245c8647bc3a027f3da914e2ffc8405f5040e2fc0382c348d812916df514",
     "lib/assets/audio.js": "6facdce4e053afd172af5b9407569b035169844ea17b49f93f8b67f72b78895f",
     "lib/assets/errors.js": "70572678655c6e53179d31920d71f29882d373a0e12d560220bb0fc2cd74f2cc",
     "lib/assets/glb.js": "b808479a36299c154db97f50c16863a3b5a2c61f725e66bf01d01a5f62a288a5",
@@ -54,9 +54,10 @@
     "lib/physics/index.js": "d2f61506b26078c75ac12ea73a6ee17c62b833145dfe950fd66835659ede30b3",
     "lib/protocol/index.js": "875c9f7ba4e67adc182aa177bc5017da0907ff9c584ba523021a219b26e38c89",
     "lib/renderer/acceleration.js": "50ccafc9bc5b463470a23cffbdff8dc1a29a77bada44d21caf1eb0c3f9de2c65",
-    "lib/renderer/browser.js": "46e7fd62b7751f3168c171459641dcccfefe9888b60945062b999998d842a672",
+    "lib/renderer/browser.js": "eef66f11cf400ad73532c63e92047914108f04b9c4d9010fd05d6f03caad2bc8",
     "lib/renderer/bsdf.js": "d6d3cd69dadb418dfb794367ac8158ef242799e248b13f4f88edeeb67ee08c69",
     "lib/renderer/checkpoint.js": "7d6b0447b924eb260aa6a8724d17ad69e2949186b2f639dff5f6bbea388f8c62",
+    "lib/renderer/cloth-visuals.js": "8da360de46b9478107e7b747b2bc654f02e50364235cb88911db9e711c9fd1c6",
     "lib/renderer/compute-executor.js": "7a9d199a1ab4f56fc99c50f82760e18169a905e63a8fa24011fb86c03e8c890a",
     "lib/renderer/compute-texture-assets.js": "05a7c79ce3c8685df67b0aed3ac9100fd414bfd53d08a45581aa324f4db69630",
     "lib/renderer/compute-view-contract.js": "8e609bb71c20b858c77f0e9f90bb1319db8477b13f9f965f1a1e18524bf50881",
@@ -66,7 +67,7 @@
     "lib/renderer/emissive-lights.js": "93ee4442cb1eb9a075c5a7a02560bb0e9af2b99d4e55d9f46d73e477e725a599",
     "lib/renderer/environment-importance.js": "b192af1173eb8235ab3f8cbe34fe7de92fe35bf970c214d7d3a122a5c77006d9",
     "lib/renderer/environment.js": "e7eff454f49e969f188d58e936cb41c217413902af5de4d9fefa3212c3394692",
-    "lib/renderer/gameplay.js": "e77b116413339af97d1e24f59b77035eeea8297ddc29963bbe21173c10077673",
+    "lib/renderer/gameplay.js": "64ab8f09305f5e9236a27e8e5afd675054b0de5edc67377b962c1018db8541f8",
     "lib/renderer/geometry.js": "8f331cb3547751a70099d80441b146e5a66072c94e23cc9f5716694d0efa1019",
     "lib/renderer/graph-expressions.js": "3cc20d472f3894976b6c8e503b915c3eaf12de9c6d93bae45edb12b0f7e0dc4e",
     "lib/renderer/graph-tsl.js": "d698d22fd2977aabd3f7331e8f3d46d8cbf80695ea503b9326cff470859e84b4",
@@ -105,7 +106,7 @@
     "lib/runtime/error.js": "544d52d5426c53266c902e7b5afda1ea76a84ac12b6027879aed647423acbbad",
     "lib/runtime/events.js": "e1d8fd5005be19d7a26d51023b97245318bce4b777748562d5e453b10f0faefe",
     "lib/runtime/game-services.js": "a026966789aca4c45a5303950f7bc757cc6c12f223cbeaba13f6d514cac8575b",
-    "lib/runtime/host.js": "b4012d63dc2a5ffb9a32840801848f590e842e8eee5f2ec4f5f1ffb718e7477c",
+    "lib/runtime/host.js": "f3e2ced4c936bb7454a746fa0525b1d4eecf6153b9c1345563e76bae8f90e219",
     "lib/runtime/material-parameters.js": "c535afa5ff3d92f399da142a45f22541598e374b6a8e4051a65f8f20dd8fb970",
     "lib/runtime/plugins.js": "8e609bb71c20b858c77f0e9f90bb1319db8477b13f9f965f1a1e18524bf50881",
     "lib/runtime/postprocess-contract.js": "8e609bb71c20b858c77f0e9f90bb1319db8477b13f9f965f1a1e18524bf50881",
@@ -124,11 +125,14 @@
     "lib/runtime/world.js": "c43621fbaca8bd2b0d6477a96e60e895312f0f7b1eb97614b6e4f9b716129ea1",
     "lib/schema/index.js": "594429eecb4494c4af2f3d04537be3211f2c9297a1fc555bbba5d028d8627965",
     "lib/sdk/graph-values.js": "a58c00f127cb82aba5fd2824981942844e06d9a59a88a05e35d1d3df2fc7ed2f",
-    "lib/sdk/index.d.ts": "e9be65ce2d1d2cb59bbf8f1e8749887e7f17aa5cdd0faab30d310b2e2ff42a5f",
-    "lib/sdk/index.js": "68283b99b69b822d5030e71d86db8ad6989533e694cba5ed765bf3c307e9583f",
+    "lib/sdk/index.d.ts": "c6c208dfa782bc388c3d946bbd3bf4149556e11a6b0f961a90918387aa0939bb",
+    "lib/sdk/index.js": "5332f2ab581aaf01e1fdb1e91c97c3a7106ab610f28e67bb7388ed548f387c6f",
+    "lib/simulation/cloth-plugin.js": "bef005219aef6aab6d91d599d9b8c94f1523d4d7141edf54bc5ec0514a452ef8",
+    "lib/simulation/cloth.js": "595dc52d6b8c1ce55cd1b2863282b7c6b22e021767ad831ed5b9e572a5bf5bcd",
     "lib/simulation/rope-body-coupling.js": "70694b73d17c79f223803a51fbf4a4dae551b717cd29bbea1fa38386ac98d621",
-    "lib/simulation/rope-plugin.js": "e96bf5c6ead475b8f14d65d5290770025a4cef6e21d9d11bbe73ae4173b20062",
-    "lib/simulation/rope.js": "3ceb972b55ba197e526b6c8896b2e7a48dcb05f38be0a0efbca188399eaf5469",
+    "lib/simulation/rope-plugin.js": "08c7c4800053b3e8f255b6dd5be2b532b8e259300666c31de5494d15704717d4",
+    "lib/simulation/rope-self-collision.js": "4d8dc5d5a88f0ae0ad5463f553f49b2ad3c8c126b98344a0966f619635bdb17f",
+    "lib/simulation/rope.js": "e00c1cfb31e3f9bee7465e99897d162a0465eb5a41718599d8ab71b03bbe2dcc",
     "lib/tools/api-index.js": "6aedc153a0ce8eaf18239b0368a76a8ae8e4397bd8e6cdf571889bc39265be5d",
     "lib/tools/browser-session.js": "1fa7f78d4752d8a59a55dc2283b4d42cd1df230f0d5a5dc80c6d78ade45b4cdb",
     "lib/tools/cli.js": "ad5e915f046cc2e6bf612edd1a88cc33758b1d2b0ce2f057be50e0a2c4770062",
@@ -199,7 +203,7 @@
     "licenses/undici-types/LICENSE": "a6db8096b2707bc0102d256917d4d33f298ba36d8c3f25de067a2b5bb379db27",
     "licenses/uniq/LICENSE": "e67aed7df22dc8031e4fcf5338fe91cb33e3817e5c58a99a2a2802eea9069791",
     "licenses/vite/LICENSE.md": "a22152baa1aef74402443008e767e7c689a524c0909d19b0431d97f5ab066a13",
-    "package.json": "4ff56c89dfd8f7583f2ad1d2c625b5ea0b01a9f3f163d70ef287af4401b47383",
+    "package.json": "06a0e516918cab7a2a8856d74593ee5c746d1105f33a591d9d15385e6aa37662",
     "README.md": "ff25e039921a85ba253c27608c77ed614a036117d7a04f908a78d1e3ed3f19ef",
     "web/index.html": "d89d6a5b5be3beae3627a8ed506ac308b165d264fb8696be3afd79fcca2f26ee"
   }

package/docs/STATUS.md

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