pelican-engine 0.3.19 → 0.3.21

package/AGENTS.md

@@ -157,8 +157,8 @@ 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
+this feature retain the disabled mode when migrated; invalid or duplicate self
+contacts are rejected atomically; 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`.
 

package/distribution.json

@@ -1,12 +1,12 @@
 {
   "format": "pelican.npm-distribution",
-  "version": "0.3.19",
+  "version": "0.3.21",
   "files": {
-    "AGENTS.md": "5d68c4774e081f092c9181fc4dfab5de2a13523d7d1666dd09419cf95cc09ed1",
+    "AGENTS.md": "3efeb184ac3c53692804ec50927b642053dbcf5c51ad25ea135aed15e4dbf7ff",
     "CONTRIBUTING.md": "0ffad5d841d90f319fc50a75b81d3c0ad6dab8d5d9bec2846c65c7f8358d5a50",
     "docs/AI-WORKFLOW.md": "aa992686df93f791795f6f3fce01713d812eea6a1b9556f07411ac5847278efa",
-    "docs/api/index.json": "c058fa1297ee63c957395dc7963a6edd981c4c6f4c506555d3e26e8ca339d7d2",
-    "docs/api/REFERENCE.md": "cdf9274b8bc847b94f9ad77b57a5add4736d5412f7151477a0e2caa7057b94d0",
+    "docs/api/index.json": "149022d834a6bbdf4e4224a9460d3d5545792c5ef01024485a69f65531d1b310",
+    "docs/api/REFERENCE.md": "b6d064bd933d9d4f26e8224cf2796fbe7bc52b22d33ff35e48f878d76af02a90",
     "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": "5d68c4774e081f092c9181fc4dfab5de2a13523d7d1666dd09419cf95cc09ed1",
+    "docs/npm/GAME-AUTHOR.md": "3efeb184ac3c53692804ec50927b642053dbcf5c51ad25ea135aed15e4dbf7ff",
     "docs/PELICAN-MIGRATION.md": "c5d6ab8e5186f4d36720a0a01d1a7e4157a5d386c5400e2db99571a7d10a1e49",
     "docs/PHYSICS-LIFECYCLE-ISSUE.md": "cc78917462de4e7e9b68e77c742192ce213b4be5b516d2ba943251fff46977ac",
     "docs/RENDER-BACKENDS.md": "d981ea94742a835d028db37d536fb7fba05102e37bc6274a37baf74f5034b954",
     "docs/ROADMAP.md": "29ac1c54f36064e23c17cfe7f549d6860889257a57d1227e322958aa9c281568",
-    "docs/STATUS.md": "65bdaf52f77b2f8bacc1d2d3809e8462482a0de0fd3e013203af55c80fc5ff8f",
+    "docs/STATUS.md": "bdb601521fc37c91de6d4f404f714cb2170d9b6e518c861d6d7fb21d7309bf67",
     "docs/THIRD-PARTY-NOTICES.md": "58f9b72e2b4dfaaaf2a4c08b9bde9ecef3d2b7e7d65fccd782ed54f39fa76fdc",
-    "engine.manifest.json": "ad46b5ec17bcc1c4164bb2eb7431a5b448095db528917838c3706143ce517c1b",
+    "engine.manifest.json": "9b45f17ab1a5d572b1ad6339537f0abc9783f0d09d3b9b638139e527eac60509",
     "lib/assets/audio.js": "6facdce4e053afd172af5b9407569b035169844ea17b49f93f8b67f72b78895f",
     "lib/assets/errors.js": "70572678655c6e53179d31920d71f29882d373a0e12d560220bb0fc2cd74f2cc",
     "lib/assets/glb.js": "b808479a36299c154db97f50c16863a3b5a2c61f725e66bf01d01a5f62a288a5",
@@ -125,10 +125,10 @@
     "lib/runtime/world.js": "c43621fbaca8bd2b0d6477a96e60e895312f0f7b1eb97614b6e4f9b716129ea1",
     "lib/schema/index.js": "594429eecb4494c4af2f3d04537be3211f2c9297a1fc555bbba5d028d8627965",
     "lib/sdk/graph-values.js": "a58c00f127cb82aba5fd2824981942844e06d9a59a88a05e35d1d3df2fc7ed2f",
-    "lib/sdk/index.d.ts": "fd5af9d29ba6a4ffe77ec535e8ae3024dcd67ece3c4968079b3594c808437ac9",
-    "lib/sdk/index.js": "a6de6170edcb7b31e8df05c966659cae067315d1b2f0bff32d3c5c183d35934c",
-    "lib/simulation/cloth-plugin.js": "bef005219aef6aab6d91d599d9b8c94f1523d4d7141edf54bc5ec0514a452ef8",
-    "lib/simulation/cloth.js": "97a52cf7217a76ce60aa995eafa680d8a782ae673fcac27d76df8d37d2154aaf",
+    "lib/sdk/index.d.ts": "a94caaad441c55fcb1756ee71ffee019312f503ecb4fef3efcaed746c62d6e05",
+    "lib/sdk/index.js": "7ef0131457ceac1e9eeb5aa2b140f854b9bbe16dff03c42714b96e6ddedf4b7c",
+    "lib/simulation/cloth-plugin.js": "edee02bb0ce7cf94d364699e47bc4891f8a53259bb70af547241759faad0b773",
+    "lib/simulation/cloth.js": "f45a1c7684904b70315c8c1a0a28153eb34a8aee150d518af379f6d2fff2e740",
     "lib/simulation/rope-body-coupling.js": "70694b73d17c79f223803a51fbf4a4dae551b717cd29bbea1fa38386ac98d621",
     "lib/simulation/rope-plugin.js": "08c7c4800053b3e8f255b6dd5be2b532b8e259300666c31de5494d15704717d4",
     "lib/simulation/rope-self-collision.js": "4d8dc5d5a88f0ae0ad5463f553f49b2ad3c8c126b98344a0966f619635bdb17f",
@@ -203,7 +203,7 @@
     "licenses/undici-types/LICENSE": "a6db8096b2707bc0102d256917d4d33f298ba36d8c3f25de067a2b5bb379db27",
     "licenses/uniq/LICENSE": "e67aed7df22dc8031e4fcf5338fe91cb33e3817e5c58a99a2a2802eea9069791",
     "licenses/vite/LICENSE.md": "a22152baa1aef74402443008e767e7c689a524c0909d19b0431d97f5ab066a13",
-    "package.json": "61c6dc585fa85083e375ac393445e82c237f94a810aa28b1e2430402fc719721",
+    "package.json": "b50c26f2427bb50bb724238d3e9c17407bd704ad5e888c33d1d53e66eb76195d",
     "README.md": "ff25e039921a85ba253c27608c77ed614a036117d7a04f908a78d1e3ed3f19ef",
     "web/index.html": "d89d6a5b5be3beae3627a8ed506ac308b165d264fb8696be3afd79fcca2f26ee"
   }

package/docs/STATUS.md

@@ -2,7 +2,7 @@
 
 ## 版本与发布
 
-- 当前版本为 `0.3.19`，包、锁文件、引擎、SDK、编译器和示例中的版本保持一致。下一项功能完成后统一递增并推送；相同版本不能重复发布。
+- 当前版本为 `0.3.21`，包、锁文件、引擎、SDK、编译器和示例中的版本保持一致。下一项功能完成后统一递增并推送；相同版本不能重复发布。
 - 推送主线会通过 GitHub Actions 和 npm 可信发布更新 `latest`；GitHub Release 用于记录里程碑。历史版本和旧标签保持原样，不代表当前源码通过。
 - 当前按用户要求仅允许编译和构建，不运行测试、浏览器、GPU、性能或其他验证。普通版本号不意味着运行行为、硬件或完整引擎已验收。
 
@@ -17,6 +17,9 @@
 - 三角布料新增 CPU 距离约束、近似弯曲、锚点、受力、采样球体/平面粒子碰撞、非相邻粒子自碰撞、Host 快照及动态网格入口；不包含面/边碰撞、刚体反作用、撕裂或连续碰撞。渲染、运行、稳定性、性能和快照兼容均未验证，不代表完整布料能力。
 - 布料、绳索、软体、流体、连续世界、导航、动画、音频和其他首发能力仍需按各自依赖完成，不能把独立候选或局部实现写成整项完成。
 
+
+- Historical cloth snapshots without `selfCollisions` restore in the legacy particle-only mode; invalid or duplicate self-contact state is rejected atomically. This migration fix is unverified.
+
 ## 单线接续
 
 只在 `main` 的主工作树串行开发。历史独有候选和失败记录在本机 `.pelican/consolidated-worktrees/`、`.pelican/worktree-snapshots/` 或原证据目录中；它们不是活动工作树，未审查前不能删除或声称已合入。其他环境不一定有这些本机目录。

package/docs/api/REFERENCE.md

@@ -1,4 +1,4 @@
-# pelican 0.3.19 API 索引
+# pelican 0.3.21 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.19"
+SDK_VERSION = "0.3.21"
 ```
 
 ## Vec2

