pelican-engine 0.3.11 → 0.3.12

package/docs/npm/GAME-AUTHOR.md

@@ -137,8 +137,24 @@ all earlier automatic ropes from that phase; the host tick may still have other
 partial changes and must be recovered from a known-good checkpoint. The source
 checkout includes `examples/rope-particles`.
 
+For each latest-tick contact, `reactionImpulse` and `reactionAngularImpulse`
+report the opposite impulse produced by the particle's position projections,
+and its moment about the world origin. These optional fields are absent when
+restoring older contact snapshots. They do not automatically act on a rigid body.
+For an explicitly mapped dynamic body, game code can read its actual world center
+of mass via `ctx.physics.centerOfMass(id)`, apply the linear impulse, and apply
+`reactionAngularImpulse - centerOfMass × reactionImpulse` as torque impulse.
+Apply each contact at most once for its `tick`; repeated `inspect` calls return
+the same contacts. The source checkout has an illustrative `examples/rope-reaction`.
+
+This sampled, manually applied reaction is delayed and uses positional correction,
+not a coupled contact solver: it omits body velocity/effective mass, friction and
+continuous collision. Applying the linear and angular impulses uses separate
+operations and is not transactional if a tick fails; recover from a known-good
+checkpoint. It must not be represented as complete two-way rigid-body interaction.
+
 This is an unverified development-stage increment, not complete rope physics:
-there is no built-in rope mesh, rigid-body reaction, segment or self collision,
+there is no built-in rope mesh, automatic rigid-body reaction, segment or self collision,
 or tearing. Moving entities to particle positions is not a rope renderer or
 coupled physics. Plane normals must be unit length; `offset` is the signed
 normal distance from the origin. Host intervals must be between 1/1000 and

package/engine.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "pelican-engine",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "milestone": "M3",
   "stage": "advanced-rendering-development",
   "license": "MIT",

package/lib/physics/index.js

@@ -746,6 +746,9 @@ function createPlugin(context) {
                 ]
                 : tuple(b.body.linvel());
         },
