pelican-engine 0.3.10 → 0.3.12

package/docs/npm/GAME-AUTHOR.md

@@ -120,21 +120,45 @@ has not been runtime or browser validated under the current project policy.
 
 ### Development-stage rope particles
 
-`ctx.ropes.create({ id, points, mass })` creates a CPU particle rope. Call
-`ctx.ropes.step(id)` **once per game fixed tick** when movement is desired;
-the host does not advance it automatically. The first particle is pinned by
-default; `anchors: []` creates a free rope. `setAnchor`, `releaseAnchor`,
-`applyForce` (next tick only), `applyImpulse`, `inspect`, and `destroy` manage
-it. `setColliders` accepts sampled planes and spheres; contacts affect only
-particles, not rigid bodies. Host snapshots include rope state. An example in
-the source checkout is `examples/rope-particles`.
+`ctx.ropes.create({ id, points, mass, autoStep: true })` creates a CPU particle
+rope that advances once after each physics phase, before `postPhysics` systems.
+Set anchors, forces and sampled colliders in `prePhysics`; read positions in
+`postPhysics`. Without `autoStep`, the rope remains manually stepped with
+`ctx.ropes.step(id)`; calling `step` for an automatic rope returns
+`TC_ROPE_AUTO_STEP` instead of advancing twice. An automatic rope created during
+`prePhysics` advances in that tick. The first particle is pinned by default;
+`anchors: []` creates a free rope. `setAnchor`, `releaseAnchor`, `applyForce`
+(next tick only), `applyImpulse`, `inspect`, and `destroy` manage it.
+
+`setColliders` accepts sampled planes and spheres; contacts affect only rope
+particles, not rigid bodies. Host snapshots include the rope definition, mode
+and state. If advancing an automatic rope fails, the engine attempts to restore
+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, automatic fixed-tick scheduling, rigid-body
-reaction, segment or self collision, or tearing. Game code may use `positions`
-to move entities but this is not a substitute for a rope renderer or coupled
-physics. Plane normals must be unit length; `offset` is the plane's signed
-normal distance from the origin. The host interval must be 1/1000?1/30 seconds.
+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
+1/30 seconds inclusive.
 
 Keyboard bindings use the browser's `KeyboardEvent.key` values, not physical
 `KeyboardEvent.code` values. For example, use `input: { up: ["w", "W", "ArrowUp"],

package/engine.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "pelican-engine",
-  "version": "0.3.10",
+  "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/runtime/host.js

@@ -99,6 +99,7 @@ export class RuntimeHost {
                 world: this.world,
                 fixedDt: this.fixedDt,
                 seed: this.seed,
+                afterPhysics: () => this.afterPhysics(),
             });
             this.scheduler = createdScheduler;
             for (const factory of options.plugins ?? []) {
@@ -255,6 +256,15 @@ export class RuntimeHost {
             },
         };
     }
+    afterPhysics() {
+        for (const plugin of this.plugins) {
+            const result = plugin.afterPhysics?.();
+            if (result && (typeof result === "object" || typeof result === "function") && "then" in result) {
+                void Promise.resolve(result).catch(() => { });
+                throw new Error(`TC_PLUGIN_ASYNC: afterPhysics for ${plugin.id} must complete synchronously.`);
+            }
+        }
+    }
     registerPlugin(plugin) {
         if (!plugin || typeof plugin !== "object")
             throw new Error("TC_PLUGIN_ID: Plugin must have a stable non-empty id.");
@@ -267,7 +277,8 @@ export class RuntimeHost {
             typeof plugin.validateSnapshot !== "function" ||
             typeof plugin.restore !== "function" ||
             typeof plugin.dispose !== "function" ||
-            (plugin.settle !== undefined && typeof plugin.settle !== "function"))
+            (plugin.settle !== undefined && typeof plugin.settle !== "function") ||
+            (plugin.afterPhysics !== undefined && typeof plugin.afterPhysics !== "function"))
             throw new Error(`TC_PLUGIN_CONTRACT: Plugin ${plugin.id} is missing lifecycle methods.`);
         for (const [key, service] of Object.entries(plugin.services ?? {})) {
             if (service === undefined)
@@ -411,6 +422,7 @@ export class RuntimeHost {
             world: this.world,
             fixedDt: this.fixedDt,
             seed: this.seed,
+            afterPhysics: () => this.afterPhysics(),
             systems: [
                 ...engineSystems.map((system) => ({
                     ...system,

package/lib/runtime/scheduler.js

@@ -131,10 +131,12 @@ function schedule(input) {
  * advance() is an alternative wall-clock driver, never a second fixed-step layer.
  * Flush boundaries: start tick, after input events, end each phase. Failed ticks
  * may have changed world/random/events: pause and require a known-good restore. */
-export function createScheduler({ world, systems = [], fixedDt = 1 / 60, maxSubsteps = 8, seed = 0, }) {
+export function createScheduler({ world, systems = [], fixedDt = 1 / 60, maxSubsteps = 8, seed = 0, afterPhysics, }) {
     if (!Number.isFinite(fixedDt) || fixedDt <= 0)
         throw new Error("TC_SCHEDULER_DT: fixedDt must be positive and finite.");
     integer(maxSubsteps, "maxSubsteps", 1);
+    if (afterPhysics !== undefined && typeof afterPhysics !== "function")
+        throw new Error("TC_SCHEDULER_AFTER_PHYSICS: Expected a synchronous callback.");
     const random = createRandom(seed);
     let plan = schedule(systems);
     let completedTick = 0, accumulator = 0, compensation = 0, paused = false, running = false;
@@ -260,6 +262,14 @@ export function createScheduler({ world, systems = [], fixedDt = 1 / 60, maxSubs
                 }
                 stage = `flush:${phase}`;
                 world.flush();
+                if (phase === "physics" && afterPhysics) {
+                    stage = "engine:afterPhysics";
+                    const result = afterPhysics();
+                    if (result && (typeof result === "object" || typeof result === "function") && "then" in result) {
+                        void Promise.resolve(result).catch(() => { });
+                        throw new Error("TC_SCHEDULER_ASYNC: Engine callbacks must complete synchronously.");
+                    }
+                }
             }
             completedTick++;
             return true;

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.10";
+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;
@@ -124,6 +124,8 @@ export interface RopeDefinition {
     radius?: number;
     /** Defaults to the host interval; an explicit value must exactly match it. */
     fixedDt?: number;
+    /** When true, step once after each physics phase; defaults to false (manual stepping). */
+    autoStep?: boolean;
     substeps?: number;
     iterations?: number;
     damping?: number;
@@ -133,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;
@@ -143,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;
@@ -159,7 +167,7 @@ export interface RopeState {
 }
 export interface RopeService {
     create(definition: RopeDefinition): void;
-    /** Explicit fixed solver ticks; not automatically advanced with the host. A failed batch leaves the rope unchanged. */
+    /** Explicit ticks for manual ropes only. Auto-stepped ropes reject this call. A failed batch leaves the rope unchanged. */
     step(id: string, ticks?: number): RopeState;
     inspect(id: string): RopeState;
     setColliders(id: string, colliders: readonly RopeCollider[]): void;
@@ -394,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.10";
+export const SDK_VERSION = "0.3.12";
 export const SYSTEM_PHASES = [
     "input",
     "prePhysics",

package/lib/simulation/rope-plugin.js

@@ -6,6 +6,8 @@ function createEntry(input, fixedDt) {
     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 a boolean.");
     if (definition.fixedDt !== undefined && definition.fixedDt !== fixedDt)
         return fail("FIXED_DT", "Rope fixedDt must exactly match the host fixedDt.");
     if (fixedDt < 1 / 1000 || fixedDt > 1 / 30)
@@ -41,7 +43,7 @@ function parseSnapshot(value, fixedDt) {
         throw error;
     }
 }
-/** Explicitly stepped CPU rope ownership; independent from the Rapier physics plugin. */
+/** CPU rope ownership; optional host-scheduled stepping remains independent from Rapier. */
 export const createRopePlugin = ({ fixedDt }) => {
     if (typeof fixedDt !== "number" || !Number.isFinite(fixedDt))
         return fail("FIXED_DT", "RuntimeHost must provide a finite fixed interval.");
@@ -68,7 +70,12 @@ export const createRopePlugin = ({ fixedDt }) => {
             const entry = createEntry(definition, hostDt);
             entries.set(entry.definition.id, entry);
         },
-        step(id, ticks) { return get(id).solver.step(ticks); },
+        step(id, ticks) {
+            const entry = get(id);
+            if (entry.definition.autoStep)
+                return fail("AUTO_STEP", `Rope '${id}' is automatically stepped; omit autoStep for manual stepping.`);
+            return entry.solver.step(ticks);
+        },
         inspect(id) { return get(id).solver.inspect(); },
         setColliders(id, colliders) { get(id).solver.setColliders(cloneSerializable(colliders)); },
         setAnchor(id, index, position) { get(id).solver.setAnchor(index, cloneSerializable(position)); },
@@ -79,6 +86,34 @@ export const createRopePlugin = ({ fixedDt }) => {
     };
     return {
         id: "$engine.ropes", version: "1", services: { ropes: service },
+        afterPhysics() {
+            alive();
+            const committed = [];
+            try {
+                // Stable ordering also makes failure and recording behavior independent of insertion order.
+                const automatic = [...entries.values()].filter(entry => entry.definition.autoStep)
+                    .sort((a, b) => a.definition.id < b.definition.id ? -1 : a.definition.id > b.definition.id ? 1 : 0);
+                for (const { solver } of automatic) {
+                    const snapshot = solver.snapshot();
+                    solver.step(); // A failed solver step rolls itself back.
+                    committed.push({ solver, snapshot });
+                }
+            }
+            catch (error) {
+                const failures = [];
+                for (const { solver, snapshot } of committed.reverse()) {
+                    try {
+                        solver.restore(snapshot);
+                    }
+                    catch (rollbackError) {
+                        failures.push(String(rollbackError));
+                    }
+                }
+                if (failures.length)
+                    throw new Error(`TC_ROPE_ROLLBACK: ${String(error)}; partialState=true; rollback failures: ${failures.join("; ")}`);
+                throw error;
+            }
+        },
         legacySnapshot: () => ({ version: 1, ropes: [] }),
         snapshot: () => ({ version: 1, ropes: [...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); disposeEntries(staged); },

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.10",
+  "version": "0.3.12",
   "description": "Pelican Engine public SDK and offline development CLI",
   "type": "module",
   "license": "MIT",