fleets

Interfaces

CapacitySummary

Defined in: packages/sage/src/internal/fleet.ts:22

Used/total Fleet capacity in the units of its on-chain capacity axis.

Example

declare const capacity: CapacitySummary;
const remaining = capacity.remaining;

Properties

overCapacity

readonly overCapacity: bigint;

Defined in: packages/sage/src/internal/fleet.ts:26

remaining

readonly remaining: bigint;

Defined in: packages/sage/src/internal/fleet.ts:25

total

readonly total: bigint;

Defined in: packages/sage/src/internal/fleet.ts:24

used

readonly used: bigint;

Defined in: packages/sage/src/internal/fleet.ts:23

---

FleetAccountData

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

SDK-owned decoded Fleet data before registry definition resolution.

Example

declare const fleet: FleetAccountData;
const owner = fleet.ownerProfile;

Properties

activeStimulants

readonly activeStimulants: readonly {
  chargesRemaining: number;
  deltaBps: number;
  stat: number;
}[];

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

ammoBank

readonly ammoBank: FleetCargoAmountData;

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

ap

readonly ap: number;

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

Banked AP. The game refills it right after an attack, so usable AP is zero until chain time reaches apReloadExpiresAt.

apReloadExpiresAt

readonly apReloadExpiresAt: bigint;

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

bump

readonly bump: number;

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

cargoHold

readonly cargoHold: FleetCargoPodData;

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

components

readonly components: FleetCargoPodData;

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

crewCount

readonly crewCount: number;

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

faction

readonly faction: "unaligned" | "mud" | "oni" | "ustur";

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

fleetShips

readonly fleetShips: readonly FleetShipAmountData[];

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

fuelTank

readonly fuelTank: FleetCargoAmountData;

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

game

readonly game: Address;

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

hp

readonly hp: number;

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

lastCombatUpdate

readonly lastCombatUpdate: bigint;

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

lastUpdateAt

readonly lastUpdateAt: bigint;

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

location

readonly location: WorldCoordinates;

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

locationRaw

readonly locationRaw: {
  x: bigint;
  y: bigint;
};

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

Exact stored I8F56 coordinates; use these for arithmetic, not the display numbers.

x

readonly x: bigint;

y

readonly y: bigint;

name

readonly name: string;

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

npcFactionId

readonly npcFactionId: number;

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

ownerProfile

readonly ownerProfile: Address;

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

pendingHp

readonly pendingHp: number;

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

rentedCrew

readonly rentedCrew: number;

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

respawningCargo

readonly respawningCargo: FleetCargoPodData;

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

scanCooldownExpiresAt

readonly scanCooldownExpiresAt: bigint;

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

shieldBreakDelayExpiresAt

readonly shieldBreakDelayExpiresAt: bigint;

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

shipCounts

readonly shipCounts: FleetShipCountsData;

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

shipDefinitionsSeqId

readonly shipDefinitionsSeqId: number;

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

sp

readonly sp: number;

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

stance

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

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

ammoUsage

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

state

readonly state: FleetStateData;

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

stats

readonly stats: FleetStatsData;

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

subProfile

readonly subProfile: Address;

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

The renter’s Profile; the System program address when the Fleet has no rental, or the SAGE program address while it is listed for rent with no renter. Any other value than the System program address makes the Fleet unusable by its owner.

subProfileInvalidator

readonly subProfileInvalidator: Address;

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

Who may end the Fleet’s rental: the owner Profile unless a rental listing named another account. Always holds an address.

version

readonly version: number;

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

warpCooldownExpiresAt

readonly warpCooldownExpiresAt: bigint;

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

---

FleetCargoAmountData

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

One unresolved cargo amount decoded from Fleet account data.

Example

declare const cargo: FleetCargoAmountData;
const cargoId = cargo.cargoId;

Properties

amount

readonly amount: bigint;

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

cargoId

readonly cargoId: number;

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

---

FleetCargoPodData

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

One immutable cargo pod decoded from Fleet account data.

Example

declare const pod: FleetCargoPodData;
const amounts = pod.amounts;

Properties

amounts

readonly amounts: readonly FleetCargoAmountData[];

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

seqId

readonly seqId: number;

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

storageCost

readonly storageCost: bigint;

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

---

FleetCargoStatsData

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

Translated Fleet cargo statistics.

Example

declare const stats: FleetCargoStatsData;
const capacity = stats.cargoCapacity;

Properties

ammoCapacity

readonly ammoCapacity: bigint;

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

ammoConsumptionRate

readonly ammoConsumptionRate: FleetFixedValue;

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

cargoCapacity

readonly cargoCapacity: bigint;

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

foodConsumptionRate

readonly foodConsumptionRate: FleetFixedValue;

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

fuelCapacity

readonly fuelCapacity: bigint;

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

loadRate

readonly loadRate: FleetFixedValue;

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

miningRate

readonly miningRate: FleetFixedValue;

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

---

FleetCompositionStats

Defined in: packages/sage/src/fleets/composition-stats.ts:59

Projected stored Fleet stats after the additions, in the same units as a Fleet’s stats. route says which program path produced them: new-fleet starts from an empty Fleet, stored builds on the Fleet’s stored stats, and resynchronized first rebuilds a Fleet on an older ship-definition sequence from the current definitions, as the program does before adding ships.

Example

declare const projected: FleetCompositionStats;
console.log(projected.route, projected.fleetPoints, projected.stats.cargo.miningRate.value);

Properties

definitionSequenceId

readonly definitionSequenceId: number;

Defined in: packages/sage/src/fleets/composition-stats.ts:61

fleetPoints

readonly fleetPoints: number;

Defined in: packages/sage/src/fleets/composition-stats.ts:68

XXS 1, XS 4, Small 9, Medium 16, Large 25, Capital 36, Commander 49, Titan 128.

route

readonly route: "new-fleet" | "stored" | "resynchronized";

Defined in: packages/sage/src/fleets/composition-stats.ts:60

shipCounts

readonly shipCounts: FleetShipCountsData;

Defined in: packages/sage/src/fleets/composition-stats.ts:66

ships

readonly ships: readonly {
  id: number;
  quantity: bigint;
}[];

Defined in: packages/sage/src/fleets/composition-stats.ts:62

stats

readonly stats: FleetStatsData;

Defined in: packages/sage/src/fleets/composition-stats.ts:69

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/fleets/composition-stats.ts:70

Returns

unknown

---

FleetCompositionStatsInput

Defined in: packages/sage/src/fleets/composition-stats.ts:26

Inputs for projecting a Fleet’s stored stats after ship assembly. Pass the whole loaded ships section (listShipConfigurations), the current Fleet snapshot (omit it for a newly created, empty Fleet) and the ships to add, one entry per add-ship instruction in submission order, as successive planAddShipToFleet Plans would submit them.

Example

declare const ctx: SageContext, fleet: FleetSnapshot;
const input: FleetCompositionStatsInput = {
  definitions: await listShipConfigurations(ctx),
  fleet,
  additions: [{ shipId: 12, amount: 1n }],
};

Properties

additions

readonly additions: readonly {
  amount: bigint;
  shipId: number;
}[];

Defined in: packages/sage/src/fleets/composition-stats.ts:42

definitions

readonly definitions: readonly Pick<ShipDefinitionSummary, "stats" | "sizeClass" | "id" | "definitionSequenceId">[];

Defined in: packages/sage/src/fleets/composition-stats.ts:27

fleet?

readonly optional fleet?: {
  shipCounts: FleetShipCountsData;
  shipDefinitionsSeqId: number;
  ships: readonly {
     id: number;
     quantity: bigint;
  }[];
  stats: FleetStatsData;
};

Defined in: packages/sage/src/fleets/composition-stats.ts:33

A Fleet snapshot, or the same fields from raw Fleet data with fleetShips mapped to { id: shipId, quantity }.

shipCounts

readonly shipCounts: FleetShipCountsData;

shipDefinitionsSeqId

readonly shipDefinitionsSeqId: number;

ships

readonly ships: readonly {
  id: number;
  quantity: bigint;
}[];

stats

readonly stats: FleetStatsData;

---

FleetCoordinateWarpEstimate

Defined in: packages/sage/src/fleets/coordinate-warp-estimate.ts:36

Whole-second duration including spool and whole-unit Fuel debit estimate. withinRange compares only computed distance with the stored maximum; it is not permission to travel. Raw distance has 56 fractional bits; AU is approximate.

