007 - Physics System

The Physics System provides Verlet-based physics simulation.

Why Physics in Creative Coding?

Physics makes generative art come alive. A particle that follows gravity appears more natural than one that flies linearly. A swarm whose individuals react to each other creates emergent patterns that you couldn't have programmed.

Why Verlet?

There are many physics approaches. I use Verlet Integration because it is:

• Stable – Nothing explodes even with large time steps
• Simple – Position + previous position = velocity (implicit)
• Constraint-friendly – "These two points should have distance X" → simply correct positions

Classic Euler integration (position += velocity * dt) accumulates errors and requires small time steps. Verlet (position_new = 2*position - position_old + acceleration*dt²) is more stable and allows larger time steps.

Why Two Levels?

The system has two separate physics worlds:

1. PhysicsWorld – For particles, swarms, chains. Each point is a Particle.
2. SoftShape – For deformable shapes. The vertices have their own mini-physics.

Why separate? Because a soft circle retains its internal jelly physics even when it flies around as a whole in the PhysicsWorld. The ShapePhysicsAdapter connects both worlds.

Two-Level Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                       Level 1: PhysicsWorld                             │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                        PhysicsWorld                               │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│         │              │              │              │                  │
│         ▼              ▼              ▼              ▼                  │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐            │
│  │ Particles  │ │ Behaviors  │ │Constraints │ │  Springs   │            │
│  └────────────┘ └────────────┘ └────────────┘ └────────────┘            │
└─────────────────────────────────────────────────────────────────────────┘
                                    ▲
┌───────────────────────────────────┼─────────────────────────────────────┐
│                       Adapter     │                                     │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                    ShapePhysicsAdapter                            │  │
│  └───────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────┼─────────────────────────────────────┘
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                        Level 2: SoftShape                               │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                          SoftShape                                │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                │                              │                         │
│                ▼                              ▼                         │
│      ┌─────────────────┐          ┌────────────────────────┐            │
│      │    Vertices     │          │  Internal Constraints  │            │
│      └─────────────────┘          └────────────────────────┘            │
└─────────────────────────────────────────────────────────────────────────┘

Level 1: PhysicsWorld

• Global point-based simulation
• Particles with Position, Velocity, Mass
• For: Particle systems, swarms, chains

Level 2: SoftShape

• Shape-internal simulation
• For: Deformable shapes (Blob, SoftCircle)

Components

PhysicsWorld

Container and update loop.

Update Order:

1. Apply behaviors (forces)
2. Update particles (Verlet)
3. Update springs
4. Apply constraints

API:

Particle

Verlet particle.

Properties:

Methods:

Behaviors

Forces that act on particles.

GravityBehavior

FrictionBehavior

AttractionBehavior

ConstantForceBehavior

Presets: createWindBehavior(), createUpdraftBehavior()

Flocking Behaviors (Boids)

Flocking Presets:

Constraints

Rules that particles must follow.

RectConstraint

Keeps particles in a rectangle.

CircularConstraint

Keeps particles in/outside a circle.

DistanceConstraint

Fixed distance between two particles.

AxisConstraint

Restricts to one axis.

Presets: createHorizontalRail(), createVerticalRail()

MinConstraint / MaxConstraint

Minimum/Maximum boundary.

Presets: createFloor(), createCeiling(), createLeftWall(), createRightWall()

Springs

Spring forces between particles.

Options:

ParticleString

Chain of particles with constraints.

Factory Functions:

CollisionZone

Zones with special behavior.

Behaviors:

ProximityConnection

Draws lines between nearby particles.

Presets:

Presets & Factory Functions

Soft Body Collisions

The soft body system (see 004-Shapes) supports shape-to-shape collisions.

Collision Pipeline

┌─────────────────┐    ┌─────────────────┐    ┌─────────────┐
│   Broad-Phase   │ -> │  Narrow-Phase   │ -> │  Response   │
│      AABB       │    │      SAT        │    │   Impulse   │
└─────────────────┘    └─────────────────┘    └─────────────┘

Phases:

Enabling

import { ShapeStateManager } from '@carstennichte/cc-toolbox';

// Create and configure shapes...
const shapes: ShapeStateManager[] = [...];

// All shapes know all others
const decorators = shapes.map(s => s.getDecorator());
for (const shape of shapes) {
  shape.setCollisionBodies(decorators);
}

Parameter Influence

Performance Notes

• All-against-All: With n shapes → n² checks
• Recommendation: ~20-30 shapes with collision, ~50 without
• Concave Shapes: SAT only works reliably for convex polygons