pelican-engine 0.3.9 → 0.3.10

package/docs/npm/GAME-AUTHOR.md

@@ -118,6 +118,24 @@ 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 })` 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`.
+
+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.
+
 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.10",
   "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

@@ -103,6 +103,7 @@ export class RuntimeHost {
             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 +198,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),

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.10";
 export type Vec2 = readonly [number, number];
 export type Vec3 = readonly [number, number, number];
 export type Vec4 = readonly [number, number, number, number];
@@ -101,6 +101,73 @@ 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;
+    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 fixed solver ticks; not automatically advanced with the host. 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.10";
 export const SYSTEM_PHASES = [
     "input",
     "prePhysics",

package/lib/simulation/rope-plugin.js

@@ -0,0 +1,89 @@
+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.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;
+    }
+}
+/** Explicitly stepped CPU rope ownership; independent from the Rapier physics plugin. */
+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) { return get(id).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 },
+        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); },
+    };
+};

package/lib/simulation/rope.js

@@ -0,0 +1,318 @@
+export class RopeError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.name = "RopeError";
+    }
+}
+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 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`);
+const bounded = (v, name, max) => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= max ? v : fail("ROPE_INPUT", `${name} must be within [0, ${max}]`);
+const indexOf = (v, count) => Number.isSafeInteger(v) && v >= 0 && v < count ? v : fail("ROPE_INDEX", "particle index out of range");
+const finiteState = (v) => vec(v);
+function readColliders(input) {
+    if (!Array.isArray(input) || input.length > 4096)
+        fail("ROPE_INPUT", "colliders must be an array (max 4096)");
+    const ids = new Set();
+    return input.map((c) => {
+        if (!c || typeof c !== "object" || typeof c.id !== "string" || !c.id || ids.has(c.id))
+            fail("ROPE_INPUT", "collider ids must be unique nonempty strings");
+        ids.add(c.id);
+        if (c.kind === "sphere")
+            return { kind: "sphere", id: c.id, center: validVec(c.center, "center"), radius: positive(c.radius, "sphere radius") };
+        if (c.kind === "plane") {
+            const normal = validVec(c.normal, "normal"), n = length(normal);
+            if (Math.abs(n - 1) > 1e-6)
+                fail("ROPE_INPUT", "plane normal must have unit length");
+            return { kind: "plane", id: c.id, normal, offset: boundedSigned(c.offset, "plane offset") };
+        }
+        return fail("ROPE_INPUT", "unsupported collider kind");
+    });
+}
+function boundedSigned(v, name) {
+    return typeof v === "number" && Number.isFinite(v) && Math.abs(v) <= 1e6 ? v : fail("ROPE_INPUT", `${name} must be finite (|value| <= 1e6)`);
+}
+function readAnchors(input, count) {
+    if (!Array.isArray(input) || input.length > count)
+        fail("ROPE_INPUT", "anchors must be an array of unique particle indices");
+    const result = new Map();
+    for (const a of input) {
+        if (!a || typeof a !== "object")
+            fail("ROPE_INPUT", "invalid anchor");
+        const i = indexOf(a.index, count);
+        if (result.has(i))
+            fail("ROPE_INPUT", "duplicate anchor index");
+        result.set(i, validVec(a.position, "anchor position"));
+    }
+    return result;
+}
+export function createRope(options) {
+    if (!options || typeof options !== "object" || !Array.isArray(options.points) || options.points.length < 2 || options.points.length > 4096)
+        fail("ROPE_INPUT", "points must contain 2..4096 particles");
+    const positions = options.points.map((p, i) => validVec(p, `points[${i}]`));
+    const mass = positive(options.mass, "mass");
+    const radius = positive(options.radius ?? 0.025, "radius");
+    const fixedDt = positive(options.fixedDt ?? 1 / 60, "fixedDt");
+    if (fixedDt < 1 / 1000 || fixedDt > 1 / 30)
+        fail("ROPE_INPUT", "fixedDt must be in [1/1000, 1/30]");
+    const substeps = options.substeps ?? 4, iterations = options.iterations ?? 12;
+    if (!Number.isInteger(substeps) || substeps < 1 || substeps > 32 || !Number.isInteger(iterations) || iterations < 1 || iterations > 64)
+        fail("ROPE_INPUT", "substeps/iterations must be positive bounded integers");
+    const damping = bounded(options.damping ?? 0.15, "damping", 100);
+    const gravity = validVec(options.gravity ?? [0, -9.81, 0], "gravity");
+    const restLengths = positions.slice(1).map((p, i) => length([p[0] - positions[i][0], p[1] - positions[i][1], p[2] - positions[i][2]]));
+    if (restLengths.some(d => !Number.isFinite(d) || d <= 1e-8))
+        fail("ROPE_INPUT", "adjacent particles must have distinct positions");
+    const anchors = readAnchors(options.anchors ?? [{ index: 0, position: positions[0] }], positions.length);
+    for (const [i, p] of anchors)
+        positions[i] = copy(p);
+    return new RopeSolver({ mass, radius, fixedDt, substeps, iterations, damping, gravity, restLengths }, positions, anchors);
+}
+export class RopeSolver {
+    config;
+    positions;
+    anchors;
+    tickValue = 0;
+    disposedValue = false;
+    velocities;
+    forces;
+    colliders = [];
+    contacts = [];
+    constructor(config, positions, anchors) {
+        this.config = config;
+        this.positions = positions;
+        this.anchors = anchors;
+        this.velocities = positions.map(() => [0, 0, 0]);
+        this.forces = positions.map(() => [0, 0, 0]);
+    }
+    alive() { if (this.disposedValue)
+        fail("ROPE_DISPOSED", "rope has been disposed"); }
+    /** Copies all inputs: callers may mutate their arrays after calling this. */
+    setColliders(input) {
+        this.alive();
+        this.colliders = readColliders(input);
+        this.contacts = [];
+    }
+    /** Pins or moves a particle; new anchor position takes effect immediately. */
+    setAnchor(index, position) {
+        this.alive();
+        const i = indexOf(index, this.positions.length), p = validVec(position, "anchor position");
+        this.anchors.set(i, p);
+        this.positions[i] = copy(p);
+        this.velocities[i] = [0, 0, 0];
+        this.forces[i] = [0, 0, 0];
+    }
+    releaseAnchor(index) { this.alive(); this.anchors.delete(indexOf(index, this.positions.length)); }
+    /** N·s (kg·m/s); changes velocity immediately, not position. */
+    applyImpulse(index, impulse) {
+        this.alive();
+        const i = indexOf(index, this.positions.length), v = validVec(impulse, "impulse");
+        if (this.anchors.has(i))
+            fail("ROPE_ANCHORED", "cannot apply impulse to an anchor");
+        const next = [0, 1, 2].map(k => this.velocities[i][k] + v[k] / this.config.mass);
+        if (!finiteState(next))
+            fail("ROPE_NUMERIC", "impulse exceeds numeric bounds");
+        this.velocities[i] = next;
+    }
+    /** Newtons accumulated for exactly one next fixed tick; not a persistent force. */
+    applyForce(index, force) {
+        this.alive();
+        const i = indexOf(index, this.positions.length), v = validVec(force, "force");
+        if (this.anchors.has(i))
+            fail("ROPE_ANCHORED", "cannot apply force to an anchor");
+        const next = [0, 1, 2].map(k => this.forces[i][k] + v[k]);
+        if (!finiteState(next))
+            fail("ROPE_NUMERIC", "force accumulation exceeds numeric bounds");
+        this.forces[i] = next;
+    }
+    /** Exactly N fixed ticks; a failed batch restores the state before the first tick. */
+    step(steps = 1) {
+        this.alive();
+        if (!Number.isSafeInteger(steps) || steps < 1 || steps > 1000 || this.tickValue + steps > Number.MAX_SAFE_INTEGER)
+            fail("ROPE_INPUT", "steps must be an integer in [1,1000] without tick overflow");
+        // stepOne replaces these arrays rather than mutating the prior committed state.
+        const before = {
+            positions: this.positions,
+            velocities: this.velocities,
+            forces: this.forces,
+            contacts: this.contacts,
+            tick: this.tickValue,
+        };
+        try {
+            for (let s = 0; s < steps; s++)
+                this.stepOne();
+        }
+        catch (error) {
+            this.positions = before.positions;
+            this.velocities = before.velocities;
+            this.forces = before.forces;
+            this.contacts = before.contacts;
+            this.tickValue = before.tick;
+            throw error;
+        }
+        return this.inspect();
+    }
+    stepOne() {
+        const { fixedDt, substeps, iterations, mass, gravity, damping, restLengths, radius } = this.config;
+        const h = fixedDt / substeps, decay = Math.exp(-damping * h);
+        // Work on copies; numeric failures must never leave half a tick applied.
+        const positions = this.positions.map(copy), velocities = this.velocities.map(copy);
+        const contacts = new Map();
+        for (let sub = 0; sub < substeps; sub++) {
+            const previous = positions.map(copy);
+            for (let i = 0; i < positions.length; i++) {
+                const anchor = this.anchors.get(i);
+                if (anchor) {
+                    positions[i] = copy(anchor);
+                    velocities[i] = [0, 0, 0];
+                    continue;
+                }
+                for (let k = 0; k < 3; k++) {
+                    velocities[i][k] = velocities[i][k] * decay + (gravity[k] + this.forces[i][k] / mass) * h;
+                    positions[i][k] += velocities[i][k] * h;
+                }
+            }
+            for (let iter = 0; iter < iterations; iter++) {
+                for (let j = 0; j < restLengths.length; j++) {
+                    const a = positions[j], b = positions[j + 1];
+                    let dx = b[0] - a[0], dy = b[1] - a[1], dz = b[2] - a[2];
+                    let dist = Math.hypot(dx, dy, dz);
+                    // If a contact collapses a link, separate it on a deterministic axis.
+                    if (dist < 1e-12) {
+                        dx = 1e-6;
+                        dy = 0;
+                        dz = 0;
+                        dist = 1e-6;
+                    }
+                    const wa = this.anchors.has(j) ? 0 : 1, wb = this.anchors.has(j + 1) ? 0 : 1;
+                    if (wa + wb === 0)
+                        continue; // two incompatible kinematic anchors are intentionally authoritative
+                    const d = (dist - restLengths[j]) / (dist * (wa + wb));
+                    for (let k = 0; k < 3; k++) {
+                        const correction = (k === 0 ? dx : k === 1 ? dy : dz) * d;
+                        a[k] += correction * wa;
+                        b[k] -= correction * wb;
+                    }
+                }
+                for (let i = 0; i < positions.length; i++) {
+                    if (this.anchors.has(i))
+                        continue; // anchors cannot be displaced by external colliders
+                    const p = positions[i];
+                    for (const c of this.colliders) {
+                        let depth = 0;
+                        let normal;
+                        if (c.kind === "plane") {
+                            depth = c.offset + radius - (p[0] * c.normal[0] + p[1] * c.normal[1] + p[2] * c.normal[2]);
+                            normal = c.normal;
+                        }
+                        else {
+                            const delta = [p[0] - c.center[0], p[1] - c.center[1], p[2] - c.center[2]];
+                            const distance = length(delta);
+                            depth = c.radius + radius - distance;
+                            normal = distance < 1e-12 ? [1, 0, 0] : [delta[0] / distance, delta[1] / distance, delta[2] / distance];
+                        }
+                        if (depth <= 0)
+                            continue;
+                        for (let k = 0; k < 3; k++)
+                            p[k] += normal[k] * depth;
+                        const key = `${i}:${c.id}`;
+                        const existing = contacts.get(key);
+                        if (existing)
+                            existing.penetration = Math.max(existing.penetration, depth);
+                        else
+                            contacts.set(key, { tick: this.tickValue + 1, particle: i, colliderId: c.id, penetration: depth });
+                    }
+                }
+            }
+            for (let i = 0; i < positions.length; i++) {
+                if (this.anchors.has(i))
+                    continue;
+                for (let k = 0; k < 3; k++)
+                    velocities[i][k] = (positions[i][k] - previous[i][k]) / h;
+                if (!finiteState(positions[i]) || !finiteState(velocities[i]))
+                    fail("ROPE_NUMERIC", "solver exceeded finite state bounds");
+            }
+        }
+        this.positions = positions;
+        this.velocities = velocities;
+        this.forces = positions.map(() => [0, 0, 0]);
+        this.contacts = [...contacts.values()];
+        this.tickValue++;
+    }
+    inspect() {
+        if (this.disposedValue)
+            return { tick: this.tickValue, simulatedSeconds: this.tickValue * this.config.fixedDt, disposed: true, positions: [], velocities: [], anchors: [], contacts: [], maxDistanceError: 0, resources: { particles: 0, constraints: 0, anchors: 0, colliders: 0 } };
+        const maxDistanceError = Math.max(0, ...this.config.restLengths.map((d, i) => {
+            const a = this.positions[i], b = this.positions[i + 1];
+            return Math.abs(Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]) - d);
+        }));
+        return {
+            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,
+            resources: { particles: this.positions.length, constraints: this.config.restLengths.length, anchors: this.anchors.size, colliders: this.colliders.length },
+        };
+    }
+    snapshot() {
+        this.alive();
+        const state = this.inspect();
+        return {
+            format: "pelican-rope-cpu", version: 1, tick: this.tickValue,
+            config: { ...this.config, gravity: copy(this.config.gravity), restLengths: [...this.config.restLengths] },
+            positions: state.positions, velocities: state.velocities, anchors: state.anchors,
+            forces: this.forces.map(copy), colliders: readColliders(this.colliders), contacts: state.contacts,
+        };
+    }
+    /** Accepts a JSON-round-tripped snapshot only from the same rope configuration. Atomic on failure. */
+    restore(input) {
+        this.alive();
+        if (!input || typeof input !== "object" || input.format !== "pelican-rope-cpu" || input.version !== 1 ||
+            !Number.isSafeInteger(input.tick) || input.tick < 0)
+            fail("ROPE_SNAPSHOT", "unsupported snapshot format or tick");
+        const c = input.config;
+        if (!c || c.mass !== this.config.mass || c.radius !== this.config.radius || c.fixedDt !== this.config.fixedDt ||
+            c.substeps !== this.config.substeps || c.iterations !== this.config.iterations || c.damping !== this.config.damping ||
+            !vec(c.gravity) || c.gravity.some((v, i) => v !== this.config.gravity[i]) ||
+            !Array.isArray(c.restLengths) || c.restLengths.length !== this.config.restLengths.length ||
+            c.restLengths.some((v, i) => v !== this.config.restLengths[i]))
+            fail("ROPE_SNAPSHOT", "rope configuration/topology mismatch");
+        const count = this.positions.length;
+        if (!Array.isArray(input.positions) || !Array.isArray(input.velocities) || !Array.isArray(input.forces) ||
+            [input.positions, input.velocities, input.forces].some(v => v.length !== count || !v.every(vec)))
+            fail("ROPE_SNAPSHOT", "invalid particle state");
+        const anchors = readAnchors(input.anchors, count);
+        if ([...anchors].some(([i, p]) => p.some((v, k) => v !== input.positions[i][k]) || input.velocities[i].some(v => v !== 0) || input.forces[i].some(v => v !== 0)))
+            fail("ROPE_SNAPSHOT", "inconsistent anchored particle state");
+        const colliders = readColliders(input.colliders);
+        if (!Array.isArray(input.contacts) || input.contacts.length > count * Math.max(1, 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))
+            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.tickValue = input.tick;
+    }
+    dispose() {
+        if (this.disposedValue)
+            return;
+        this.disposedValue = true;
+        this.positions = [];
+        this.velocities = [];
+        this.forces = [];
+        this.colliders = [];
+        this.contacts = [];
+        this.anchors.clear();
+    }
+}

package/package.json

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