Queue a force to be applied to a rigid body during the next physics step. Returns updated world with the command queued.

Example

let world = physics.apply_force(world, "player", vec3.Vec3(0.0, 100.0, 0.0))
let world = physics.step(world, ctx.delta_time)  // Force is applied here

Queue an impulse to be applied to a rigid body during the next physics step. Returns updated world with the command queued.

Example

// Jump
let world = physics.apply_impulse(world, "player", vec3.Vec3(0.0, 10.0, 0.0))

Queue a torque to be applied to a rigid body during the next physics step. Returns updated world with the command queued.

Queue a torque impulse to be applied to a rigid body during the next physics step. Returns updated world with the command queued.

Build the final rigid body from the builder.

This function is type-safe - you cannot call it without first calling with_collider().

Example

let body = physics.new_rigid_body(physics.Dynamic)
  |> physics.with_collider(physics.Sphere(transform.identity, 1.0))
  |> physics.with_mass(5.0)
  |> physics.build()  // Returns RigidBody ready to use

Compute collision-aware movement for a kinematic character. Returns the actual movement that can be safely applied without penetrating colliders. Must have created a character controller for this body first.

Get the current angular velocity of a rigid body

Get all collision events that occurred during the last physics step.

Events are automatically collected when step() is called and stored in the world.

Example

let physics_world = physics.step(physics_world)
let collision_events = physics.get_collision_events(physics_world)

list.each(collision_events, fn(event) {
  case event {
    physics.CollisionStarted(a, b) ->
      io.println(a <> " started colliding with " <> b)
    physics.CollisionEnded(a, b) ->
      io.println(a <> " ended colliding with " <> b)
  }
})

Get the current transform of a rigid body.

Queries the physics simulation directly, so it always returns the latest position even for bodies that were just created in the current frame.

Example

let cube_transform = case physics.get_transform(physics_world, Cube1) {
  Ok(t) -> t
  Error(_) -> transform.at(position: vec3.Vec3(0.0, 10.0, 0.0))
}

Get the current velocity of a rigid body

Check if a character is grounded (on the ground). This uses the character controller’s computed grounded state. Must have called compute_character_movement for this body first in this frame.

Create a new rigid body builder.

Start here to build a physics body using the fluent builder pattern. You must call with_collider() before build().

Body Types:

• Dynamic: Moves and responds to forces (balls, characters, props)
• Kinematic: Programmatically controlled, doesn’t respond to forces (elevators, doors)
• Fixed: Static, immovable (walls, floors, terrain)

Example

import tiramisu/physics
import tiramisu/transform

// Dynamic ball
let ball = physics.new_rigid_body(physics.Dynamic)
  |> physics.with_collider(physics.Sphere(
    offset: transform.identity,
    radius: 1.0,
  ))
  |> physics.with_mass(5.0)
  |> physics.with_restitution(0.8)
  |> physics.build()

// Static ground
let ground = physics.new_rigid_body(physics.Fixed)
  |> physics.with_collider(physics.Box(
    offset: transform.identity,
    width: 50.0,
    height: 1.0,
    depth: 50.0,
  ))
  |> physics.build()

Create a new physics world.

Call this in your init() function and store the world in your Model. Return it as the third element of the init triple so Tiramisu can manage it.

Gravity: Typical Earth gravity is Vec3(0.0, -9.81, 0.0). Use Vec3(0.0, 0.0, 0.0) for zero-gravity space games.

Example

import tiramisu/physics
import vec/vec3
import gleam/option

type Model {
  Model(physics_world: physics.PhysicsWorld(String))
}

fn init(ctx) {
  let world = physics.new_world(physics.WorldConfig(
    gravity: vec3.Vec3(0.0, -9.81, 0.0),  // Earth gravity
  ))

  #(
    Model(physics_world: world),
    effect.none(),
    option.Some(world),  // Return world for Tiramisu to manage
  )
}

Cast a ray and return the first hit

Useful for shooting mechanics, line-of-sight checks, and ground detection.

Example

// Cast ray downward from player position
let origin = player_position
let direction = vec3.Vec3(0.0, -1.0, 0.0)

case physics.raycast(world, origin, direction, max_distance: 10.0) {
  Ok(hit) -> {
    // Found ground at hit.distance units below player
    io.println("Hit body with ID")
  }
  Error(Nil) -> {
    // No ground found within 10 units
  }
}

Queue an angular velocity change for a rigid body during the next physics step. Returns updated world with the command queued.

Queue a kinematic translation change for a kinematic rigid body during the next physics step. This is the proper way to move kinematic bodies in Rapier. Returns updated world with the command queued.

Queue a velocity change for a rigid body during the next physics step. Returns updated world with the command queued.

Step the physics simulation forward with variable timestep This should be called in your update function each frame

IMPORTANT: Pass ctx.delta_time for frame-rate independent physics!

Example

