Documentation: 0.5.0 (source: v0.5.0).
# Warp & subwarp

> Plan, inspect, sign, execute, and refresh one fleet move.

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

Moving a fleet starts with an explicit choice. You choose one movement
primitive, inspect the resulting Plan, let your wallet sign it, execute it once,
and then read the fleet again. No step silently chooses a route or movement mode
for you, and the available primitives are alternatives rather than one chained
journey.

This guide uses undocking because it is the smallest complete movement: the
fleet begins docked and finishes idle at the same system. Subwarp, coordinate
warp, lane warp, and docking follow the same Plan flow with their own explicit
destinations.

## Read before you move

> **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/moving-a-fleet/.

The embedded [playground remains read-only](/start-here/first-read/#try-it-here)
under D039. It is useful for exploring live state before planning, but it will
not request a wallet or run this signing flow.

## Plan and inspect

Planning accepts game intent plus the Profile authorization your wallet will
satisfy later. It does not open the wallet or change the game. Here
`authoritySigner` is the Kit signer returned by your wallet integration, and
`keyIndex` is its matching Profile key slot; the example uses the first slot.

```ts
import type { PlanAuthorization } from '@aephia/atlas-kit/fleets/actions';
import { planFleetUndock } from '@aephia/atlas-kit/fleets/actions';

const authorization = {
  profile: fleet.ownerProfile.address,
  authority: authoritySigner.address,
  keyIndex: 0,
} satisfies PlanAuthorization;

const plan = await planFleetUndock(ctx, fleet, { authorization });
console.log(plan.summary);
console.table(plan.describe());
```

`describe()` returns stable game-language steps. Show those lines to the person
signing so they can decide whether the move matches their intent. If fleet state
has changed since it was read, create a new Plan instead of trying to repair the
old one.

## Sign and execute once

The signer comes from your wallet integration. The SDK receives only the Kit
signer interface for this call; it does not take custody of keys. Here the same
signer pays the fee and satisfies the selected Profile authorization.

```ts
import type { PlanAuthorization } from '@aephia/atlas-kit/fleets/actions';
import { planFleetUndock } from '@aephia/atlas-kit/fleets/actions';
import { executePlan } from '@aephia/atlas-kit/planning';

const authorization = {
  profile: fleet.ownerProfile.address,
  authority: authoritySigner.address,
  keyIndex: 0,
} satisfies PlanAuthorization;

const plan = await planFleetUndock(ctx, fleet, { authorization });
const result = await executePlan(ctx, plan, { feePayer: authoritySigner });

if (result.status === 'unknown') {
  console.log('Check wallet history before deciding what to do next.');
  return;
}

const refreshedFleet = await sage.fleets.get(fleet.address);
console.log(result.signature, refreshedFleet.state);
```

Execution checks that the supplied signer matches the Plan, verifies that the
Plan is still fresh, sends exactly once, and waits for a terminal result. A
confirmed result makes the next ordinary Fleet read fresh. An `unknown` result
is deliberately not called a failure: do not retry until wallet and chain
history prove whether the move happened.

## Other movement primitives

Choose the primitive yourself rather than asking the SDK to infer a route:

- `planFleetSubwarp` moves an idle fleet to a coordinate.
- `planFleetWarpToCoordinate` warps an idle fleet to a coordinate.
- `planFleetWarpLane` uses an explicit connected destination system.
- `planFleetDock` docks an idle fleet at its current system.

:::note[Warp lanes are the third mode of travel]
Subwarp and coordinate warp move within reach of a coordinate; a warp lane
jumps system to system, and only where the starmap says the two connect. A
lane also works only when both ends are held by the same faction, and it
charges an ATLAS toll. The lane network, its tolls, and how to read both are
covered in [the Starmap guide](/guides/world/#warp-lanes).
:::

## Arriving

A fleet that reaches its destination keeps reporting the move it was on.
Nothing rewrites that on a timer, so a fleet that arrived weeks ago still reads
as warping until something acts on it.

The game settles it for you. Docking, starting another move, and starting
mining each complete an elapsed arrival as their first step, inside the same
transaction. Crossing systems is undock, move, dock - the arrival settles
itself when you dock, and you pay for no extra transaction.

Undocking is not on that list. It refuses any fleet that is not already
docked, so it never reaches an arrival to settle.

`planFleetSettleArrival` does that settling on its own, with one explicit
funder address. Reach for it when you want the fleet to read as arrived
without taking another action, or to finalise subwarp fuel by itself. It is
not an early subwarp stop: it completes an elapsed move, and calling it
mid-flight is a safe no-op. Subwarp fuel is charged during settlement, warp
fuel was charged when warp started, and the independent warp cooldown is
unchanged. To end a subwarp before it completes, use `planFleetStopSubwarp`.

:::caution[The planners are currently stricter than the game]
Today the docking and movement planners require a fleet that already reports
as idle, so an arrived fleet must be settled before you can plan its next
action - even though the game would have settled it for free. This is an SDK
limitation, not a game rule, and it is tracked in
[issue 358](https://github.com/Aephia/atlas-kit/issues/358).
:::

Each planner produces the same inspectable Plan shape and uses the same
execution call.
The planner validates facts it can prove from current game state; fuel, timing,
range, and cost estimates remain outside W1 until they have verified formulas.

`combinePlans` places the combined steps in one transaction; it inserts neither
elapsed time nor a confirmation boundary. Its finite reviewed same-Fleet
movement-start conflict covers exactly subwarp, coordinate warp, and lane warp.
The validator rejects only conflicts expressed by semantic facts; absent
semantic facts remain unknown rather than proving the actions compatible.

For a journey that must move, wait/confirm, then move again, use the shipped
[`PlanSequence` coordinator](/guides/plan-sequences/). It preserves separate
confirmed transactions, lazy capability readiness, caller-owned checkpoints,
and fresh authorization for every reached Plan.

## Reference

- [`fleets/actions`](/reference/fleets/actions/) — every movement planner
- [`planning`](/reference/planning/) — Plan inspection, assembly, and execution
- [Plan sequences](/guides/plan-sequences/) — non-atomic multi-transaction journeys
- [Fleets](/guides/fleets/) — reading fleet state before and after a move