---
name: ferret-physics-actuators
description: Use for pushing and turning things on a schedule in Ferret: forces, impulses, torques and motors at chosen points of bodies and vessels; shafts that always turn or can jam; oars, winches, levers, conveyors; and wiring them to input, interactables, zones, events, AI and animations.
---

# Actuators and bindings

## When to use
An oar that pushes a boat, a mill shaft that turns forever, a winch that jams under load, a lever that starts a conveyor, a gust that kicks a flag, a rower whose animation says when the blade is in the water.

## The model
An actuator says where a force acts (a node, a point), what it is (`force`, `impulse`, `torque`, `motor`, `spin`, `blade`) and how it runs (a profile over time, a body's angle, another actuator's phase or a sensor), times a run-time `command`. Bindings set the command from input actions, interactables, zones and events; events and numbers come back to the game and to animations.

## Steps
1. Enable `actuators` (and `rotors` for blades and wheels).
2. Add actuators to `physics.actuators` or with `edit.physics.actuator.set`; a point off the centre of mass turns the body.
3. Add `physics.bindings` (or `edit.physics.binding.set`): `action` + `hold | press | toggle | axis`, `interactable`, `zone`, or `event` + `match` + `on | off | toggle | press | set`.
4. For animation: an `animate` binding writes `phase`, `command`, `power` ... to a graph parameter or fires a trigger; an `anim:notify` event binding lets the animation switch the force.
5. Commands: `actuator.command | on | off | fire | state`, `edit.physics.actuator.*`, `edit.physics.binding.*`.

## Check afterwards
`actuator.state { name }` shows force, power, work and phase; the body's momentum changes by F·dt; `cap.bindings()` shows binding errors.

## What usually goes wrong
- Nothing moves: `command` is 0 (the default of a bound actuator in the examples), the actuator is off, or the node has no body.
- A binding does nothing: no `input` service, a wrong action name, or an event `match` that the payload does not satisfy.
- A kinematic body gets a force: only `spin` acts on a kinematic body.
- A second force on a vessel needs a `vesselTarget`; the actuator names the target by `node`.

## Files

- `reference/actuators.md` — Forces, impulses, torques and motors at chosen points of chosen bodies, on a schedule (constant, for a time, periodic, by a curve) over time, a body's angle, another actuator's phase or a sensor; by hand, by data and over MCP.
- `reference/rotors.md` — N blades, paddles or buckets around an axis that turn the local wind or water, or the weight of water, into a torque on a body or a drivetrain shaft; and the blade actuator, a plate swept through a medium.
- `reference/api-physics-actuators.md` — every export of `@ferret/physics-actuators` with signature and doc comment
- `reference/api-physics-rotor.md` — every export of `@ferret/physics-rotor` with signature and doc comment
- `reference/commands.md` — 30 commands of these packages with their arguments