---
name: ferret-character
description: Use for the Ferret player and character movement: spawnCharacter, CharacterMovement (capsule, walk, run, crouch, jump, steps, slopes), PlayerController with named actions, CameraRig first/third person. Parameters follow Unreal's Character Movement Component.
---

# Characters and the player

## When to use
A walking player or NPC body, jump and slope tuning, camera modes.

## The model
`spawnCharacter(world, id, position)` returns an entity with `CharacterMovement`: a capsule moving against static geometry, with walk, run, crouch, jump, steps, slopes, acceleration. `CharacterParams` follow UE's Character Movement Component, in metres and seconds. `PlayerController` turns input actions into movement and camera, reading the action names you give (`PlayerActions`) and ignoring the ones you leave out. `CameraRig` is first or third person, switchable at run time, with spring-arm collision.

## Steps
1. `spawnCharacter`, then `entity.add(PlayerController, { camera: { view: 'first' } })`.
2. Tune with `CharacterParams`, or per level through the manifest's `movement` block.
3. Hook events: `character:jump`, `character:land`.
4. Level movement values override Ferret's defaults for that level only.

## Check afterwards
Walk a slope, a step and a gap in a grey-box level; land and jump events fire; the camera does not clip through walls.

## What usually goes wrong
- Solid meshes not marked `checkCollisions` (or not `collide` in the manifest): the capsule falls through.
- Gravity changed by the physics gravity capability: the character reads the field only while it is on (see `ferret-physics-gravity-media`).
- Unit mistakes: values are metres and seconds, not centimetres as in the UE editor.

## Files

- `reference/packages.md` — Characters, animation graphs, NPC navigation, interactables, zones and transformations.
- `reference/api-character.md` — every export of `@ferret/character` with signature and doc comment