---
name: ferret-physics-host
description: Use to switch realistic physics on in a Ferret game: PhysicsHost, registering and enabling capabilities, the order of the step, scoped values (world, level, zone, entity), physics.* commands, and writing a capability of your own.
---

# The capability host

## When to use
Turning a capability on, setting its values for one place, loading a level's physics, or writing a new capability.

## The model
`PhysicsHost` runs **capabilities**, each in its own package (`gravity`, `media`, `friction`, `impact`, `strength`, `stretch`, `terrain`, `explosion`, `heat`, `chemistry`, `nuclear`, `combustion`, `electric`, `machine`, `vehicles`, `liquids`, `links`). A game loads only what it registers. Each runs in a fixed **phase** of the step. Values are **scoped**: world, level, zone, entity; the narrowest wins. Dependencies are declared in `requires`.

## Steps
1. `const host = world.addService(new PhysicsHost({ kernel, capabilities }))` (kernel: `LightKernel` or Havok, see `ferret-physics-bodies`).
2. `host.register(cap)` once, then `host.enable('name')` in dependency order (or `configure` with a list).
3. Set values: `host.config('strength').set('world' | 'entity' | ..., 'toughness', 10, id)`; read with `config.get(key, ctx)` to see what wins.
4. A level brings its own physics: the manifest `physics` block applied by `beginLevel`, undone by `endLevel`.
5. From outside: `physics.info`, `physics.enable`, `physics.configure`, `physics.materials`.

## Check afterwards
`physics.info` lists the capabilities on and the step time; one body behaves as the capability says in a headless test.

## What usually goes wrong
- `capability "x" is already registered` or `no capability "x"`: register once; the error lists the registered names.
- `needs "y" switched on first`: enable in dependency order.
- A value seems ignored: a narrower scope overrides it.
- A body does not fall: gravity off, body `static`, `gravityScale` 0 or exempt.
- The node does not follow its body: `rotate: false` or a transformed parent.

## Files

- `reference/host.md` — How a game turns realistic physics on: registering and enabling capabilities, the order of the step, scoped values, commands, and how to write a capability of your own.
- `reference/overview.md` — Realism as capabilities a game switches on, the host and kernels, scoped values, the fixed phases, budgets and tiers.
- `reference/capabilities.md` — Every physics capability: the package, its registered name, its phase and what it adds.
- `reference/api-physics.md` — every export of `@ferret/physics` with signature and doc comment
- `reference/commands.md` — 7 commands of these packages with their arguments