pelican-engine 0.3.24 → 0.3.26

package/docs/npm/GAME-AUTHOR.md

@@ -233,7 +233,12 @@ 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.
 
 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.24",
+  "version": "0.3.26",
   "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.24";
+export declare const SDK_VERSION = "0.3.26";
 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.24";
+export const SDK_VERSION = "0.3.26";
 export const SYSTEM_PHASES = [
     "input",
     "prePhysics",

package/lib/simulation/cloth-plugin.js

@@ -1,3 +1,4 @@
+import { resolveEntityDefinition } from "../runtime/prefabs.js";
 import { cloneSerializable } from "../runtime/random.js";
 import { createCloth } from "./cloth.js";
 const fail = (code, detail) => { throw new Error(`TC_CLOTH_${code}: ${detail}`); };
@@ -21,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.");
@@ -36,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)
@@ -68,6 +75,22 @@ function createEntry(input, fixedDt, materials, restoredSelfMode, restoredSurfac
 }
 function disposeEntries(entries) { for (const entry of entries.values())
     entry.solver.dispose(); entries.clear(); }
+function validateBodyBindings(entries, context, world) {
+    const records = world ? new Map(world.entities.map(record => [record.id, record])) : undefined;
+    const bridge = [...entries].some(entry => (entry.definition.bodyColliders?.length ?? 0) > 0)
+        ? context.getRopePhysicsBridge?.() : undefined;
+    for (const entry of entries)
+        for (const binding of entry.definition.bodyColliders ?? []) {
+            const record = records?.get(binding.entity);
+            if (records && (!record || !resolveEntityDefinition(context.scene, record)?.rigidBody))
+                fail("SNAPSHOT", `Bound body '${binding.entity}' is missing from the restored world.`);
+            if (!context.world.isAlive(binding.entity))
+                fail("BODY_COLLIDER", `Body '${binding.entity}' is not a live entity.`);
+            if (!bridge)
+                fail("BODY_COLLIDER", "Body bindings require the physics plugin.");
+            bridge.sampleSphere(binding.entity);
+        }
+}
 function parseSnapshot(value, fixedDt, materials) {
     if (!value || typeof value !== "object" || value.version !== 1 || !Array.isArray(value.cloths) || value.cloths.length > 256)
         return fail("SNAPSHOT", "Expected a version 1 snapshot containing at most 256 cloths.");
@@ -118,12 +141,7 @@ export const createClothPlugin = context => {
                 return fail("CAPACITY", "At most 256 cloths per host.");
             const entry = createEntry(definition, hostDt, materials);
             try {
-                const bridge = entry.definition.bodyColliders?.length ? context.getRopePhysicsBridge?.() : undefined;
-                for (const binding of entry.definition.bodyColliders ?? []) {
-                    if (!context.world.isAlive(binding.entity))
-                        return fail("BODY_COLLIDER", `Body '${binding.entity}' is not a live entity.`);
-                    bridge?.sampleSphere(binding.entity);
-                }
+                validateBodyBindings([entry], context);
                 entries.set(entry.definition.id, entry);
             }
             catch (error) {
@@ -179,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) {
@@ -200,7 +236,28 @@ export const createClothPlugin = context => {
         snapshot: () => ({ version: 1, cloths: [...entries.values()].sort((a, b) => a.definition.id < b.definition.id ? -1 : a.definition.id > b.definition.id ? 1 : 0)
                 .map(({ definition, solver }) => ({ definition: cloneSerializable(definition), state: solver.snapshot() })) }),
         validateSnapshot(value) { const staged = parseSnapshot(value, hostDt, materials); disposeEntries(staged); },
-        restore(value) { alive(); const staged = parseSnapshot(value, hostDt, materials); disposeEntries(entries); entries = staged; },
+        validateWorld(value, world) {
+            const staged = parseSnapshot(value, hostDt, materials);
+            try {
+                validateBodyBindings(staged.values(), context, world);
+            }
+            finally {
+                disposeEntries(staged);
+            }
+        },
+        restore(value) {
+            alive();
+            const staged = parseSnapshot(value, hostDt, materials);
+            try {
+                validateBodyBindings(staged.values(), context);
+            }
+            catch (error) {
+                disposeEntries(staged);
+                throw error;
+            }
+            disposeEntries(entries);
+            entries = staged;
+        },
         dispose() { if (disposed)
             return; disposed = true; disposeEntries(entries); },
     };

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,11 +281,18 @@ 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)
@@ -303,11 +311,17 @@ export class ClothSolver {
                             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 +405,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}`;
@@ -418,7 +432,7 @@ export class ClothSolver {
             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 ||
                 !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.24",
+  "version": "0.3.26",
   "description": "Pelican Engine public SDK and offline development CLI",
   "type": "module",
   "license": "MIT",