combat/actions

Interfaces

FleetAttackStance

Defined in: packages/sage/src/combat/actions/index.ts:141

Public attack stance translated from the generated combat vocabulary.

Example

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

Properties

ammoUsage

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

Defined in: packages/sage/src/combat/actions/index.ts:142

---

FleetLootCargoRequest

Defined in: packages/sage/src/combat/actions/index.ts:177

One requested cargo quantity from one Loot item.

Example

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

Properties

cargoId

readonly cargoId: number;

Defined in: packages/sage/src/combat/actions/index.ts:178

quantityRaw

readonly quantityRaw: bigint;

Defined in: packages/sage/src/combat/actions/index.ts:179

---

FleetLootTargetRequest

Defined in: packages/sage/src/combat/actions/index.ts:191

One indexed Loot item and its requested cargo quantities.

Example

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

Properties

cargo

readonly cargo: readonly FleetLootCargoRequest[];

Defined in: packages/sage/src/combat/actions/index.ts:193

itemIndex

readonly itemIndex: number;

Defined in: packages/sage/src/combat/actions/index.ts:192

---

PlanFleetApplyCombatStimulantOptions

Defined in: packages/sage/src/combat/actions/index.ts:131

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

Example

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

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/combat/actions/index.ts:132

---

PlanFleetAttackFleetOptions

Defined in: packages/sage/src/combat/actions/index.ts:153

Address-only signer inputs for one Fleet attack.

Example

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

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/combat/actions/index.ts:154

loot

readonly loot: Address;

Defined in: packages/sage/src/combat/actions/index.ts:155

---

PlanFleetAttackStarbaseOptions

Defined in: packages/sage/src/combat/actions/index.ts:166

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

Example

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

Properties

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/combat/actions/index.ts:167

loot

readonly loot: Address;

Defined in: packages/sage/src/combat/actions/index.ts:168

---

PlanFleetRetrieveLootOptions

Defined in: packages/sage/src/combat/actions/index.ts:216

Address-only authorization for one Loot retrieval.

Example

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

Properties

atUnixSeconds

readonly atUnixSeconds: bigint;

Defined in: packages/sage/src/combat/actions/index.ts:218

Explicit current Unix timestamp used only to evaluate Loot exclusivity.

authorization

readonly authorization: PlanAuthorization;

Defined in: packages/sage/src/combat/actions/index.ts:219

Type Aliases

FleetLootSelection

type FleetLootSelection = readonly FleetLootTargetRequest[];

Defined in: packages/sage/src/combat/actions/index.ts:204

Finite ordered cargo selection for one Loot retrieval.

Example

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

Functions

planFleetApplyCombatStimulant()

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

Defined in: packages/sage/src/combat/actions/index.ts:665

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
fleet	FleetSnapshot
stimulant	CombatStimulantDefinition
input	PlanFleetApplyCombatStimulantOptions

Returns

Promise<Plan>

Example

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());

---

planFleetAttackFleet()

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

Defined in: packages/sage/src/combat/actions/index.ts:1052

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
attacker	FleetSnapshot
defender	FleetSnapshot
inputStance	FleetAttackStance
inputOptions	PlanFleetAttackFleetOptions

Returns

Promise<Plan>

Example

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 },
);

---

planFleetAttackStarbase()

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

Defined in: packages/sage/src/combat/actions/index.ts:1317

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
attacker	FleetSnapshot
target	StarSystemSnapshot
inputStance	FleetAttackStance
inputOptions	PlanFleetAttackStarbaseOptions

Returns

Promise<Plan>

Example

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 },
);

---

planFleetRetrieveLoot()

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

Defined in: packages/sage/src/combat/actions/index.ts:1955

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
fleet	FleetSnapshot
loot	LootSnapshot
inputWant	FleetLootSelection
inputOptions	PlanFleetRetrieveLootOptions

Returns

Promise<Plan>

Example

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

PlanAuthorization

Re-exports PlanAuthorization