pelican-engine 0.3.13 → 0.3.15

package/lib/simulation/rope-plugin.js

@@ -1,9 +1,10 @@
 import { resolveEntityDefinition } from "../runtime/prefabs.js";
 import { cloneSerializable } from "../runtime/random.js";
 import { createRope } from "./rope.js";
+import { createRopeBodyCoupling, VirtualRopeSphere } from "./rope-body-coupling.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) {
+function createEntry(input, fixedDt, materials) {
     const definition = cloneSerializable(input);
     if (!definition || !validId(definition.id))
         return fail("ID", "Expected a nonempty id of at most 128 characters.");
@@ -13,6 +14,19 @@ 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.visual !== undefined) {
+        const visual = definition.visual;
+        if (!visual || typeof visual !== "object" || Array.isArray(visual) || !validId(visual.material) || !materials.has(visual.material))
+            return fail("VISUAL_MATERIAL", "visual.material must name a declared engine material.");
+        const radius = visual.radius ?? definition.radius ?? 0.025;
+        if (typeof radius !== "number" || !Number.isFinite(radius) || radius <= 0 || radius > 1e6 || Math.fround(radius) === 0)
+            return fail("VISUAL_RADIUS", "visual radius must be positive, finite, representable and at most 1e6.");
+        const sides = visual.radialSegments ?? 8;
+        if (!Number.isSafeInteger(sides) || sides < 3 || sides > 32)
+            return fail("VISUAL_SEGMENTS", "radialSegments must be an integer in [3,32].");
+        if ((visual.castShadow !== undefined && typeof visual.castShadow !== "boolean") || (visual.receiveShadow !== undefined && typeof visual.receiveShadow !== "boolean"))
+            return fail("VISUAL_SHADOW", "Visual shadow options must be boolean.");
+    }
     if (definition.bodyColliders !== undefined) {
         if (!Array.isArray(definition.bodyColliders) || definition.bodyColliders.length > 64)
             return fail("BODY_COLLIDER", "bodyColliders must contain at most 64 bindings.");
@@ -34,7 +48,7 @@ function disposeEntries(entries) {
         solver.dispose();
     entries.clear();
 }
-function parseSnapshot(value, fixedDt) {
+function parseSnapshot(value, fixedDt, materials) {
     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();
@@ -42,7 +56,7 @@ function parseSnapshot(value, fixedDt) {
         for (const item of value.ropes) {
             if (!item || typeof item !== "object")
                 fail("SNAPSHOT", "Invalid rope entry.");
-            const entry = createEntry(item.definition, fixedDt);
+            const entry = createEntry(item.definition, fixedDt, materials);
             if (entries.has(entry.definition.id)) {
                 entry.solver.dispose();
                 fail("SNAPSHOT", "Duplicate rope id.");
@@ -93,12 +107,13 @@ function validateWorldBindings(entries, context, world) {
                 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. */
+/** Split-step sphere contact uses virtual mass/velocity state; native commit is deferred. */
 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;
+    const materials = new Set(context.scene.materials.map(material => material.id));
     let entries = new Map();
     let disposed = false, pendingRefs = false;
     const alive = () => { if (disposed)
@@ -130,7 +145,7 @@ export const createRopePlugin = (context) => {
                 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);
+            const entry = createEntry(definition, hostDt, materials);
             try {
                 entry.bodyRefs = resolveRefs(entry, context, true);
                 entries.set(entry.definition.id, entry);
@@ -147,6 +162,18 @@ export const createRopePlugin = (context) => {
             return entry.solver.step(ticks);
         },
         inspect(id) { return get(id).solver.inspect(); },
+        visuals() {
+            alive();
+            ensureRefs();
+            return [...entries.values()].filter(entry => entry.definition.visual !== undefined)
+                .sort((a, b) => a.definition.id < b.definition.id ? -1 : a.definition.id > b.definition.id ? 1 : 0)
+                .map(entry => {
+                const visual = entry.definition.visual;
+                return { id: entry.definition.id, material: visual.material, radius: visual.radius ?? entry.definition.radius ?? 0.025,
+                    radialSegments: visual.radialSegments ?? 8, castShadow: visual.castShadow ?? true, receiveShadow: visual.receiveShadow ?? true,
+                    positions: entry.solver.particlePositions() };
+            });
+        },
         setColliders(id, colliders) {
             const entry = get(id);
             if (Array.isArray(colliders)) {
@@ -170,7 +197,7 @@ export const createRopePlugin = (context) => {
             alive();
             ensureRefs();
             const committed = [];
-            const reactions = new Map();
+            const bodies = new Map();
             try {
                 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);
@@ -191,33 +218,27 @@ export const createRopePlugin = (context) => {
                         entry.bodyRefs = new Map(live.map(binding => [binding.id, entry.bodyRefs.get(binding.id)]));
                         entry.staleBodies = new Set();
                     }
+                    const coupled = new Map();
                     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 };
+                            let body = bodies.get(binding.entity);
+                            if (!body) {
+                                body = new VirtualRopeSphere(bridge.sampleSphere(binding.entity));
+                                bodies.set(binding.entity, body);
+                            }
+                            coupled.set(binding.id, body);
+                            return { kind: "sphere", id: binding.id, center: [...body.center], radius: body.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);
-                    }
+                    entry.solver.step(1, coupled.size ? createRopeBodyCoupling(coupled) : undefined);
                 }
-                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 }));
+                const batch = [...bodies].map(([entity, body]) => ({ entity, ...body.reaction() }))
+                    .filter(item => item.impulse.some(value => value !== 0) || item.moment.some(value => value !== 0))
+                    .sort((a, b) => a.entity < b.entity ? -1 : a.entity > b.entity ? 1 : 0);
                 if (batch.length)
                     bridgeFor(context).applySphereReactions(batch);
             }
@@ -253,9 +274,9 @@ export const createRopePlugin = (context) => {
                     return { definition: cloneSerializable(entry.definition), state: entry.solver.snapshot(), ...(stale.length ? { staleBodyColliders: stale } : {}) };
                 }) };
         },
-        validateSnapshot(value) { const staged = parseSnapshot(value, hostDt); disposeEntries(staged); },
+        validateSnapshot(value) { const staged = parseSnapshot(value, hostDt, materials); disposeEntries(staged); },
         validateWorld(value, world) {
-            const staged = parseSnapshot(value, hostDt);
+            const staged = parseSnapshot(value, hostDt, materials);
             try {
                 validateWorldBindings(staged, context, world);
             }
@@ -264,7 +285,7 @@ export const createRopePlugin = (context) => {
             }
         },
         validatePeers(value, peers) {
-            const staged = parseSnapshot(value, hostDt);
+            const staged = parseSnapshot(value, hostDt, materials);
             try {
                 const bindings = [...staged.values()].flatMap(entry => (entry.definition.bodyColliders ?? []).filter(binding => !entry.staleBodies.has(binding.id)));
                 if (!bindings.length)
@@ -285,7 +306,7 @@ export const createRopePlugin = (context) => {
         },
         restore(value) {
             alive();
-            const staged = parseSnapshot(value, hostDt);
+            const staged = parseSnapshot(value, hostDt, materials);
             disposeEntries(entries);
             entries = staged;
             pendingRefs = true;

package/lib/simulation/rope.js

@@ -140,8 +140,10 @@ export class RopeSolver {
         this.forces[i] = next;
     }
     /** Exactly N fixed ticks; a failed batch restores the state before the first tick. */
-    step(steps = 1) {
+    step(steps = 1, coupling) {
         this.alive();
+        if (coupling && steps !== 1)
+            fail("ROPE_INPUT", "coupled stepping requires exactly one tick");
         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.
@@ -154,7 +156,7 @@ export class RopeSolver {
         };
         try {
             for (let s = 0; s < steps; s++)
-                this.stepOne();
+                this.stepOne(coupling);
         }
         catch (error) {
             this.positions = before.positions;
@@ -166,7 +168,7 @@ export class RopeSolver {
         }
         return this.inspect();
     }
-    stepOne() {
+    stepOne(coupling) {
         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.
@@ -215,29 +217,41 @@ export class RopeSolver {
                     for (const c of this.colliders) {
                         let depth = 0;
                         let normal;
+                        const dynamic = c.kind === "sphere" ? coupling?.sphere(c.id) : undefined;
                         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 center = dynamic?.center ?? c.center, colliderRadius = dynamic?.radius ?? c.radius;
+                            const delta = [p[0] - center[0], p[1] - center[1], p[2] - center[2]];
                             const distance = length(delta);
-                            depth = c.radius + radius - distance;
+                            depth = colliderRadius + 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;
-                        // 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]];
+                        let reaction, moment;
+                        if (dynamic && coupling) {
+                            const result = coupling.resolve(c.id, normal, depth, p, previous[i], mass, h);
+                            if (!finiteVector(result.correction) || !finiteVector(result.reactionImpulse) || !finiteVector(result.reactionAngularImpulse))
+                                fail("ROPE_NUMERIC", "coupled contact exceeded finite numeric bounds");
+                            for (let k = 0; k < 3; k++)
+                                p[k] += result.correction[k];
+                            reaction = result.reactionImpulse;
+                            moment = result.reactionAngularImpulse;
+                        }
+                        else {
+                            for (let k = 0; k < 3; k++)
+                                p[k] += normal[k] * depth;
+                            // A manually sampled collider remains immovable; expose its projection reaction.
+                            const magnitude = -mass * depth / h;
+                            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];
+                            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}`;
@@ -271,6 +285,8 @@ export class RopeSolver {
         this.contacts = [...contacts.values()];
         this.tickValue++;
     }
+    /** Detached positions for renderer synchronization without copying contact state. */
+    particlePositions() { this.alive(); return this.positions.map(copy); }
     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 } };

package/package.json

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