Documentation: 0.5.0 (source: v0.5.0).
# Fleets

> Reading fleets, understanding fleet state, and knowing where a fleet actually is.

Markdown source of https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/fleets/ — see https://docs-v0-5-0.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

A fleet is a group of ships that move and act together. Ships do not travel
individually, so the fleet is the unit almost everything else attaches to:
cargo, mining, scanning, combat.

:::game[Ships operate as fleets]
Ships take part in SAGE as fleets. A fleet can contain many ships, but even one
ship becomes a one-ship fleet before it starts travelling or working. The
fleet moves, carries supplies, mines, scans, and fights as one group. Which
ships you put together determines how much the fleet can carry and how well it
can perform those jobs.
:::

## Listing a character's fleets

```ts
const character = await sage.characters.forProfile(profileAddress);
const fleets = await character.fleets.all();
```

> **Runnable example — Read a fleet.** Walk from a profile to its character, then to the fleets that character owns. Run it in the browser at https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/fleets/.

## Fleet state is a union, not a status string

This is the single most important thing to understand about fleets. A fleet's
state is a **discriminated union**, and what data is available depends on which
variant you have:

```ts
if (fleet.state.kind === 'docked') {
  const system = await getStarSystem(ctx, fleet.state.system.address);
}
```

The variants are `idle`, `docked`, `mining`, `warp`, `subwarp`, `respawn`, and
`claimStakeTransfer`.

The reason this matters: **a fleet's location is not a field.** There is no
`fleet.system`. Where a fleet is depends on what it is doing — a docked fleet is
at a starbase, a warping fleet is between two points with an arrival time, a
mining fleet is at a resource. Flattening that into one field would mean
inventing a value for cases where it does not exist.

:::game[Warp trades fuel for time]
Fleets can travel by warp or subwarp. Warp gets a fleet to its destination
much faster, but it costs more fuel and the fleet can only warp so far before
it must wait. Subwarp is the slower, cheaper option when time matters less than
fuel. The ships in the fleet decide its actual speed, fuel use, warp range, and
waiting time.
:::

So the pattern is always: narrow on `kind` first, then read what that variant
offers. TypeScript enforces this — reaching for `state.system` without narrowing
is a compile error, not a runtime surprise.

## What hangs off a fleet

```ts
const inventory = await fleet.inventory.get();
const mining = await fleet.mining.get(); // undefined when not mining
```

Note that `mining.get()` returns `undefined` rather than throwing when the fleet
is not mining. That is a legitimate state, not an error.

> **Runnable example — Read a fleet's cargo.** Follow a relationship one step further: from a fleet to what it is carrying. Run it in the browser at https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/fleets/.

## Gotchas

**Fleet names are strings, already trimmed.** On chain they are fixed-width byte
arrays padded with zeros. The SDK decodes and trims them, so `fleet.name` is
`"Dread Kraken"`, not a padded buffer.

**An empty fleet list is a valid answer.** A character with no fleets returns
`[]`. Do not treat it as an error.

**NPC-owned fleets decode with `faction: 0`.** Their identity comes from the
owning profile, not the faction field.

**Movement timings are derived, not stored.** Arrival times come from the
fleet's state plus the Game account's movement rules. Where the SDK cannot
verify the arithmetic against the current program version, it declines to
guess rather than reporting a number that might be wrong.

## Reference

- [`fleets`](/reference/fleets/) — every export in this entry
- [`cargo`](/guides/cargo/) — what a fleet is carrying
- [`world`](/guides/world/) — where a fleet's state points
- [Warp & subwarp](/guides/moving-a-fleet/) — plan and execute an explicit move