machin-game-demo-physics

name	machin-game-demo-physics
description	Build, run, and modify machin-game-demo-physics — a 3D verlet physics sandbox with pure-MFL position-based dynamics, distance constraints, sphere-ground and sphere-sphere collision, and a chain pendulum. Use when working on this repo or as the reference example of verlet physics in machin (value-semantic particle arrays, constraint relaxation, O(n²) collision).

machin-game-demo-physics

A 3D verlet physics sandbox — spheres fall, collide, stack, and a chain pendulum swings through them. Written in machin (MFL) via raylib's C FFI. This is the pure-MFL physics layer that the Tier 4 combat sim needs — no C library, no FFI callbacks, just the Vec3 module and a constraint solver.

Shared game-dev setup, the FFI surface, and cross-cutting gotchas live in the canonical machin-gamedev skill. This file covers the specifics of this demo.

Build & run

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

Needs machin v0.48.0+, a C compiler, raylib, and a display. build.sh prefers a system raylib, else vendors the prebuilt static release into vendor/ (no root).

Architecture

math3d module (inline)

The Vec3 type with 10 ops — identical to the solar demo's module. Every physics calculation (position, velocity, constraint projection, collision normal) flows through it.

Verlet particle

type Particle struct {
    pos    Vec3     // current position
    old    Vec3     // previous position (velocity = pos - old)
    radius float    // for collision and rendering
    mass   float    // not used for verlet integration (equal for all), for future weighting
    pinned int      // 1 = fixed in place
}

Physics world

type Physics struct {
    particles  []Particle
    constraints []Constraint
    gravity    Vec3
    damping    float
    substeps  int
    iters     int   // constraint relaxation iterations per substep
}

Simulation loop (fixed timestep)

accumulator += frame_dt
while accumulator >= FIXED_DT:
    for each substep (6):
        phys_integrate(w, dt_sub)         // verlet step: pos += (pos-old)*damping + g*dt²
        for each iteration (3):
            phys_solve_constraints(w)     // project overlapping particles
        phys_collide_ground(w, 0.0)       // clamp pos.y ≥ radius
        phys_collide_spheres(w)           // O(n²) sphere-sphere push-apart
    accumulator -= FIXED_DT
    if steps > 8: break                   // spiral-of-death cap

Rendering

• Particles: DrawSphere(pos, radius, color) — raylib draws smooth filled spheres. Color is a velocity heat map: cold blue (still) → cyan → yellow → hot red (fast).
• Constraints: DrawLine3D between particle centers. Color indicates tension: stretched → red, compressed → green, relaxed → grey-blue.
• Ground: DrawGrid(40, 1.5) for a reference plane.

Scene

The demo spawns:

1. A chain pendulum — 20 particles, top one pinned, connected by distance constraints. Hangs from (-3, 13, 0) and swings under gravity.
2. 64 random particles — scattered in a box (-5..5, 4..14, -5..5) with random radii (0.25–0.5). They fall, collide with the ground and each other, and form a pile.
3. 2 heavy spheres — large mass, at (3, 10, 2) and (-2, 8, -3), radius ~1.0. They push through the light particles.

Patterns worth copying

• Verlet avoids velocity storage. old_pos is the implicit velocity store. The integration is a one-liner. No Euler/Verlet distinction — just new = pos + (pos-old)*damping + a*dt².
• Parallel slices for particle arrays. Cstruct types like Model can't be fields of MFL type structs, but Particle is a pure-MFL struct so it's fine in a []Particle. For the physics module, everything is pure MFL types.
• Constraint relaxation. Don't solve constraints exactly — iterate 3–5 times per substep. The half-step *0.5 distributes the correction equally between paired particles.
• Color by speed for live diagnostics. One speed_color() function turns a scalar into a heat map without any branch-per-pixel overhead.
• Separate substeps from frame rate. The physics tick is always 1/60; multiple substeps (6) maintain stability. The accumulator pattern from solar re-used verbatim.

Modifying

• Scene density: change the number of particles in main() (the 64‑particle while loop range, build calls, or build_grid call — build_grid is available but commented out).
• Gravity: phys_new(0.0, -15.0, 0.0, ...) — the Y value can be adjusted or negated for antigravity.
• Damping: the 0.995 factor in phys_new — higher = more elastic, lower = more damped.
• Substeps: 6 is stable for fast-falling particles. Lower for performance, higher for stability.
• Constraint iterations: 3 is a good balance. More = stiffer constraints at higher CPU cost.

Future directions

• Soft body cubes — particles at cube corners + edge constraints + a center constraint → a deformable block that squishes and bounces.
• Cloth simulation — build_grid() is already written; uncomment and the demo shows a pinned grid of particles acting as hanging cloth.
• Mouse picking — raycast from camera → find nearest particle → drag it with a temporary constraint.
• Friction / restitution — per-particle bounce coefficient, Coulomb friction at ground contact.
• Floor rendering — a DrawCube ground plane instead of just a grid, optionally with a checkerboard texture.
• Extract physics module — physics.src as a vendored module for reuse.