# fleets/actions
Documentation: next (source: develop).

Install the preview: `pnpm add @aephia/atlas-kit@next`. These docs follow develop and may include changes not yet published to npm.

Markdown source of https://develop.atlas-kit-docs.pages.dev/reference/fleets/actions/ — see https://develop.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

## Interfaces

<a id="planfleetcoordinatemovementoptions"></a>

### PlanFleetCoordinateMovementOptions

Defined in: [packages/sage/src/fleets/actions/index.ts:121](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L121)

Inputs for planning one explicit coordinate-destination Fleet movement.

#### Example

```ts
declare const authorization: PlanAuthorization;
const options: PlanFleetCoordinateMovementOptions = {
  authorization,
  destination: { x: 12, y: -7 },
};
```

#### Properties

<a id="authorization"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:122](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L122)

<a id="destination"></a>

##### destination

```ts
readonly destination: WorldCoordinates;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:123](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L123)

***

<a id="planfleetdockoptions"></a>

### PlanFleetDockOptions

Defined in: [packages/sage/src/fleets/actions/index.ts:106](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L106)

Inputs for planning one idle-to-docked Fleet transition.

#### Example

```ts
declare const authorization: PlanAuthorization;
const options: PlanFleetDockOptions = { authorization };
```

#### Properties

<a id="authorization-1"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:107](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L107)

***

<a id="planfleetsettlearrivaloptions"></a>

### PlanFleetSettleArrivalOptions

Defined in: [packages/sage/src/fleets/actions/index.ts:154](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L154)

Address-only input for settling one Fleet movement arrival.

The funder is the sole required signer. Reusing the later assembly fee payer
is convenient, but the planner does not require the two addresses to match.

#### Example

```ts
declare const funder: Address;
const options: PlanFleetSettleArrivalOptions = { funder };
```

#### Properties

<a id="funder"></a>

##### funder

```ts
readonly funder: Address;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:155](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L155)

***

<a id="planfleetstopsubwarpoptions"></a>

### PlanFleetStopSubwarpOptions

Defined in: [packages/sage/src/fleets/actions/index.ts:166](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L166)

Inputs for stopping one Fleet subwarp early.

#### Example

```ts
declare const authorization: PlanAuthorization;
const options: PlanFleetStopSubwarpOptions = { authorization };
```

#### Properties

<a id="authorization-2"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:167](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L167)

***

<a id="planfleetundockoptions"></a>

### PlanFleetUndockOptions

Defined in: [packages/sage/src/fleets/actions/index.ts:94](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L94)

Inputs for planning one docked-to-idle Fleet transition.

#### Example

```ts
declare const authorization: PlanAuthorization;
const options: PlanFleetUndockOptions = { authorization };
```

#### Properties

<a id="authorization-3"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:95](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L95)

***

<a id="planfleetwarplaneoptions"></a>

### PlanFleetWarpLaneOptions

Defined in: [packages/sage/src/fleets/actions/index.ts:138](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L138)

Inputs for planning one explicit connected-system Fleet warp.

#### Example

```ts
declare const authorization: PlanAuthorization;
declare const destinationSystem: Address;
const options: PlanFleetWarpLaneOptions = {
  authorization,
  destinationSystem,
};
```

#### Properties

<a id="authorization-4"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:139](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L139)

<a id="destinationsystem"></a>

##### destinationSystem

```ts
readonly destinationSystem: Address;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:140](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L140)

## Functions

<a id="planfleetdock"></a>

### planFleetDock()

```ts
function planFleetDock(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:1559](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L1559)

Plans one explicit Fleet dock without signing, simulation, or write RPC.

