---
title: Physics & Simulation
description: GPU-accelerated cloth, rope, fluids, and rigid bodies — the mass-spring cloth solver, PBD rope, SPH and Eulerian fluids, ECS rigid bodies, PBD ragdoll, and the per-frame simulation order.
updated: 2026-06-05
---

# Physics & Simulation

GPU-accelerated cloth, rope, fluid volumes, and rigid-body physics. All solvers run on compute shaders via [vGPU](vgpu.md).

> For the full WebGPU compute physics engine with PhysX 5 parity (rigid bodies, solver, CCD, vehicles, CCT, FEM soft bodies, mesh/heightfield queries), see [GPU Physics Engine](gpu-physics.md).

## Cloth simulation

A mass-spring cloth solver in `engine/sim/cloth/`. Each cloth is a grid of particles connected by structural, shear, and bending springs, solved on GPU compute. Configurable: stiffness (spring force coefficient), damping (velocity damping), per-cloth gravity override, wind (directional force with turbulence noise), pin constraints (fixed vertices), and sphere/plane collision response.

## Rope physics

A Position-Based Dynamics (PBD) rope solver in `engine/sim/particles/RopePhysics.js`. Ropes are chains of particles with distance constraints solved iteratively:

- **PBD constraints** — distance constraints with configurable compliance.
- **Material properties** — stiffness, damping, mass per unit length (`RopeMaterial.js`).
- **Particle interaction** — ropes interact with the particle system (`RopeParticleInteraction.js`).
- **GPU rendering** — smooth tube rendering with normals and lighting (`RopeGPURenderer.js`).

## Fluid simulation

Two approaches:

- **Lagrangian (SPH)** — smoothed-particle hydrodynamics via the [particle system](particles.md). Each fluid particle carries density, pressure, and viscosity; the solver computes inter-particle forces using a neighbor grid (`ParticleSPH.js`).
- **Eulerian (grid-based)** — `ParticleEulerianFluid.js` solves the Navier-Stokes equations on a 3D grid using pressure projection and velocity advection, suitable for contained volumes (pools, rivers).

## Rigid body physics

The ECS `PhysicsBody` component drives rigid-body simulation: body types (dynamic, kinematic, static), collider shapes (sphere, box, capsule, mesh via the `Collider` component), forces (gravity, impulses, torques), and constraints (distance, hinge, ball-socket).

## PBD ragdoll

A Position-Based Dynamics ragdoll solver for character physics — joint limits, bone chains, and muscle constraints. It integrates with the [AGI](../agi/overview.md) system for learning-based locomotion.

## Simulation update

`SimulationUpdate.js` orchestrates all simulation systems each frame, in order:

1. ECS physics system tick (rigid bodies, colliders).
2. Cloth solver step (GPU compute).
3. Rope constraint solving (PBD iterations).
4. Particle simulation (main compute + advanced subsystems).
5. Fluid pressure solve (if active).

## Key files

| File | Purpose |
| --- | --- |
| `sim/SimulationUpdate.js` | Master simulation orchestrator |
| `sim/cloth/` | Mass-spring cloth solver |
| `sim/fluids/` | Eulerian fluid volumes |
| `sim/physics/` | Rigid body physics system |
| `sim/particles/RopePhysics.js` | PBD rope solver |
| `sim/particles/RopeMaterial.js` | Rope material properties |
| `sim/particles/ParticleSPH.js` | SPH fluid solver |
| `sim/particles/ParticleEulerianFluid.js` | Grid-based fluid |
| `sim/particles/ParticleConstraints.js` | Distance/position constraints |