pelican-engine 0.3.16 → 0.3.18

package/docs/npm/GAME-AUTHOR.md

@@ -147,8 +147,20 @@ solver snapshots without this field retain particle-only behavior when migrated;
 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.
+provide continuous collision detection; the segment solver and snapshot migration
+have not been runtime validated.
+
+New ropes also resolve discrete self-contact between non-adjacent segments using
+sweep-and-prune and endpoint projection. `inspect(id).selfContacts` reports
+segment indices, closest-point fractions and maximum overlap; `selfCollisions`
+reports the active mode. Set `selfCollisions: false` to disable it. Adjacent
+segments and collisions between separate ropes are not handled. Immovable anchored
+endpoints stay fixed, and contacts introduced by corrections can wait until the
+next iteration. Dense overlap can approach quadratic work. Snapshots from before
+this feature retain the disabled mode when migrated; Host engine-version rules
+still apply. This is unverified discrete contact, not a guarantee against
+penetration, continuous collision, friction or full rope physics. The source
+checkout includes `examples/rope-self`.
 
 For optional visual presentation, declare a material in `defineGame({ materials:
 [...] })` and create the rope with `visual: { material: "your-material-id" }`.
@@ -206,10 +218,32 @@ checkpoint. It must not be represented as complete two-way rigid-body interactio
 
 This is an unverified development-stage increment, not complete rope physics:
 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
+general rigid-body coupling, continuous collision, cross-rope 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.
 
+### Development-stage triangular cloth
+
+Declare a material in `defineGame({ materials: [...] })`, then use
+`ctx.cloth.create({ id, points, triangles, mass, autoStep: true, visual: {
+material: "material-id" } })`. Triangles reference particle indices and shared
+edges must be manifold with consistent winding. Anchors are explicit; no particles
+are pinned by default. Automatic cloth advances after the physics phase;
+manual cloth uses `ctx.cloth.step`. Use `setAnchor`, `releaseAnchor`, `applyForce`
+(next tick), `applyImpulse`, `setColliders`, `inspect`, and `destroy` to manage it.
+The source checkout includes `examples/cloth-sheet`.
+
+The CPU solver uses edge distance constraints and an optional distance-based
+bending approximation (`bending: true` by default). Sampled planes and spheres
+only move cloth particles; they do not receive reactions. Contacts do not cover
+triangle interiors or edges. There is no self-contact, cloth–rope interaction,
+rigid-body coupling, tearing, friction or continuous collision. The optional
+visual deforms the actual triangle mesh; UVs may be provided per particle or use a
+planar projection. Use a double-sided material when both sides must be visible.
+Collapsed or unrepresentable triangles return `TC_CLOTH_VISUAL_DEGENERATE` rather
+than being silently replaced. Runtime, GPU, performance, stability and snapshot
+compatibility have not been validated; this is not complete cloth physics.
+
 Keyboard bindings use the browser's `KeyboardEvent.key` values, not physical
 `KeyboardEvent.code` values. For example, use `input: { up: ["w", "W", "ArrowUp"],
 restart: ["r", "R"] }`, not `"KeyW"` or `"KeyR"`. Letter case depends on the

package/engine.manifest.json

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

package/lib/renderer/browser.js

@@ -1,6 +1,7 @@
 import * as THREE from "three/webgpu";
 import { prepareGameplay } from "./gameplay.js";
 import { createRopeVisualOwner } from "./rope-visuals.js";
+import { createClothVisualOwner } from "./cloth-visuals.js";
 import { GPUTracer } from "./pathtrace.js";
 import { SurfaceTracer } from "./surface-tracer.js";
 import { createRenderSettingsDriver, resolveRenderSettings, } from "../runtime/render-settings.js";
