combat

Interfaces

CombatConfigurationSnapshot

Defined in: packages/sage/src/combat/index.ts:129

Immutable Game combat configuration and stimulant catalog.

Example

declare const configuration: CombatConfigurationSnapshot;
console.log(configuration.globalCeasefire, configuration.maxFleetSize);

Extends

• Omit<GameCombatConfigurationData, "stimulantDefinitions">

Properties

address

readonly address: Address;

Defined in: packages/sage/src/combat/index.ts:134

cargoRespawnTimeSeconds

readonly cargoRespawnTimeSeconds: bigint;

Defined in: packages/sage/src/internal/c4/game.ts:243

Inherited from

GameCombatConfigurationData.cargoRespawnTimeSeconds

crewRespawnTimeSeconds

readonly crewRespawnTimeSeconds: bigint;

Defined in: packages/sage/src/internal/c4/game.ts:242

Inherited from

GameCombatConfigurationData.crewRespawnTimeSeconds

globalCeasefire

readonly globalCeasefire: boolean;

Defined in: packages/sage/src/internal/c4/game.ts:237

Inherited from

GameCombatConfigurationData.globalCeasefire

interactionRange

readonly interactionRange: GameCombatFixedValueData;

Defined in: packages/sage/src/internal/c4/game.ts:238

Inherited from

GameCombatConfigurationData.interactionRange

kind

readonly kind: "combatConfiguration";

Defined in: packages/sage/src/combat/index.ts:133

lootExclusivityTimeSeconds

readonly lootExclusivityTimeSeconds: bigint;

Defined in: packages/sage/src/internal/c4/game.ts:239

Inherited from

GameCombatConfigurationData.lootExclusivityTimeSeconds

maxFleetSize

readonly maxFleetSize: number;

Defined in: packages/sage/src/internal/c4/game.ts:245

Inherited from

GameCombatConfigurationData.maxFleetSize

maxLootRate

readonly maxLootRate: GameCombatFixedValueData;

Defined in: packages/sage/src/internal/c4/game.ts:240

Inherited from

GameCombatConfigurationData.maxLootRate

rawShipsRespawnTimeSeconds

readonly rawShipsRespawnTimeSeconds: bigint;

Defined in: packages/sage/src/internal/c4/game.ts:244

Inherited from

GameCombatConfigurationData.rawShipsRespawnTimeSeconds

starbaseUpgradeProgressContinuation

readonly starbaseUpgradeProgressContinuation: GameCombatFixedValueData;

Defined in: packages/sage/src/internal/c4/game.ts:241

Inherited from

GameCombatConfigurationData.starbaseUpgradeProgressContinuation

stimulantDefinitions

readonly stimulantDefinitions: {
  definitions: readonly CombatStimulantDefinition[];
  sequenceId: number;
};

Defined in: packages/sage/src/combat/index.ts:135

definitions

readonly definitions: readonly CombatStimulantDefinition[];

sequenceId

readonly sequenceId: number;

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/combat/index.ts:139

Returns

unknown

---

CombatStimulantDefinition

Defined in: packages/sage/src/combat/index.ts:117

One cargo-backed combat stimulant definition.

Example

declare const stimulant: CombatStimulantDefinition;
console.log(stimulant.cargo.name, stimulant.effects.length);

Properties

cargo

readonly cargo: CargoDefinitionSummary;

Defined in: packages/sage/src/combat/index.ts:118

effects

readonly effects: readonly GameStimulantEffectData[];

Defined in: packages/sage/src/combat/index.ts:119

---

FleetCombatStatsData

Defined in: packages/sage/src/internal/c4/fleet.ts:243

Translated Fleet combat statistics.

Example

declare const stats: FleetCombatStatsData;
const hitPoints = stats.hp;

Properties

aimAbility

readonly aimAbility: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:284

ammoConsumptionRate

readonly ammoConsumptionRate: FleetFixedValue;

Defined in: packages/sage/src/internal/c4/fleet.ts:247

ap

readonly ap: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:244

apRegenRate

readonly apRegenRate: FleetFixedValue;

Defined in: packages/sage/src/internal/c4/fleet.ts:248

counterDecoy

readonly counterDecoy: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:273

counterEnergyCapacitor

readonly counterEnergyCapacitor: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:274

counterFaradayShielding

readonly counterFaradayShielding: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:281