Example

declare const estimate: FleetCoordinateWarpEstimate;
console.log(estimate.durationSeconds, estimate.fuelDebit, estimate.withinRange);

Properties

distanceAu

readonly distanceAu: number;

Defined in: packages/sage/src/fleets/coordinate-warp-estimate.ts:37

distanceRaw

readonly distanceRaw: bigint;

Defined in: packages/sage/src/fleets/coordinate-warp-estimate.ts:38

durationSeconds

readonly durationSeconds: bigint;

Defined in: packages/sage/src/fleets/coordinate-warp-estimate.ts:39

fuelDebit

readonly fuelDebit: bigint;

Defined in: packages/sage/src/fleets/coordinate-warp-estimate.ts:40

withinRange

readonly withinRange: boolean;

Defined in: packages/sage/src/fleets/coordinate-warp-estimate.ts:41

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/fleets/coordinate-warp-estimate.ts:42

Returns

unknown

---

FleetCoordinateWarpEstimateInput

Defined in: packages/sage/src/fleets/coordinate-warp-estimate.ts:17

Exact inputs for an Idle Fleet’s coordinate warp, not lane travel. Coordinates are I8F56, speed U16F16, Fuel rate U26F6, Character warp-speed modifier I32F32, range U8F8 and spool time integer seconds.

Example

const input: FleetCoordinateWarpEstimateInput = {
  fromRaw: { x: 0n, y: 0n }, toRaw: { x: 1n << 56n, y: 0n },
  speedRaw: 65536n, fuelRateRaw: 64n, speedModifierRaw: 4294967296n,
  spoolSeconds: 3, maxWarpDistanceRaw: 256n,
};

Properties

fromRaw

readonly fromRaw: {
  x: bigint;
  y: bigint;
};

Defined in: packages/sage/src/fleets/coordinate-warp-estimate.ts:18

x

readonly x: bigint;

y

readonly y: bigint;

fuelRateRaw

readonly fuelRateRaw: bigint;

Defined in: packages/sage/src/fleets/coordinate-warp-estimate.ts:21

maxWarpDistanceRaw

readonly maxWarpDistanceRaw: bigint;

Defined in: packages/sage/src/fleets/coordinate-warp-estimate.ts:24

speedModifierRaw

readonly speedModifierRaw: bigint;

Defined in: packages/sage/src/fleets/coordinate-warp-estimate.ts:22

speedRaw

readonly speedRaw: bigint;

Defined in: packages/sage/src/fleets/coordinate-warp-estimate.ts:20

spoolSeconds

readonly spoolSeconds: number;

Defined in: packages/sage/src/fleets/coordinate-warp-estimate.ts:23

toRaw

readonly toRaw: {
  x: bigint;
  y: bigint;
};

Defined in: packages/sage/src/fleets/coordinate-warp-estimate.ts:19

x

readonly x: bigint;

y

readonly y: bigint;

---

FleetFixedValue

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

A translated fixed-point value retaining exact arithmetic source data.

Example

declare const fixed: FleetFixedValue;
const exact = fixed.raw;

Properties

raw

readonly raw: bigint;

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

value

readonly value: number;

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

---

FleetMiscStatsData

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

Translated miscellaneous Fleet statistics.

Example

declare const stats: FleetMiscStatsData;
const requiredCrew = stats.requiredCrew;

Properties

lpValue

readonly lpValue: number;

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

medallionValue

readonly medallionValue: number;

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

passengerCapacity

readonly passengerCapacity: number;

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

recoveryFeeAtlas

readonly recoveryFeeAtlas: number;

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

recoveryFeeRaw in ATLAS.

recoveryFeeRaw

readonly recoveryFeeRaw: bigint;

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

Per-hull recovery fee in raw ATLAS, charged on every entry to Respawn. It is not the separate Respawn fee paid to skip the respawn timer.

requiredCrew

readonly requiredCrew: number;

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

respawnTimeWithFeeSeconds

readonly respawnTimeWithFeeSeconds: number;

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

Configured paid-respawn time; the game no longer consults it, because the paid Respawn route has no timer and prices by remaining time instead.

respawnTimeWithoutFeeSeconds

readonly respawnTimeWithoutFeeSeconds: number;

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

scanBonus

readonly scanBonus: FleetFixedValue;

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

Signed I16F16 fixed-point bonus added to the base scan value.

scanCoolDownSeconds

readonly scanCoolDownSeconds: FleetFixedValue;

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

U16F16 fixed-point scanning cooldown in seconds.

scanCost

readonly scanCost: number;

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

scanPower

readonly scanPower: FleetFixedValue;

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

U26F6 fixed-point scanning power.

xpValue

readonly xpValue: FleetFixedValue;

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

U16F16 fixed-point configured XP value; not an awarded-XP calculation.

---

FleetMovementStatsData

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

Translated Fleet movement statistics.

Example

declare const stats: FleetMovementStatsData;
const speed = stats.subwarpSpeed.value;

Properties

maxWarpDistance

readonly maxWarpDistance: FleetFixedValue;

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

planetExitFuelAmount

readonly planetExitFuelAmount: number;

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

subwarpFuelConsumptionRate

readonly subwarpFuelConsumptionRate: FleetFixedValue;

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

subwarpSpeed

readonly subwarpSpeed: FleetFixedValue;

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

subwarpXpRate

readonly subwarpXpRate: FleetFixedValue;

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

warpCoolDownSeconds

readonly warpCoolDownSeconds: number;

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

warpFuelConsumptionRate

readonly warpFuelConsumptionRate: FleetFixedValue;

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

warpLaneSpeed

readonly warpLaneSpeed: FleetFixedValue;

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

warpSpeed

readonly warpSpeed: FleetFixedValue;

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

warpXpRate

readonly warpXpRate: FleetFixedValue;

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

---

FleetShipAmountData

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

One unresolved ship quantity decoded from Fleet account data.

Example

declare const ship: FleetShipAmountData;
const quantity = ship.quantity;

Properties

quantity

readonly quantity: bigint;

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

shipId

readonly shipId: number;

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

---

FleetShipCountsData

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

Fleet ship counts by SAGE size class.

Example

declare const counts: FleetShipCountsData;
const total = counts.total;

Properties

capital

readonly capital: number;

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

commander

readonly commander: number;

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

large

readonly large: number;

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

medium

readonly medium: number;

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

small

readonly small: number;

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

titan

readonly titan: number;

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

total

readonly total: number;

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

xSmall

readonly xSmall: number;

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

xxSmall

readonly xxSmall: number;

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

---

FleetSnapshot

Defined in: packages/sage/src/fleets/index.ts:132

Immutable, translated Fleet snapshot with registry-resolved definitions.

Example

declare const ctx: SageContext;
declare const fleetAddress: Address;
const fleet: FleetSnapshot = await getFleet(ctx, fleetAddress);
console.log(fleet.name, fleet.ships);

Extends

• Omit<ResolvedFleetAccountData, "ownerProfile">

Extended by

• FleetView

Properties

activeStimulants

readonly activeStimulants: readonly {
  chargesRemaining: number;
  deltaBps: number;
  stat: number;
}[];

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

Inherited from

FleetAccountData.activeStimulants

address

readonly address: Address;

Defined in: packages/sage/src/fleets/index.ts:137

ammo

readonly ammo: ResolvedCargoAmount;

Defined in: packages/sage/src/internal/fleet.ts:101

Inherited from

ResolvedFleetAccountData.ammo

ap

readonly ap: number;

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

Banked AP. The game refills it right after an attack, so usable AP is zero until chain time reaches apReloadExpiresAt.

Inherited from

FleetAccountData.ap

apReloadExpiresAt

readonly apReloadExpiresAt: bigint;

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

Inherited from

FleetAccountData.apReloadExpiresAt

bump

readonly bump: number;

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

Inherited from

FleetAccountData.bump

capacities

readonly capacities: {
  ammo: CapacitySummary;
  cargo: CapacitySummary;
  fuel: CapacitySummary;
};

Defined in: packages/sage/src/internal/fleet.ts:117

ammo

readonly ammo: CapacitySummary;

cargo

readonly cargo: CapacitySummary;

fuel

readonly fuel: CapacitySummary;

Inherited from

Omit.capacities

cargoHold

readonly cargoHold: {
  items: readonly ResolvedCargoAmount[];
  seqId: number;
  storageCost: bigint;
};

Defined in: packages/sage/src/internal/fleet.ts:102

