# combat/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/combat/actions/ — see https://develop.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

## Interfaces

<a id="fleetattackstance"></a>

### FleetAttackStance

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

Public attack stance translated from the generated combat vocabulary.

#### Example

```ts
const stance: FleetAttackStance = { ammoUsage: 'light' };
```

#### Properties

<a id="ammousage"></a>

##### ammoUsage

```ts
readonly ammoUsage: "none" | "light" | "heavy";
```

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

***

<a id="fleetlootcargorequest"></a>

### FleetLootCargoRequest

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

One requested cargo quantity from one Loot item.

#### Example

```ts
const cargo: FleetLootCargoRequest = { cargoId: 1, quantityRaw: 5n };
```

#### Properties

<a id="cargoid"></a>

##### cargoId

```ts
readonly cargoId: number;
```

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

<a id="quantityraw"></a>

##### quantityRaw

```ts
readonly quantityRaw: bigint;
```

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

***

<a id="fleetloottargetrequest"></a>

### FleetLootTargetRequest

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

One indexed Loot item and its requested cargo quantities.

#### Example

```ts
const target: FleetLootTargetRequest = {
  itemIndex: 0,
  cargo: [{ cargoId: 1, quantityRaw: 5n }],
};
```

#### Properties

<a id="cargo"></a>

##### cargo

```ts
readonly cargo: readonly FleetLootCargoRequest[];
```

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

<a id="itemindex"></a>

##### itemIndex

```ts
readonly itemIndex: number;
```

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

***

<a id="planfleetapplycombatstimulantoptions"></a>

### PlanFleetApplyCombatStimulantOptions

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

Inputs for applying one catalogued combat stimulant to an owned Fleet.

#### Example

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

#### Properties

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

##### authorization

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

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

***

<a id="planfleetattackfleetoptions"></a>

### PlanFleetAttackFleetOptions

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

Address-only signer inputs for one Fleet attack.

#### Example

```ts
declare const authorization: PlanAuthorization;
declare const loot: Address;
const options: PlanFleetAttackFleetOptions = { authorization, loot };
```

#### Properties

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

##### authorization

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

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

<a id="loot"></a>

##### loot

```ts
readonly loot: Address;
```

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

***

<a id="planfleetattackstarbaseoptions"></a>

### PlanFleetAttackStarbaseOptions

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

Address-only signer inputs for one Fleet attack against a shared Starbase.

#### Example

```ts
declare const authorization: PlanAuthorization;
declare const loot: Address;
const options: PlanFleetAttackStarbaseOptions = { authorization, loot };
```

#### Properties

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

##### authorization

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

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

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

##### loot

```ts
readonly loot: Address;
```

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

***

<a id="planfleetretrievelootoptions"></a>

### PlanFleetRetrieveLootOptions

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

Address-only authorization for one Loot retrieval.

#### Example

```ts
declare const authorization: PlanAuthorization;
const options: PlanFleetRetrieveLootOptions = {
  atUnixSeconds: 1_700_000_000n,
  authorization,
};
```

#### Properties

<a id="atunixseconds"></a>

##### atUnixSeconds

```ts
readonly atUnixSeconds: bigint;
```

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

Explicit current Unix timestamp used only to evaluate Loot exclusivity.

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

##### authorization

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

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

## Type Aliases

<a id="fleetlootselection"></a>

### FleetLootSelection

```ts
type FleetLootSelection = readonly FleetLootTargetRequest[];
```

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

Finite ordered cargo selection for one Loot retrieval.

#### Example

```ts
const want: FleetLootSelection = [
  { itemIndex: 0, cargo: [{ cargoId: 1, quantityRaw: 5n }] },
];
```

## Functions

<a id="planfleetapplycombatstimulant"></a>

### planFleetApplyCombatStimulant()

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

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

Plans application of one configured combat stimulant without predicting its effects.

