pelican-engine 0.3.14 → 0.3.16

package/docs/npm/GAME-AUTHOR.md

@@ -137,6 +137,33 @@ 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`.
 
+New ropes resolve discrete sphere overlaps along segment interiors as well as at
+particles. Corrections are distributed to movable endpoints; a segment with two
+fixed anchors cannot move. `ctx.ropes.inspect(id).segmentContacts` reports the
+segment index, closest-point fraction and reaction impulses. Set
+`segmentCollisions: false` to retain particle-only behavior. Historical rope
+solver snapshots without this field retain particle-only behavior when migrated;
+`inspect(id).segmentCollisions` reports the active mode. Normal Host snapshot
+engine-version restrictions still apply. Plane contacts use particle endpoints.
+The segment index names its first particle; `fraction` runs toward the next.
+Work increases with segment, sphere, substep and iteration counts. This does not
+provide continuous collision detection or self collision, and the segment solver
+and snapshot migration have not been runtime validated.
+
+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
@@ -167,8 +194,8 @@ 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's `examples/rope-reaction` uses the
+For manual coupling, include both `contacts` and `segmentContacts` and apply each
+contact at most once for its `tick`; repeated `inspect` calls return 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,
@@ -178,9 +205,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, 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.16",
   "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.16";
 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 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,10 @@ export interface RopeDefinition {
     autoStep?: boolean;
     /** Automatically sample and react to existing dynamic, non-trigger sphere bodies. Requires autoStep. */
     bodyColliders?: readonly RopeBodyCollider[];
+    /** Resolve sphere contacts on segment interiors; defaults to true for new ropes. */
+    segmentCollisions?: boolean;
+    /** Optional segmented presentation using an already-declared material id. */
+    visual?: RopeVisualOptions;
     substeps?: number;
     iterations?: number;
     damping?: number;
@@ -153,10 +175,23 @@ export interface RopeContact {
     /** Angular impulse about the world origin; absent in older snapshots. */
     reactionAngularImpulse?: Vec3;
 }
+/** Contact between an interior rope segment and a sampled sphere. */
+export interface RopeSegmentContact {
+    tick: number;
+    /** Zero-based index of the first endpoint; the second is segment + 1. */
+    segment: number;
+    colliderId: string;
+    /** Last closest-point fraction from the first endpoint toward the second. */
+    fraction: number;
+    penetration: number;
+    reactionImpulse?: Vec3;
+    reactionAngularImpulse?: Vec3;
+}
 export interface RopeState {
     tick: number;
     simulatedSeconds: number;
     disposed: boolean;
+    segmentCollisions: boolean;
     positions: Vec3[];
     velocities: Vec3[];
     anchors: {
@@ -164,6 +199,7 @@ export interface RopeState {
         position: Vec3;
     }[];
     contacts: RopeContact[];
+    segmentContacts: RopeSegmentContact[];
     maxDistanceError: number;
     resources: {
         particles: number;
@@ -177,6 +213,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.16";
 export const SYSTEM_PHASES = [
     "input",
     "prePhysics",

package/lib/simulation/rope-plugin.js

@@ -4,16 +4,33 @@ 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, restoredSegmentMode) {
     const definition = cloneSerializable(input);
     if (!definition || !validId(definition.id))
         return fail("ID", "Expected a nonempty id of at most 128 characters.");
     if (definition.autoStep !== undefined && typeof definition.autoStep !== "boolean")
         return fail("AUTO_STEP", "autoStep must be a boolean.");
+    if (definition.segmentCollisions !== undefined && typeof definition.segmentCollisions !== "boolean")
+        return fail("SEGMENT_COLLISION", "segmentCollisions must be a boolean.");
+    if (restoredSegmentMode !== undefined && definition.segmentCollisions !== undefined && definition.segmentCollisions !== restoredSegmentMode)
+        return fail("SNAPSHOT", "Segment collision configuration does not match the saved solver.");
     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.");
+    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.");
@@ -27,7 +44,7 @@ function createEntry(input, fixedDt) {
             entities.add(binding.entity);
         }
     }
-    const solver = createRope({ ...definition, fixedDt });
+    const solver = createRope({ ...definition, fixedDt, ...(restoredSegmentMode === undefined ? {} : { segmentCollisions: restoredSegmentMode }) });
     return { definition, solver, bodyRefs: new Map(), staleBodies: new Set() };
 }
 function disposeEntries(entries) {
@@ -35,7 +52,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 +60,11 @@ 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 savedSegmentMode = item.state?.config?.segmentCollisions;
+            if (savedSegmentMode !== undefined && typeof savedSegmentMode !== "boolean")
+                fail("SNAPSHOT", "Invalid segment collision configuration.");
+            // Snapshots made before segment contacts represent particle-only behavior.
+            const entry = createEntry(item.definition, fixedDt, materials, savedSegmentMode ?? false);
             if (entries.has(entry.definition.id)) {
                 entry.solver.dispose();
                 fail("SNAPSHOT", "Duplicate rope id.");
@@ -100,6 +121,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 +153,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 +170,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 +282,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 +293,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 +314,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;