pelican-engine 0.3.14 → 0.3.15

package/docs/npm/GAME-AUTHOR.md

@@ -137,6 +137,20 @@ 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`.
 
+For optional visual presentation, declare a material in `defineGame({ materials:
+[...] })` and create the rope with `visual: { material: "your-material-id" }`.
+The renderer draws capped cylindrical instances between consecutive simulated
+particles and updates their transforms as the rope moves. `radius` defaults to
+the particle collision radius (or 0.025); `radialSegments` defaults to 8 and
+accepts 3–32. `castShadow` and `receiveShadow` default to true. A collapsed
+zero-length segment has no visible surface. `ctx.ropes.visuals()` returns
+detached descriptions, not renderer objects. Visual configuration is included
+in the rope snapshot and is disposed with the owning content.
+
+This is segmented geometry with overlapping caps, not a continuous deformable
+tube. Large ropes may be expensive. Raster, ray-traced modes, GPU resource
+lifecycle and snapshot restoration have not been runtime validated.
+
 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
@@ -178,9 +192,8 @@ 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, 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
+the optional segmented visual does not provide a continuous deformable rope mesh,
+general rigid-body coupling, segment or self collision, or tearing. 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.
 

package/engine.manifest.json

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

package/lib/renderer/browser.js

@@ -1,5 +1,6 @@
 import * as THREE from "three/webgpu";
 import { prepareGameplay } from "./gameplay.js";
+import { createRopeVisualOwner } from "./rope-visuals.js";
 import { GPUTracer } from "./pathtrace.js";
 import { SurfaceTracer } from "./surface-tracer.js";
 import { createRenderSettingsDriver, resolveRenderSettings, } from "../runtime/render-settings.js";
@@ -134,6 +135,11 @@ const recoveryEvents = [];
 const gameObjects = new Map();
 const gameRoot = new THREE.Group();
 scene.add(gameRoot);
+const ropeVisuals = createRopeVisualOwner();
+scene.add(ropeVisuals.root);
+let ropeVisualRevision = 0, renderedRopeVisualRevision = 0;
+const clearRopeVisuals = () => { if (ropeVisuals.clear())
+    ropeVisualRevision++; };
 let authoredCamera = { position: [0, 3.4, 7], target: [0, 0.9, 0] };
 let authoredLights = [];
 let compiledIR = null;
@@ -352,8 +358,10 @@ function createEntityView(entity, materials) {
     return node;
 }
 function syncRuntime() {
-    if (!runtime)
-        return;
+    if (!runtime) {
+        clearRopeVisuals();
+        return ropeVisualRevision !== renderedRopeVisualRevision;
+    }
     transforms.clear();
     componentState.clear();
     const records = runtime.world.records();
@@ -428,6 +436,13 @@ function syncRuntime() {
             if (light)
                 authoredLights.push({ definition: entity.light, object: light });
         }
+    if (gameplay) {
+        if (ropeVisuals.sync(runtime.facade.ropes.visuals(), gameMaterials))
+            ropeVisualRevision++;
+    }
+    else
+        clearRopeVisuals();
+    return ropeVisualRevision !== renderedRopeVisualRevision;
 }
 let simulation;
 const simulationGroup = new THREE.Group();
@@ -720,6 +735,7 @@ async function loadGame(sceneId, saved, loadSlot) {
         contentScope = nextScope;
         gameMaterials = nextMaterials;
         committed = true;
+        clearRopeVisuals();
         if (nextRoot.children.length)
             gameRoot.add(...nextRoot.children);
         gameObjects.clear();
@@ -950,7 +966,9 @@ async function drawFrame(accumulate = false, changed = true) {
         throw new Error("TC_BROWSER_DISPOSED");
     await computeControl?.flush();
     const start = performance.now();
-    syncRuntime();
+    const ropeChanged = syncRuntime();
+    const ropeRevision = ropeVisualRevision;
+    changed = changed || ropeChanged;
     animate();
     renderBufferBridge?.update();
     renderTextureBridge?.update();
@@ -1030,6 +1048,7 @@ async function drawFrame(accumulate = false, changed = true) {
             triangles: triangleCount,
             faulted: terminalFault,
         });
+        renderedRopeVisualRevision = ropeRevision;
         return;
     }
     if (changed) {
@@ -1082,6 +1101,7 @@ async function drawFrame(accumulate = false, changed = true) {
         triangles: triangleCount,
         faulted: terminalFault,
     });
+    renderedRopeVisualRevision = ropeRevision;
 }
 async function applyInput(key) {
     if (!probeEnabled) {
@@ -1327,6 +1347,7 @@ async function disposeBrowser() {
     clean(() => simulation?.dispose());
     clean(() => world?.dispose());
     clean(() => resourceManager.dispose());
+    clean(() => ropeVisuals.dispose());
     clean(() => releaseObject(scene, true, gameMaterials.values()));
     clean(() => pendingSurface?.abort());
     clean(() => tracer?.dispose());

package/lib/renderer/geometry.js

@@ -18,22 +18,32 @@ export function extractTriangles(scene) {
             new THREE.Vector3(),
             new THREE.Vector3(),
         ];
-        for (let i = 0; i < count; i += 3) {
-            for (let k = 0; k < 3; k++)
-                object
-                    .getVertexPosition(geometry.index?.getX(i + k) ?? i + k, points[k])
-                    .applyMatrix4(object.matrixWorld);
-            const color = material.color ?? new THREE.Color(0.6, 0.6, 0.6);
-            triangles.push({
-                a: points[0].toArray(),
-                b: points[1].toArray(),
-                c: points[2].toArray(),
-                color: color.toArray(),
-                emission: material.emissiveIntensity && material.emissive?.getHex()
-                    ? material.emissiveIntensity
-                    : 0,
-                roughness: material.roughness ?? 0.8,
-            });
+        const instanced = object instanceof THREE.InstancedMesh ? object : undefined;
+        const instance = new THREE.Matrix4(), transform = new THREE.Matrix4();
+        for (let slot = 0; slot < (instanced?.count ?? 1); slot++) {
+            if (instanced) {
+                instanced.getMatrixAt(slot, instance);
+                transform.multiplyMatrices(object.matrixWorld, instance);
+            }
+            else
+                transform.copy(object.matrixWorld);
+            for (let i = 0; i < count; i += 3) {
+                for (let k = 0; k < 3; k++)
+                    object
+                        .getVertexPosition(geometry.index?.getX(i + k) ?? i + k, points[k])
+                        .applyMatrix4(transform);
+                const color = material.color ?? new THREE.Color(0.6, 0.6, 0.6);
+                triangles.push({
+                    a: points[0].toArray(),
+                    b: points[1].toArray(),
+                    c: points[2].toArray(),
+                    color: color.toArray(),
+                    emission: material.emissiveIntensity && material.emissive?.getHex()
+                        ? material.emissiveIntensity
+                        : 0,
+                    roughness: material.roughness ?? 0.8,
+                });
+            }
         }
     });
     return triangles;

package/lib/renderer/rope-visuals.js

@@ -0,0 +1,122 @@
+import * as THREE from "three/webgpu";
+/** Presentation owns its instance buffers and geometries; scene materials remain borrowed. */
+export function createRopeVisualOwner() {
+    const root = new THREE.Group();
+    root.name = "pelican-rope-visuals";
+    const views = new Map();
+    let disposed = false;
+    const remove = (view) => { view.mesh.removeFromParent(); view.mesh.dispose(); view.geometry.dispose(); };
+    const clear = () => { const changed = views.size > 0; for (const view of views.values())
+        remove(view); views.clear(); return changed; };
+    const signature = (state) => JSON.stringify([state.material, state.radius, state.radialSegments, state.castShadow, state.receiveShadow, state.positions.length]);
+    const create = (state, material) => {
+        let geometry;
+        let mesh;
+        try {
+            geometry = new THREE.CylinderGeometry(state.radius, state.radius, 1, state.radialSegments, 1, false);
+            const uv = geometry.getAttribute("uv");
+            if (uv)
+                geometry.setAttribute("uv1", uv.clone());
+            mesh = new THREE.InstancedMesh(geometry, material, state.positions.length - 1);
+            mesh.name = `rope:${state.id}`;
+            mesh.castShadow = state.castShadow;
+            mesh.receiveShadow = state.receiveShadow;
+            mesh.count = 0;
+            mesh.visible = false;
+            mesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+            return { mesh, geometry, signature: signature(state), positions: [] };
+        }
+        catch (error) {
+            mesh?.dispose();
+            geometry?.dispose();
+            throw error;
+        }
+    };
+    const matrices = (state) => {
+        const data = new Float32Array((state.positions.length - 1) * 16);
+        const axis = new THREE.Vector3(0, 1, 0), direction = new THREE.Vector3();
+        const position = new THREE.Vector3(), scale = new THREE.Vector3(), rotation = new THREE.Quaternion();
+        const matrix = new THREE.Matrix4();
+        let count = 0;
+        for (let index = 0; index < state.positions.length - 1; index++) {
+            const a = state.positions[index], b = state.positions[index + 1];
+            direction.set(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
+            const length = direction.length();
+            // A collapsed segment has no surface; never submit a singular instance transform.
+            if (length === 0)
+                continue;
+            if (!Number.isFinite(length) || Math.fround(length) === 0)
+                throw new Error(`TC_ROPE_VISUAL_NUMERIC: Segment ${index} of '${state.id}' has an unrepresentable length.`);
+            position.set((a[0] + b[0]) / 2, (a[1] + b[1]) / 2, (a[2] + b[2]) / 2);
+            rotation.setFromUnitVectors(axis, direction.multiplyScalar(1 / length));
+            scale.set(1, length, 1);
+            matrix.compose(position, rotation, scale);
+            for (const value of matrix.elements)
+                if (!Number.isFinite(value) || !Number.isFinite(Math.fround(value)))
+                    throw new Error(`TC_ROPE_VISUAL_NUMERIC: Segment ${index} of '${state.id}' has a non-finite transform.`);
+            data.set(matrix.elements, count++ * 16);
+        }
+        return { data, count };
+    };
+    const sync = (states, materials) => {
+        if (disposed)
+            throw new Error("TC_ROPE_VISUAL_DISPOSED: Create a new presentation owner.");
+        const staged = new Map();
+        const created = [];
+        try {
+            for (const state of states) {
+                if (staged.has(state.id))
+                    throw new Error(`TC_ROPE_VISUAL_ID: Duplicate rope '${state.id}'.`);
+                const material = materials.get(state.material);
+                if (!material)
+                    throw new Error(`TC_ROPE_VISUAL_MATERIAL: Material '${state.material}' is not declared.`);
+                if (!Array.isArray(state.positions) || state.positions.length < 2 || state.positions.length > 4096 ||
+                    state.positions.some(point => !Array.isArray(point) || point.length !== 3 || !point.every(Number.isFinite)))
+                    throw new Error(`TC_ROPE_VISUAL_POSITION: Rope '${state.id}' requires finite particle positions.`);
+                if (!Number.isFinite(state.radius) || state.radius <= 0 || Math.fround(state.radius) === 0 ||
+                    !Number.isInteger(state.radialSegments) || state.radialSegments < 3 || state.radialSegments > 32)
+                    throw new Error(`TC_ROPE_VISUAL_SHAPE: Rope '${state.id}' has an invalid radius or radial segment count.`);
+                const old = views.get(state.id), same = old && old.signature === signature(state) && old.mesh.material === material;
+                const view = same ? old : create(state, material);
+                if (!same)
+                    created.push(view);
+                const positions = state.positions.flatMap(point => [...point]);
+                const changed = !same || positions.length !== view.positions.length || positions.some((value, index) => value !== view.positions[index]);
+                const update = changed ? matrices(state) : undefined;
+                staged.set(state.id, { view, created: !same, positions, ...(update ? { matrices: update.data, count: update.count } : {}) });
+            }
+        }
+        catch (error) {
+            for (const view of created)
+                remove(view);
+            throw error;
+        }
+        let changed = false;
+        for (const [id, view] of views)
+            if (!staged.has(id) || staged.get(id).view !== view) {
+                remove(view);
+                changed = true;
+            }
+        views.clear();
+        for (const [id, item] of staged) {
+            if (item.created) {
+                root.add(item.view.mesh);
+                changed = true;
+            }
+            if (item.matrices) {
+                item.view.mesh.instanceMatrix.array.set(item.matrices);
+                item.view.mesh.count = item.count;
+                item.view.mesh.visible = item.count > 0;
+                item.view.mesh.instanceMatrix.needsUpdate = true;
+                if (item.count > 0)
+                    item.view.mesh.computeBoundingSphere();
+                item.view.positions = item.positions;
+                changed = true;
+            }
+            views.set(id, item.view);
+        }
+        return changed;
+    };
+    return { root, sync, clear, dispose() { if (disposed)
+            return; clear(); root.removeFromParent(); disposed = 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.14";
+export declare const SDK_VERSION = "0.3.15";
 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. Explicit body bindings apply a delayed
- * projection reaction to dynamic spheres; no full rigid-body coupling, segment/self collision or rope rendering. */
+/** CPU particles with sampled sphere/plane collisions. Explicit body bindings apply delayed
+ * contact impulses to dynamic spheres; there is no full rigid-body coupling or segment/self collision. */
 export type RopeCollider = {
     kind: "sphere";
     id: string;
@@ -121,6 +121,24 @@ export interface RopeBodyCollider {
     readonly id: string;
     readonly entity: string;
 }
+/** Optional renderer-owned cylindrical segments following simulated particle positions. */
+export interface RopeVisualOptions {
+    material: string;
+    radius?: number;
+    radialSegments?: number;
+    castShadow?: boolean;
+    receiveShadow?: boolean;
+}
+/** Detached presentation state; native renderer objects are not exposed. */
+export interface RopeVisualState {
+    id: string;
+    material: string;
+    radius: number;
+    radialSegments: number;
+    castShadow: boolean;
+    receiveShadow: boolean;
+    positions: Vec3[];
+}
 export interface RopeDefinition {
     id: string;
     points: readonly Vec3[];
@@ -133,6 +151,8 @@ export interface RopeDefinition {
     autoStep?: boolean;
     /** Automatically sample and react to existing dynamic, non-trigger sphere bodies. Requires autoStep. */
     bodyColliders?: readonly RopeBodyCollider[];
+    /** Optional segmented presentation using an already-declared material id. */
+    visual?: RopeVisualOptions;
     substeps?: number;
     iterations?: number;
     damping?: number;
@@ -177,6 +197,8 @@ export interface RopeService {
     /** 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;
+    /** Detached visual descriptions, sorted by rope id; empty when no visuals are requested. */
+    visuals(): readonly RopeVisualState[];
     setColliders(id: string, colliders: readonly RopeCollider[]): void;
     setAnchor(id: string, index: number, position: Vec3): void;
     releaseAnchor(id: string, index: number): 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.14";
+export const SDK_VERSION = "0.3.15";
 export const SYSTEM_PHASES = [
     "input",
     "prePhysics",

package/lib/simulation/rope-plugin.js

@@ -4,7 +4,7 @@ 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.");
@@ -14,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.");
@@ -35,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();
@@ -43,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.");
@@ -100,6 +113,7 @@ export const createRopePlugin = (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)
@@ -131,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);
@@ -148,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)) {
@@ -248,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);
             }
@@ -259,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)
@@ -280,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

@@ -285,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.14",
+  "version": "0.3.15",
   "description": "Pelican Engine public SDK and offline development CLI",
   "type": "module",
   "license": "MIT",