counterFireSuppressor

readonly counterFireSuppressor: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:275

counterFlare

readonly counterFlare: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:276

counterHealingNanobots

readonly counterHealingNanobots: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:277

counterMine

readonly counterMine: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:278

counterNegativeRemPlating

readonly counterNegativeRemPlating: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:279

counterWarmingPlates

readonly counterWarmingPlates: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:280

critChance

readonly critChance: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:285

critMultiplier

readonly critMultiplier: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:286

damageBomb

readonly damageBomb: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:271

damageBombVariance

readonly damageBombVariance: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:272

damageEmp

readonly damageEmp: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:261

damageEmpVariance

readonly damageEmpVariance: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:262

damageEnergy

readonly damageEnergy: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:259

damageEnergyVariance

readonly damageEnergyVariance: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:260

damageGraygoo

readonly damageGraygoo: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:267

damageGraygooVariance

readonly damageGraygooVariance: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:268

damageHeat

readonly damageHeat: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:269

damageHeatVariance

readonly damageHeatVariance: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:270

damageKinetic

readonly damageKinetic: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:257

damageKineticVariance

readonly damageKineticVariance: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:258

damageShockwave

readonly damageShockwave: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:265

damageShockwaveVariance

readonly damageShockwaveVariance: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:266

damageSuperchill

readonly damageSuperchill: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:263

damageSuperchillVariance

readonly damageSuperchillVariance: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:264

fuelConsumptionRate

readonly fuelConsumptionRate: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:287

hitChance

readonly hitChance: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:283

hp

readonly hp: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:245

lootRate

readonly lootRate: FleetFixedValue;

Defined in: packages/sage/src/internal/c4/fleet.ts:254

missileDamage

readonly missileDamage: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:288

missileFireRate

readonly missileFireRate: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:289

repairAbility

readonly repairAbility: FleetFixedValue;

Defined in: packages/sage/src/internal/c4/fleet.ts:251

repairCost

readonly repairCost: FleetFixedValue;

Defined in: packages/sage/src/internal/c4/fleet.ts:253

repairEfficiency

readonly repairEfficiency: FleetFixedValue;

Defined in: packages/sage/src/internal/c4/fleet.ts:252

repairRate

readonly repairRate: FleetFixedValue;

Defined in: packages/sage/src/internal/c4/fleet.ts:250

shieldBreakDelaySeconds

readonly shieldBreakDelaySeconds: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:255

shieldRechargeRate

readonly shieldRechargeRate: FleetFixedValue;

Defined in: packages/sage/src/internal/c4/fleet.ts:249

sp

readonly sp: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:246

stealthPower

readonly stealthPower: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:282

warpSpoolTimeSeconds

readonly warpSpoolTimeSeconds: number;

Defined in: packages/sage/src/internal/c4/fleet.ts:256

---

FleetCombatStatusSnapshot

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

Immutable focused combat projection of one Fleet.

Example

declare const status: FleetCombatStatusSnapshot;
console.log(
  status.current.abilityPowerPoints,
  status.timing.abilityPowerReloadAtUnixSeconds,
);

Properties

current

readonly current: {
  abilityPowerPoints: number;
  hullPoints: number;
  pendingHullPoints: number;
  shieldPoints: number;
};

Defined in: packages/sage/src/combat/index.ts:160

abilityPowerPoints

readonly abilityPowerPoints: number;

hullPoints

readonly hullPoints: number;

pendingHullPoints

readonly pendingHullPoints: number;

shieldPoints

readonly shieldPoints: number;

faction

readonly faction: CombatFaction;

Defined in: packages/sage/src/combat/index.ts:156

fleet

readonly fleet: EntityRef<"fleet">;

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

kind

readonly kind: "fleetCombatStatus";

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

ownerProfile

readonly ownerProfile: EntityRef<"profile">;

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

participant

readonly participant:
  | {
  kind: "player";
}
  | {
  factionId: number;
  kind: "npc";
};

Defined in: packages/sage/src/combat/index.ts:157

stance

readonly stance: {
  ammoUsage: "none" | "light" | "heavy";
};

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

ammoUsage

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

stats

readonly stats: FleetCombatStatsData;

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

stimulants

readonly stimulants: readonly {
  chargesRemaining: number;
  deltaBps: number;
  statId: number;
}[];

