Physics: cloth / soft-body support (Jolt soft-body currently unsupported)

[drsnuggles8]

Problem

No cloth or soft-body simulation. Jolt's soft-body shape is explicitly rejected in Physics3D/JoltShapes.cpp ("SoftBody shape type not supported, defaulting to Box") — the same defaults-to-Box pattern as the terrain heightfield gap (#428).

Why it matters

Flags, banners, capes, ropes/cables, and deformable cloth are common open-world dressing. Today they'd need custom solvers or fakes.

Proposed approach

• Wire Jolt SoftBodyShape / soft-body creation through JoltScene + a ClothComponent (or soft-body collider), resolving the unsupported shape-type path.

• Skinned cloth attachment to skeletons (capes / cloaks); wind coupling via the existing WindSystem.

Acceptance criteria

• A cloth mesh simulates under gravity + wind and collides with the world; a cape attached to a character moves believably.

---

Tier D — simulation richness. Mirrors the #428 heightfield "defaults to Box" pattern.

Score

capability: 3
craft: 5
stability: 1
decay: 1
effort: 3
confidence: 0.8
learning: 5
fun: 8
kano: delighter
blocked_by: []
blocks: []

_{Rated per issue-scoring · score = confidence × (capability + craft + stability + decay) / effort, derived by the picker.}

[coderabbitai]

🔗 Related PRs

#78 - Feature/physics integration [closed]
#340 - feat(physics): add CollideConnected toggle for joints (#308 item 1) [merged]
#345 - feat(physics): add Pulley, Gear, RackAndPinion joints (#308 item 4) [merged]
#468 - feat(physics): wire Jolt HeightFieldShape into terrain collision (#428) [merged]
#539 - fix(physics3d): route JoltScene through PhysicsSettings, fix contact-… [merged]

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[drsnuggles8]

First slice shipped — cloth simulates under gravity + collides with the world ✅

Branch feature/physics-cloth-softbody. This resolves the "SoftBody shape type not supported, defaulting to Box" gap for the base cloth case; the remaining acceptance criteria (wind, skeleton/cape attachment) are scoped as follow-up slices below.

What landed

• ClothComponent (all-trivial authored fields: grid columns/rows, width/height, mass, edge + bend compliance, linear damping, pressure, solver iterations, a ClothAttachment pin mode {None, TopEdge, TopCorners, LeftEdge}, enabled). Being all-trivial it round-trips through scene YAML, the AllComponents tuple, save-game capture/restore, and C# bindings entirely via OloHeaderTool codegen — only the SaveGame Serialize() overload and Lua binding are hand-written.
• JoltShapes::CreateClothSharedSettings — builds a JPH::SoftBodySharedSettings grid (particles + faces + auto-generated stretch/shear/bend constraints), bakes the entity world transform into the rest positions, distributes mass over free particles, and pins the attachment set (inverse mass 0). Grid clamped [2,128]/axis; fails closed on non-finite input.
• JoltScene soft-body lifecycle (m_Cloths map, CreateClothBody / DestroyClothBody / GetClothVertices) on the MOVING layer, mirroring the Physics: terrain has no collision — wire Jolt HeightFieldShape into TerrainComponent #428 terrain-body pattern. Vertex readback is GPU-free (works headless / on the dedicated server).
• Scene builds the soft bodies at OnPhysics3DStart, reads deformed vertices back each tick into CPU buffers, and renders a live-updated deforming mesh (two-sided, SetPreOptimized to keep the grid↔VBO mapping stable) in the runtime render pass. ShapeType::SoftBody now round-trips through GetShapeType instead of defaulting to Box.

Verification

• ClothSharedSettingsTest (6 contract tests — grid/pin/mass/transform math, fail-closed).
• ClothSimulationTest (Functional — free cloth falls & rests on a static floor; pinned cloth holds while the free part sags), driven headless through Scene::OnUpdateRuntime.
• ClothVisualEvidenceTest (L8 — renders the real runtime pipeline; the PNG shows a red curtain draping from a pinned top edge and a blue sheet draping over a box, with realistic folds). Sandbox scene ClothTest.olo added.
• All four cross-binding coverage guards + physics/serialization regressions green.

Remaining slices (this issue stays open)

• Wind coupling via WindSystem (apply wind force to soft-body particles).
• Skeleton attachment — pin cloth particles to bone transforms for capes/cloaks.
• Editor edit-mode preview (cloth currently only renders in play mode) + inspector polish.
• Optional: authored per-vertex pinning / tearing.

Leaving open for the follow-up slices per the first-shippable-slice scope.

