pelican-engine 0.3.25 → 0.3.27

package/docs/npm/GAME-AUTHOR.md

@@ -233,7 +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`.
 
-An automatic cloth may bind a live dynamic sphere with `bodyColliders: [{ id: "sphere-id", entity: "body-id" }]`. The plugin samples the real sphere after physics and uses it as a one-way moving obstacle. The body receives no cloth reaction impulse. Destroyed bodies are removed on the next automatic step. This is not complete cloth-rigid-body coupling.
+An automatic cloth may bind a live dynamic sphere with `bodyColliders: [{ id: "sphere-id", entity: "body-id" }]`. The plugin samples the real sphere after physics and uses it as a one-way moving obstacle. Set `bodyReactions: true` to submit approximate normal reaction impulses from
+particle and triangle-surface contacts through the physics bridge. This changes
+body velocity on the next physics step; it is delayed, projection-derived and
+not mass-coupled with cloth velocity. The body receives no reaction when the
+option is omitted. Destroyed bodies are removed on the next automatic step.
+This is not complete cloth-rigid-body coupling.
+
+Sampled planes use the triangle centroid for discrete surface projection; this is not continuous triangle-plane collision.
 
 New cloth also resolves detected sphere overlaps against triangle surface interiors
 using closest-point barycentric projection. `inspect(id).surfaceContacts` reports

package/engine.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "pelican-engine",
-  "version": "0.3.25",
+  "version": "0.3.27",
   "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.25";
+export declare const SDK_VERSION = "0.3.27";
 export type Vec2 = readonly [number, number];
 export type Vec3 = readonly [number, number, number];
 export type Vec4 = readonly [number, number, number, number];
@@ -277,14 +277,18 @@ export interface ClothDefinition {
     selfCollisions?: boolean;
     /** Sphere triangle-surface contacts; defaults to true for new cloth. */
     surfaceCollisions?: boolean;
-    /** Optional live dynamic sphere bindings; sampled after the physics phase, one-way only. */
+    /** Optional live dynamic sphere bindings; sampled after the physics phase. */
     bodyColliders?: readonly ClothBodyCollider[];
+    /** When true, detected contacts submit approximate reaction impulses to bound bodies. */
+    bodyReactions?: boolean;
 }
 export interface ClothContact {
     tick: number;
     particle: number;
     colliderId: string;
     penetration: number;
+    reactionImpulse?: Vec3;
+    reactionAngularImpulse?: Vec3;
 }
 export interface ClothSelfContact {
     tick: number;
@@ -298,6 +302,8 @@ export interface ClothSurfaceContact {
     colliderId: string;
     penetration: number;
     barycentric: [number, number, number];
+    reactionImpulse?: Vec3;
+    reactionAngularImpulse?: Vec3;
 }
 export interface ClothState {
     tick: 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.25";
+export const SDK_VERSION = "0.3.27";
 export const SYSTEM_PHASES = [
     "input",
     "prePhysics",

package/lib/simulation/cloth-plugin.js

@@ -22,6 +22,10 @@ function createEntry(input, fixedDt, materials, restoredSelfMode, restoredSurfac
         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.bodyReactions !== undefined && typeof definition.bodyReactions !== "boolean")
+        return fail("BODY_REACTION", "bodyReactions must be boolean.");
+    if (definition.bodyReactions && !definition.bodyColliders?.length)
+        return fail("BODY_REACTION", "bodyReactions require bodyColliders.");
     if (definition.bodyColliders !== undefined) {
         if (!Array.isArray(definition.bodyColliders) || definition.bodyColliders.length > 64)
             return fail("BODY_COLLIDER", "bodyColliders must contain at most 64 bindings.");
@@ -37,6 +41,8 @@ function createEntry(input, fixedDt, materials, restoredSelfMode, restoredSurfac
     }
     if (definition.selfCollisions !== undefined && typeof definition.selfCollisions !== "boolean")
         return fail("SELF_COLLISION", "selfCollisions must be boolean.");
+    if (definition.bodyReactions !== undefined && typeof definition.bodyReactions !== "boolean")
+        return fail("BODY_REACTION", "bodyReactions must be boolean.");
     if (definition.surfaceCollisions !== undefined && typeof definition.surfaceCollisions !== "boolean")
         return fail("SURFACE_COLLISION", "surfaceCollisions must be boolean.");
     if (restoredSurfaceMode !== undefined && definition.surfaceCollisions !== undefined && definition.surfaceCollisions !== restoredSurfaceMode)
@@ -191,7 +197,25 @@ export const createClothPlugin = context => {
                         entry.definition = { ...entry.definition, bodyColliders: live };
                         entry.solver.setColliders([...manual, ...sampled]);
                     }
-                    entry.solver.step();
+                    const state = entry.solver.step();
+                    if (entry.definition.bodyReactions && entry.definition.bodyColliders?.length) {
+                        const bridge = context.getRopePhysicsBridge?.() ?? fail("BODY_REACTION", "bodyReactions require the physics plugin.");
+                        const byCollider = new Map((entry.definition.bodyColliders ?? []).map(binding => [binding.id, binding.entity]));
+                        const reactions = new Map();
+                        for (const contact of [...state.contacts, ...state.surfaceContacts]) {
+                            const entity = byCollider.get(contact.colliderId);
+                            if (!entity || !contact.reactionImpulse || !contact.reactionAngularImpulse)
+                                continue;
+                            const current = reactions.get(entity) ?? { impulse: [0, 0, 0], moment: [0, 0, 0] };
+                            for (let k = 0; k < 3; k++) {
+                                current.impulse[k] += contact.reactionImpulse[k];
+                                current.moment[k] += contact.reactionAngularImpulse[k];
+                            }
+                            reactions.set(entity, current);
+                        }
+                        if (reactions.size)
+                            bridge.applySphereReactions([...reactions].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([entity, value]) => ({ entity, ...value })));
+                    }
                 }
             }
             catch (error) {

package/lib/simulation/cloth.js

@@ -14,6 +14,7 @@ const positive = (input, label) => typeof input === "number" && Number.isFinite(
 const indexOf = (input, count) => Number.isSafeInteger(input) && input >= 0 && input < count ? input : fail("CLOTH_INDEX", "particle index is out of range");
 const distance = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
 const tuple = (a) => [a[0], a[1], a[2]];
+const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
 function readAnchors(input, count) {
     if (!Array.isArray(input) || input.length > count)
         fail("CLOTH_INPUT", "anchors must be an array of unique particle indices");
@@ -280,34 +281,57 @@ export class ClothSolver {
                             continue;
                         for (let k = 0; k < 3; k++)
                             p[k] += normal[k] * depth;
-                        const key = `${i}:${collider.id}`, old = contacts.get(key);
-                        if (old)
+                        const magnitude = -mass * depth / h, reactionImpulse = [normal[0] * magnitude, normal[1] * magnitude, normal[2] * magnitude];
+                        const point = collider.kind === "sphere" ? [collider.center[0] + normal[0] * collider.radius, collider.center[1] + normal[1] * collider.radius, collider.center[2] + normal[2] * collider.radius] : [p[0] - normal[0] * radius, p[1] - normal[1] * radius, p[2] - normal[2] * radius];
+                        const reactionAngularImpulse = cross(point, reactionImpulse), key = `${i}:${collider.id}`, old = contacts.get(key);
+                        if (old) {
                             old.penetration = Math.max(old.penetration, depth);
+                            for (let k = 0; k < 3; k++) {
+                                old.reactionImpulse[k] += reactionImpulse[k];
+                                old.reactionAngularImpulse[k] += reactionAngularImpulse[k];
+                            }
+                        }
                         else
-                            contacts.set(key, { tick: this.tickValue + 1, particle: i, colliderId: collider.id, penetration: depth });
+                            contacts.set(key, { tick: this.tickValue + 1, particle: i, colliderId: collider.id, penetration: depth, reactionImpulse, reactionAngularImpulse });
                     }
                 }
                 if (this.config.surfaceCollisions)
                     for (let triangleIndex = 0; triangleIndex < this.config.triangles.length; triangleIndex++) {
                         const triangle = this.config.triangles[triangleIndex], a = positions[triangle[0]], b = positions[triangle[1]], c = positions[triangle[2]];
                         for (const collider of this.colliders) {
-                            if (collider.kind !== "sphere")
-                                continue;
-                            const closest = closestTriangle(collider.center, a, b, c), delta = [closest.point[0] - collider.center[0], closest.point[1] - collider.center[1], closest.point[2] - collider.center[2]], length = Math.hypot(...delta), depth = collider.radius + radius - length;
+                            let closest, normal, depth;
+                            if (collider.kind === "sphere") {
+                                closest = closestTriangle(collider.center, a, b, c);
+                                const delta = [closest.point[0] - collider.center[0], closest.point[1] - collider.center[1], closest.point[2] - collider.center[2]], length = Math.hypot(...delta);
+                                depth = collider.radius + radius - length;
+                                normal = length < 1e-12 ? [0, 1, 0] : [delta[0] / length, delta[1] / length, delta[2] / length];
+                            }
+                            else {
+                                const centroid = [(a[0] + b[0] + c[0]) / 3, (a[1] + b[1] + c[1]) / 3, (a[2] + b[2] + c[2]) / 3];
+                                normal = collider.normal;
+                                depth = collider.offset + radius - (centroid[0] * normal[0] + centroid[1] * normal[1] + centroid[2] * normal[2]);
+                                closest = { point: centroid, barycentric: [1 / 3, 1 / 3, 1 / 3] };
+                            }
                             if (depth <= 0)
                                 continue;
-                            const normal = length < 1e-12 ? [0, 1, 0] : [delta[0] / length, delta[1] / length, delta[2] / length], weights = [this.anchors.has(triangle[0]) ? 0 : closest.barycentric[0], this.anchors.has(triangle[1]) ? 0 : closest.barycentric[1], this.anchors.has(triangle[2]) ? 0 : closest.barycentric[2]], denominator = weights.reduce((sum, value) => sum + value * value, 0);
+                            const weights = [this.anchors.has(triangle[0]) ? 0 : closest.barycentric[0], this.anchors.has(triangle[1]) ? 0 : closest.barycentric[1], this.anchors.has(triangle[2]) ? 0 : closest.barycentric[2]], denominator = weights.reduce((sum, value) => sum + value * value, 0);
                             if (denominator === 0)
                                 continue;
                             const correction = depth / denominator;
                             for (let vertex = 0; vertex < 3; vertex++)
                                 for (let axis = 0; axis < 3; axis++)
                                     positions[triangle[vertex]][axis] += normal[axis] * correction * weights[vertex];
+                            const magnitude = -mass * depth / h, reactionImpulse = [normal[0] * magnitude, normal[1] * magnitude, normal[2] * magnitude], reactionAngularImpulse = cross(closest.point, reactionImpulse);
                             const key = `${triangleIndex}:${collider.id}`, old = surfaceContacts.get(key);
-                            if (old)
+                            if (old) {
                                 old.penetration = Math.max(old.penetration, depth);
+                                for (let k = 0; k < 3; k++) {
+                                    old.reactionImpulse[k] += reactionImpulse[k];
+                                    old.reactionAngularImpulse[k] += reactionAngularImpulse[k];
+                                }
+                            }
                             else
-                                surfaceContacts.set(key, { tick: this.tickValue + 1, triangle: triangleIndex, colliderId: collider.id, penetration: depth, barycentric: closest.barycentric });
+                                surfaceContacts.set(key, { tick: this.tickValue + 1, triangle: triangleIndex, colliderId: collider.id, penetration: depth, barycentric: closest.barycentric, reactionImpulse, reactionAngularImpulse });
                         }
                     }
                 if (this.config.selfCollisions)
@@ -391,7 +415,7 @@ export class ClothSolver {
         const colliders = readColliders(input.colliders), keys = new Set();
         if (!Array.isArray(input.contacts) || input.contacts.length > count * colliders.length || input.contacts.some(contact => !contact || contact.tick !== input.tick ||
             !Number.isSafeInteger(contact.particle) || contact.particle < 0 || contact.particle >= count || !colliders.some(collider => collider.id === contact.colliderId) ||
-            typeof contact.penetration !== "number" || !Number.isFinite(contact.penetration) || contact.penetration <= 0))
+            typeof contact.penetration !== "number" || !Number.isFinite(contact.penetration) || contact.penetration <= 0 || (contact.reactionImpulse === undefined) !== (contact.reactionAngularImpulse === undefined) || (contact.reactionImpulse !== undefined && (!vec(contact.reactionImpulse) || !vec(contact.reactionAngularImpulse)))))
             fail("CLOTH_SNAPSHOT", "invalid contact state");
         for (const contact of input.contacts) {
             const key = `${contact.particle}:${contact.colliderId}`;
@@ -416,9 +440,9 @@ export class ClothSolver {
         const surfaceKeys = new Set();
         if (!Array.isArray(surfaceContacts) || surfaceContacts.length > this.config.triangles.length * colliders.length || (!this.config.surfaceCollisions && surfaceContacts.length > 0) ||
             surfaceContacts.some(contact => !contact || contact.tick !== input.tick || !Number.isSafeInteger(contact.triangle) || contact.triangle < 0 || contact.triangle >= this.config.triangles.length ||
-                !colliders.some(collider => collider.id === contact.colliderId && collider.kind === "sphere") || typeof contact.penetration !== "number" || !Number.isFinite(contact.penetration) || contact.penetration <= 0 ||
+                !colliders.some(collider => collider.id === contact.colliderId) || typeof contact.penetration !== "number" || !Number.isFinite(contact.penetration) || contact.penetration <= 0 ||
                 !Array.isArray(contact.barycentric) || contact.barycentric.length !== 3 || !contact.barycentric.every(value => typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1) ||
-                Math.abs(contact.barycentric[0] + contact.barycentric[1] + contact.barycentric[2] - 1) > 1e-5))
+                Math.abs(contact.barycentric[0] + contact.barycentric[1] + contact.barycentric[2] - 1) > 1e-5 || (contact.reactionImpulse === undefined) !== (contact.reactionAngularImpulse === undefined) || (contact.reactionImpulse !== undefined && (!vec(contact.reactionImpulse) || !vec(contact.reactionAngularImpulse)))))
             fail("CLOTH_SNAPSHOT", "invalid surface contact state");
         for (const contact of surfaceContacts) {
             const key = `${contact.triangle}:${contact.colliderId}`;

package/package.json

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