pelican-engine 0.3.9 → 0.3.11

package/docs/npm/GAME-AUTHOR.md

@@ -118,6 +118,32 @@ batch, and the last update wins if a cell appears more than once. Entity and
 transform changes are separate from this grid-only batch. This API is new and
 has not been runtime or browser validated under the current project policy.
 
+### Development-stage 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, 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"],
 restart: ["r", "R"] }`, not `"KeyW"` or `"KeyR"`. Letter case depends on the

package/engine.manifest.json

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

package/lib/renderer/gameplay.js

@@ -4,6 +4,7 @@ import { RoomEnvironment } from "three/addons/environments/RoomEnvironment.js";
 import { createGameServices } from "../runtime/game-services.js";
 import { createPhysicsFactory } from "../physics/index.js";
 import { createNavigationPlugin } from "../navigation/index.js";
+import { createRopePlugin } from "../simulation/rope-plugin.js";
 import { createModelLibrary } from "./models.js";
 import { resolveEntityDefinition } from "../runtime/prefabs.js";
 /** Private presentation ownership. Games receive only SDK services, never browser/library objects. */
@@ -134,6 +135,7 @@ export async function prepareGameplay(ir, baseURL, renderer, materials = new Map
         const plugins = [
             services.factory,
             createNavigationPlugin,
+            createRopePlugin,
             (context) => ({
                 id: "$engine.models",
                 version: "2",

package/lib/runtime/host.js

@@ -99,10 +99,12 @@ export class RuntimeHost {
                 world: this.world,
                 fixedDt: this.fixedDt,
                 seed: this.seed,
+                afterPhysics: () => this.afterPhysics(),
             });
             this.scheduler = createdScheduler;
             for (const factory of options.plugins ?? []) {
                 const plugin = factory({
+                    fixedDt: this.fixedDt,
                     world: this.world,
                     scene: this.scene,
                     events: (type) => this.scheduler.events(type),
@@ -197,6 +199,9 @@ export class RuntimeHost {
             get navigation() {
                 return host.service("navigation");
             },
+            get ropes() {
+                return host.service("ropes");
+            },
             entities: {
                 resolve: (entity) => this.world.resolve(entity),
                 isAlive: (entity) => this.world.isAlive(entity),
@@ -251,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.");
@@ -263,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)
@@ -407,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.9";
+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];
@@ -101,6 +101,75 @@ export interface SystemContext extends EngineFacade {
     readonly render: RenderService;
     readonly compute: ComputeService;
     readonly navigation: NavigationService;
+    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. */
+export type RopeCollider = {
+    kind: "sphere";
+    id: string;
+    center: Vec3;
+    radius: number;
+} | {
+    kind: "plane";
+    id: string;
+    normal: Vec3;
+    offset: number;
+};
+export interface RopeDefinition {
+    id: string;
+    points: readonly Vec3[];
+    /** Kilograms per particle, positive and at most 1e6. */
+    mass: number;
+    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;
+    gravity?: Vec3;
+    anchors?: readonly {
+        index: number;
+        position: Vec3;
+    }[];
+}
+export interface RopeState {
+    tick: number;
+    simulatedSeconds: number;
+    disposed: boolean;
+    positions: Vec3[];
+    velocities: Vec3[];
+    anchors: {
+        index: number;
+        position: Vec3;
+    }[];
+    contacts: {
+        tick: number;
+        particle: number;
+        colliderId: string;
+        penetration: number;
+    }[];
+    maxDistanceError: number;
+    resources: {
+        particles: number;
+        constraints: number;
+        anchors: number;
+        colliders: number;
+    };
+}
+export interface RopeService {
+    create(definition: RopeDefinition): void;
+    /** 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;
+    setAnchor(id: string, index: number, position: Vec3): void;
+    releaseAnchor(id: string, index: number): void;
+    applyForce(id: string, index: number, force: Vec3): void;
+    applyImpulse(id: string, index: number, impulse: Vec3): void;
+    destroy(id: string): void;
 }
 /** Integer cells on a finite 2D orthogonal grid; not continuous, flying or underwater navigation.
  * Searches allocate sparse state and depend on available memory. At most 2^32-1 cells may be defined.

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

package/lib/simulation/rope-plugin.js

@@ -0,0 +1,124 @@
+import { cloneSerializable } from "../runtime/random.js";
+import { createRope } from "./rope.js";
+const fail = (code, detail) => { throw new Error(`TC_ROPE_${code}: ${detail}`); };
+const validId = (id) => typeof id === "string" && id.trim() === id && id.length > 0 && id.length <= 128;
+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)
+        return fail("FIXED_DT", "Host fixedDt must be within [1/1000, 1/30] seconds for ropes.");
+    const solver = createRope({ ...definition, fixedDt });
+    return { definition, solver };
+}
+function disposeEntries(entries) {
+    for (const { solver } of entries.values())
+        solver.dispose();
+    entries.clear();
+}
+function parseSnapshot(value, fixedDt) {
+    if (!value || typeof value !== "object" || value.version !== 1 || !Array.isArray(value.ropes) || value.ropes.length > 256)
+        return fail("SNAPSHOT", "Expected a version 1 rope snapshot with at most 256 ropes.");
+    const entries = new Map();
+    try {
+        for (const item of value.ropes) {
+            if (!item || typeof item !== "object")
+                fail("SNAPSHOT", "Invalid rope entry.");
+            const entry = createEntry(item.definition, fixedDt);
+            if (entries.has(entry.definition.id)) {
+                entry.solver.dispose();
+                fail("SNAPSHOT", "Duplicate rope id.");
+            }
+            entries.set(entry.definition.id, entry);
+            entry.solver.restore(item.state);
+        }
+        return entries;
+    }
+    catch (error) {
+        disposeEntries(entries);
+        throw error;
+    }
+}
+/** 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.");
+    const hostDt = fixedDt;
+    let entries = new Map();
+    let disposed = false;
+    const alive = () => { if (disposed)
+        fail("DISPOSED", "Rope service is disposed."); };
+    const get = (id) => {
+        alive();
+        if (!validId(id))
+            return fail("ID", "Expected a nonempty rope id.");
+        return entries.get(id) ?? fail("MISSING", `Rope '${id}' does not exist.`);
+    };
+    const service = {
+        create(definition) {
+            alive();
+            if (!definition || !validId(definition.id))
+                return fail("ID", "Expected a nonempty rope id.");
+            if (entries.has(definition.id))
+                return fail("DUPLICATE", `Rope '${definition.id}' already exists.`);
+            if (entries.size >= 256)
+                return fail("CAPACITY", "At most 256 ropes per host.");
+            const entry = createEntry(definition, hostDt);
+            entries.set(entry.definition.id, entry);
+        },
+        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)); },
+        releaseAnchor(id, index) { get(id).solver.releaseAnchor(index); },
+        applyForce(id, index, force) { get(id).solver.applyForce(index, cloneSerializable(force)); },
+        applyImpulse(id, index, impulse) { get(id).solver.applyImpulse(index, cloneSerializable(impulse)); },
+        destroy(id) { const entry = get(id); entry.solver.dispose(); entries.delete(id); },
+    };
+    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); },
+        restore(value) { alive(); const staged = parseSnapshot(value, hostDt); disposeEntries(entries); entries = staged; },
+        dispose() { if (disposed)
+            return; disposed = true; disposeEntries(entries); },
+    };
+};