---
name: ferret-physics-bodies
description: Use for Ferret rigid bodies and materials: choosing the light or Havok kernel, shapes and body kinds, joints and constraints, contact events, layers, triggers, raycasts, PhysicalMaterial tables and combine rules, and the physics block of a level manifest.
---

# Rigid bodies, kernels, materials

## When to use
Making things collide, choosing a kernel, defining materials, or writing a level's `physics` block.

## Choosing a kernel
`LightKernel`: small, no joints beyond rod, rope and spring, dynamic **spheres** only (boxes are not supported as dynamic bodies). `Havok` (`loadHavok`, `havokKernel`, in `@ferret/physics-havok`): full rigid bodies, joints, sweeps; per-pair material tables are not read there. Capabilities that need real rigid bodies say so.

## Steps
1. Add `RigidBody` (shape, mass or density, kind `dynamic|static|kinematic`, material) to entities.
2. Define materials as data: friction, restitution, density, strengths. A **missing value means "does not apply"** (no `tensileStrength` = unbreakable).
3. Pair and combine rules for two materials meeting; validate with `validateMaterials`.
4. Layers and masks for what hits what; triggers for zones; raycasts for queries.
5. In a level: manifest `physics` with capabilities, materials, pairs, gravity, `constraints` (node names), `fractured` bodies.

## Check afterwards
`physics.materials` prints what the host sees; `body.state` shows each body; the level's `physics` block validates before shipping.

## What usually goes wrong
- A box falls through a plane on the light kernel: use a sphere or Havok.
- A hinge or ball joint throws on the light kernel.
- Thin fast bodies tunnel: raise `substeps`.
- Mass wildly wrong: it is density times shape volume; check units (metres).
- Physics of the previous level lingers: it was applied at world scope; use `beginLevel`.

## Files

- `reference/bodies-and-kernels.md` — Rigid bodies in Ferret: the light and Havok kernels, shapes, body kinds, joints and their forces, contact events, and choosing between the two.
- `reference/materials.md` — Physical materials as data: the properties, what a missing value means, combine rules and pair tables, validation, and how capabilities read them.
- `reference/level-block.md` — The `physics` block of a level manifest: capabilities, materials, pair and combine rules, gravity, constraints and pre-fractured bodies, and what happens when the level loads and unloads.
- `reference/api-physics-havok.md` — every export of `@ferret/physics-havok` with signature and doc comment