items

readonly items: readonly ResolvedCargoAmount[];

seqId

readonly seqId: number;

storageCost

readonly storageCost: bigint;

Inherited from

Omit.cargoHold

components

readonly components: {
  items: readonly ResolvedCargoAmount[];
  seqId: number;
  storageCost: bigint;
};

Defined in: packages/sage/src/internal/fleet.ts:107

items

readonly items: readonly ResolvedCargoAmount[];

seqId

readonly seqId: number;

storageCost

readonly storageCost: bigint;

Inherited from

Omit.components

crewCount

readonly crewCount: number;

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

Inherited from

FleetAccountData.crewCount

faction

readonly faction: "unaligned" | "mud" | "oni" | "ustur";

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

Inherited from

FleetAccountData.faction

fuel

readonly fuel: ResolvedCargoAmount;

Defined in: packages/sage/src/internal/fleet.ts:100

Inherited from

ResolvedFleetAccountData.fuel

game

readonly game: Address;

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

Inherited from

FleetAccountData.game

hp

readonly hp: number;

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

Inherited from

FleetAccountData.hp

kind

readonly kind: "fleet";

Defined in: packages/sage/src/fleets/index.ts:136

lastCombatUpdate

readonly lastCombatUpdate: bigint;

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

Inherited from

FleetAccountData.lastCombatUpdate

lastUpdateAt

readonly lastUpdateAt: bigint;

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

Inherited from

FleetAccountData.lastUpdateAt

location

readonly location: WorldCoordinates;

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

Inherited from

FleetAccountData.location

locationRaw

readonly locationRaw: {
  x: bigint;
  y: bigint;
};

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

Exact stored I8F56 coordinates; use these for arithmetic, not the display numbers.

x

readonly x: bigint;

y

readonly y: bigint;

Inherited from

FleetAccountData.locationRaw

name

readonly name: string;

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

Inherited from

FleetAccountData.name

npcFactionId

readonly npcFactionId: number;

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

Inherited from

FleetAccountData.npcFactionId

ownerProfile

readonly ownerProfile: EntityRef<"profile">;

Defined in: packages/sage/src/fleets/index.ts:138

pendingHp

readonly pendingHp: number;

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

Inherited from

FleetAccountData.pendingHp

rentedCrew

readonly rentedCrew: number;

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

Inherited from

FleetAccountData.rentedCrew

respawningCargo

readonly respawningCargo: {
  items: readonly ResolvedCargoAmount[];
  seqId: number;
  storageCost: bigint;
};

Defined in: packages/sage/src/internal/fleet.ts:112

items

readonly items: readonly ResolvedCargoAmount[];

seqId

readonly seqId: number;

storageCost

readonly storageCost: bigint;

Inherited from

Omit.respawningCargo

scanCooldownExpiresAt

readonly scanCooldownExpiresAt: bigint;

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

Inherited from

FleetAccountData.scanCooldownExpiresAt

shieldBreakDelayExpiresAt

readonly shieldBreakDelayExpiresAt: bigint;

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

Inherited from

FleetAccountData.shieldBreakDelayExpiresAt

shipCounts

readonly shipCounts: FleetShipCountsData;

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

Inherited from

FleetAccountData.shipCounts

shipDefinitionsSeqId

readonly shipDefinitionsSeqId: number;

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

Inherited from

FleetAccountData.shipDefinitionsSeqId

ships

readonly ships: readonly ResolvedShipAmount[];

Defined in: packages/sage/src/internal/fleet.ts:99

Inherited from

Omit.ships

sp

readonly sp: number;

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

Inherited from

FleetAccountData.sp

stance

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

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

ammoUsage

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

Inherited from

FleetAccountData.stance

state

readonly state: ResolvedFleetState;

Defined in: packages/sage/src/internal/fleet.ts:122

Inherited from

ResolvedFleetAccountData.state

stats

readonly stats: FleetStatsData;

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

Inherited from

FleetAccountData.stats

subProfile?

readonly optional subProfile?: Address;

Defined in: packages/sage/src/internal/fleet.ts:98

The renter’s Profile, or the SAGE program address while the Fleet is listed for rent with no renter; omitted when the Fleet has no rental.

Inherited from

Omit.subProfile

subProfileInvalidator

readonly subProfileInvalidator: Address;

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

Who may end the Fleet’s rental: the owner Profile unless a rental listing named another account. Always holds an address.

Inherited from

FleetAccountData.subProfileInvalidator

version

readonly version: number;

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

Inherited from

FleetAccountData.version

warpCooldownExpiresAt

readonly warpCooldownExpiresAt: bigint;

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

Inherited from

FleetAccountData.warpCooldownExpiresAt

Methods

toJSON()

toJSON(): unknown;

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

Returns

unknown

---

FleetStatsData

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

Grouped translated Fleet statistics.

Example

declare const stats: FleetStatsData;
const movement = stats.movement;

Properties

cargo

readonly cargo: FleetCargoStatsData;

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

combat

readonly combat: FleetCombatStatsData;

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

misc

readonly misc: FleetMiscStatsData;

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

movement

readonly movement: FleetMovementStatsData;

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

---

FleetSubscriptionObserver

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

Observer for live, fully translated Fleet snapshots.

Example

const observer: FleetSubscriptionObserver = {
  onSnapshot: fleet => console.log(fleet.name),
  onError: error => console.error(error.code),
  onDiagnostic: event => console.debug(event.kind, event.coalescedCount),
};

Properties

onDiagnostic?

readonly optional onDiagnostic?: (event) => void;

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

Parameters

Parameter	Type
event	SubscriptionDiagnosticEvent

Returns

void

onError

readonly onError: (error) => void | Promise<void>;

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

Parameters

Parameter	Type
error	SageSdkError

Returns

void | Promise<void>

onSnapshot

readonly onSnapshot: (fleet) => void | Promise<void>;

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

Parameters

Parameter	Type
fleet	FleetSnapshot

Returns

void | Promise<void>

---

FleetSubwarpEstimate

Defined in: packages/sage/src/fleets/subwarp-estimate.ts:37

Prospective journey values; all three raw outputs have 56 fractional bits. Display numbers are approximate. fuelBudget rounds recorded expenditure up to whole Fuel units; it is not a measured settlement debit or travel approval.

Example

declare const estimate: FleetSubwarpEstimate;
const budget: bigint = estimate.fuelBudget;
console.log(estimate.durationSeconds, JSON.stringify(estimate));

Properties

distanceAu

readonly distanceAu: number;

Defined in: packages/sage/src/fleets/subwarp-estimate.ts:38

distanceRaw

readonly distanceRaw: bigint;

Defined in: packages/sage/src/fleets/subwarp-estimate.ts:39

durationSeconds

readonly durationSeconds: number;

Defined in: packages/sage/src/fleets/subwarp-estimate.ts:40

durationSecondsRaw

readonly durationSecondsRaw: bigint;

Defined in: packages/sage/src/fleets/subwarp-estimate.ts:41

fuelBudget

readonly fuelBudget: bigint;

Defined in: packages/sage/src/fleets/subwarp-estimate.ts:44

fuelExpenditure

readonly fuelExpenditure: number;

Defined in: packages/sage/src/fleets/subwarp-estimate.ts:42

fuelExpenditureRaw

readonly fuelExpenditureRaw: bigint;

Defined in: packages/sage/src/fleets/subwarp-estimate.ts:43

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/fleets/subwarp-estimate.ts:45

Returns

unknown

---

FleetSubwarpEstimateInput

Defined in: packages/sage/src/fleets/subwarp-estimate.ts:19

Raw inputs for an Idle Fleet’s direct subwarp journey. Coordinates use signed I8F56, speed U16F16, Fuel rate U26F6 and the Character subwarp-speed modifier I32F32. Use the Fleet’s exact stored locationRaw; reconstructing it from location display numbers loses precision.

Example

const input: FleetSubwarpEstimateInput = {
  fromRaw: { x: 0n, y: 0n }, toRaw: { x: 1n << 56n, y: 0n },
  speedRaw: 65536n, fuelRateRaw: 64n, speedModifierRaw: 4294967296n,
};

Properties

fromRaw

readonly fromRaw: {
  x: bigint;
  y: bigint;
};

Defined in: packages/sage/src/fleets/subwarp-estimate.ts:20

x

readonly x: bigint;

y

readonly y: bigint;

fuelRateRaw

