---
name: ferret-physics-rotors
description: Use for wind turbines and windmill sails, propellers, water wheels (undershot with paddles, overshot with buckets) and oars in Ferret: blades, paddles and buckets that turn wind or water into torque on a body or a drivetrain shaft, and the blade actuator.
---

# Rotors and blades

## When to use
A windmill on a hill, a wheel in a mill race, an overshot wheel under a flume, a propeller on a boat, an oar that sweeps through the water.

## The model
A rotor is N elements around an axis summed into one torque (and a force) per step, with no body per element. It reads the medium at the rotor (density and flow, which include the flow field), so weather and currents drive it. A rotor turns a drivetrain `shaft` (a torque source: load, gears and housing reaction follow) and/or pushes a `node` body (thrust, weight, reaction).

## Steps
1. Enable `media` and `rotors`; add a `FlowService` for wind and currents; give the capability the drivetrain with `useDrivetrain` for shaft rotors.
2. Add the rotor to the level's `physics.rotors` or with `edit.physics.rotor.set { name, node|shaft, axis, radius, elements }`.
3. Pick the element: `blade` (pitch, polar), `paddle` (area, depth), `bucket` (capacity, fill, empty).
4. Read `rotor.state`; turn the blades with `rotor.pitch`, open the sluice with `rotor.command`.
5. An oar is an actuator of kind `blade` with a `stroke`.

## Check afterwards
Power is under the Betz limit (`cp`); a wheel never turns faster than the water that drives it; an overshot wheel's torque is the weight of its full buckets times the lever.

## What usually goes wrong
- Nothing turns: the rotor has no shaft or node, `media` is off, or the point is out of the water (paddles only count when the medium there is dense).
- A windmill stalls near rest: a fixed-pitch rotor has a dip in its torque at low speed; give it a push or a smaller pitch, or less bearing friction.
- A kind `blade` actuator is refused: `@ferret/physics-rotor` was not loaded.
- A body rotor spins its body the wrong way: `axis` is in the body's frame, and a positive turn is right-handed about it.

## Files

- `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/flow.md` — Wind, fronts, vortices, jets, shelters and channels that add up to one field of moving air and water, a pure function of position and time that bodies, vessels, the character and the render can all read.
- `reference/api-physics-rotor.md` — every export of `@ferret/physics-rotor` with signature and doc comment
- `reference/api-flow.md` — every export of `@ferret/flow` with signature and doc comment
- `reference/api-physics-media.md` — every export of `@ferret/physics-media` with signature and doc comment
- `reference/commands.md` — 22 commands of these packages with their arguments