pelican-engine 0.3.12 → 0.3.13

package/docs/npm/GAME-AUTHOR.md

@@ -137,15 +137,35 @@ 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`.
 
+To bind a rope to existing dynamic sphere bodies, create it with `autoStep: true`
+and `bodyColliders: [{ id: "rope-collider-id", entity: "body-id" }]`. After the
+rigid-body physics phase, the host samples each bound sphere's actual collider
+center and radius, steps the rope, and applies the resulting normal projection
+impulse to the body. That impulse changes body velocity; displacement responds on
+the next body step. Bindings require live dynamic non-trigger spheres and unique
+collider ids and body entities within each rope. Do not use a bound collider id
+in `setColliders`; its manual planes and spheres remain separate. A destroyed body
+is unbound at the next automatic step, and a new entity with the same id is not
+implicitly rebound. Bindings are saved with Host snapshots.
+
+Do not manually apply the same contact's reaction when using a body binding: the
+host already applies it. A native failure can still leave the host tick partially
+changed, so restore a known-good checkpoint. This is delayed sampled coupling and
+is not a complete physics solver: body velocity/effective mass, friction,
+continuous collision and coupled substeps are not included. It has not been
+runtime or snapshot validated.
+
 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.
+restoring older contact snapshots. Contacts from unbound manual colliders 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`.
+the same contacts. The source checkout's `examples/rope-reaction` uses the
+automatic binding instead.
 
 This sampled, manually applied reaction is delayed and uses positional correction,
 not a coupled contact solver: it omits body velocity/effective mass, friction and
@@ -154,7 +174,7 @@ 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 rigid-body reaction, segment or self collision,
+there is no built-in rope mesh, general rigid-body coupling, 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.12",
+  "version": "0.3.13",
   "milestone": "M3",
   "stage": "advanced-rendering-development",
   "license": "MIT",

package/lib/physics/index.js

@@ -809,10 +809,35 @@ function createPlugin(context) {
             };
         },
     };