The planner validates Fleet ownership and Game membership, current catalog
membership, known cargo balance, crewed non-destroyed state, and fresh
whole-account Fleet state. Permission, stacking, charge application, and
combat arithmetic remain chain-authoritative.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `FleetSnapshot` |
| `stimulant` | `CombatStimulantDefinition` |
| `input` | [`PlanFleetApplyCombatStimulantOptions`](/reference/combat/actions/#planfleetapplycombatstimulantoptions) |

#### Returns

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

#### Example

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

***

<a id="planfleetattackfleet"></a>

### planFleetAttackFleet()

```ts
function planFleetAttackFleet(
   ctx, 
   attacker, 
   defender, 
   inputStance, 
inputOptions): Promise<Plan>;
```

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

Plans one singleton Fleet-on-Fleet attack without predicting its outcome.

Range, randomness, recent slot hashes, final combat arithmetic, and chain
races remain authoritative. This Plan cannot be combined with another
gameplay instruction because the generated program contract requires a
singleton transaction.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `attacker` | `FleetSnapshot` |
| `defender` | `FleetSnapshot` |
| `inputStance` | [`FleetAttackStance`](/reference/combat/actions/#fleetattackstance) |
| `inputOptions` | [`PlanFleetAttackFleetOptions`](/reference/combat/actions/#planfleetattackfleetoptions) |

#### Returns

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

#### Example

```ts
declare const ctx: SageContext;
declare const attacker: FleetSnapshot;
declare const defender: FleetSnapshot;
declare const authorization: PlanAuthorization;
declare const loot: Address;
const plan = await planFleetAttackFleet(
  ctx,
  attacker,
  defender,
  { ammoUsage: 'light' },
  { authorization, loot },
);
```

***

<a id="planfleetattackstarbase"></a>

### planFleetAttackStarbase()

```ts
function planFleetAttackStarbase(
   ctx, 
   attacker, 
   target, 
   inputStance, 
inputOptions): Promise<Plan>;
```

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

Plans one singleton Fleet-on-Starbase attack without predicting its outcome.

The planner validates the owned attacking Fleet, canonical target System and
nested shared Starbase, configured faction ownership mode, reward
configuration, and the optional dynamic-NPC capture economy. Range,
capture-cost debit outcome, randomness, damage, rewards, and final
admissibility remain chain-authoritative.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `attacker` | `FleetSnapshot` |
| `target` | `StarSystemSnapshot` |
| `inputStance` | [`FleetAttackStance`](/reference/combat/actions/#fleetattackstance) |
| `inputOptions` | [`PlanFleetAttackStarbaseOptions`](/reference/combat/actions/#planfleetattackstarbaseoptions) |

#### Returns

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

#### Example

```ts
declare const ctx: SageContext;
declare const attacker: FleetSnapshot;
declare const target: StarSystemSnapshot;
declare const authorization: PlanAuthorization;
declare const loot: Address;
const plan = await planFleetAttackStarbase(
  ctx,
  attacker,
  target,
  { ammoUsage: 'light' },
  { authorization, loot },
);
```

***

<a id="planfleetretrieveloot"></a>

### planFleetRetrieveLoot()

```ts
function planFleetRetrieveLoot(
   ctx, 
   fleet, 
   loot, 
   inputWant, 
inputOptions): Promise<Plan>;
```

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

Plans one transaction-exclusive retrieval from a loaded Loot snapshot.

The planner validates the owned idle Fleet, Loot identity, destroyer
exclusivity, and every requested known quantity. Range, recent-slot inputs,
destination capacity, intervening races, and final acquired quantities
remain chain-authoritative.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `FleetSnapshot` |
| `loot` | `LootSnapshot` |
| `inputWant` | [`FleetLootSelection`](/reference/combat/actions/#fleetlootselection) |
| `inputOptions` | [`PlanFleetRetrieveLootOptions`](/reference/combat/actions/#planfleetretrievelootoptions) |

#### Returns

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

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const loot: LootSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetRetrieveLoot(
  ctx,
  fleet,
  loot,
  [{ itemIndex: 0, cargo: [{ cargoId: 1, quantityRaw: 5n }] }],
  { atUnixSeconds: 1_700_000_000n, authorization },
);
console.log(plan.describe());
```

## References

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

### PlanAuthorization

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