+        centerOfMass(id) {
+            return tuple(get(id).body.worldCom());
+        },
         setVelocity(id, value) {
             get(id);
             record({ kind: "velocity", id, value });

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.11";
+export declare const SDK_VERSION = "0.3.12";
 export type Vec2 = readonly [number, number];
 export type Vec3 = readonly [number, number, number];
 export type Vec4 = readonly [number, number, number, number];
@@ -104,7 +104,7 @@ export interface SystemContext extends EngineFacade {
     readonly ropes: RopeService;
 }
 /** CPU particles with sampled sphere/plane collisions. Collision only moves rope particles;
- * no rigid-body reaction, segment/self collision, rendering or complete M4 physics. */
+ * no automatic rigid-body reaction, segment/self collision, rendering or complete physics. */
 export type RopeCollider = {
     kind: "sphere";
     id: string;
@@ -135,6 +135,17 @@ export interface RopeDefinition {
         position: Vec3;
     }[];
 }
+/** Sampled-collider contact from the most recently completed rope tick. */
+export interface RopeContact {
+    tick: number;
+    particle: number;
+    colliderId: string;
+    penetration: number;
+    /** Opposite of particle projection impulses, N·s; absent in older snapshots. */
+    reactionImpulse?: Vec3;
+    /** Angular impulse about the world origin; absent in older snapshots. */
+    reactionAngularImpulse?: Vec3;
+}
 export interface RopeState {
     tick: number;
     simulatedSeconds: number;
@@ -145,12 +156,7 @@ export interface RopeState {
         index: number;
         position: Vec3;
     }[];
-    contacts: {
-        tick: number;
-        particle: number;
-        colliderId: string;
-        penetration: number;
-    }[];
+    contacts: RopeContact[];
     maxDistanceError: number;
     resources: {
         particles: number;
@@ -396,6 +402,8 @@ export interface PhysicsService {
     moveCharacter(entity: string, displacement: Vec3): void;
     grounded(entity: string): boolean;
     velocity(entity: string): Vec3;
+    /** World-space rigid-body center of mass, including collider offsets. */
+    centerOfMass(entity: string): Vec3;
     setVelocity(entity: string, velocity: Vec3): void;
     impulse(entity: string, impulse: Vec3): void;
     /** Angular velocity in world-space radians per second. */

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.11";
+export const SDK_VERSION = "0.3.12";
 export const SYSTEM_PHASES = [
     "input",
     "prePhysics",

package/lib/simulation/rope.js

@@ -9,6 +9,15 @@ export class RopeError extends Error {
 const fail = (code, reason) => { throw new RopeError(code, reason); };
 const vec = (v) => Array.isArray(v) && v.length === 3 && v.every(x => typeof x === "number" && Number.isFinite(x) && Math.abs(x) <= 1e6);
 const copy = (v) => [v[0], v[1], v[2]];
+const finiteVector = (v) => Array.isArray(v) && v.length === 3 && v.every(x => typeof x === "number" && Number.isFinite(x));
+const copyContact = (contact) => {
+    const { reactionImpulse, reactionAngularImpulse, ...rest } = contact;
+    return {
+        ...rest,
+        ...(reactionImpulse === undefined ? {} : { reactionImpulse: copy(reactionImpulse) }),
+        ...(reactionAngularImpulse === undefined ? {} : { reactionAngularImpulse: copy(reactionAngularImpulse) }),
+    };
+};
 const length = (v) => Math.hypot(v[0], v[1], v[2]);
 const validVec = (v, name) => vec(v) ? copy(v) : fail("ROPE_INPUT", `${name} must be a finite 3D vector (|component| <= 1e6)`);
 const positive = (v, name) => typeof v === "number" && Number.isFinite(v) && v > 0 && v <= 1e6 ? v : fail("ROPE_INPUT", `${name} must be positive and <= 1e6`);
@@ -220,12 +229,30 @@ export class RopeSolver {
                             continue;
                         for (let k = 0; k < 3; k++)
                             p[k] += normal[k] * depth;
+                        // Each positional projection changes the particle's velocity by depth / h.
+                        // Report its equal-and-opposite impulse and moment on the sampled surface;
+                        // the collider itself remains an immutable input and is not moved here.
+                        const magnitude = -mass * depth / h;
+                        const reaction = [normal[0] * magnitude, normal[1] * magnitude, normal[2] * magnitude];
+                        const point = c.kind === "sphere"
+                            ? [c.center[0] + normal[0] * c.radius, c.center[1] + normal[1] * c.radius, c.center[2] + normal[2] * c.radius]
+                            : [p[0] - normal[0] * radius, p[1] - normal[1] * radius, p[2] - normal[2] * radius];
+                        const moment = [point[1] * reaction[2] - point[2] * reaction[1], point[2] * reaction[0] - point[0] * reaction[2], point[0] * reaction[1] - point[1] * reaction[0]];
+                        if (!finiteVector(reaction) || !finiteVector(moment))
+                            fail("ROPE_NUMERIC", "contact reaction exceeded finite numeric bounds");
                         const key = `${i}:${c.id}`;
                         const existing = contacts.get(key);
-                        if (existing)
+                        if (existing) {
                             existing.penetration = Math.max(existing.penetration, depth);
+                            for (let k = 0; k < 3; k++) {
+                                existing.reactionImpulse[k] += reaction[k];
+                                existing.reactionAngularImpulse[k] += moment[k];
+                            }
+                            if (!finiteVector(existing.reactionImpulse) || !finiteVector(existing.reactionAngularImpulse))
+                                fail("ROPE_NUMERIC", "contact reaction accumulation exceeded finite numeric bounds");
+                        }
                         else
-                            contacts.set(key, { tick: this.tickValue + 1, particle: i, colliderId: c.id, penetration: depth });
+                            contacts.set(key, { tick: this.tickValue + 1, particle: i, colliderId: c.id, penetration: depth, reactionImpulse: reaction, reactionAngularImpulse: moment });
                     }
                 }
             }
@@ -255,7 +282,7 @@ export class RopeSolver {
             tick: this.tickValue, simulatedSeconds: this.tickValue * this.config.fixedDt, disposed: false,
             positions: this.positions.map(copy), velocities: this.velocities.map(copy),
             anchors: [...this.anchors].map(([index, position]) => ({ index, position: copy(position) })).sort((a, b) => a.index - b.index),
-            contacts: this.contacts.map(c => ({ ...c })), maxDistanceError,
+            contacts: this.contacts.map(copyContact), maxDistanceError,
             resources: { particles: this.positions.length, constraints: this.config.restLengths.length, anchors: this.anchors.size, colliders: this.colliders.length },
         };
     }
@@ -294,14 +321,16 @@ export class RopeSolver {
             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 && (!finiteVector(contact.reactionImpulse) || !finiteVector(contact.reactionAngularImpulse)))))
             fail("ROPE_SNAPSHOT", "invalid contact state");
         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(c => ({ ...c }));
+        this.contacts = input.contacts.map(copyContact);
         this.tickValue = input.tick;
     }
     dispose() {

package/package.json

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