cloth

GPU cloth simulation system. Simulates any number of rectangular cloth sheets entirely on the GPU — Verlet integration, Jacobi constraint relaxation (structural / shear / bend springs), pin presets (top edge, left edge, corners, scalloped, center thumbtack), gusty form-drag wind, per-cloth contact friction, and analytic collisions against a ground plane plus up to four spheres per cloth.

All cloths share one particle domain, so stepping is a fixed dispatch sequence regardless of cloth count: one integrate pass, a ping-ponged series of constraint passes, then one vertex-write pass per cloth straight into that cloth's mesh vertex buffer (engine Vertex layout — rendering costs zero CPU geometry work). Grids (re)initialize analytically on the GPU from each cloth's origin + axis vectors, so building, resetting, or re-dropping a cloth never uploads particle data.

API

• Cloth.build(specs, opts?) -> handles — build the system from a list of cloth specs (grid size, spacing, origin/axes, pin preset, wind, colliders, pattern + colours, material). opts.iterations sets constraint iterations per step (default 9, forced odd).
• Cloth.step(dt) — advance every cloth one step; call once per frame in play mode.
• Cloth.reset(handle?) — re-initialize one cloth's grid (nil = all) on the next step.
• Cloth.setSphere(handle, slot, x, y, z, r) — animate a collider sphere (r <= 0 disables the slot).
• Cloth.setOrigin(handle, x, y, z) — move the grid origin; pinned particles follow live.
• Cloth.setWind(handle, dir, strength, gust?, freq?) — retune wind.
• Cloth.readPositions(handle) — read simulated particle positions back to the CPU (validation / tooling).
• Cloth.destroy() — tear down render entities, meshes, and GPU buffers.

Compute passes: cloth_step (integrate), cloth_constrain (one Jacobi iteration), cloth_vertices (particles → engine vertices with smooth normals, grid UVs, and procedural pattern colours). Pair with the fabric_surface shader / fabric_* materials for two-sided sheen-lit rendering.