pelican-engine 0.3.18 → 0.3.19

package/docs/npm/GAME-AUTHOR.md

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

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))
@@ -320,8 +350,9 @@ export class ClothSolver {
         this.anchors = anchors;
         this.colliders = colliders;
         this.contacts = input.contacts.map(contact => ({ ...contact }));
+        this.selfContacts = (input.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.19",
   "description": "Pelican Engine public SDK and offline development CLI",
   "type": "module",
   "license": "MIT",