Rigid Bodies

A rigid body is a physics object that simulates real-world mass, inertia, and collision response. In ShapeBox, any object with Physics Enabled and Body Type set to Dynamic or Kinematic is a rigid body.

Dynamic bodies

Dynamic bodies are fully simulated by the physics engine. They respond to:

Gravity — pulled downward at the scene's global gravity setting.
Collisions — bounce off other colliders based on restitution.
Applied forces — pushed, pulled, or torqued via scripts.

Key dynamic body properties

Property	Range	Description
Mass	0.01 – 10000	Object weight in kg. Heavier objects require more force to move.
Gravity Scale	-10 – 10	Per-object gravity multiplier. Set to 0 for floating objects.
Linear Damping	0 – 1	How quickly linear velocity decays (air resistance).
Angular Damping	0 – 1	How quickly rotational velocity decays.
Restitution	0 – 1	Bounciness on collision impact.
Friction	0 – 1	Surface friction against other colliders.

Locking axes

Sometimes you want a dynamic body to simulate physics but not rotate or move on certain axes — for example, a coin that slides but stays upright:

In Inspector → Physics → Constraints, lock specific axes:

Freeze Position X / Y / Z — prevent translation on that axis.
Freeze Rotation X / Y / Z — prevent rotation on that axis.

Applying forces via script

import { getObject } from '@shapebox/api'
import { applyForce, applyImpulse, applyTorque } from '@shapebox/physics'

const ball = getObject('Ball')

// Continuous force (applied every frame while held)
applyForce(ball, { x: 0, y: 10, z: 0 })  // lift upward

// Instant impulse (applied once — like a hit or explosion)
applyImpulse(ball, { x: 5, y: 0, z: 0 })

// Rotational force
applyTorque(ball, { x: 0, y: 2, z: 0 })

Kinematic bodies

Kinematic bodies are moved by scripts or the animation system, not by the physics simulation itself. They still register collisions with dynamic bodies and push them out of the way — but gravity and forces do not affect them.

Uses:

Moving platforms and elevators
Automated doors and shutters
Player character controllers
Any object that follows a scripted path

import { getObject } from '@shapebox/api'

const platform = getObject('Platform')

let t = 0
onUpdate((delta) => {
  t += delta
  platform.position.y = Math.sin(t) * 2  // oscillate up and down
})

Constraints

Constraints link two rigid bodies so they move in relation to each other. Add a constraint in Inspector → Physics → Add Constraint:

Constraint	Description
Hinge	Rotation around a single axis — doors, wheels, clocks
Ball & Socket	Free rotation in all directions — shoulder joint, pendulum
Fixed	Locks two objects together rigidly — welds them
Slider	Translation along one axis — pistons, drawers
Spring	Elastic connection between two objects — suspension

Hinge example — swinging door

Select the door object.
In Inspector → Physics → Add Constraint → Hinge.
Set Anchor to the hinge edge of the door.
Set Axis to Y (vertical rotation).
Optionally set Min Angle and Max Angle to limit the swing.

Sleeping

Idle dynamic bodies that have had no forces applied for a short time automatically enter a sleep state to save performance. They wake up as soon as another object touches them or a script applies a force.

To prevent an object from sleeping: Inspector → Physics → Never Sleep.

Continuous collision detection (CCD)

Fast-moving objects can "tunnel" through thin walls because the physics step moves them so far in one frame that they skip past the collider. Enable CCD for high-speed projectiles or small fast objects:

Inspector → Physics → Collision Detection → Continuous