readonly fuelRateRaw: bigint;

Defined in: packages/sage/src/fleets/subwarp-estimate.ts:23

speedModifierRaw

readonly speedModifierRaw: bigint;

Defined in: packages/sage/src/fleets/subwarp-estimate.ts:24

speedRaw

readonly speedRaw: bigint;

Defined in: packages/sage/src/fleets/subwarp-estimate.ts:22

toRaw

readonly toRaw: {
  x: bigint;
  y: bigint;
};

Defined in: packages/sage/src/fleets/subwarp-estimate.ts:21

x

readonly x: bigint;

y

readonly y: bigint;

---

FleetTimers

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

Date-valued timers derived from Fleet account sentinels and lifecycle state.

Fleet snapshots retain their exact bigint unix-second fields; these values are an ergonomic projection for UI scheduling and display.

Example

declare const timers: FleetTimers;
console.log(
  timers.arrivesAt?.toISOString(),
  timers.transferEndsAt?.toISOString(),
);

Properties

abilityPowerReloadsAt?

readonly optional abilityPowerReloadsAt?: Date;

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

arrivesAt?

readonly optional arrivesAt?: Date;

Defined in: packages/sage/src/internal/fleet.ts:290

recoversAt?

readonly optional recoversAt?: Date;

Defined in: packages/sage/src/internal/fleet.ts:291

scanCooldownEndsAt?

readonly optional scanCooldownEndsAt?: Date;

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

shieldRegenerationResumesAt?

readonly optional shieldRegenerationResumesAt?: Date;

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

transferEndsAt?

readonly optional transferEndsAt?: Date;

Defined in: packages/sage/src/internal/fleet.ts:292

warpCooldownEndsAt?

readonly optional warpCooldownEndsAt?: Date;

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

---

FleetTravelProfile

Defined in: packages/sage/src/fleets/travel-profile.ts:52

Reference travel values per AU, per maximum-range warp and per full tank. Each section is null when its speed (or warp range) is zero. Whole seconds and whole Fuel are bigint, as in the movement estimates; ratios are numbers. A null full-tank value means that movement mode burns no Fuel.

Example

declare const profile: FleetTravelProfile;
console.log(profile.subwarp?.fullTankRangeAu, JSON.stringify(profile));

Properties

coordinateWarp

readonly coordinateWarp:
  | {
  cooldownSeconds: bigint;
  cycleSeconds: bigint;
  fullTankRangeAu: number | null;
  maxJumpAu: number;
  maxJumpFuel: bigint;
  maxJumpSeconds: bigint;
  maxJumpsPerFullTank: bigint | null;
  sustainedAuPerHour: number;
}
  | null;

Defined in: packages/sage/src/fleets/travel-profile.ts:63

Union Members

Type Literal

{
  cooldownSeconds: bigint;
  cycleSeconds: bigint;
  fullTankRangeAu: number | null;
  maxJumpAu: number;
  maxJumpFuel: bigint;
  maxJumpSeconds: bigint;
  maxJumpsPerFullTank: bigint | null;
  sustainedAuPerHour: number;
}

cooldownSeconds

readonly cooldownSeconds: bigint;

Whole seconds of warp cooldown assigned at arrival.

cycleSeconds

readonly cycleSeconds: bigint;

Seconds from one maximum-range departure to the next: jump plus cooldown.

fullTankRangeAu

readonly fullTankRangeAu: number | null;

Distance covered by those warps.

maxJumpAu

readonly maxJumpAu: number;

Maximum coordinate-warp distance, in AU.

maxJumpFuel

readonly maxJumpFuel: bigint;

Whole Fuel debited for one maximum-range warp.

maxJumpSeconds

readonly maxJumpSeconds: bigint;

Whole seconds for one maximum-range warp, including spool.

maxJumpsPerFullTank

readonly maxJumpsPerFullTank: bigint | null;

Maximum-range warp debits that fit in a full tank.

sustainedAuPerHour

readonly sustainedAuPerHour: number;

AU per hour when chaining maximum-range warps as cooldown allows.

---

null

subwarp

readonly subwarp:
  | {
  fuelPerAu: number;
  fullTankRangeAu: number | null;
  fullTankSeconds: number | null;
  secondsPerAu: number;
}
  | null;

Defined in: packages/sage/src/fleets/travel-profile.ts:53

Union Members

Type Literal

{
  fuelPerAu: number;
  fullTankRangeAu: number | null;
  fullTankSeconds: number | null;
  secondsPerAu: number;
}

fuelPerAu

readonly fuelPerAu: number;

Fractional Fuel expenditure recorded for one AU.

fullTankRangeAu

readonly fullTankRangeAu: number | null;

Subwarp distance whose Fuel expenditure equals a full tank.

fullTankSeconds

readonly fullTankSeconds: number | null;

Seconds to subwarp the full-tank range.

secondsPerAu

readonly secondsPerAu: number;

Seconds to subwarp exactly one AU.

---

null

warpLane

readonly warpLane:
  | {
  secondsPerAu: number;
}
  | null;

Defined in: packages/sage/src/fleets/travel-profile.ts:81

Union Members

Type Literal

{
  secondsPerAu: number;
}

secondsPerAu

readonly secondsPerAu: number;

Seconds per AU of lane; each hop rounds up to whole seconds.

---

null

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/fleets/travel-profile.ts:85

Returns

unknown

---

FleetTravelProfileInput

Defined in: packages/sage/src/fleets/travel-profile.ts:22

Stats read by the travel profile: a Fleet’s stats or a ship configuration’s stats, which equal a one-ship Fleet’s. Character modifiers are raw I32F32 values; omitted or zero modifiers are neutral, as in the movement estimates.

Example

declare const ship: { readonly stats: FleetTravelProfileInput['stats'] };
const input: FleetTravelProfileInput = { stats: ship.stats };

Properties

stats

readonly stats: {
  cargo: Pick<FleetCargoStatsData, "fuelCapacity">;
  combat: Pick<FleetCombatStatsData, "warpSpoolTimeSeconds">;
  movement: Pick<FleetMovementStatsData,
     | "subwarpSpeed"
     | "subwarpFuelConsumptionRate"
     | "warpSpeed"
     | "warpFuelConsumptionRate"
     | "maxWarpDistance"
     | "warpCoolDownSeconds"
    | "warpLaneSpeed">;
};

Defined in: packages/sage/src/fleets/travel-profile.ts:23

cargo

readonly cargo: Pick<FleetCargoStatsData, "fuelCapacity">;

combat

readonly combat: Pick<FleetCombatStatsData, "warpSpoolTimeSeconds">;

movement

readonly movement: Pick<FleetMovementStatsData,
  | "subwarpSpeed"
  | "subwarpFuelConsumptionRate"
  | "warpSpeed"
  | "warpFuelConsumptionRate"
  | "maxWarpDistance"
  | "warpCoolDownSeconds"
| "warpLaneSpeed">;

subwarpSpeedModifierRaw?

readonly optional subwarpSpeedModifierRaw?: bigint;

Defined in: packages/sage/src/fleets/travel-profile.ts:37

warpCooldownModifierRaw?

readonly optional warpCooldownModifierRaw?: bigint;

Defined in: packages/sage/src/fleets/travel-profile.ts:39

warpSpeedModifierRaw?

readonly optional warpSpeedModifierRaw?: bigint;

Defined in: packages/sage/src/fleets/travel-profile.ts:38

---

FleetWarpLaneEstimate

Defined in: packages/sage/src/fleets/warp-lane-estimate.ts:29

Whole-second lane duration and zero Fuel debit on the qualified deployment. Raw distance has 56 fractional bits; AU is approximate.

Example

declare const estimate: FleetWarpLaneEstimate;
console.log(estimate.durationSeconds, estimate.fuelDebit);

Properties

distanceAu

readonly distanceAu: number;

Defined in: packages/sage/src/fleets/warp-lane-estimate.ts:30

distanceRaw

readonly distanceRaw: bigint;

Defined in: packages/sage/src/fleets/warp-lane-estimate.ts:31

durationSeconds

readonly durationSeconds: bigint;

Defined in: packages/sage/src/fleets/warp-lane-estimate.ts:32

fuelDebit

readonly fuelDebit: 0n;

Defined in: packages/sage/src/fleets/warp-lane-estimate.ts:33

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/fleets/warp-lane-estimate.ts:34

Returns

unknown

---

FleetWarpLaneEstimateInput

