combat/actions

Interfaces

FleetAttackStance

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

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:153

---

FleetLootCargoRequest

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

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:189

quantityRaw

readonly quantityRaw: bigint;

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

---

FleetLootTargetRequest

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

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:204

itemIndex

readonly itemIndex: number;

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

---

PlanFleetApplyCombatStimulantOptions

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

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:143

---

PlanFleetAttackFleetOptions

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

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:165

loot

readonly loot: Address;

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

---

PlanFleetAttackStarbaseOptions

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

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:178

loot

readonly loot: Address;

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

---

PlanFleetRetrieveLootOptions

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

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:229

Explicit current Unix timestamp used only to evaluate Loot exclusivity.

authorization

readonly authorization: PlanAuthorization;

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

Type Aliases

FleetLootSelection

type FleetLootSelection = readonly FleetLootTargetRequest[];

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

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:615

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:1070

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:1315

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.

Requires Disabled rent: the Game’s rent catalog and the target System’s Starbase-level rent history must not exist, and both stay guarded absent until signing.

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:1870

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

The planner validates the owned idle Fleet, its normalized crew and usable ability power at atUnixSeconds, Loot identity, destroyer exclusivity and reward locks against the authorization Profile, and every requested known quantity. Retrieval spends the Fleet’s whole ability power pool. 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