combat/actions

Interfaces

FleetAttackStance

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

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

---

FleetLootCargoRequest

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

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

quantityRaw

readonly quantityRaw: bigint;

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

---

FleetLootTargetRequest

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

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

itemIndex

readonly itemIndex: number;

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

---

PlanFleetApplyCombatStimulantOptions

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

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

---

PlanFleetAttackFleetOptions

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

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

loot

readonly loot: Address;

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

---

PlanFleetAttackStarbaseOptions

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

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

loot

readonly loot: Address;

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

---

PlanFleetRetrieveLootOptions

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

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

Explicit current Unix timestamp used only to evaluate Loot exclusivity.

authorization

readonly authorization: PlanAuthorization;

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

Type Aliases

FleetLootSelection

type FleetLootSelection = readonly FleetLootTargetRequest[];

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

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

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, a crewed Fleet that is neither destroyed nor respawning, and fresh whole-account Fleet state. Only stimulants whose effects use the refresh stack rule are planned, as the game applies no other rule yet. Permission, 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:1149

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

At chain time the attacker must be Idle or subwarping (a finished warp counts as Idle), carry its required crew, and have finished reloading AP. 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:1404

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

At chain time the attacker must be Idle or subwarping (a finished warp counts as Idle), carry its required crew, and have finished reloading AP. 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.

From the RegionTracker, the attack reads only the target System’s Region, so the Plan guards only that Region’s owner, safety status and risk zone and a Starbase capture or upgrade in another Region leaves it valid. If the System’s stored Region disagrees with the Region map, the whole tracker stays guarded.

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

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