Defined in: packages/sage/src/fleets/warp-lane-estimate.ts:15

Exact System coordinates (I8F56) and Fleet lane speed (U16F16). No Character warp-speed modifier or spool time applies to lane travel.

Example

const input: FleetWarpLaneEstimateInput = {
  fromRaw: { x: 0n, y: 0n }, toRaw: { x: 1n << 56n, y: 0n },
  speedRaw: 65536n,
};

Properties

fromRaw

readonly fromRaw: {
  x: bigint;
  y: bigint;
};

Defined in: packages/sage/src/fleets/warp-lane-estimate.ts:16

x

readonly x: bigint;

y

readonly y: bigint;

speedRaw

readonly speedRaw: bigint;

Defined in: packages/sage/src/fleets/warp-lane-estimate.ts:18

toRaw

readonly toRaw: {
  x: bigint;
  y: bigint;
};

Defined in: packages/sage/src/fleets/warp-lane-estimate.ts:17

x

readonly x: bigint;

y

readonly y: bigint;

---

FleetWarpLanePolicy

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:52

Policy result only: passing never proves travel eligibility or affordability.

Example

declare const assessment: FleetWarpLanePolicy;
console.log(assessment.passesPolicy, assessment.failures);

Properties

effectiveRisk

readonly effectiveRisk:
  | {
  faction: FactionAlignment;
  kind: "low";
}
  | {
  kind: "medium" | "high";
};

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:55

failures

readonly failures: readonly FleetWarpLanePolicyFailure[];

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:54

passesPolicy

readonly passesPolicy: boolean;

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:53

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:56

Returns

unknown

---

FleetWarpLanePolicyInput

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:15

Explicit lane policy inputs; destinationRegion must contain the destination coordinates. A System’s stored region id alone does not establish this spatial relationship.

Example

declare const input: FleetWarpLanePolicyInput;
console.log(input.destinationRegion.risk, input.securityZoneAccess);

Properties

crossFactionEconomicsEnabled

readonly crossFactionEconomicsEnabled: boolean;

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:21

destinationLevel

readonly destinationLevel: WorldStarbaseLevel;

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:20

destinationOwner

readonly destinationOwner: WorldFaction;

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:18

destinationRegion

readonly destinationRegion: Pick<FactionRegionData, "owner" | "safety" | "risk">;

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:22

enemyFactionZoneAccess

readonly enemyFactionZoneAccess: boolean;

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:28

The Character’s enemy-faction-zone access research.

fleetFaction

readonly fleetFaction: WorldFaction;

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:16

securityZoneAccess

readonly securityZoneAccess: RiskZoneAccess;

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:26

sourceLevel

readonly sourceLevel: WorldStarbaseLevel;

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:19

sourceOwner

readonly sourceOwner: WorldFaction;

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:17

---

FleetWarpLaneToll

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:45

Character’s prospective ATLAS debit, entirely in raw ATLAS units (Floyds).

Example

declare const toll: FleetWarpLaneToll;
console.log(toll.modifiedBaseRaw, toll.surchargeRaw, toll.totalRaw);

Properties

baseRaw

readonly baseRaw: bigint;

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:46

modifiedBaseRaw

readonly modifiedBaseRaw: bigint;

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:47

surchargeRaw

readonly surchargeRaw: bigint;

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:48

totalRaw

readonly totalRaw: bigint;

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:49

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:50

Returns

unknown

---

FleetWarpLaneTollInput

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:18

Current source connection costs, ownership and Character fee modifier. destinationRelationship is Fleet-to-destination-owner, not endpoint-to-endpoint.

Example

declare const input: FleetWarpLaneTollInput;
console.log(input.sourceLevel, input.feeModifierRaw);

Properties

alliedTollBps

readonly alliedTollBps: number;

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:34

costs

readonly costs: Pick<WorldConnectionCosts,
  | "level1Raw"
  | "level2Raw"
  | "level3Raw"
  | "level4Raw"
  | "level5Raw"
| "cssRaw">;

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:19

destinationOwner

readonly destinationOwner: WorldFaction;

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:31

destinationRelationship

readonly destinationRelationship: FactionRelationship;

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:32

feeModifierRaw

readonly feeModifierRaw: bigint;

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:33

fleetFaction

readonly fleetFaction: WorldFaction;

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:29

neutralTollBps

readonly neutralTollBps: number;

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:35

sourceLevel

readonly sourceLevel: WorldStarbaseLevel;

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:28

sourceOwner

readonly sourceOwner: WorldFaction;

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:30

---

ResolvedFleetAccountData

Defined in: packages/sage/src/internal/fleet.ts:85

Fleet data after joining account ids against the lazy definitions registry.

Example

declare const fleet: ResolvedFleetAccountData;
const shipName = fleet.ships[0]?.name;

Extends

• Omit<FleetAccountData, | "fleetShips" | "fuelTank" | "ammoBank" | "cargoHold" | "components" | "respawningCargo" | "state" | "subProfile">

Properties

activeStimulants

readonly activeStimulants: readonly {
  chargesRemaining: number;
  deltaBps: number;
  stat: number;
}[];

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

Inherited from

FleetAccountData.activeStimulants

ammo

readonly ammo: ResolvedCargoAmount;

Defined in: packages/sage/src/internal/fleet.ts:101

ap

readonly ap: number;

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

Banked AP. The game refills it right after an attack, so usable AP is zero until chain time reaches apReloadExpiresAt.

Inherited from

FleetAccountData.ap

apReloadExpiresAt

readonly apReloadExpiresAt: bigint;

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

Inherited from

FleetAccountData.apReloadExpiresAt

bump

readonly bump: number;

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

Inherited from

FleetAccountData.bump

capacities

readonly capacities: {
  ammo: CapacitySummary;
  cargo: CapacitySummary;
  fuel: CapacitySummary;
};

Defined in: packages/sage/src/internal/fleet.ts:117

ammo

readonly ammo: CapacitySummary;

cargo

readonly cargo: CapacitySummary;

fuel

readonly fuel: CapacitySummary;

cargoHold

readonly cargoHold: {
  items: readonly ResolvedCargoAmount[];
  seqId: number;
  storageCost: bigint;
};

Defined in: packages/sage/src/internal/fleet.ts:102

items

readonly items: readonly ResolvedCargoAmount[];

seqId

readonly seqId: number;

storageCost

readonly storageCost: bigint;

components

readonly components: {
  items: readonly ResolvedCargoAmount[];
  seqId: number;
  storageCost: bigint;
};

Defined in: packages/sage/src/internal/fleet.ts:107

items

readonly items: readonly ResolvedCargoAmount[];

seqId

readonly seqId: number;

storageCost

readonly storageCost: bigint;

crewCount

readonly crewCount: number;

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

Inherited from

FleetAccountData.crewCount

faction

readonly faction: "unaligned" | "mud" | "oni" | "ustur";

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

Inherited from

FleetAccountData.faction

fuel

readonly fuel: ResolvedCargoAmount;

Defined in: packages/sage/src/internal/fleet.ts:100

game

readonly game: Address;

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

Inherited from

FleetAccountData.game

hp

readonly hp: number;

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

Inherited from

FleetAccountData.hp

lastCombatUpdate

readonly lastCombatUpdate: bigint;

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

Inherited from

FleetAccountData.lastCombatUpdate

lastUpdateAt

readonly lastUpdateAt: bigint;

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

Inherited from

FleetAccountData.lastUpdateAt

location

readonly location: WorldCoordinates;

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

Inherited from

FleetAccountData.location

locationRaw

readonly locationRaw: {
  x: bigint;
  y: bigint;
};

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

Exact stored I8F56 coordinates; use these for arithmetic, not the display numbers.

x

readonly x: bigint;

y

readonly y: bigint;

Inherited from

FleetAccountData.locationRaw

name

readonly name: string;

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

Inherited from

FleetAccountData.name

npcFactionId

readonly npcFactionId: number;

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

Inherited from

FleetAccountData.npcFactionId

ownerProfile

readonly ownerProfile: Address;

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

Inherited from

FleetAccountData.ownerProfile

pendingHp

readonly pendingHp: number;

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

Inherited from

FleetAccountData.pendingHp

rentedCrew

readonly rentedCrew: number;

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

Inherited from

FleetAccountData.rentedCrew

respawningCargo

readonly respawningCargo: {
  items: readonly ResolvedCargoAmount[];
  seqId: number;
  storageCost: bigint;
};

