Moving a fleet

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

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

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 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.
• planFleetSettleArrival settles a warp or subwarp arrival with one explicit funder address.

Arrival settlement is not an early subwarp stop. It completes an elapsed move; an in-transit call is a safe program no-op. Subwarp fuel is charged during settlement, warp fuel was charged when warp started, and the independent warp cooldown is unchanged.

Each 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 separate confirmed transactions today. Future W4 Plan sequences will represent that multi-transaction journey after their API is reviewed; no sequence API ships yet.

Reference

• fleets/actions — every movement planner
• planning — Plan inspection, assembly, and execution
• Fleets — reading fleet state before and after a move