@@ -136,10 +137,14 @@ 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++; };
+const clothVisuals = createClothVisualOwner();
+scene.add(ropeVisuals.root, clothVisuals.root);
+let dynamicVisualRevision = 0, renderedDynamicVisualRevision = 0;
+const clearDynamicVisuals = () => {
+    const ropesChanged = ropeVisuals.clear(), clothChanged = clothVisuals.clear();
+    if (ropesChanged || clothChanged)
+        dynamicVisualRevision++;
+};
 let authoredCamera = { position: [0, 3.4, 7], target: [0, 0.9, 0] };
 let authoredLights = [];
 let compiledIR = null;
@@ -359,8 +364,8 @@ function createEntityView(entity, materials) {
 }
 function syncRuntime() {
     if (!runtime) {
-        clearRopeVisuals();
-        return ropeVisualRevision !== renderedRopeVisualRevision;
+        clearDynamicVisuals();
+        return dynamicVisualRevision !== renderedDynamicVisualRevision;
     }
     transforms.clear();
     componentState.clear();
@@ -438,11 +443,13 @@ function syncRuntime() {
         }
     if (gameplay) {
         if (ropeVisuals.sync(runtime.facade.ropes.visuals(), gameMaterials))
-            ropeVisualRevision++;
+            dynamicVisualRevision++;
+        if (clothVisuals.sync(runtime.facade.cloth.visuals(), gameMaterials))
+            dynamicVisualRevision++;
     }
     else
-        clearRopeVisuals();
-    return ropeVisualRevision !== renderedRopeVisualRevision;
+        clearDynamicVisuals();
+    return dynamicVisualRevision !== renderedDynamicVisualRevision;
 }
 let simulation;
 const simulationGroup = new THREE.Group();
@@ -735,7 +742,7 @@ async function loadGame(sceneId, saved, loadSlot) {
         contentScope = nextScope;
         gameMaterials = nextMaterials;
         committed = true;
-        clearRopeVisuals();
+        clearDynamicVisuals();
         if (nextRoot.children.length)
             gameRoot.add(...nextRoot.children);
         gameObjects.clear();
@@ -967,7 +974,7 @@ async function drawFrame(accumulate = false, changed = true) {
     await computeControl?.flush();
     const start = performance.now();
     const ropeChanged = syncRuntime();
-    const ropeRevision = ropeVisualRevision;
+    const ropeRevision = dynamicVisualRevision;
     changed = changed || ropeChanged;
     animate();
     renderBufferBridge?.update();
@@ -1048,7 +1055,7 @@ async function drawFrame(accumulate = false, changed = true) {
             triangles: triangleCount,
             faulted: terminalFault,
         });
-        renderedRopeVisualRevision = ropeRevision;
+        renderedDynamicVisualRevision = ropeRevision;
         return;
     }
     if (changed) {
@@ -1101,7 +1108,7 @@ async function drawFrame(accumulate = false, changed = true) {
         triangles: triangleCount,
         faulted: terminalFault,
     });