fn update(model, msg, ctx) {
  let world = physics.step(model.physics_world, ctx.delta_time)
  #(Model(..model, physics_world: world), effect.none(), option.None)
}

Returns updated world with new transforms for all bodies

Set angular damping (air resistance for rotation).

Damping: 0.0 = no resistance, higher = more drag Prevents bodies from spinning forever. Default: 0.0

Enable Continuous Collision Detection (CCD).

CCD prevents fast-moving objects from tunneling through thin obstacles. Use for bullets, fast-moving balls, or high-velocity objects.

Example

// Bullet that shouldn't pass through walls
physics.new_rigid_body(physics.Dynamic)
  |> physics.with_collider(physics.Sphere(transform.identity, 0.1))
  |> physics.with_body_ccd_enabled()

Add a character controller for collision-aware kinematic movement.

Character controllers are perfect for player characters and NPCs, providing:

• Automatic collision detection and response
• Sliding along surfaces
• Configurable offset from obstacles

Note: Character controllers are only useful for Kinematic bodies.

Example

// Player character with character controller
let player = physics.new_rigid_body(physics.Kinematic)
  |> physics.with_collider(physics.Capsule(
    offset: transform.identity,
    half_height: 0.9,
    radius: 0.3,
  ))
  |> physics.with_character_controller(
    offset: 0.01,
    up_vector: vec3.Vec3(0.0, 1.0, 0.0),
    slide_enabled: True,
  )
  |> physics.build()

Enable collision event tracking for this body.

By default, collision events are not tracked to minimize performance overhead. Call this method if you need to receive collision events via get_collision_events().

Performance Note: Only enable collision events for bodies where you actually need to detect collisions (e.g., player, enemies, collectibles). Static decorations and particle effects typically don’t need event tracking.

Example

// Player needs collision events (e.g., for damage detection)
let player = physics.new_rigid_body(physics.Dynamic)
  |> physics.with_collider(physics.Capsule(
    offset: transform.identity,
    half_height: 0.9,
    radius: 0.3,
  ))
  |> physics.with_collision_events()  // Enable events
  |> physics.build()

// Static ground doesn't need events
let ground = physics.new_rigid_body(physics.Fixed)
  |> physics.with_collider(physics.Box(
    offset: transform.identity,
    width: 50.0,
    height: 1.0,
    depth: 50.0,
  ))
  |> physics.build()  // No events, saves performance

Set collision groups for filtering which objects can collide

Example

// Player belongs to layer 0, collides with enemies (1) and ground (2)
let body = physics.new_rigid_body(physics.Dynamic)
  |> physics.body_collider(physics.Capsule(1.0, 0.5))
  |> physics.body_collision_groups(
    membership: [0],
    filter: [1, 2]
  )
  |> physics.build_body()

Set friction coefficient.

Friction: 0.0 = ice (no friction), 1.0+ = very grippy Default: 0.5

Example

// Slippery ice
physics.new_rigid_body(physics.Fixed)
  |> physics.with_friction(0.05)

// Grippy rubber
physics.new_rigid_body(physics.Fixed)
  |> physics.with_friction(0.9)

Set linear damping (air resistance for translation).

Damping: 0.0 = no resistance, higher = more drag Useful for simulating air/water resistance. Default: 0.0

Example

// Underwater physics
physics.new_rigid_body(physics.Dynamic)
  |> physics.with_linear_damping(2.0)  // Heavy water resistance

Lock rotation on the X axis (pitch)

Lock rotation on the Y axis (yaw)

Lock rotation on the Z axis (roll)

Lock translation on the X axis

Lock translation on the Y axis

Lock translation on the Z axis

Set the mass in kilograms (for Dynamic bodies).

Mass affects how forces and collisions influence the body. Default: Calculated from volume and density if not specified.

Example

physics.new_rigid_body(physics.Dynamic)
  |> physics.with_mass(70.0)  // Average human = 70kg

Set restitution (bounciness).

Restitution: 0.0 = no bounce, 1.0 = perfect bounce (energy conserved) Default: 0.3

Example

// Bouncy ball
physics.new_rigid_body(physics.Dynamic)
  |> physics.with_restitution(0.9)  // Very bouncy

// Non-bouncy box
physics.new_rigid_body(physics.Dynamic)
  |> physics.with_restitution(0.1)  // Barely bounces

Make this collider a sensor (trigger).

Sensors detect collisions and generate events, but don’t cause physical response (no pushing, bouncing, or blocking). Perfect for:

• Projectiles that should pass through targets
• Trigger zones (checkpoints, damage areas)
• Collectibles that don’t block movement

Note: Sensor colliders still need with_collision_events() to receive collision events.

Example

// Projectile that detects hits but passes through enemies
let bullet = physics.new_rigid_body(physics.Dynamic)
  |> physics.with_collider(physics.Sphere(transform.identity, 0.1))
  |> physics.with_sensor()
  |> physics.with_collision_events()
  |> physics.build()