ofxPBD

Unified Extended Position-Based Dynamics (XPBD) physics for openFrameworks.

Cloth, ropes, soft bodies, and flying rigid spheres — all in one ECS-native solver built from scratch with GLM and EnTT.

Features

• Cloth with structural, shear and skip-1 bend constraints
• Ropes / chains (distance constraints)
• Soft bodies (octahedral particle clusters + volume constraints)
• Dynamic spheres that interact with cloth and each other (two-body collision)
• Static plane / box / sphere colliders
• Wind force component
• Live-tunable compliance (stiffness) sliders
• Swept-sphere CCD (planes, spheres, boxes) — safe at extreme speeds
• Header-only solver — just add src/ to your include path

Dependencies

Addon	Required
ofxEnTT	Yes (EnTT headers)
ofxEnTTKit	Optional (ofxPBDKit.h only)
ofxImGui + ofxImGuiStyle	Examples only

Quick start (standalone)

#include "ofxPBD.h"

entt::registry reg;
ofxPBD         physics;

void setup() {
    pbd::SolverConfig cfg;
    cfg.substeps = 14;
    physics.setup(cfg);

    pbd::makeCloth(reg, 30, 20, 0.35f, {-5.f, 8.f, 0.f});
    pbd::makeStaticPlane(reg);
}

void update() { physics.update(reg, ofGetLastFrameTime()); }
void draw()   { cam.begin(); ofxPBD::drawDebug(reg); cam.end(); }

Namespace summary

pbd::particle              fundamental simulation unit
pbd::cloth_body            grid of particles + constraint lists
pbd::rope_body             chain of particles + constraint lists
pbd::soft_body             cluster of particles + constraint lists
pbd::rigid_body            stiff particle group (e.g. pole rod)
pbd::hinge_constraint      base spring / swing joint between two particles
pbd::fixed_constraint      world-offset weld between two particles
pbd::distance_constraint   structural / shear / bend / rope link
pbd::volume_constraint     tetrahedral volume preservation
pbd::plane_collider        infinite static plane
pbd::box_collider          static oriented box
pbd::sphere_collider       static or dynamic sphere
pbd::capsule_collider      segment collider between two particles
pbd::torus_collider        analytic ring collider
pbd::spin                  angular state, Magnus force, rolling contact
pbd::collision_filter      optional collision layer and mask
pbd::kinematic_tag         externally driven particle marker
pbd::gravity_override      per-scene gravity component
pbd::wind_force            per-scene wind impulse

pbd::makeCloth(...)        → body entity
pbd::makeRigidRod(...)        → rigid_body (2 particles + shaft + base hinge)
pbd::makeHingeConstraint(...) → hinge entity
pbd::makeFixedConstraint(...) → weld entity
pbd::makeRope(...)         → body entity
pbd::makeSoftSphere(...)   → body entity
pbd::makeSoftTetra(...)    → tetrahedral soft body
pbd::makeDynamicSphere(...)→ particle + sphere_collider entity
pbd::makeStaticSphere(...) → static sphere collider
pbd::makeStaticPlane(...)  → collider entity
pbd::makeStaticBox(...)    → collider entity
pbd::makeTorusCollider(...)→ analytic ring collider
pbd::makeCapsuleCollider(...) → particle-ended segment collider
pbd::attachSpin(...)       → angular state on an existing particle
pbd::destroyBody(...)      → destroys all owned particles + constraints

pbd_kit::buildClothMesh()  → ofMesh  (call once)
pbd_kit::syncClothMesh()   → update verts + normals each frame
pbd_kit::XPBDSystem        → drop-in ecs::ISystem
pbd_kit::makePhysicsCloth()→ cloth body + built ofMesh

References

This addon implements the algorithm described in:

XPBD: Position-Based Simulation of Compliant Constrained Dynamics
Miles Macklin, Matthias Müller, Nuttapong Chentanez
Proceedings of the 9th International Conference on Motion in Games (MIG 2016)
ACM, 2016. DOI: 10.1145/2994258.2994272
Full text: <https://matthias-research.github.io/pages/publications/XPBD.pdf>

The core idea is that XPBD extends the original PBD (Müller et al., 2007) by introducing a compliance parameter α per constraint. This decouples constraint stiffness from the timestep and number of substeps, making it straightforward to tune behaviour like cloth drape and soft-body squishiness independently of simulation frequency.

Key concepts used directly in pbd/constraints.h and pbd/solver.h:

XPBD concept	ofxPBD location
Compliance α̃ = α / Δt²	solve_distance, solve_volume in constraints.h
Position update Δx = −C / (w + α̃) · ∇C / ‖∇C‖²	All constraint solvers
Velocity from positions v = (x − x_prev) / Δt	XPBDSolver::update_velocities in solver.h
Sub-stepping for stability	SolverConfig::substeps in solver.h

Related reading:

• Müller et al., "Position Based Dynamics", Journal of Visual Communication and Image Representation, 2007 — the original PBD formulation. DOI: 10.1016/j.jvcir.2007.01.005
• Macklin, "A Constraint-based Formulation of Stable Neo-Hookean Materials", 2021 — extends XPBD to finite-element elasticity. <https://matthias-research.github.io/pages/publications/neohookean.pdf>