Defined in: packages/sage/src/internal/fleet.ts:112

items

readonly items: readonly ResolvedCargoAmount[];

seqId

readonly seqId: number;

storageCost

readonly storageCost: bigint;

scanCooldownExpiresAt

readonly scanCooldownExpiresAt: bigint;

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

Inherited from

FleetAccountData.scanCooldownExpiresAt

shieldBreakDelayExpiresAt

readonly shieldBreakDelayExpiresAt: bigint;

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

Inherited from

FleetAccountData.shieldBreakDelayExpiresAt

shipCounts

readonly shipCounts: FleetShipCountsData;

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

Inherited from

FleetAccountData.shipCounts

shipDefinitionsSeqId

readonly shipDefinitionsSeqId: number;

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

Inherited from

FleetAccountData.shipDefinitionsSeqId

ships

readonly ships: readonly ResolvedShipAmount[];

Defined in: packages/sage/src/internal/fleet.ts:99

sp

readonly sp: number;

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

Inherited from

FleetAccountData.sp

stance

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

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

ammoUsage

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

Inherited from

FleetAccountData.stance

state

readonly state: ResolvedFleetState;

Defined in: packages/sage/src/internal/fleet.ts:122

stats

readonly stats: FleetStatsData;

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

Inherited from

FleetAccountData.stats

subProfile?

readonly optional subProfile?: Address;

Defined in: packages/sage/src/internal/fleet.ts:98

The renter’s Profile, or the SAGE program address while the Fleet is listed for rent with no renter; omitted when the Fleet has no rental.

subProfileInvalidator

readonly subProfileInvalidator: Address;

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

Who may end the Fleet’s rental: the owner Profile unless a rental listing named another account. Always holds an address.

Inherited from

FleetAccountData.subProfileInvalidator

version

readonly version: number;

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

Inherited from

FleetAccountData.version

warpCooldownExpiresAt

readonly warpCooldownExpiresAt: bigint;

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

Inherited from

FleetAccountData.warpCooldownExpiresAt

---

SubwarpPosition

Defined in: packages/sage/src/internal/fleet.ts:378

Display-only interpolation matching incremental on-chain subwarp settlement.

Example

declare const subwarp: SubwarpPosition;
if (subwarp.displayOnly) console.log(subwarp.position, subwarp.progress);

Properties

displayOnly

readonly displayOnly: true;

Defined in: packages/sage/src/internal/fleet.ts:379

position

readonly position: WorldCoordinates;

Defined in: packages/sage/src/internal/fleet.ts:380

progress

readonly progress: number;

Defined in: packages/sage/src/internal/fleet.ts:381

---

WorldCoordinates

Defined in: packages/sage/src/internal/c4/world.ts:91

A position in the shared SAGE coordinate space, in gameplay units.

Example

const coordinates: WorldCoordinates = { x: 1, y: 2 };

Properties

x

readonly x: number;

Defined in: packages/sage/src/internal/c4/world.ts:92

y

readonly y: number;

Defined in: packages/sage/src/internal/c4/world.ts:93

Type Aliases

FleetDiscoveryOptions

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

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

Options supported by targeted Fleet discovery.

Example

declare const ctx: SageContext;
declare const profileAddress: Address;
const options: FleetDiscoveryOptions = {
  commitment: 'confirmed',
  policy: 'no-store',
};
const fleets = await getFleetsByOwner(ctx, profileAddress, options);

---

FleetMovementCooldownInput

type FleetMovementCooldownInput =
  | {
  arrivesAtUnixSeconds: bigint;
  baseCooldownSeconds: number;
  cooldownModifierRaw: bigint;
  kind: "coordinateWarp";
}
  | {
  departsAtUnixSeconds: bigint;
  existingCooldownExpiresAt: bigint;
  kind: "warpLane";
}
  | {
  existingCooldownExpiresAt: bigint;
  kind: "subwarp";
};

Defined in: packages/sage/src/fleets/cooldown.ts:13

Explicit inputs for cooldown assignment, not permission to move. The Character modifier is its raw I32F32 value, not its display number.

Example

const input: FleetMovementCooldownInput = {
  kind: 'coordinateWarp', arrivesAtUnixSeconds: 1_800_000_000n,
  baseCooldownSeconds: 60, cooldownModifierRaw: 4_294_967_296n,
};

---

FleetStateData

type FleetStateData =
  | {
  kind: "idle";
}
  | {
  claimStake: Address;
  endAtUnixSeconds: bigint;
  kind: "claimStakeTransfer";
  load: readonly FleetCargoAmountData[];
  planet: Address;
  unload: readonly FleetCargoAmountData[];
}
  | {
  kind: "destroyed";
}
  | {
  kind: "docked";
  system: Address;
  systemSeqId: bigint;
}
  | {
  asteroid: Address;
  kind: "mining";
  regionXpModifier: number;
  regionXpModifierRaw: bigint;
  resourceIds: readonly number[];
}
  | {
  arrivesAtUnixSeconds: bigint;
  departsAtUnixSeconds: bigint;
  kind: "warp";
  to: WorldCoordinates;
}
  | {
  arrivesAtUnixSeconds: bigint;
  departsAtUnixSeconds: bigint;
  durationSeconds: number;
  durationSecondsRaw: bigint;
  from: WorldCoordinates;
  kind: "subwarp";
  to: WorldCoordinates;
  totalFuelExpenditure: number;
  totalFuelExpenditureRaw: bigint;
  totalXp: number;
  totalXpRaw: bigint;
}
  | {
  kind: "respawn";
  recoversAtUnixSeconds: bigint;
  startedAtUnixSeconds: bigint;
  wasInLowRiskZone: boolean;
};

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

Stable translated Fleet movement state, exhaustive for the pinned bindings.

Example

declare const state: FleetStateData;
if (state.kind === 'docked') console.log(state.system);

---

FleetWarpLanePolicyFailure

type FleetWarpLanePolicyFailure =
  | "source-level-zero"
  | "destination-level-zero"
  | "cross-faction-disabled"
  | "foreign-low-risk"
  | "security-zone-access"
  | "region-owner-access";

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:37

A bounded policy failure, not a simulation or transaction error.

Example

const reason: FleetWarpLanePolicyFailure = 'foreign-low-risk';

Functions

deriveFleetCompositionStats()

function deriveFleetCompositionStats(input): FleetCompositionStats;

Defined in: packages/sage/src/fleets/composition-stats.ts:348

Projects the stats a Fleet stores after ship assembly, exactly as the program aggregates them; verified against the program’s behaviour. Capacities, Fuel and upkeep rates, mining and load rates, crew, AP/HP/SP and damage are added and capped. Subwarp, warp and lane speeds take the lowest value. Maximum warp distance, warp cooldown, warp spool, shield break delay, damage variance, respawn times and scan cooldown take the highest. Stealth, hit, aim and critical values are truncated per-ship averages, which the program rescales on every addition, so one addition of two ships can differ from two additions of one. Repair cost (weighted by hull points) and repair efficiency (weighted by repair ability) are recomputed over every ship aboard.

A Fleet on the definitions’ sequence builds on its stored stats and counts. One on an older sequence is first rebuilt from the current definitions of the ships aboard, as the program does before adding ships. A missing ship definition, mixed definition sequences, an amount outside 1n-255n or an overflow the program refuses throw InvalidDerivationInputError; other inputs are trusted as typed.

Character research does not change stored stats: pass the Character’s raw speed and cooldown modifiers to the travel helpers at use time. This is not an eligibility check (planAddShipToFleet applies ship size, research tags, Fleet size and formation limits), and checks no funding, entitlement or crew provisioning. Current AP, SP and HP are not projected. Read the Fleet back after confirmation; the chain stays authoritative. Requalify after program changes.

Parameters

Parameter	Type
input	FleetCompositionStatsInput

Returns

FleetCompositionStats

Example

declare const ctx: SageContext, fleet: FleetSnapshot, character: CharacterSnapshot;
const projected = deriveFleetCompositionStats({
  definitions: await listShipConfigurations(ctx),
  fleet,
  additions: [{ shipId: 12, amount: 1n }],
});
const travel = deriveFleetTravelProfile({
  stats: projected.stats,
  subwarpSpeedModifierRaw: character.modifiers.values.subwarpSpeedModifierRaw,
});
console.log(projected.stats.cargo.miningRate.value, travel.subwarp?.secondsPerAu);

---

deriveFleetCoordinateWarpEstimate()