[drsnuggles8]

First slice opened as PR #516 (feature/physics-cloth-softbody → master). Keeping this issue open for the wind / skeleton-attachment / edit-mode-preview follow-up slices.

[drsnuggles8]

PR #516 merged (2026-07-03T06:19:45Z) — first shippable slice of cloth/soft-body support (grid cloth simulates under gravity, collides with the world, renders as a deforming mesh); worktree removed. Follow-up slices (wind coupling, skeleton/bone attachment, edit-mode preview, per-vertex pin/tear) remain, so keeping this open.

[drsnuggles8]

Appears resolved by #516 (merged 2026-07-02): feat(physics): Jolt soft-body cloth simulation + rendering (#460). The "SoftBody shape type not supported, defaulting to Box" path in JoltShapes.cpp is gone — it now has JoltShapes::CreateClothSharedSettings (SoftBodySharedSettings + bend constraints), a ClothComponent (declared in Scene/Components.h, save-serialized in SaveGameComponentSerializer.h), a ClothTest.olo sandbox scene, plus ClothSharedSettingsTest, the Functional ClothSimulationTest, and ClothVisualEvidenceTest (with Cloth_VisualEvidence.png). The issue body still describes the pre-#516 rejected-shape state. Flagging for closure.

[drsnuggles8]

Partial progress: #516 (merged 2026-07-03) landed the first shippable slice — ClothComponent procedural grid cloth, Jolt soft-body wiring through JoltScene/JoltShapes.cpp (resolves the "defaults to Box" gap), and rendering as a live deforming mesh. Per the PR description, wind coupling (via WindSystem) and skeleton/cape attachment are explicitly scoped as follow-up slices and remain unimplemented — so this issue's acceptance criteria ("simulates under gravity + wind", "a cape attached to a character") are not yet fully met. Leaving open.

[drsnuggles8]

Wind coupling shipped — cloth simulates under gravity + wind ✅

Branch feature/cloth-wind-attachment. This closes the "Wind coupling via WindSystem" checkbox from the first-slice comment; skeleton attachment, edit-mode preview, and per-vertex pin/tear remain open follow-up slices.

What landed

• ClothComponent::m_WindInfluence (0–1, default 1) — how strongly a cloth responds to the scene's wind. All-trivial, so it round-trips through scene YAML / save-games / C# bindings via OloHeaderTool codegen with zero hand-written serializer changes.
• ClothWindSystem (Physics3D/ClothWindSystem.{h,cpp}) — mirrors BuoyancySystem's scene-bridging pattern: for each enabled cloth, samples WindSystem::GetWindAtPoint at the entity's world position and queues a uniform force scaled by mass × m_WindInfluence.
• JoltScene::ApplyClothWindForce — thin wrapper over JPH::BodyInterface::AddForce, which the soft-body sub-stepper divides evenly across every particle (confirmed via the vendored Jolt source — no per-vertex API needed).
• Wired into Scene::StepPhysics/KickPhysicsStep right alongside BuoyancySystem::OnUpdate, same "queue before the step" timing contract.

Two real bugs found via live-editor verification (not by the headless suite — see the new docs/agent-rules/scene-copy-must-carry-scene-level-settings.md for the full writeup):

1. Scene::Copy() (used entering Play/Simulate mode) silently dropped WindSettings and five sibling scene-level settings structs, resetting them to defaults the instant Play started. Wind (and fog/snow/precipitation/post-process read via Scene::GetXSettings()) was completely inert in the actual editor despite passing every automated test, because FunctionalTest never routes through Scene::Copy(). Fixed — all six structs now copy.
2. The cloth render pass hardcoded entityID = -1 in its DrawMesh call, so cloth entities never participated in mouse-picking/hover/selection-outline in the editor. Fixed to use the same entt-handle convention as the MeshComponent pass.

Verification

• ClothWindTest (Functional) — two pinned cloths under the same wind field, one m_WindInfluence=0 control and one =1; asserts the full-influence cloth billows measurably sideways relative to the control.
• ClothWindScene (L8 visual evidence) — real runtime pipeline, Cloth_WindVisualEvidence.png.
• New ClothWindTest.olo sandbox scene (+ TEST_SCENES.md entry) — wind cloth vs. no-wind control side by side; confirmed live in the editor via the run-oloengine MCP tools (olo_scene_open/olo_scene_play/olo_screenshot) after fixing the two bugs above.
• Full suite green: 4200/4200 (0 failed, 8 pre-existing disabled).

Leaving the issue open for skeleton/cape attachment + edit-mode preview.