Defined in: packages/sage/src/combat/index.ts:172

timing

readonly timing: {
  abilityPowerReloadAtUnixSeconds: bigint;
  lastCombatUpdateAtUnixSeconds: bigint;
  shieldBreakDelayEndsAtUnixSeconds: bigint;
};

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

abilityPowerReloadAtUnixSeconds

readonly abilityPowerReloadAtUnixSeconds: bigint;

lastCombatUpdateAtUnixSeconds

readonly lastCombatUpdateAtUnixSeconds: bigint;

shieldBreakDelayEndsAtUnixSeconds

readonly shieldBreakDelayEndsAtUnixSeconds: bigint;

Methods

toJSON()

toJSON(): unknown;

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

Returns

unknown

---

GameCombatConfigurationData

Defined in: packages/sage/src/internal/c4/game.ts:236

Translated Game combat configuration before cargo resolution.

Example

declare const configuration: GameCombatConfigurationData;
console.log(configuration.maxFleetSize);

Properties

cargoRespawnTimeSeconds

readonly cargoRespawnTimeSeconds: bigint;

Defined in: packages/sage/src/internal/c4/game.ts:243

crewRespawnTimeSeconds

readonly crewRespawnTimeSeconds: bigint;

Defined in: packages/sage/src/internal/c4/game.ts:242

globalCeasefire

readonly globalCeasefire: boolean;

Defined in: packages/sage/src/internal/c4/game.ts:237

interactionRange

readonly interactionRange: GameCombatFixedValueData;

Defined in: packages/sage/src/internal/c4/game.ts:238

lootExclusivityTimeSeconds

readonly lootExclusivityTimeSeconds: bigint;

Defined in: packages/sage/src/internal/c4/game.ts:239

maxFleetSize

readonly maxFleetSize: number;

Defined in: packages/sage/src/internal/c4/game.ts:245

maxLootRate

readonly maxLootRate: GameCombatFixedValueData;

Defined in: packages/sage/src/internal/c4/game.ts:240

rawShipsRespawnTimeSeconds

readonly rawShipsRespawnTimeSeconds: bigint;

Defined in: packages/sage/src/internal/c4/game.ts:244

starbaseUpgradeProgressContinuation

readonly starbaseUpgradeProgressContinuation: GameCombatFixedValueData;

Defined in: packages/sage/src/internal/c4/game.ts:241

stimulantDefinitions

readonly stimulantDefinitions: {
  definitions: readonly GameStimulantDefinitionData[];
  sequenceId: number;
};

Defined in: packages/sage/src/internal/c4/game.ts:246

definitions

readonly definitions: readonly GameStimulantDefinitionData[];

sequenceId

readonly sequenceId: number;

---

GameStimulantEffectData

Defined in: packages/sage/src/internal/c4/game.ts:224

One translated combat stimulant effect.

Example

const effect: GameStimulantEffectData = {
  charges: 1,
  deltaBps: 250,
  stackRuleId: 0,
  statId: 2,
};

Properties

charges

readonly charges: number;

Defined in: packages/sage/src/internal/c4/game.ts:227

deltaBps

readonly deltaBps: number;

Defined in: packages/sage/src/internal/c4/game.ts:226

stackRuleId

readonly stackRuleId: number;

Defined in: packages/sage/src/internal/c4/game.ts:228

statId

readonly statId: number;

Defined in: packages/sage/src/internal/c4/game.ts:225

---

LootCargoItem

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

One resolved cargo quantity inside Loot.

Example

declare const item: LootCargoItem;
console.log(item.cargo.name, item.quantityRaw);

Properties

cargo

readonly cargo: CargoDefinitionSummary;

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

quantityRaw

readonly quantityRaw: bigint;

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

---

LootInventory

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

Resolved inventory for one Loot leg.

Example

declare const inventory: LootInventory;
console.log(inventory.items.length);

Properties

items

readonly items: readonly LootCargoItem[];

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

sequenceId

readonly sequenceId: number;

Defined in: packages/sage/src/combat/index.ts:201

storageCostRaw

readonly storageCostRaw: bigint;

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

---

LootItem

Defined in: packages/sage/src/combat/index.ts:213

One translated Loot item group.

Example

declare const item: LootItem;
console.log(item.destroyer.address, item.exclusivityUnlockAtUnixSeconds);

