---
name: ferret-physics-vehicles
description: Use to build boats, submarines, balloons and similar in Ferret: a Vessel is one body with a hull that displaces water, ballast tanks, flooding compartments, gas envelopes, thrusters, rudders, foils and sails; stability (GM), breaches and doors.
---

# Vehicles: ships, submarines, balloons

## When to use
Anything that floats, dives, flies on gas, or is pushed by a screw or a sail.

## The model
A `Vessel` (`VesselSpec`) is one body with parts: `hull` (cells), `tanks`, `compartments` (flood through `breach` and `doors`), `envelopes`, `thrusters`, surfaces (rudders, foils, sails). Draft = mass / (ρ × waterplane area). `stability()` gives the metacentric height `gm`: positive rights itself, negative rolls over.

## Steps
1. Size the hull so mass matches displacement; set `cog` low.
2. Add `hullDamping` and `angularDamping`, `addedMass` 0.1–1.
3. Submarines: `fill`/`blow` tanks; neutral fill = `(displacement − dry mass) / tank capacity`; `crushDepth`.
4. Drive by `vessel.thrust`, rudders, sails (`sailPolar`).
5. Commands: `vessel.add|info|state|fill|thrust|breach|blow|surface`.

## Check afterwards
Light and loaded drafts follow Archimedes; `gm` is positive; a breach floods the named compartment.

## What usually goes wrong
- Floats too high or low: mass and hull do not match.
- Rolls over: `gm` negative; lower `cog`, widen, empty part-filled tanks.
- Never settles: no damping.
- Passes through the shore: light kernel or `body: false`; use Havok.
- `vessel.breach` refused: unknown compartment name.

## Files

- `reference/vehicles.md` — A vessel is one body with parts: a hull that displaces water, ballast tanks, flooding compartments, gas envelopes, thrusters, rudders and sails. How to build one, drive it and read its stability.
- `reference/api-physics-vehicles.md` — every export of `@ferret/physics-vehicles` with signature and doc comment
- `reference/commands.md` — 7 commands of these packages with their arguments
- `recipes/water-and-boats.md` — Six recipes: tanks that equalise, a U-tube of two liquids, a wave that slows on a beach, a boat that sinks deeper with cargo, a wing that stalls, a ball that curves.