machin-game-demo-softbody

name

machin-game-demo-softbody

description

Build, run, and modify machin-game-demo-softbody — a pair of 3×3×3 cubes held by shape-matching pull-toward-COM+rest_offset, dropping onto a jagged floor in machin (MFL). Use when working on this repo, or as the reference example of soft-body shape-matching dynamics built on machin-game-demo-physics. Covers the new `Particle` fields (rest_offset, body_id), the `phys_shape_match(w)` solver, the `build_soft_cube` 2-pass builder, and the spring-stiffness K constant.

machin-game-demo-softbody

Two 3×3×3 cubes + jagged floor + shape-matching dynamics — pure composition on machin-game-demo-physics.

Shared game-dev substrate (raylib FFI, FlyCam, math module, build/vendoring raylib) lives in the canonical machin-gamedev skill.

Build & run

./build.sh                            # → ./machin-game-demo-softbody
./machin-game-demo-softbody

Needs machin v0.48.0+, a C compiler, raylib, and a display.

Architecture

The shared substrate

Inherited verbatim from the base:

• math3d (Vec3 + 11 ops)
• raylib FFI (DrawSphere, DrawLine3D, DrawGrid, Camera3D cstruct, mouse/keyboard helpers)
• Verlet integrator (phys_integrate extended to preserve rest_offset and body_id through the struct-literal replacement)
• ground + sphere-sphere collisions
• FlyCam, RNG

The softbody deltas

1. Particle gains two fields

type Particle struct {
    pos         Vec3
    old         Vec3
    radius      float
    mass        float
    pinned      int
    rest_offset Vec3
    body_id     int
}

rest_offset = position relative to the body's COM at REST. body_id = -1 for non-soft particles (jagged floor, balls).

part_new now takes 6 args. phys_add_particle defaults body_id = -1, rest_offset = zero so it stays a "regular particle" call.

2. phys_shape_match(w) — the spring layer

K := 0.18  // spring stiffness per substep-iteration

for each distinct body_id:
    count, COM := average(positions in that body)
    for each particle p in body_id:
        target := COM + p.rest_offset
        p.pos = v3_lerp(p.pos, target, K)  // K * (target - pos) per pull

Called inside phys_tick's relaxation loop, so it runs iters times per substep. With iters = 3 and K = 0.18, a deformed cube springs back to its rest shape in 1-2 substeps.

3. build_soft_cube — two-pass builder

Pass 1: place 27 particles in a 3×3×3 grid at world-space coords. Pass 2: compute the body's COM (averaging positions) and assign each particle rest_offset = pos - COM.

build_jagged_floor is similar but its particles are pinned (no shape-matching; they're just collision geometry).

4. phys_tick calls phys_shape_match inside its relaxation loop

phys_solve_constraints is preserved verbatim but its loop runs over an empty constraints slice in softbody → no-op. The active spring is phys_shape_match.

Patterns worth copying

• Shape-matching in pure position-based dynamics. Lerp-toward-target works inside a Verlet integrator because both are position-only — no velocity state to maintain.
• A 2-pass builder to compute per-body rest_offset. Always capture rest_offset after placing particles, so it points relative to the body's COM, not the world.
• Compose visually distinct bodies by body_id. The render color is soft_color_for(p.body_id); the rest-target debug lines are picked by the same id. Easy to add more bodies — just build_soft_cube again with a new id.
• K is the king knob. Changing K from 0.05 → 0.18 → 0.30 takes you from molasses → standard → oscillating. Anything you build on this should expose K as a tuning parameter.

Modifying

• Stiffer / softer cubes: edit K := 0.18 in phys_shape_match.
• More iterations (deeper spring-back): bump iters in phys_new(0, -22, 0, 0.95, 3, 3) — e.g. (3, 5) for stronger pull.
• Bigger / smaller cubes: scale spacing in build_soft_cube.
• More cubes: just call build_soft_cube(..., 2) and build_soft_cube(..., 3) — extend soft_color_for to color them.
• Different floor: replace build_jagged_floor with a flat plane (pinned particles at constant Y) or a sine-wave ridge using noise2.
• Distance constraints + shape match: pre-build n² edges; add them to phys_solve_constraints. Both spring layers will run together.

Future directions

• Distance constraints on cube edges — gives a stiffer cube that bounces more (less squish, more restore torque).
• Pressure-volume — Müller-style: each body has a target volume; the solver adds an outward/inward pressure to keep that volume constant. Result: the cube truly holds its shape under compression.
• Rest pose rotation — currently rest_offset is captured once and frozen. A rotation-aware shape-matcher (compute orientation from two particle pairs) handles tumbling bodies.
• Multi-body collisions — two cubes colliding should push each other apart. The base's O(n²) sphere-sphere handles this for free; we just need to test it.