-    renderedRopeVisualRevision = ropeRevision;
+    renderedDynamicVisualRevision = ropeRevision;
 }
 async function applyInput(key) {
     if (!probeEnabled) {
@@ -1348,6 +1355,7 @@ async function disposeBrowser() {
     clean(() => world?.dispose());
     clean(() => resourceManager.dispose());
     clean(() => ropeVisuals.dispose());
+    clean(() => clothVisuals.dispose());
     clean(() => releaseObject(scene, true, gameMaterials.values()));
     clean(() => pendingSurface?.abort());
     clean(() => tracer?.dispose());

package/lib/renderer/cloth-visuals.js

@@ -0,0 +1,140 @@
+import * as THREE from "three/webgpu";
+/** Owns dynamic cloth geometry and buffers; scene materials remain borrowed. */
+export function createClothVisualOwner() {
+    const root = new THREE.Group();
+    root.name = "pelican-cloth-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.castShadow, state.receiveShadow, state.positions.length, state.triangles, state.uvs]);
+    const create = (state, material) => {
+        const geometry = new THREE.BufferGeometry();
+        let mesh;
+        try {
+            const count = state.triangles.length * 3;
+            const position = new THREE.BufferAttribute(new Float32Array(count * 3), 3), normal = new THREE.BufferAttribute(new Float32Array(count * 3), 3);
+            position.setUsage(THREE.DynamicDrawUsage);
+            normal.setUsage(THREE.DynamicDrawUsage);
+            geometry.setAttribute("position", position);
+            geometry.setAttribute("normal", normal);
+            const values = new Float32Array(count * 2);
+            let offset = 0;
+            for (const triangle of state.triangles)
+                for (const index of triangle) {
+                    const uv = state.uvs[index];
+                    values[offset++] = uv[0];
+                    values[offset++] = uv[1];
+                }
+            const uv = new THREE.BufferAttribute(values, 2);
+            geometry.setAttribute("uv", uv);
+            geometry.setAttribute("uv1", uv.clone());
+            mesh = new THREE.Mesh(geometry, material);
+            mesh.name = `cloth:${state.id}`;
+            mesh.castShadow = state.castShadow;
+            mesh.receiveShadow = state.receiveShadow;
+            return { mesh, geometry, signature: signature(state), positions: [] };
+        }
+        catch (error) {
+            mesh?.dispose();
+            geometry.dispose();
+            throw error;
+        }
+    };
+    const geometryData = (state) => {
+        const vertices = new Float32Array(state.triangles.length * 9), normals = new Float32Array(vertices.length);
+        const accumulated = Array.from({ length: state.positions.length }, () => [0, 0, 0]);
+        const faces = [];
+        let offset = 0;
+        for (let face = 0; face < state.triangles.length; face++) {
+            const triangle = state.triangles[face];
+            const points = triangle.map(index => state.positions[index].map(Math.fround));
+            const u = points[1].map((value, axis) => value - points[0][axis]), v = points[2].map((value, axis) => value - points[0][axis]);
+            const n = [u[1] * v[2] - u[2] * v[1], u[2] * v[0] - u[0] * v[2], u[0] * v[1] - u[1] * v[0]];
+            const length = Math.hypot(...n);
+            if (!Number.isFinite(length) || length === 0)
+                throw new Error(`TC_CLOTH_VISUAL_DEGENERATE: Triangle ${face} of '${state.id}' collapsed or is not representable; adjust cloth geometry or simulation.`);
+            faces.push([n[0] / length, n[1] / length, n[2] / length]);
+            for (let vertex = 0; vertex < 3; vertex++) {
+                const index = triangle[vertex];
+                for (let axis = 0; axis < 3; axis++) {
+                    vertices[offset++] = points[vertex][axis];
+                    accumulated[index][axis] += n[axis];
+                }
+            }
+        }
+        offset = 0;
+        for (let face = 0; face < state.triangles.length; face++)
+            for (const index of state.triangles[face]) {
+                const n = accumulated[index], length = Math.hypot(...n), source = length > 1e-20 ? [n[0] / length, n[1] / length, n[2] / length] : faces[face];
+                for (const value of source) {
+                    if (!Number.isFinite(value))
+                        throw new Error(`TC_CLOTH_VISUAL_NUMERIC: Invalid normal in '${state.id}'.`);
+                    normals[offset++] = value;
+                }
+            }
+        return { vertices, normals };
+    };
+    const sync = (states, materials) => {
+        if (disposed)
+            throw new Error("TC_CLOTH_VISUAL_DISPOSED: Create a new presentation owner.");
+        const staged = new Map(), created = [];
+        try {
+            for (const state of states) {
+                if (staged.has(state.id))
+                    throw new Error(`TC_CLOTH_VISUAL_ID: Duplicate cloth '${state.id}'.`);
+                const material = materials.get(state.material);
+                if (!material)
+                    throw new Error(`TC_CLOTH_VISUAL_MATERIAL: Material '${state.material}' is not declared.`);
+                if (!Array.isArray(state.positions) || state.positions.length < 3 || state.positions.length > 4096 ||
+                    state.positions.some(point => !Array.isArray(point) || point.length !== 3 || !point.every(value => Number.isFinite(value) && Number.isFinite(Math.fround(value)))) ||
+                    !Array.isArray(state.triangles) || state.triangles.length < 1 || state.triangles.length > 8192 ||
+                    state.triangles.some(triangle => !Array.isArray(triangle) || triangle.length !== 3 || triangle.some(index => !Number.isSafeInteger(index) || index < 0 || index >= state.positions.length)) ||
+                    !Array.isArray(state.uvs) || state.uvs.length !== state.positions.length || state.uvs.some(uv => !Array.isArray(uv) || uv.length !== 2 || !uv.every(value => Number.isFinite(value) && Number.isFinite(Math.fround(value)))))
+                    throw new Error(`TC_CLOTH_VISUAL_INPUT: Cloth '${state.id}' has invalid positions, topology or UVs.`);
+                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 ? geometryData(state) : undefined;
+                staged.set(state.id, { view, created: !same, positions, ...update });
+            }
+        }
+        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.vertices && item.normals) {
+                const position = item.view.geometry.getAttribute("position"), normal = item.view.geometry.getAttribute("normal");
+                position.array.set(item.vertices);
+                normal.array.set(item.normals);
+                position.needsUpdate = true;
+                normal.needsUpdate = true;
+                item.view.geometry.computeBoundingBox();
+                item.view.geometry.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/renderer/gameplay.js

@@ -5,6 +5,7 @@ import { createGameServices } from "../runtime/game-services.js";
 import { createPhysicsFactory } from "../physics/index.js";
 import { createNavigationPlugin } from "../navigation/index.js";
 import { createRopePlugin } from "../simulation/rope-plugin.js";
+import { createClothPlugin } from "../simulation/cloth-plugin.js";
 import { createModelLibrary } from "./models.js";
 import { resolveEntityDefinition } from "../runtime/prefabs.js";
 /** Private presentation ownership. Games receive only SDK services, never browser/library objects. */
@@ -136,6 +137,7 @@ export async function prepareGameplay(ir, baseURL, renderer, materials = new Map
             services.factory,
             createNavigationPlugin,
             createRopePlugin,
+            createClothPlugin,
             (context) => ({
                 id: "$engine.models",
                 version: "2",

package/lib/runtime/host.js

@@ -203,6 +203,9 @@ export class RuntimeHost {
             get ropes() {
                 return host.service("ropes");
             },
+            get cloth() {
+                return host.service("cloth");
+            },
             entities: {
                 resolve: (entity) => this.world.resolve(entity),
                 isAlive: (entity) => this.world.isAlive(entity),

package/lib/sdk/index.d.ts

@@ -1,5 +1,5 @@
 /** Pelican Engine public API. No renderer or GPU implementation types escape this module. */
-export declare const SDK_VERSION = "0.3.16";
+export declare const SDK_VERSION = "0.3.18";
 export type Vec2 = readonly [number, number];
 export type Vec3 = readonly [number, number, number];
 export type Vec4 = readonly [number, number, number, number];
@@ -102,9 +102,10 @@ export interface SystemContext extends EngineFacade {
     readonly compute: ComputeService;
     readonly navigation: NavigationService;
     readonly ropes: RopeService;
+    readonly cloth: ClothService;
 }
 /** 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. */
+ * contact impulses to dynamic spheres; there is no full rigid-body coupling. */
 export type RopeCollider = {
     kind: "sphere";
     id: string;
@@ -153,6 +154,8 @@ export interface RopeDefinition {
     bodyColliders?: readonly RopeBodyCollider[];
     /** Resolve sphere contacts on segment interiors; defaults to true for new ropes. */
     segmentCollisions?: boolean;
+    /** Resolve discrete non-adjacent segment self contacts; defaults to true for new ropes. */
+    selfCollisions?: boolean;
     /** Optional segmented presentation using an already-declared material id. */
     visual?: RopeVisualOptions;
     substeps?: number;
@@ -187,11 +190,24 @@ export interface RopeSegmentContact {
     reactionImpulse?: Vec3;
     reactionAngularImpulse?: Vec3;
 }
+/** Discrete self-contact between two non-adjacent rope segments. */
+export interface RopeSelfContact {
+    tick: number;
+    /** Zero-based first endpoint of each non-adjacent segment, ordered ascending. */
+    firstSegment: number;
+    secondSegment: number;
+    /** Last closest-point fractions along the respective segments. */
+    firstFraction: number;
+    secondFraction: number;
+    /** Maximum observed overlap in metres during this tick. */
+    penetration: number;
+}
 export interface RopeState {
     tick: number;
     simulatedSeconds: number;
     disposed: boolean;
     segmentCollisions: boolean;
+    selfCollisions: boolean;
     positions: Vec3[];
     velocities: Vec3[];
     anchors: {
@@ -200,6 +216,7 @@ export interface RopeState {
     }[];
     contacts: RopeContact[];
     segmentContacts: RopeSegmentContact[];
+    selfContacts: RopeSelfContact[];
     maxDistanceError: number;
     resources: {
         particles: number;
@@ -222,6 +239,86 @@ export interface RopeService {
     applyImpulse(id: string, index: number, impulse: Vec3): void;
     destroy(id: string): void;
 }
+/** CPU triangulated cloth with particle contacts against sampled spheres and planes. */
+export type ClothCollider = RopeCollider;
+export type ClothTriangle = readonly [number, number, number];
+export interface ClothVisualOptions {
+    material: string;
+    /** Optional per-particle UV coordinates; defaults to a planar projection. */
+    uvs?: readonly Vec2[];
+    castShadow?: boolean;
+    receiveShadow?: boolean;
+}
+export interface ClothDefinition {
+    id: string;
+    points: readonly Vec3[];
+    triangles: readonly ClothTriangle[];
+    /** Kilograms per movable particle. */
+    mass: number;
+    radius?: number;
+    fixedDt?: number;
+    autoStep?: boolean;
+    substeps?: number;
+    iterations?: number;
+    damping?: number;
+    gravity?: Vec3;
+    /** Distance-based bending approximation across shared triangle edges; defaults to true. */
+    bending?: boolean;
+    anchors?: readonly {
+        index: number;
+        position: Vec3;
+    }[];
+    visual?: ClothVisualOptions;
+}
+export interface ClothContact {
+    tick: number;
+    particle: number;
+    colliderId: string;
+    penetration: number;
+}
+export interface ClothState {
+    tick: number;
+    simulatedSeconds: number;
+    disposed: boolean;
+    positions: Vec3[];
+    velocities: Vec3[];
+    triangles: ClothTriangle[];
+    anchors: {
+        index: number;
+        position: Vec3;
+    }[];
+    contacts: ClothContact[];
+    maxDistanceError: number;
+    resources: {
+        particles: number;
+        triangles: number;
+        constraints: number;
+        anchors: number;
+        colliders: number;
+    };
+}
+export interface ClothVisualState {
+    id: string;
+    material: string;
+    positions: Vec3[];
+    triangles: ClothTriangle[];
+    uvs: Vec2[];
+    castShadow: boolean;
+    receiveShadow: boolean;
+}
+export interface ClothService {
+    create(definition: ClothDefinition): void;
+    /** Explicit ticks for manual cloth only; automatic cloth rejects this call. */
+    step(id: string, ticks?: number): ClothState;
+    inspect(id: string): ClothState;
+    visuals(): readonly ClothVisualState[];
+    setColliders(id: string, colliders: readonly ClothCollider[]): void;
+    setAnchor(id: string, index: number, position: Vec3): void;
+    releaseAnchor(id: string, index: number): void;
+    applyForce(id: string, index: number, force: Vec3): void;
+    applyImpulse(id: string, index: number, impulse: Vec3): void;
+    destroy(id: string): void;
+}
 /** Integer cells on a finite 2D orthogonal grid; not continuous, flying or underwater navigation.
  * Searches allocate sparse state and depend on available memory. At most 2^32-1 cells may be defined.
  * Owners are explicit strings and are not automatically tied to entities. */

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

package/lib/simulation/cloth-plugin.js

@@ -0,0 +1,152 @@
+import { cloneSerializable } from "../runtime/random.js";
+import { createCloth } from "./cloth.js";
+const fail = (code, detail) => { throw new Error(`TC_CLOTH_${code}: ${detail}`); };
+const validId = (value) => typeof value === "string" && value.trim() === value && value.length > 0 && value.length <= 128;
+function planarUvs(points) {
+    const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+    for (const point of points)
+        for (let axis = 0; axis < 3; axis++) {
+            min[axis] = Math.min(min[axis], point[axis]);
+            max[axis] = Math.max(max[axis], point[axis]);
+        }
+    const axes = [0, 1, 2].sort((a, b) => (max[b] - min[b]) - (max[a] - min[a]) || a - b), first = axes[0], second = axes[1];
+    const width = max[first] - min[first], height = max[second] - min[second];
+    if (!(width > 0) || !(height > 0))
+        return fail("VISUAL_UV", "Initial points need two nonzero projection axes or explicit UVs.");
+    return points.map(point => [(point[first] - min[first]) / width, (point[second] - min[second]) / height]);
+}
+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.");
+    if (definition.autoStep !== undefined && typeof definition.autoStep !== "boolean")
+        return fail("AUTO_STEP", "autoStep must be boolean.");
+    if (definition.fixedDt !== undefined && definition.fixedDt !== fixedDt)
+        return fail("FIXED_DT", "Cloth fixedDt must match the host fixedDt.");
+    if (fixedDt < 1 / 1000 || fixedDt > 1 / 30)
+        return fail("FIXED_DT", "Host fixedDt must be in [1/1000,1/30].");
+    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.");
+        if ((visual.castShadow !== undefined && typeof visual.castShadow !== "boolean") || (visual.receiveShadow !== undefined && typeof visual.receiveShadow !== "boolean"))
+            return fail("VISUAL_SHADOW", "Shadow options must be boolean.");
+        if (visual.uvs !== undefined && (!Array.isArray(visual.uvs) || !Array.isArray(definition.points) || visual.uvs.length !== definition.points.length ||
+            visual.uvs.some(uv => !Array.isArray(uv) || uv.length !== 2 || !uv.every(value => typeof value === "number" && Number.isFinite(value) && Math.abs(value) <= 1e6))))
+            return fail("VISUAL_UV", "UVs must contain one finite 2D coordinate per particle.");
+    }
+    const solver = createCloth({ ...definition, fixedDt });
+    try {
+        const uvs = definition.visual ? (definition.visual.uvs ? definition.visual.uvs.map(uv => [uv[0], uv[1]]) : planarUvs(definition.points)) : [];
+        return { definition, solver, uvs };
+    }
+    catch (error) {
+        solver.dispose();
+        throw error;
+    }
+}
+function disposeEntries(entries) { for (const entry of entries.values())
+    entry.solver.dispose(); entries.clear(); }
+function parseSnapshot(value, fixedDt, materials) {
+    if (!value || typeof value !== "object" || value.version !== 1 || !Array.isArray(value.cloths) || value.cloths.length > 256)
+        return fail("SNAPSHOT", "Expected a version 1 snapshot containing at most 256 cloths.");
+    const entries = new Map();
+    try {
+        for (const item of value.cloths) {
+            if (!item || typeof item !== "object")
+                fail("SNAPSHOT", "Invalid cloth entry.");
+            const entry = createEntry(item.definition, fixedDt, materials);
+            if (entries.has(entry.definition.id)) {
+                entry.solver.dispose();
+                fail("SNAPSHOT", "Duplicate cloth id.");
+            }
+            entries.set(entry.definition.id, entry);
+            entry.solver.restore(item.state);
+        }
+        return entries;
+    }
+    catch (error) {
+        disposeEntries(entries);
+        throw error;
+    }
+}
+export const createClothPlugin = 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, materials = new Set(context.scene.materials.map(material => material.id));
+    let entries = new Map(), disposed = false;
+    const alive = () => { if (disposed)
+        fail("DISPOSED", "Cloth service is disposed."); };
+    const get = (id) => { alive(); if (!validId(id))
+        return fail("ID", "Expected a nonempty cloth id."); return entries.get(id) ?? fail("MISSING", `Cloth '${id}' does not exist.`); };
+    const service = {
+        create(definition) {
+            alive();
+            if (!definition || !validId(definition.id))
+                return fail("ID", "Expected a nonempty cloth id.");
+            if (entries.has(definition.id))
+                return fail("DUPLICATE", `Cloth '${definition.id}' already exists.`);
+            if (entries.size >= 256)
+                return fail("CAPACITY", "At most 256 cloths per host.");
+            const entry = createEntry(definition, hostDt, materials);
+            entries.set(entry.definition.id, entry);
+        },
+        step(id, ticks) { const entry = get(id); if (entry.definition.autoStep)
+            return fail("AUTO_STEP", `Cloth '${id}' is automatically stepped.`); return entry.solver.step(ticks); },
+        inspect(id) { return get(id).solver.inspect(); },
+        visuals() {
+            alive();
+            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 state = entry.solver.inspect(), visual = entry.definition.visual;
+                return { id: entry.definition.id, material: visual.material,
+                    positions: state.positions, triangles: state.triangles, uvs: entry.uvs.map(uv => [uv[0], uv[1]]),
+                    castShadow: visual.castShadow ?? true, receiveShadow: visual.receiveShadow ?? true };
+            });
+        },
+        setColliders(id, colliders) { get(id).solver.setColliders(cloneSerializable(colliders)); },
+        setAnchor(id, index, position) { get(id).solver.setAnchor(index, cloneSerializable(position)); },
+        releaseAnchor(id, index) { get(id).solver.releaseAnchor(index); },
+        applyForce(id, index, force) { get(id).solver.applyForce(index, cloneSerializable(force)); },
+        applyImpulse(id, index, impulse) { get(id).solver.applyImpulse(index, cloneSerializable(impulse)); },
+        destroy(id) { const entry = get(id); entry.solver.dispose(); entries.delete(id); },
+    };
+    return {
+        id: "$engine.cloth", version: "1", services: { cloth: service },
+        afterPhysics() {
+            alive();
+            const committed = [];
+            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);
+                for (const { solver } of automatic) {
+                    const snapshot = solver.snapshot();
+                    committed.push({ solver, snapshot });
+                    solver.step();
+                }
+            }
+            catch (error) {
+                const failures = [];
+                for (const { solver, snapshot } of committed.reverse())
+                    try {
+                        solver.restore(snapshot);
+                    }
+                    catch (rollbackError) {
+                        failures.push(String(rollbackError));
+                    }
+                if (failures.length)
+                    throw new Error(`TC_CLOTH_ROLLBACK: ${String(error)}; partialState=true; rollback failures: ${failures.join("; ")}`);
+                throw error;
+            }
+        },
+        legacySnapshot: () => ({ version: 1, cloths: [] }),
+        snapshot: () => ({ version: 1, cloths: [...entries.values()].sort((a, b) => a.definition.id < b.definition.id ? -1 : a.definition.id > b.definition.id ? 1 : 0)
+                .map(({ definition, solver }) => ({ definition: cloneSerializable(definition), state: solver.snapshot() })) }),
+        validateSnapshot(value) { const staged = parseSnapshot(value, hostDt, materials); disposeEntries(staged); },
+        restore(value) { alive(); const staged = parseSnapshot(value, hostDt, materials); disposeEntries(entries); entries = staged; },
+        dispose() { if (disposed)
+            return; disposed = true; disposeEntries(entries); },
+    };
+};