function deriveFleetCoordinateWarpEstimate(input): FleetCoordinateWarpEstimate;

Defined in: packages/sage/src/fleets/coordinate-warp-estimate.ts:69

Estimates a coordinate warp from Idle using deployment-54356023 arithmetic. Truncates each squared axis before distance calculation, divides duration by base speed and then modifier, rounds travel and Fuel upward, and adds spool. Zero speed modifier means neutral. Exact computed maximum range is inclusive.

Coordinates, axis differences and distance must fit signed I8F56, with distinct endpoints. Speed is positive u32 raw, Fuel rate u32 raw, modifier nonnegative i64 raw, spool an integer 0..65535 and range u16 raw. Unsupported inputs are rejected. Tiny distinct points can produce only spool time and zero Fuel. Out-of-range trips still return estimates with withinRange=false.

No planet-exit surcharge, XP, cooldown, route policy, Fleet state, crew, permissions or available Fuel are checked. Use the exact encoded destination and Fleet.locationRaw; simulate the actual Plan before signing. Requalify after relevant program changes. Use deriveFleetMovementCooldown separately.

Parameters

Parameter	Type
input	FleetCoordinateWarpEstimateInput

Returns

FleetCoordinateWarpEstimate

Example

const estimate = deriveFleetCoordinateWarpEstimate({
  fromRaw: { x: 0n, y: 0n }, toRaw: { x: 1n << 56n, y: 0n },
  speedRaw: 65536n, fuelRateRaw: 64n, speedModifierRaw: 4294967296n,
  spoolSeconds: 3, maxWarpDistanceRaw: 256n,
}); // 4 seconds including spool, 1 Fuel, within range

---

deriveFleetMovementCooldown()

function deriveFleetMovementCooldown(input): bigint;

Defined in: packages/sage/src/fleets/cooldown.ts:59

Predicts the assigned warp-cooldown expiry in Unix seconds for a movement. Coordinate warp anchors at arrival and rounds the modified base upward; a zero modifier uses the unmodified base. Lane warp adds no cooldown but never erases an active one: the expiry becomes the later of the existing expiry and the departure time. Subwarp preserves the existing expiry.

Coordinate-warp arithmetic is qualified against PTR deployment slot 54356023; the lane rule follows the current program. Coordinate/lane timestamps must be nonnegative signed-i64 values, base seconds an integer in 0..65535, and modifier raw a nonnegative signed-i64 value. Overflow is rejected. An existing expiry may be any signed-i64 value, including sentinels. This pure helper does not calculate journey duration or check state, active cooldown, permissions, Fuel or lane eligibility. Use deriveFleetTimers for observed timer display and simulate the intended action before signing.

Parameters

Parameter	Type
input	FleetMovementCooldownInput

Returns

bigint

Example

const expiry = deriveFleetMovementCooldown({
  kind: 'coordinateWarp', arrivesAtUnixSeconds: 1_800_000_000n,
  baseCooldownSeconds: 61, cooldownModifierRaw: 2_147_483_648n,
}); // 1_800_000_031n

---

deriveFleetSubwarpEstimate()

function deriveFleetSubwarpEstimate(input): FleetSubwarpEstimate;

Defined in: packages/sage/src/fleets/subwarp-estimate.ts:73

Estimates direct subwarp duration and recorded fractional Fuel expenditure. Qualified against PTR deployment slot 54356023, with exact integer rounding within the supported model. Each squared axis truncates before the square root; base-speed division precedes modifier division. Modifier zero means 1.

Coordinates, axis differences and distance must fit signed I8F56; endpoints must differ. Speed is positive u32 raw, Fuel rate u32 raw and modifier nonnegative i64 raw. These bounds keep intermediate arithmetic within i128. A route shorter than the program can measure (its squared length truncates to zero, a displacement below 2^28 raw quanta on both axes) is rejected, because the program refuses to start such a subwarp.

Applies to departure from Idle, not planet departure, warp or lane travel. Does not check Fleet state, crew, permissions, tank Fuel, readiness or region restrictions. Subwarp may start with insufficient Fuel; compare fuelBudget with the tank and simulate before signing. No planet-exit surcharge or XP is predicted. Requalify this model after relevant program changes.

Parameters

Parameter	Type
input	FleetSubwarpEstimateInput

Returns

FleetSubwarpEstimate

Example

const journey = deriveFleetSubwarpEstimate({
  fromRaw: { x: 0n, y: 0n }, toRaw: { x: 1n << 56n, y: 0n },
  speedRaw: 65536n, fuelRateRaw: 64n, speedModifierRaw: 4294967296n,
}); // 1 second, budget 1 Fuel

---

deriveFleetTimers()

function deriveFleetTimers<TState>(fleet): FleetTimers;

Defined in: packages/sage/src/internal/fleet.ts:328

Derives only active Fleet timers; non-positive sentinels and values outside JavaScript’s supported Date range stay absent.

Type Parameters

Type Parameter
TState extends FleetTimerState

Parameters

Parameter	Type
fleet	Pick<FleetAccountData, | "warpCooldownExpiresAt" | "scanCooldownExpiresAt" | "apReloadExpiresAt" | "shieldBreakDelayExpiresAt"> & { state: TState; }

Returns

FleetTimers

Example

declare const fleet: FleetSnapshot;
const timers = deriveFleetTimers(fleet);
console.log(
  timers.warpCooldownEndsAt?.toISOString(),
  timers.transferEndsAt?.toISOString(),
);

---

deriveFleetTravelProfile()

function deriveFleetTravelProfile(input): FleetTravelProfile;

Defined in: packages/sage/src/fleets/travel-profile.ts:130

Derives reference travel values from Fleet or ship configuration stats, using the qualified subwarp, coordinate-warp, warp-lane and cooldown arithmetic (PTR deployment slot 54356023) on one-AU and maximum-range trips from Idle. Full-tank range inverts the qualified Fuel rate; sustained warp speed chains maximum-range warps, each waiting out the cooldown assigned at arrival.

These are reference values, not a route or permission check: no planet departure, region policy, lane connectivity or toll, crew, XP, active timers or current tank are considered, and whether a warp may depart with less Fuel than its debit is not established. A configuration’s stats describe one ship; stats of Fleets mixing configurations are not qualified here.

Parameters

Parameter	Type
input	FleetTravelProfileInput

Returns

FleetTravelProfile

Throws

InvalidDerivationInputError for a maximum warp distance of 128 AU or more, or modifiers and stats outside the movement estimates’ bounds.

Example

const profile = deriveFleetTravelProfile({
  stats: {
    movement: {
      subwarpSpeed: { raw: 65536n, value: 1 },
      subwarpFuelConsumptionRate: { raw: 64n, value: 1 },
      warpSpeed: { raw: 65536n, value: 1 },
      warpFuelConsumptionRate: { raw: 128n, value: 2 },
      maxWarpDistance: { raw: 512n, value: 2 },
      warpCoolDownSeconds: 6,
      warpLaneSpeed: { raw: 131072n, value: 2 },
    },
    cargo: { fuelCapacity: 100n },
    combat: { warpSpoolTimeSeconds: 2 },
  },
});
console.log(profile.subwarp?.fullTankRangeAu); // 100
console.log(profile.coordinateWarp?.cycleSeconds); // 10n: 2 spool + 2 travel + 6 cooldown

---

deriveFleetWarpLaneEstimate()

function deriveFleetWarpLaneEstimate(input): FleetWarpLaneEstimate;

Defined in: packages/sage/src/fleets/warp-lane-estimate.ts:58

Estimates lane travel using empirically qualified deployment-54356023 arithmetic. Truncates each squared axis, computes distance, truncates fixed-point speed division and rounds duration upward to whole seconds. No Fuel is debited.

Coordinates, axis differences and distance must fit signed I8F56. Speed is positive u32 raw. Identical and zero-quantized paths are rejected rather than predicting a successful zero-time lane. Unsupported overflow is rejected.

Supply exact System coordinates and Fleet lane speed, not coordinate-warp stats. This checks no lane connection, policy, toll, affordability, cooldown, Fleet state, crew, XP or permissions. Use deriveFleetMovementCooldown for cooldown separately. Refresh and simulate the Plan before signing; requalify the arithmetic after relevant program changes.

Parameters

Parameter	Type
input	FleetWarpLaneEstimateInput

Returns

FleetWarpLaneEstimate

Example

