pelican-engine 0.3.10 → 0.3.11

package/docs/npm/GAME-AUTHOR.md

@@ -120,21 +120,29 @@ 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`.
 
 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, 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.11",
   "milestone": "M3",
   "stage": "advanced-rendering-development",
   "license": "MIT",

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.11";
 export type Vec2 = readonly [number, number];
 export type Vec3 = readonly [number, number, number];
 export type Vec4 = readonly [number, number, number, number];
@@ -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;
@@ -159,7 +161,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;

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.11";
 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/package.json

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