Properties

destroyer

readonly destroyer: EntityRef<"fleet">;

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

exclusivityUnlockAtUnixSeconds

readonly exclusivityUnlockAtUnixSeconds: bigint;

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

inventory

readonly inventory: LootInventory;

Defined in: packages/sage/src/combat/index.ts:217

rewardReclaimAtUnixSeconds

readonly rewardReclaimAtUnixSeconds: bigint;

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

---

LootSnapshot

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

Immutable Loot snapshot with resolved cargo inventory.

Example

declare const loot: LootSnapshot;
console.log(loot.reward.kind, loot.items.length);

Properties

address

readonly address: Address;

Defined in: packages/sage/src/combat/index.ts:229

coordinates

readonly coordinates: {
  x: number;
  y: number;
};

Defined in: packages/sage/src/combat/index.ts:233

x

readonly x: number;

y

readonly y: number;

game

readonly game: EntityRef<"game">;

Defined in: packages/sage/src/combat/index.ts:231

items

readonly items: readonly LootItem[];

Defined in: packages/sage/src/combat/index.ts:235

kind

readonly kind: "loot";

Defined in: packages/sage/src/combat/index.ts:228

profile

readonly profile: EntityRef<"profile">;

Defined in: packages/sage/src/combat/index.ts:232

reward

readonly reward: LootRewardData;

Defined in: packages/sage/src/combat/index.ts:234

version

readonly version: number;

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

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/combat/index.ts:236

Returns

unknown

---

OutlawFlagAccountData

Defined in: packages/sage/src/internal/c4/combat.ts:139

Fully translated OutlawFlag account data.

Properties

bump

readonly bump: number;

Defined in: packages/sage/src/internal/c4/combat.ts:146

declaredAtUnixSeconds

readonly declaredAtUnixSeconds: bigint;

Defined in: packages/sage/src/internal/c4/combat.ts:144

faction

readonly faction: CombatFaction;

Defined in: packages/sage/src/internal/c4/combat.ts:142

isOutlaw

readonly isOutlaw: boolean;

Defined in: packages/sage/src/internal/c4/combat.ts:143

profile

readonly profile: Address;

Defined in: packages/sage/src/internal/c4/combat.ts:141

pvpUntilUnixSeconds

readonly pvpUntilUnixSeconds: bigint;

Defined in: packages/sage/src/internal/c4/combat.ts:145

version

readonly version: number;

Defined in: packages/sage/src/internal/c4/combat.ts:140

---

OutlawFlagSnapshot

Defined in: packages/sage/src/combat/index.ts:246

Immutable optional outlaw declaration derived from Profile and faction.

Example

declare const flag: OutlawFlagSnapshot;
console.log(flag.isOutlaw, flag.pvpUntilUnixSeconds);

Extends

• Omit<OutlawFlagAccountData, "profile">

Properties

address

readonly address: Address;

Defined in: packages/sage/src/combat/index.ts:251

bump

readonly bump: number;

Defined in: packages/sage/src/internal/c4/combat.ts:146

Inherited from

OutlawFlagAccountData.bump

declaredAtUnixSeconds

readonly declaredAtUnixSeconds: bigint;

Defined in: packages/sage/src/internal/c4/combat.ts:144

Inherited from

OutlawFlagAccountData.declaredAtUnixSeconds

faction

readonly faction: CombatFaction;

Defined in: packages/sage/src/internal/c4/combat.ts:142

Inherited from

OutlawFlagAccountData.faction

isOutlaw

readonly isOutlaw: boolean;

Defined in: packages/sage/src/internal/c4/combat.ts:143

Inherited from

OutlawFlagAccountData.isOutlaw

kind

readonly kind: "outlawFlag";

Defined in: packages/sage/src/combat/index.ts:250

profile

readonly profile: EntityRef<"profile">;

Defined in: packages/sage/src/combat/index.ts:252

pvpUntilUnixSeconds

readonly pvpUntilUnixSeconds: bigint;

Defined in: packages/sage/src/internal/c4/combat.ts:145

Inherited from

OutlawFlagAccountData.pvpUntilUnixSeconds

version

readonly version: number;

Defined in: packages/sage/src/internal/c4/combat.ts:140

Inherited from

OutlawFlagAccountData.version

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/combat/index.ts:253

Returns

unknown

