Fleets

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.

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

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

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:

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.

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

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.

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 — every export in this entry
• cargo — what a fleet is carrying
• world — where a fleet’s state points
• Moving a fleet — plan and execute an explicit move