+    const sampleRopeSphere = (id) => {
+        const b = get(id);
+        if (b.type !== "dynamic" || b.definition.rigidBody?.collider.shape !== "sphere" || b.collider.isSensor())
+            fail("TC_PHYSICS_ROPE_BODY", `Rope body '${id}' must be a live dynamic, non-trigger sphere.`);
+        return { center: tuple(b.collider.translation()), radius: b.collider.radius() };
+    };
     return {
         id: pluginId,
         version: "3",
         services: { physics },
+        ropePhysicsBridge: {
+            sampleSphere: sampleRopeSphere,
+            applySphereReactions(reactions) {
+                alive();
+                if (history.length + reactions.length > limit)
+                    fail("TC_PHYSICS_HISTORY_LIMIT", "Rope reactions exceed physics history capacity; start a new scene.");
+                const seen = new Set();
+                const actions = reactions.map(({ entity, impulse }) => {
+                    if (seen.has(entity))
+                        fail("TC_PHYSICS_ROPE_BODY", `Duplicate rope reaction body '${entity}'.`);
+                    seen.add(entity);
+                    const sample = sampleRopeSphere(entity);
+                    return { kind: "impulseAtPoint", id: entity, value: tuple(vec(impulse, "rope reaction")), point: sample.center };
+                });
+                // Validation precedes mutation; a native error can still leave a partial batch.
+                for (const action of actions)
+                    record(action);
+            },
+        },
         systems: [
             {
                 id: pluginId,

package/lib/runtime/host.js

@@ -105,6 +105,7 @@ export class RuntimeHost {
             for (const factory of options.plugins ?? []) {
                 const plugin = factory({
                     fixedDt: this.fixedDt,
+                    getRopePhysicsBridge: () => this.plugins.find((plugin) => plugin.id === "$engine.physics")?.ropePhysicsBridge,
                     world: this.world,
                     scene: this.scene,
                     events: (type) => this.scheduler.events(type),

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.12";
+export declare const SDK_VERSION = "0.3.13";
 export type Vec2 = readonly [number, number];
 export type Vec3 = readonly [number, number, number];
 export type Vec4 = readonly [number, number, number, number];
@@ -103,8 +103,8 @@ export interface SystemContext extends EngineFacade {
     readonly navigation: NavigationService;
     readonly ropes: RopeService;
 }
-/** CPU particles with sampled sphere/plane collisions. Collision only moves rope particles;
- * no automatic rigid-body reaction, segment/self collision, rendering or complete physics. */
+/** CPU particles with sampled sphere/plane collisions. Explicit body bindings apply a delayed
+ * projection reaction to dynamic spheres; no full rigid-body coupling, segment/self collision or rope rendering. */
 export type RopeCollider = {
     kind: "sphere";
     id: string;
@@ -116,6 +116,11 @@ export type RopeCollider = {
     normal: Vec3;
     offset: number;
 };
+/** Explicit connection between a sampled rope collider id and a dynamic sphere body. */
+export interface RopeBodyCollider {
+    readonly id: string;
+    readonly entity: string;
+}
 export interface RopeDefinition {
     id: string;
     points: readonly Vec3[];
@@ -126,6 +131,8 @@ export interface RopeDefinition {
     fixedDt?: number;
     /** When true, step once after each physics phase; defaults to false (manual stepping). */
     autoStep?: boolean;
+    /** Automatically sample and react to existing dynamic, non-trigger sphere bodies. Requires autoStep. */
+    bodyColliders?: readonly RopeBodyCollider[];
     substeps?: number;
     iterations?: number;
     damping?: number;

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

package/lib/simulation/rope-plugin.js

@@ -1,3 +1,4 @@
+import { resolveEntityDefinition } from "../runtime/prefabs.js";
 import { cloneSerializable } from "../runtime/random.js";
 import { createRope } from "./rope.js";
 const fail = (code, detail) => { throw new Error(`TC_ROPE_${code}: ${detail}`); };
@@ -12,8 +13,21 @@ function createEntry(input, 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.");
+    if (definition.bodyColliders !== undefined) {
+        if (!Array.isArray(definition.bodyColliders) || definition.bodyColliders.length > 64)
+            return fail("BODY_COLLIDER", "bodyColliders must contain at most 64 bindings.");
+        if (definition.bodyColliders.length && !definition.autoStep)
+            return fail("BODY_COLLIDER", "Body bindings require autoStep: true.");
+        const ids = new Set(), entities = new Set();
+        for (const binding of definition.bodyColliders) {
+            if (!binding || typeof binding !== "object" || !validId(binding.id) || !validId(binding.entity) || ids.has(binding.id) || entities.has(binding.entity))
+                return fail("BODY_COLLIDER", "Each binding requires a unique nonempty collider id and body entity.");
+            ids.add(binding.id);
+            entities.add(binding.entity);
+        }
+    }
     const solver = createRope({ ...definition, fixedDt });
-    return { definition, solver };
+    return { definition, solver, bodyRefs: new Map(), staleBodies: new Set() };
 }
 function disposeEntries(entries) {
     for (const { solver } of entries.values())
@@ -34,6 +48,11 @@ function parseSnapshot(value, fixedDt) {
                 fail("SNAPSHOT", "Duplicate rope id.");
             }
             entries.set(entry.definition.id, entry);
+            const stale = item.staleBodyColliders === undefined ? [] : item.staleBodyColliders;
+            const bound = new Set((entry.definition.bodyColliders ?? []).map(binding => binding.id));
+            if (!Array.isArray(stale) || stale.some(id => typeof id !== "string" || !bound.has(id)) || new Set(stale).size !== stale.length)
+                fail("SNAPSHOT", "Invalid stale body collider list.");
+            entry.staleBodies = new Set(stale);
             entry.solver.restore(item.state);
         }
         return entries;
@@ -43,17 +62,60 @@ function parseSnapshot(value, fixedDt) {
         throw error;
     }
 }
-/** CPU rope ownership; optional host-scheduled stepping remains independent from Rapier. */
-export const createRopePlugin = ({ fixedDt }) => {
+function bridgeFor(context) {
+    return context.getRopePhysicsBridge?.() ?? fail("BODY_COLLIDER", "Body colliders require the physics plugin and a live dynamic sphere.");
+}
+function resolveRefs(entry, context, checkPhysics) {
+    const refs = new Map();
+    const specs = entry.definition.bodyColliders ?? [];
+    const bridge = checkPhysics && specs.length ? bridgeFor(context) : undefined;
+    for (const spec of specs) {
+        if (entry.staleBodies.has(spec.id))
+            continue;
+        if (!context.world.isAlive(spec.entity))
+            fail("BODY_COLLIDER", `Body '${spec.entity}' is not a live entity.`);
+        if (bridge)
+            bridge.sampleSphere(spec.entity);
+        refs.set(spec.id, context.world.resolve(spec.entity));
+    }
+    return refs;
+}
+function validateWorldBindings(entries, context, world) {
+    const records = new Map(world.entities.map(record => [record.id, record]));
+    for (const entry of entries.values())
+        for (const binding of entry.definition.bodyColliders ?? []) {
+            if (entry.staleBodies.has(binding.id))
+                continue;
+            const record = records.get(binding.entity);
+            const definition = record && resolveEntityDefinition(context.scene, record);
+            const body = definition?.rigidBody;
+            if (!record || !body || body.type !== "dynamic" || body.collider.shape !== "sphere" || body.trigger)
+                fail("SNAPSHOT", `Bound body '${binding.entity}' must exist as a dynamic, non-trigger sphere in the restored world.`);
+        }
+}
+/** Position-based sphere reactions are delayed and do not yet solve body effective mass. */
+export const createRopePlugin = (context) => {
+    const { fixedDt } = context;
     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;
+    let disposed = false, pendingRefs = false;
     const alive = () => { if (disposed)
         fail("DISPOSED", "Rope service is disposed."); };
+    // Host replay restores plugin data before it replaces the World. Resolve handles
+    // lazily at the first use, after that World replacement has completed.
+    const ensureRefs = () => {
+        if (!pendingRefs)
+            return;
+        const staged = [...entries.values()].map(entry => ({ entry, refs: resolveRefs(entry, context, false) }));
+        for (const { entry, refs } of staged)
+            entry.bodyRefs = refs;
+        pendingRefs = false;
+    };
     const get = (id) => {
         alive();
+        ensureRefs();
         if (!validId(id))
             return fail("ID", "Expected a nonempty rope id.");
         return entries.get(id) ?? fail("MISSING", `Rope '${id}' does not exist.`);
@@ -61,6 +123,7 @@ export const createRopePlugin = ({ fixedDt }) => {
     const service = {
         create(definition) {
             alive();
+            ensureRefs();
             if (!definition || !validId(definition.id))
                 return fail("ID", "Expected a nonempty rope id.");
             if (entries.has(definition.id))
@@ -68,7 +131,14 @@ export const createRopePlugin = ({ fixedDt }) => {
             if (entries.size >= 256)
                 return fail("CAPACITY", "At most 256 ropes per host.");
             const entry = createEntry(definition, hostDt);
-            entries.set(entry.definition.id, entry);
+            try {
+                entry.bodyRefs = resolveRefs(entry, context, true);
+                entries.set(entry.definition.id, entry);
+            }
+            catch (error) {
+                entry.solver.dispose();
+                throw error;
+            }
         },
         step(id, ticks) {
             const entry = get(id);
@@ -77,7 +147,17 @@ export const createRopePlugin = ({ fixedDt }) => {
             return entry.solver.step(ticks);
         },
         inspect(id) { return get(id).solver.inspect(); },
-        setColliders(id, colliders) { get(id).solver.setColliders(cloneSerializable(colliders)); },
+        setColliders(id, colliders) {
+            const entry = get(id);
+            if (Array.isArray(colliders)) {
+                const bound = new Set((entry.definition.bodyColliders ?? []).map(item => item.id));
+                if (colliders.length + bound.size > 4096)
+                    return fail("BODY_COLLIDER", "Manual and bound colliders together may not exceed 4096.");
+                if (colliders.some(collider => collider && bound.has(collider.id)))
+                    return fail("BODY_COLLIDER", "Manual collider ids must not conflict with body bindings.");
+            }
+            entry.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)); },
@@ -88,22 +168,67 @@ export const createRopePlugin = ({ fixedDt }) => {
         id: "$engine.ropes", version: "1", services: { ropes: service },
         afterPhysics() {
             alive();
+            ensureRefs();
             const committed = [];
+            const reactions = new Map();
             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 });
+                for (const entry of automatic) {
+                    const snapshot = entry.solver.snapshot();
+                    committed.push({ entry, snapshot, definition: entry.definition, refs: entry.bodyRefs, stale: entry.staleBodies });
+                    const previous = entry.definition.bodyColliders ?? [];
+                    const live = [];
+                    for (const binding of previous) {
+                        const ref = entry.bodyRefs.get(binding.id);
+                        if (!ref && !entry.staleBodies.has(binding.id))
+                            fail("BODY_COLLIDER", `Missing live handle for '${binding.id}'; restore a known-good checkpoint.`);
+                        if (ref && context.world.isAlive(ref))
+                            live.push(binding);
+                    }
+                    if (live.length !== previous.length) {
+                        entry.definition = { ...entry.definition, bodyColliders: live };
+                        entry.bodyRefs = new Map(live.map(binding => [binding.id, entry.bodyRefs.get(binding.id)]));
+                        entry.staleBodies = new Set();
+                    }
+                    if (previous.length) {
+                        const boundIds = new Set(previous.map(item => item.id));
+                        const manual = snapshot.colliders.filter(collider => !boundIds.has(collider.id));
+                        const bridge = live.length ? bridgeFor(context) : undefined;
+                        const sampled = live.map(binding => {
+                            const sphere = bridge.sampleSphere(binding.entity);
+                            return { kind: "sphere", id: binding.id, center: [...sphere.center], radius: sphere.radius };
+                        });
+                        entry.solver.setColliders([...manual, ...sampled]);
+                    }
+                    const state = entry.solver.step();
+                    const byCollider = new Map(live.map(binding => [binding.id, binding.entity]));
+                    for (const contact of state.contacts) {
+                        const entity = byCollider.get(contact.colliderId), impulse = contact.reactionImpulse;
+                        if (!entity || !impulse)
+                            continue;
+                        const total = reactions.get(entity) ?? [0, 0, 0];
+                        for (let k = 0; k < 3; k++)
+                            total[k] += impulse[k];
+                        if (!total.every(Number.isFinite))
+                            fail("NUMERIC", `Reaction for '${entity}' exceeded finite bounds.`);
+                        reactions.set(entity, total);
+                    }
                 }
+                const batch = [...reactions].filter(([, impulse]) => impulse.some(value => value !== 0))
+                    .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+                    .map(([entity, impulse]) => ({ entity, impulse }));
+                if (batch.length)
+                    bridgeFor(context).applySphereReactions(batch);
             }
             catch (error) {
                 const failures = [];
-                for (const { solver, snapshot } of committed.reverse()) {
+                for (const item of committed.reverse()) {
+                    item.entry.definition = item.definition;
+                    item.entry.bodyRefs = item.refs;
+                    item.entry.staleBodies = item.stale;
                     try {
-                        solver.restore(snapshot);
+                        item.entry.solver.restore(item.snapshot);
                     }
                     catch (rollbackError) {
                         failures.push(String(rollbackError));
@@ -115,9 +240,56 @@ export const createRopePlugin = ({ fixedDt }) => {
             }
         },
         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() })) }),
+        snapshot: () => {
+            alive();
+            ensureRefs();
+            return { version: 1, ropes: [...entries.values()].sort((a, b) => a.definition.id < b.definition.id ? -1 : a.definition.id > b.definition.id ? 1 : 0).map(entry => {
+                    const stale = (entry.definition.bodyColliders ?? []).filter(binding => {
+                        const ref = entry.bodyRefs.get(binding.id);
+                        if (!ref && !entry.staleBodies.has(binding.id))
+                            return fail("SNAPSHOT", `Missing handle for '${binding.id}'.`);
+                        return !ref || !context.world.isAlive(ref);
+                    }).map(binding => binding.id);
+                    return { definition: cloneSerializable(entry.definition), state: entry.solver.snapshot(), ...(stale.length ? { staleBodyColliders: stale } : {}) };
+                }) };
+        },
         validateSnapshot(value) { const staged = parseSnapshot(value, hostDt); disposeEntries(staged); },
-        restore(value) { alive(); const staged = parseSnapshot(value, hostDt); disposeEntries(entries); entries = staged; },
+        validateWorld(value, world) {
+            const staged = parseSnapshot(value, hostDt);
+            try {
+                validateWorldBindings(staged, context, world);
+            }
+            finally {
+                disposeEntries(staged);
+            }
+        },
+        validatePeers(value, peers) {
+            const staged = parseSnapshot(value, hostDt);
+            try {
+                const bindings = [...staged.values()].flatMap(entry => (entry.definition.bodyColliders ?? []).filter(binding => !entry.staleBodies.has(binding.id)));
+                if (!bindings.length)
+                    return;
+                const physics = peers["$engine.physics"]?.payload;
+                if (!physics || !Array.isArray(physics.bindings) || !Array.isArray(physics.entities))
+                    return fail("SNAPSHOT", "Body-bound ropes require a matching physics snapshot.");
+                const bodyStates = physics.entities, bodyIds = physics.bindings;
+                for (const binding of bindings) {
+                    const found = bodyStates.find(item => item && typeof item === "object" && item.id === binding.entity && item.type === "dynamic");
+                    if (!found || !bodyIds.includes(binding.entity))
+                        fail("SNAPSHOT", `Bound body '${binding.entity}' is missing from physics state.`);
+                }
+            }
+            finally {
+                disposeEntries(staged);
+            }
+        },
+        restore(value) {
+            alive();
+            const staged = parseSnapshot(value, hostDt);
+            disposeEntries(entries);
+            entries = staged;
+            pendingRefs = true;
+        },
         dispose() { if (disposed)
             return; disposed = true; disposeEntries(entries); },
     };

package/package.json

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