const estimate = deriveFleetWarpLaneEstimate({
  fromRaw: { x: 0n, y: 0n }, toRaw: { x: 1n << 56n, y: 0n },
  speedRaw: 65536n,
}); // durationSeconds: 1n, fuelDebit: 0n

---

deriveFleetWarpLanePolicy()

function deriveFleetWarpLanePolicy(input): FleetWarpLanePolicy;

Defined in: packages/sage/src/fleets/warp-lane-policy.ts:88

Assesses qualified lane policy independently of Plan validation or execution. Both endpoint owners must equal Fleet faction when cross-faction economics is disabled. Both endpoint Starbases need nonzero levels. Stored low risk keeps its embedded faction; a Safe medium/high region owned by a playable faction becomes low risk of that owner, while Border and Unaligned-owned regions retain their tier. Foreign low risk rejects; higher tiers require sufficient Character access, and entry to a medium/high region owned by another playable faction also needs the Character’s enemy-faction-zone access. Relationships and combat/territory gates do not block the lane policy.

Only playable factions (the destination region may also be Unaligned) and known levels/tiers are supported. Resolve the region containing the destination coordinates before calling: this pure helper does not perform spatial lookup and does not trust a System region id on your behalf. It checks no connection, Fleet state, cooldown, crew, XP, permission, toll or available balance. Deployment 54356023 is the empirical scope; requalify on relevant game changes and simulate before signing.

Parameters

Parameter	Type
input	FleetWarpLanePolicyInput

Returns

FleetWarpLanePolicy

Example

const result = deriveFleetWarpLanePolicy({
  fleetFaction: 'oni', sourceOwner: 'oni', destinationOwner: 'oni',
  sourceLevel: 'css', destinationLevel: 'level-1',
  crossFactionEconomicsEnabled: false, securityZoneAccess: 'low',
  enemyFactionZoneAccess: false,
  destinationRegion: { owner: 'oni', safety: 'safe',
    risk: { kind: 'low', faction: 'oni' } },
}); // passesPolicy: true; still simulate the actual Plan

---

deriveFleetWarpLaneToll()

function deriveFleetWarpLaneToll(input): FleetWarpLaneToll;

Defined in: packages/sage/src/fleets/warp-lane-toll.ts:79

Estimates the Character ATLAS toll using deployment-54356023 lane rules. Selects cost by departure level. Ceils the Character-modified base, then adds a separately floored surcharge on the unmodified base if either endpoint is foreign. Allied uses allied bps; neutral/hostile/ceasefire use neutral bps. A foreign source with own destination uses neutral bps. Modifier zero waives only the modified base. Relationship expiry does not alter the measured toll.

Accepts playable factions only, usable source levels, u64 raw base cost, nonnegative i64 raw I32F32 modifier, and u16 bps. Rejects a result beyond u64. No RPC, balance, connection, region, permission or execution checks occur. ATLAS is paid from Character, not wallet. Requalify after program changes.

Parameters

Parameter	Type
input	FleetWarpLaneTollInput

Returns

FleetWarpLaneToll

Example

declare const input: FleetWarpLaneTollInput;
const toll = deriveFleetWarpLaneToll(input);
console.log(toll.totalRaw);

---

discoverFleetAddresses()

function discoverFleetAddresses(ctx, options?): Promise<readonly Address[]>;

Defined in: packages/sage/src/fleets/index.ts:381

Discovers every Fleet address for the configured Game.

The existing discovery data plane downloads and validates complete Fleet account bytes before exposing an address. It does not hydrate Fleet snapshots or load ship, cargo, or Game registry definitions.

Parameters

Parameter	Type
ctx	SageContext
options?	FleetDiscoveryOptions

Returns

Promise<readonly Address[]>

Example

declare const ctx: SageContext;
const fleetAddresses = await discoverFleetAddresses(ctx);
console.log(fleetAddresses, readMeta(fleetAddresses)?.strategy);

---

getFleet()

function getFleet(
   ctx,
   address,
options?): Promise<FleetSnapshot>;

Defined in: packages/sage/src/fleets/index.ts:223

Reads a required Fleet by account address.

Parameters

Parameter	Type
ctx	SageContext
address	Address
options?	ReadOptions

Returns

Promise<FleetSnapshot>

Example

declare const ctx: SageContext;
declare const fleetAddress: Address;
const fleet = await getFleet(ctx, fleetAddress);

---

getFleets()

function getFleets(
   ctx,
   addresses,
options?): Promise<readonly FleetSnapshot[]>;

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

Reads required Fleets by account address in one batched data-plane request.

The frozen result preserves input order and duplicate positions. Every requested address must exist; use separate optional reads when absence is an expected outcome.

Parameters

Parameter	Type
ctx	SageContext
addresses	readonly Address[]
options?	ReadOptions

Returns

Promise<readonly FleetSnapshot[]>

Example

declare const ctx: SageContext;
declare const fleetAddresses: readonly Address[];
const fleets = await getFleets(ctx, fleetAddresses);

---

getFleetsByOwner()

function getFleetsByOwner(
   ctx,
   profileAddress,
options?): Promise<readonly FleetSnapshot[]>;

Defined in: packages/sage/src/fleets/index.ts:355

Discovers Fleets owned by a known Player Profile using targeted stable filters.

Parameters

Parameter	Type
ctx	SageContext
profileAddress	Address
options?	FleetDiscoveryOptions

Returns

Promise<readonly FleetSnapshot[]>

Example

declare const ctx: SageContext;
declare const profileAddress: Address;
const fleets = await getFleetsByOwner(ctx, profileAddress);

---

interpolateSubwarpPosition()

function interpolateSubwarpPosition(state, atUnixSeconds): SubwarpPosition;

Defined in: packages/sage/src/internal/fleet.ts:395

Interpolates a display-only subwarp position, clamped to both endpoints.

The result must not be used as authoritative on-chain position state.

Parameters

Parameter	Type
state	{ arrivesAtUnixSeconds: bigint; departsAtUnixSeconds: bigint; durationSeconds: number; durationSecondsRaw: bigint; from: WorldCoordinates; kind: "subwarp"; to: WorldCoordinates; totalFuelExpenditure: number; totalFuelExpenditureRaw: bigint; totalXp: number; totalXpRaw: bigint; }
state.arrivesAtUnixSeconds	bigint
state.departsAtUnixSeconds	bigint
state.durationSeconds	number
state.durationSecondsRaw	bigint
state.from	WorldCoordinates
state.kind	"subwarp"
state.to	WorldCoordinates
state.totalFuelExpenditure	number
state.totalFuelExpenditureRaw	bigint
state.totalXp	number
state.totalXpRaw	bigint
atUnixSeconds	bigint

Returns

SubwarpPosition

Example

declare const state: Extract<FleetStateData, { readonly kind: 'subwarp' }>;
const position = interpolateSubwarpPosition(state, 1_700_000_000n);
console.log(position.position, position.progress);

---

maybeGetFleet()

function maybeGetFleet(
   ctx,
   address,
options?): Promise<FleetSnapshot | undefined>;

Defined in: packages/sage/src/fleets/index.ts:283

Reads an optional Fleet by account address.

Parameters

Parameter	Type
ctx	SageContext
address	Address
options?	ReadOptions

Returns

Promise<FleetSnapshot | undefined>

Example

declare const ctx: SageContext;
declare const fleetAddress: Address;
const fleet = await maybeGetFleet(ctx, fleetAddress);

---

watchFleet()

function watchFleet(
   ctx,
   address,
   observer,
options?): Promise<SageSubscription>;

Defined in: packages/sage/src/fleets/index.ts:313

Watches one Fleet through its context-owned WebSocket subscription.

Registration emits the current validated Fleet first, then only selected slot/commitment advances. Unsubscribe explicitly or dispose the context.

Parameters

Parameter	Type
ctx	SageContext
address	Address
observer	FleetSubscriptionObserver
options?	ReadAccountOptions

Returns

Promise<SageSubscription>

Example

declare const ctx: SageContext;
declare const fleetAddress: Address;
const subscription = await watchFleet(ctx, fleetAddress, {
  onSnapshot: fleet => console.log(fleet.name),
  onError: error => console.error(error.code),
});
await subscription.unsubscribe();

References

FleetCombatStatsData

Re-exports FleetCombatStatsData

---

listShipConfigurations

Re-exports listShipConfigurations

---

listShipConfigurationsByMint

Re-exports listShipConfigurationsByMint