The planner accepts a loaded idle or refreshable movement Fleet snapshot,
resolves the only canonical Character, Star System at its action coordinate,
and Starbase Player internally, and returns one inspectable idle-to-docked
Plan.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | [`FleetSnapshot`](/reference/fleets/#fleetsnapshot) |
| `options` | [`PlanFleetDockOptions`](/reference/fleets/actions/#planfleetdockoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetDock(ctx, fleet, { authorization });
console.log(plan.describe());
```

***

<a id="planfleetsettlearrival"></a>

### planFleetSettleArrival()

```ts
function planFleetSettleArrival(
   ctx, 
   fleet, 
input): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:1322](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L1322)

Plans settlement of one Fleet warp or subwarp arrival.

Settlement is distinct from stopping subwarp early: the program completes an
elapsed movement, while an in-transit call is a measured safe no-op. Subwarp
settlement charges the fuel recorded when movement started; warp fuel was
already charged up front. Settlement does not clear the independent warp
cooldown, so an arrived Fleet can be idle but still unable to warp again.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | [`FleetSnapshot`](/reference/fleets/#fleetsnapshot) |
| `input` | [`PlanFleetSettleArrivalOptions`](/reference/fleets/actions/#planfleetsettlearrivaloptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const funder: Address;
const plan = await planFleetSettleArrival(ctx, fleet, { funder });
console.log(plan.describe());
```

***

<a id="planfleetstopsubwarp"></a>

### planFleetStopSubwarp()

```ts
function planFleetStopSubwarp(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:1371](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L1371)

Plans an early Fleet subwarp stop without signing, simulation, or write RPC.

This operation stops an in-progress subwarp before arrival. Use
[planFleetSettleArrival](/reference/fleets/actions/#planfleetsettlearrival) for a trip already known to have completed;
callers should not deliberately stop a completed trip. An idle Fleet is
still accepted so the program's benign no-op handles the normal race where
subwarp completes between planning and execution.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | [`FleetSnapshot`](/reference/fleets/#fleetsnapshot) |
| `options` | [`PlanFleetStopSubwarpOptions`](/reference/fleets/actions/#planfleetstopsubwarpoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetStopSubwarp(ctx, fleet, { authorization });
console.log(plan.describe());
```

***

<a id="planfleetsubwarp"></a>

### planFleetSubwarp()

```ts
function planFleetSubwarp(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:1276](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L1276)

Plans one explicit Fleet subwarp to a coordinate without movement estimates.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | [`FleetSnapshot`](/reference/fleets/#fleetsnapshot) |
| `options` | [`PlanFleetCoordinateMovementOptions`](/reference/fleets/actions/#planfleetcoordinatemovementoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetSubwarp(ctx, fleet, {
  authorization,
  destination: { x: 12, y: -7 },
});
```

***

<a id="planfleetundock"></a>

### planFleetUndock()

```ts
function planFleetUndock(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:1431](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L1431)

Plans one explicit Fleet undock without signing, simulation, or write RPC.

The planner accepts a loaded Fleet snapshot, resolves its canonical Character,
docked Star System, and Starbase Player internally, and returns one inspectable
docked-to-idle Plan.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | [`FleetSnapshot`](/reference/fleets/#fleetsnapshot) |
| `options` | [`PlanFleetUndockOptions`](/reference/fleets/actions/#planfleetundockoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetUndock(ctx, fleet, { authorization });
console.log(plan.describe());
```

***

<a id="planfleetwarplane"></a>

### planFleetWarpLane()

```ts
function planFleetWarpLane(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:1193](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L1193)

Plans one explicit connected-system Fleet warp without local economics estimates.

The planner resolves the source Star System from the Fleet's action coordinate,
proves connectivity from that System's decoded connections, and resolves all
generated instruction accounts internally.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | [`FleetSnapshot`](/reference/fleets/#fleetsnapshot) |
| `options` | [`PlanFleetWarpLaneOptions`](/reference/fleets/actions/#planfleetwarplaneoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const destinationSystem: Address;
declare const authorization: PlanAuthorization;
const plan = await planFleetWarpLane(ctx, fleet, {
  authorization,
  destinationSystem,
});
```

***

<a id="planfleetwarptocoordinate"></a>

### planFleetWarpToCoordinate()

```ts
function planFleetWarpToCoordinate(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:1297](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L1297)

Plans one explicit Fleet coordinate warp without movement estimates.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | [`FleetSnapshot`](/reference/fleets/#fleetsnapshot) |
| `options` | [`PlanFleetCoordinateMovementOptions`](/reference/fleets/actions/#planfleetcoordinatemovementoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetWarpToCoordinate(ctx, fleet, {
  authorization,
  destination: { x: 12, y: -7 },
});
```

## References

<a id="planauthorization"></a>

### PlanAuthorization

Re-exports [PlanAuthorization](/reference/cargo/actions/#planauthorization)