Warp & subwarp

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. The rules behind that flow are laid out in How Atlas Kit changes the game; this guide walks it end to end.

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

The embedded playground remains read-only. 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.

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.

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 means submission could not be confirmed: 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 or arrived-but-unsettled fleet to a coordinate.
• planFleetWarpToCoordinate warps an idle or arrived-but-unsettled fleet to a coordinate.
• planFleetWarpLane warps an idle or arrived-but-unsettled fleet to an explicit connected destination system.
• planFleetDock docks an idle fleet at its current system or an arrived Fleet at its movement destination.

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.

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.

Docking and movement planners accept stored warp and subwarp states and let the program perform its normal refresh-to-idle step. They use the stored movement destination without guessing from local time; a genuinely in-transit action is still rejected by chain simulation.

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 are not included until their formulas have been verified.

combinePlans places the combined steps in one transaction; it inserts neither elapsed time nor a confirmation boundary. It rejects conflicting subwarp, coordinate warp, and lane warp starts for the same Fleet. If the Plans do not contain enough information to identify a conflict, the SDK leaves their compatibility unknown instead of assuming they are safe to combine.

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

Reference

• fleets/actions — every movement planner
• planning — Plan inspection, assembly, and execution
• Plan sequences — non-atomic multi-transaction journeys
• Fleets — reading fleet state before and after a move