package/docs/api/index.json

@@ -1,14 +1,14 @@
 {
   "format": "pelican.api-index",
   "version": 1,
-  "engineVersion": "0.3.19",
+  "engineVersion": "0.3.21",
   "entry": "pelican-engine",
   "source": "packages/sdk/src/index.ts",
   "symbols": [
     {
       "name": "SDK_VERSION",
       "kind": "constant",
-      "signature": "SDK_VERSION = \"0.3.19\"",
+      "signature": "SDK_VERSION = \"0.3.21\"",
       "line": 2
     },
     {

package/docs/npm/GAME-AUTHOR.md

@@ -157,8 +157,8 @@ 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
+this feature retain the disabled mode when migrated; invalid or duplicate self
+contacts are rejected atomically; 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`.
 

package/engine.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "pelican-engine",
-  "version": "0.3.19",
+  "version": "0.3.21",
   "milestone": "M3",
   "stage": "advanced-rendering-development",
   "license": "MIT",

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.19";
+export declare const SDK_VERSION = "0.3.21";
 export type Vec2 = readonly [number, number];
 export type Vec3 = readonly [number, number, number];
 export type Vec4 = readonly [number, number, number, number];

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.19";
+export const SDK_VERSION = "0.3.21";
 export const SYSTEM_PHASES = [
     "input",
     "prePhysics",

package/lib/simulation/cloth-plugin.js

@@ -15,12 +15,16 @@ function planarUvs(points) {
         return fail("VISUAL_UV", "Initial points need two nonzero projection axes or explicit UVs.");
     return points.map(point => [(point[first] - min[first]) / width, (point[second] - min[second]) / height]);
 }
-function createEntry(input, fixedDt, materials) {
+function createEntry(input, fixedDt, materials, restoredSelfMode) {
     const definition = cloneSerializable(input);
     if (!definition || !validId(definition.id))
         return fail("ID", "Expected a nonempty id of at most 128 characters.");
     if (definition.autoStep !== undefined && typeof definition.autoStep !== "boolean")
         return fail("AUTO_STEP", "autoStep must be boolean.");
+    if (definition.selfCollisions !== undefined && typeof definition.selfCollisions !== "boolean")
+        return fail("SELF_COLLISION", "selfCollisions must be boolean.");
+    if (restoredSelfMode !== undefined && definition.selfCollisions !== undefined && definition.selfCollisions !== restoredSelfMode)
+        return fail("SNAPSHOT", "Self collision configuration does not match the saved solver.");
     if (definition.fixedDt !== undefined && definition.fixedDt !== fixedDt)
         return fail("FIXED_DT", "Cloth fixedDt must match the host fixedDt.");
     if (fixedDt < 1 / 1000 || fixedDt > 1 / 30)
@@ -35,7 +39,7 @@ function createEntry(input, fixedDt, materials) {
             visual.uvs.some(uv => !Array.isArray(uv) || uv.length !== 2 || !uv.every(value => typeof value === "number" && Number.isFinite(value) && Math.abs(value) <= 1e6))))
             return fail("VISUAL_UV", "UVs must contain one finite 2D coordinate per particle.");
     }
-    const solver = createCloth({ ...definition, fixedDt });
+    const solver = createCloth({ ...definition, fixedDt, ...(restoredSelfMode === undefined ? {} : { selfCollisions: restoredSelfMode }) });
     try {
         const uvs = definition.visual ? (definition.visual.uvs ? definition.visual.uvs.map(uv => [uv[0], uv[1]]) : planarUvs(definition.points)) : [];
         return { definition, solver, uvs };
@@ -55,7 +59,10 @@ function parseSnapshot(value, fixedDt, materials) {
         for (const item of value.cloths) {
             if (!item || typeof item !== "object")
                 fail("SNAPSHOT", "Invalid cloth entry.");
-            const entry = createEntry(item.definition, fixedDt, materials);
+            const savedSelfMode = item.state?.config?.selfCollisions;
+            if (savedSelfMode !== undefined && typeof savedSelfMode !== "boolean")
+                fail("SNAPSHOT", "Invalid self collision configuration.");
+            const entry = createEntry(item.definition, fixedDt, materials, savedSelfMode ?? false);
             if (entries.has(entry.definition.id)) {
                 entry.solver.dispose();
                 fail("SNAPSHOT", "Duplicate cloth id.");

package/lib/simulation/cloth.js

@@ -344,13 +344,26 @@ export class ClothSolver {
                 fail("CLOTH_SNAPSHOT", "duplicate contact");
             keys.add(key);
         }
+        const selfContacts = input.selfContacts ?? [];
+        const selfKeys = new Set();
+        if (!Array.isArray(selfContacts) || selfContacts.length > count * Math.max(0, count - 1) / 2 || (!this.config.selfCollisions && selfContacts.length > 0) ||
+            selfContacts.some(contact => !contact || contact.tick !== input.tick || !Number.isSafeInteger(contact.firstParticle) || !Number.isSafeInteger(contact.secondParticle) ||
+                contact.firstParticle < 0 || contact.secondParticle >= count || contact.firstParticle >= contact.secondParticle ||
+                this.adjacent.has(`${contact.firstParticle}:${contact.secondParticle}`) || typeof contact.penetration !== "number" || !Number.isFinite(contact.penetration) || contact.penetration <= 0))
+            fail("CLOTH_SNAPSHOT", "invalid self contact state");
+        for (const contact of selfContacts) {
+            const key = `${contact.firstParticle}:${contact.secondParticle}`;
+            if (selfKeys.has(key))
+                fail("CLOTH_SNAPSHOT", "duplicate self contact");
+            selfKeys.add(key);
+        }
         this.positions = input.positions.map(copy);
         this.velocities = input.velocities.map(copy);
         this.forces = input.forces.map(copy);
         this.anchors = anchors;
         this.colliders = colliders;
         this.contacts = input.contacts.map(contact => ({ ...contact }));
-        this.selfContacts = (input.selfContacts ?? []).map(contact => ({ ...contact }));
+        this.selfContacts = selfContacts.map(contact => ({ ...contact }));
         this.tickValue = input.tick;
     }
     dispose() { if (this.disposed)

package/package.json

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