pelican-engine 0.3.19 → 0.3.20

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.20",
   "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": "8123bf23e260ffe7268ccd6507c1ea3c36bc1358a7148a77ca6ddab758348117",
+    "docs/api/REFERENCE.md": "d1c151baf7c148202e73f9eb0cd3854ba001daa32e32e6af6dd0b161c46e7781",
     "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": "d16f1505f821fc497bfb57a82a3ff8ea9e9143fcb0dcd512614a84bda7740ec3",
     "docs/THIRD-PARTY-NOTICES.md": "58f9b72e2b4dfaaaf2a4c08b9bde9ecef3d2b7e7d65fccd782ed54f39fa76fdc",
-    "engine.manifest.json": "ad46b5ec17bcc1c4164bb2eb7431a5b448095db528917838c3706143ce517c1b",
+    "engine.manifest.json": "c90b9ff8ef45bc83111d149fffde0dd441ffeef5501bd79a4bdcc35fa2571912",
     "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": "a0f81926953f6f40a24cdf91241dd4205b44a24f49f92c0b4dd43deffffa991f",
+    "lib/sdk/index.js": "dd88241bb5f213c7dd3c6e1c8fe5e2b888d7ecc62d02e0930803fa44b20cabd9",
+    "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": "d2c9fa59ddfe28141abe4d08f2518c8dd07fc71e0caee076cf01c84c2c6a4107",
     "README.md": "ff25e039921a85ba253c27608c77ed614a036117d7a04f908a78d1e3ed3f19ef",
     "web/index.html": "d89d6a5b5be3beae3627a8ed506ac308b165d264fb8696be3afd79fcca2f26ee"
   }

package/docs/STATUS.md

@@ -2,7 +2,7 @@
 
 ## 版本与发布
 
-- 当前版本为 `0.3.19`，包、锁文件、引擎、SDK、编译器和示例中的版本保持一致。下一项功能完成后统一递增并推送；相同版本不能重复发布。
+- 当前版本为 `0.3.20`，包、锁文件、引擎、SDK、编译器和示例中的版本保持一致。下一项功能完成后统一递增并推送；相同版本不能重复发布。
 - 推送主线会通过 GitHub Actions 和 npm 可信发布更新 `latest`；GitHub Release 用于记录里程碑。历史版本和旧标签保持原样，不代表当前源码通过。
 - 当前按用户要求仅允许编译和构建，不运行测试、浏览器、GPU、性能或其他验证。普通版本号不意味着运行行为、硬件或完整引擎已验收。
 

package/docs/api/REFERENCE.md

@@ -1,4 +1,4 @@
-# pelican 0.3.19 API 索引
+# pelican 0.3.20 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.20"
 ```
 
 ## Vec2

package/docs/api/index.json

@@ -1,14 +1,14 @@
 {
   "format": "pelican.api-index",
   "version": 1,
-  "engineVersion": "0.3.19",
+  "engineVersion": "0.3.20",
   "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.20\"",
       "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.20",
   "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.20";
 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.20";
 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.20",
   "description": "Pelican Engine public SDK and offline development CLI",
   "type": "module",
   "license": "MIT",