Type Aliases

CombatFaction

type CombatFaction = "unaligned" | "mud" | "oni" | "ustur";

Defined in: packages/sage/src/internal/c4/combat.ts:84

Faction identifier accepted by combat reads.

Example

const faction: CombatFaction = 'mud';

---

LootDiscoveryOptions

type LootDiscoveryOptions = Omit<DiscoveryRequest, "filters" | "strategy">;

Defined in: packages/sage/src/combat/index.ts:105

Options supported by targeted Loot discovery.

Example

const options: LootDiscoveryOptions = { commitment: 'confirmed' };

---

LootRewardData

type LootRewardData =
  | {
  kind: "none";
}
  | {
  committedAtUnixSeconds: bigint;
  configVersion: number;
  kind: "committed" | "resolved";
  legs: readonly LootRewardLegData[];
  slot: bigint;
}
  | {
  committedAtUnixSeconds: bigint;
  configVersion: number;
  kind: "unknown";
  legs: readonly LootRewardLegData[];
  rawStatus: number;
  slot: bigint;
};

Defined in: packages/sage/src/internal/c4/combat.ts:110

Translated Loot reward state, including unknown raw status bytes.

Example

const reward: LootRewardData = { kind: 'none' };

Functions

getCombatConfiguration()

function getCombatConfiguration(context, options?): Promise<CombatConfigurationSnapshot>;

Defined in: packages/sage/src/combat/index.ts:321

Reads the configured Game’s combat settings and stimulant catalog.

Parameters

Parameter	Type
context	SageContext
options?	ReadOptions

Returns

Promise<CombatConfigurationSnapshot>

Example

declare const ctx: SageContext;
const configuration = await getCombatConfiguration(ctx);

---

getFleetCombatStatus()

function getFleetCombatStatus(
   context,
   address,
options?): Promise<FleetCombatStatusSnapshot>;

Defined in: packages/sage/src/combat/index.ts:387

Reads one Fleet and returns only its translated combat state.

Parameters

Parameter	Type
context	SageContext
address	Address
options?	ReadOptions

Returns

Promise<FleetCombatStatusSnapshot>

Example

declare const ctx: SageContext;
declare const fleet: Address;
const status = await getFleetCombatStatus(ctx, fleet);

---

getLoot()

function getLoot(
   context,
   address,
options?): Promise<LootSnapshot>;

Defined in: packages/sage/src/combat/index.ts:483

Reads required Loot by its signer-created account address.

Parameters

Parameter	Type
context	SageContext
address	Address
options?	ReadOptions

Returns

Promise<LootSnapshot>

Example

declare const ctx: SageContext;
declare const address: Address;
const loot = await getLoot(ctx, address);

---

getLootByProfile()

function getLootByProfile(
   context,
   profile,
options?): Promise<readonly LootSnapshot[]>;

Defined in: packages/sage/src/combat/index.ts:525

Discovers Loot created by one Profile using stable targeted filters.

Parameters

Parameter	Type
context	SageContext
profile	Address
options?	LootDiscoveryOptions

Returns

Promise<readonly LootSnapshot[]>

Example

declare const ctx: SageContext;
declare const profile: Address;
const loot = await getLootByProfile(ctx, profile);

---

getOutlawFlag()

function getOutlawFlag(
   context,
   profile,
   againstFaction,
   options?): Promise<
  | OutlawFlagSnapshot
| undefined>;

Defined in: packages/sage/src/combat/index.ts:567

Derives and reads an optional OutlawFlag for a Profile/faction pair.

Parameters

Parameter	Type
context	SageContext
profile	Address
againstFaction	CombatFaction
options?	ReadOptions

Returns

Promise< | OutlawFlagSnapshot | undefined>

Example

declare const ctx: SageContext;
declare const profile: Address;
const flag = await getOutlawFlag(ctx, profile, 'mud');

---

maybeGetLoot()

function maybeGetLoot(
   context,
   address,
options?): Promise<LootSnapshot | undefined>;

Defined in: packages/sage/src/combat/index.ts:503

Reads optional Loot by account address.

Parameters

Parameter	Type
context	SageContext
address	Address
options?	ReadOptions

Returns

Promise<LootSnapshot | undefined>

Example

declare const ctx: SageContext;
declare const address: Address;
const loot = await maybeGetLoot(ctx, address);