pelican-engine 0.3.18 → 0.3.20

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`.
 
@@ -233,6 +233,14 @@ manual cloth uses `ctx.cloth.step`. Use `setAnchor`, `releaseAnchor`, `applyForc
 (next tick), `applyImpulse`, `setColliders`, `inspect`, and `destroy` to manage it.
 The source checkout includes `examples/cloth-sheet`.
 
+New cloth also resolves discrete self-contact between non-adjacent particles by
+projecting movable particles apart; shared triangle edges are excluded.
+`selfCollisions` defaults to true for new cloth and is reported by
+`ctx.cloth.inspect(id)`. Set it to false for particle-only cloth. Self-contact
+state is included in snapshots. This is particle self-contact, not triangle
+interior/edge collision, continuous collision, friction or a guarantee against
+penetration. It has not been runtime or stability validated.
+
 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

package/engine.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "pelican-engine",
-  "version": "0.3.18",
+  "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.18";
+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];
@@ -269,6 +269,8 @@ export interface ClothDefinition {
         position: Vec3;
     }[];
     visual?: ClothVisualOptions;
+    /** Discrete non-adjacent particle self-contact; defaults to true for new cloth. */
+    selfCollisions?: boolean;
 }
 export interface ClothContact {
     tick: number;
@@ -276,10 +278,17 @@ export interface ClothContact {
     colliderId: string;
     penetration: number;
 }
+export interface ClothSelfContact {
+    tick: number;
+    firstParticle: number;
+    secondParticle: number;
+    penetration: number;
+}
 export interface ClothState {
     tick: number;
     simulatedSeconds: number;
     disposed: boolean;
+    selfCollisions: boolean;
     positions: Vec3[];
     velocities: Vec3[];
     triangles: ClothTriangle[];
@@ -288,6 +297,7 @@ export interface ClothState {
         position: Vec3;
     }[];
     contacts: ClothContact[];
+    selfContacts: ClothSelfContact[];
     maxDistanceError: number;
     resources: {
         particles: 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.18";
+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

@@ -110,12 +110,14 @@ export function createCloth(input) {
         fail("CLOTH_INPUT", "damping must be in [0,100]");
     if (input.bending !== undefined && typeof input.bending !== "boolean")
         fail("CLOTH_INPUT", "bending must be boolean");
-    const bending = input.bending ?? true, gravity = readVec(input.gravity ?? [0, -9.81, 0], "gravity");
+    const bending = input.bending ?? true, selfCollisions = input.selfCollisions ?? true, gravity = readVec(input.gravity ?? [0, -9.81, 0], "gravity");
+    if (typeof selfCollisions !== "boolean")
+        fail("CLOTH_INPUT", "selfCollisions must be boolean");
     const { triangles, constraints } = topology(positions, input.triangles, bending);
     const anchors = readAnchors(input.anchors ?? [], positions.length);
     for (const [index, point] of anchors)
         positions[index] = copy(point);
-    return new ClothSolver({ mass, radius, fixedDt, substeps, iterations, damping, gravity, bending, triangles, constraints }, positions, anchors);
+    return new ClothSolver({ mass, radius, fixedDt, substeps, iterations, damping, gravity, bending, selfCollisions, triangles, constraints }, positions, anchors);
 }
 export class ClothSolver {
     config;
@@ -127,12 +129,15 @@ export class ClothSolver {
     forces;
     colliders = [];
     contacts = [];
+    selfContacts = [];
+    adjacent;
     constructor(config, positions, anchors) {
         this.config = config;
         this.positions = positions;
         this.anchors = anchors;
         this.velocities = positions.map(() => [0, 0, 0]);
         this.forces = positions.map(() => [0, 0, 0]);
+        this.adjacent = new Set(config.triangles.flatMap(([a, b, c]) => [`${Math.min(a, b)}:${Math.max(a, b)}`, `${Math.min(b, c)}:${Math.max(b, c)}`, `${Math.min(c, a)}:${Math.max(c, a)}`]));
     }
     alive() { if (this.disposed)
         fail("CLOTH_DISPOSED", "cloth has been disposed"); }
@@ -171,7 +176,7 @@ export class ClothSolver {
         this.alive();
         if (!Number.isSafeInteger(steps) || steps < 1 || steps > 1000 || this.tickValue + steps > Number.MAX_SAFE_INTEGER)
             fail("CLOTH_INPUT", "steps must be in [1,1000] without tick overflow");
-        const before = { positions: this.positions, velocities: this.velocities, forces: this.forces, contacts: this.contacts, tick: this.tickValue };
+        const before = { positions: this.positions, velocities: this.velocities, forces: this.forces, contacts: this.contacts, selfContacts: this.selfContacts, tick: this.tickValue };
         try {
             for (let i = 0; i < steps; i++)
                 this.stepOne();
@@ -181,6 +186,7 @@ export class ClothSolver {
             this.velocities = before.velocities;
             this.forces = before.forces;
             this.contacts = before.contacts;
+            this.selfContacts = before.selfContacts;
             this.tickValue = before.tick;
             throw error;
         }
@@ -189,7 +195,7 @@ export class ClothSolver {
     stepOne() {
         const { fixedDt, substeps, iterations, mass, gravity, damping, constraints, radius } = this.config;
         const h = fixedDt / substeps, decay = Math.exp(-damping * h);
-        const positions = this.positions.map(copy), velocities = this.velocities.map(copy), contacts = new Map();
+        const positions = this.positions.map(copy), velocities = this.velocities.map(copy), contacts = new Map(), selfContacts = new Map();
         for (let sub = 0; sub < substeps; sub++) {
             const previous = positions.map(copy);
             for (let i = 0; i < positions.length; i++) {
@@ -250,6 +256,29 @@ export class ClothSolver {
                             contacts.set(key, { tick: this.tickValue + 1, particle: i, colliderId: collider.id, penetration: depth });
                     }
                 }
+                if (this.config.selfCollisions)
+                    for (let i = 0; i < positions.length; i++)
+                        for (let j = i + 1; j < positions.length; j++) {
+                            if (this.adjacent.has(`${i}:${j}`))
+                                continue;
+                            const a = positions[i], b = positions[j], dx = a[0] - b[0], dy = a[1] - b[1], dz = a[2] - b[2], length = Math.hypot(dx, dy, dz), depth = 2 * radius - length;
+                            if (depth <= 0)
+                                continue;
+                            const normal = length < 1e-12 ? [1, 0, 0] : [dx / length, dy / length, dz / length];
+                            const wa = this.anchors.has(i) ? 0 : 1, wb = this.anchors.has(j) ? 0 : 1;
+                            if (wa + wb === 0)
+                                continue;
+                            const correction = depth / (wa + wb);
+                            for (let axis = 0; axis < 3; axis++) {
+                                a[axis] += normal[axis] * correction * wa;
+                                b[axis] -= normal[axis] * correction * wb;
+                            }
+                            const key = `${i}:${j}`, old = selfContacts.get(key);
+                            if (old)
+                                old.penetration = Math.max(old.penetration, depth);
+                            else
+                                selfContacts.set(key, { tick: this.tickValue + 1, firstParticle: i, secondParticle: j, penetration: depth });
+                        }
             }
             for (let i = 0; i < positions.length; i++) {
                 if (this.anchors.has(i))
@@ -264,18 +293,19 @@ export class ClothSolver {
         this.velocities = velocities;
         this.forces = positions.map(() => [0, 0, 0]);
         this.contacts = [...contacts.values()];
+        this.selfContacts = [...selfContacts.values()];
         this.tickValue++;
     }
     inspect() {
         if (this.disposed)
-            return { tick: this.tickValue, simulatedSeconds: this.tickValue * this.config.fixedDt, disposed: true, positions: [], velocities: [], triangles: [], anchors: [], contacts: [], maxDistanceError: 0, resources: { particles: 0, triangles: 0, constraints: 0, anchors: 0, colliders: 0 } };
+            return { tick: this.tickValue, simulatedSeconds: this.tickValue * this.config.fixedDt, disposed: true, selfCollisions: this.config.selfCollisions, positions: [], velocities: [], triangles: [], anchors: [], contacts: [], selfContacts: [], maxDistanceError: 0, resources: { particles: 0, triangles: 0, constraints: 0, anchors: 0, colliders: 0 } };
         let maxDistanceError = 0;
         for (const [a, b, rest] of this.config.constraints)
             maxDistanceError = Math.max(maxDistanceError, Math.abs(distance(this.positions[a], this.positions[b]) - rest));
-        return { tick: this.tickValue, simulatedSeconds: this.tickValue * this.config.fixedDt, disposed: false,
+        return { tick: this.tickValue, simulatedSeconds: this.tickValue * this.config.fixedDt, disposed: false, selfCollisions: this.config.selfCollisions,
             positions: this.positions.map(copy), velocities: this.velocities.map(copy), triangles: this.config.triangles.map(tuple),
             anchors: [...this.anchors].map(([index, position]) => ({ index, position: copy(position) })).sort((a, b) => a.index - b.index),
-            contacts: this.contacts.map(contact => ({ ...contact })), maxDistanceError,
+            contacts: this.contacts.map(contact => ({ ...contact })), selfContacts: this.selfContacts.map(contact => ({ ...contact })), maxDistanceError,
             resources: { particles: this.positions.length, triangles: this.config.triangles.length, constraints: this.config.constraints.length, anchors: this.anchors.size, colliders: this.colliders.length } };
     }
     snapshot() {
@@ -283,7 +313,7 @@ export class ClothSolver {
         const state = this.inspect();
         return { format: "pelican-cloth-cpu", version: 1, tick: this.tickValue,
             config: { ...this.config, gravity: copy(this.config.gravity), triangles: this.config.triangles.map(tuple), constraints: this.config.constraints.map(tuple) },
-            positions: state.positions, velocities: state.velocities, forces: this.forces.map(copy), anchors: state.anchors, colliders: readColliders(this.colliders), contacts: state.contacts };
+            positions: state.positions, velocities: state.velocities, forces: this.forces.map(copy), anchors: state.anchors, colliders: readColliders(this.colliders), contacts: state.contacts, selfContacts: state.selfContacts };
     }
     restore(input) {
         this.alive();
@@ -291,7 +321,7 @@ export class ClothSolver {
             fail("CLOTH_SNAPSHOT", "unsupported snapshot format or tick");
         const config = input.config, expected = this.config;
         if (!config || config.mass !== expected.mass || config.radius !== expected.radius || config.fixedDt !== expected.fixedDt || config.substeps !== expected.substeps ||
-            config.iterations !== expected.iterations || config.damping !== expected.damping || config.bending !== expected.bending ||
+            config.iterations !== expected.iterations || config.damping !== expected.damping || config.bending !== expected.bending || (config.selfCollisions ?? false) !== expected.selfCollisions ||
             !vec(config.gravity) || config.gravity.some((value, i) => value !== expected.gravity[i]) ||
             !Array.isArray(config.triangles) || JSON.stringify(config.triangles) !== JSON.stringify(expected.triangles) ||
             !Array.isArray(config.constraints) || JSON.stringify(config.constraints) !== JSON.stringify(expected.constraints))
@@ -314,14 +344,28 @@ 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 = selfContacts.map(contact => ({ ...contact }));
         this.tickValue = input.tick;
     }
     dispose() { if (this.disposed)
-        return; this.disposed = true; this.positions = []; this.velocities = []; this.forces = []; this.colliders = []; this.contacts = []; this.anchors.clear(); }
+        return; this.disposed = true; this.positions = []; this.velocities = []; this.forces = []; this.colliders = []; this.contacts = []; this.selfContacts = []; this.anchors.clear(); }
 }

package/package.json

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