world

Interfaces

AsteroidSnapshot

Defined in: packages/sage/src/world/index.ts:195

Immutable Asteroid projection over a CelestialBody account.

Example

declare const asteroid: AsteroidSnapshot;
console.log(asteroid.details.resources);

Extends

• Omit<AsteroidAccountData, "system">

Properties

address

readonly address: Address;

Defined in: packages/sage/src/world/index.ts:196

details

readonly details: WorldAsteroidData;

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

Inherited from

Omit.details

game

readonly game: Address;

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

Inherited from

Omit.game

id

readonly id: number;

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

Inherited from

Omit.id

kind

readonly kind: "asteroid";

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

Inherited from

Omit.kind

lastSyncAtUnixSeconds

readonly lastSyncAtUnixSeconds: bigint;

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

Inherited from

Omit.lastSyncAtUnixSeconds

name

readonly name: string;

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

Inherited from

Omit.name

system

readonly system: EntityRef<"starSystem">;

Defined in: packages/sage/src/world/index.ts:197

systemSequenceId

readonly systemSequenceId: bigint;

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

Inherited from

Omit.systemSequenceId

version

readonly version: number;

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

Inherited from

Omit.version

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/world/index.ts:198

Returns

unknown

---

PlanetClaimStakePlotDefinition

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:115

One Claim Stake definition of a tier and whether the Planet suits it.

requiredTagsProvided is true when the Planet provides every tag the definition requires. It is not a complete eligibility verdict: permissions, rent, faction rules and concurrent placements remain chain-authoritative.

Example

declare const entry: PlanetClaimStakePlotDefinition;
console.log(entry.definition.name, entry.requiredTagsProvided);

Properties

definition

readonly definition: GameClaimStakeDefinitionData;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:116

requiredTagsProvided

readonly requiredTagsProvided: boolean;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:117

---

PlanetClaimStakePlotRow

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:95

One plot row of a Planet: the Claim Stakes placed at one Starbase level.

The program records placed stakes per Starbase level row, not per Claim Stake definition. occupied counts every stake in the row, of every tier and including deactivated stakes that still hold their plot. chronology is the stored placement order the program uses to index the row’s stakes.

Example

declare const row: PlanetClaimStakePlotRow;
console.log(row.level, row.occupied);

Properties

chronology

readonly chronology: readonly Address[];

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:100

level

readonly level: WorldStarbaseLevel;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:96

levelIndex

readonly levelIndex: number;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:97

occupied

readonly occupied: number;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:98

structures

readonly structures: readonly PlanetClaimStakePlotStructure[];

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:99

---

PlanetClaimStakePlotsSnapshot

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:165

Immutable Claim Stake plot availability of one Planet.

rows always holds the seven plot rows in Starbase level order, and tiers the five Claim Stake tiers in order. starbaseLevel and starbaseLevelIndex come from the Planet’s StarSystem and are absent when that System has no Starbase. Read metadata reports the older of the Planet and StarSystem observations.

Example

declare const plots: PlanetClaimStakePlotsSnapshot;
const open = plots.tiers.filter((tier) => (tier.available ?? 0) > 0);
console.log(plots.name, open.map((tier) => tier.tier));

Properties

address

readonly address: Address;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:167

bodyId

readonly bodyId: number;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:168

game

readonly game: Address;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:170

kind

readonly kind: "planetClaimStakePlots";

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:166

name

readonly name: string;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:169

providedTags

readonly providedTags: readonly number[];

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:174

rows

readonly rows: readonly PlanetClaimStakePlotRow[];

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:175

starbaseLevel?

readonly optional starbaseLevel?: WorldStarbaseLevel;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:172

starbaseLevelIndex?

readonly optional starbaseLevelIndex?: number;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:173

system

readonly system: EntityRef<"starSystem">;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:171

tiers

readonly tiers: readonly PlanetClaimStakePlotTier[];

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:176

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:177

Returns

unknown

---

PlanetClaimStakePlotStructure

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:76

One Claim Stake structure recorded on a Planet plot.

active is true while the stored deactivation time is zero. A deactivated structure still occupies its plot until the program removes it from the Planet.

Example

declare const structure: PlanetClaimStakePlotStructure;
console.log(structure.address, structure.active);

Properties

active

readonly active: boolean;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:79

address

readonly address: Address;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:77

deactivationTimeUnixSeconds

readonly deactivationTimeUnixSeconds: bigint;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:78

---

PlanetClaimStakePlotTier

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:139

Plot limits and availability for one Claim Stake tier on a Planet.

plotLimitByLevel, baseRentRateByLevel and basePlacementFeeByLevel list the stored cell of every plot row in starbaseLevelIndex order. A row’s limit caps the stakes of all tiers in that row: placing a stake of this tier needs a row whose occupied count is below this tier’s limit. The program uses the first such row from level-0 up to the System’s Starbase level; placementLevel names it. available sums the free plots of this tier over those rows. Both are absent when the System has no Starbase. Tiers share rows, so availability across tiers does not add up. Definition multipliers and the exact rent and fee settlement remain program-authoritative.

Example

declare const tier: PlanetClaimStakePlotTier;
console.log(tier.tier, tier.available, tier.placementLevel);

Properties

available?

readonly optional available?: number;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:145

basePlacementFeeByLevel

readonly basePlacementFeeByLevel: readonly WorldFixedValue[];

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:144

baseRentRateByLevel

readonly baseRentRateByLevel: readonly WorldFixedValue[];

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:143

definitions

readonly definitions: readonly PlanetClaimStakePlotDefinition[];

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:147

placementLevel?

readonly optional placementLevel?: WorldStarbaseLevel;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:146

plotLimitByLevel

readonly plotLimitByLevel: readonly number[];

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:142

tier

readonly tier: ClaimStakeTier;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:140

tierIndex

readonly tierIndex: number;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:141

---

PlanetResourceItem

Defined in: packages/sage/src/world/index.ts:163

One registry-resolved resource row observed in a Planet account.

Example

declare const resource: PlanetResourceItem;
console.log(resource.cargo.name, resource.richness.value);

Properties

cargo

readonly cargo: CargoDefinitionSummary;

Defined in: packages/sage/src/world/index.ts:164

richness

readonly richness: WorldFixedValue;

Defined in: packages/sage/src/world/index.ts:165

---

PlanetResourcesSnapshot

Defined in: packages/sage/src/world/index.ts:175

Immutable Planet resource observation with registry-resolved cargo definitions.

Example

declare const resources: PlanetResourcesSnapshot;
console.log(resources.name, resources.resources);

Properties

address

readonly address: Address;

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

bodyId

readonly bodyId: number;

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

game

readonly game: Address;

Defined in: packages/sage/src/world/index.ts:180

kind

readonly kind: "planetResources";

Defined in: packages/sage/src/world/index.ts:176

lastSyncedAtUnixSeconds

readonly lastSyncedAtUnixSeconds: bigint;

Defined in: packages/sage/src/world/index.ts:183

name

readonly name: string;

Defined in: packages/sage/src/world/index.ts:179

resources

readonly resources: readonly PlanetResourceItem[];

Defined in: packages/sage/src/world/index.ts:184

system

readonly system: EntityRef<"starSystem">;

Defined in: packages/sage/src/world/index.ts:181

systemSequenceId

readonly systemSequenceId: bigint;

Defined in: packages/sage/src/world/index.ts:182

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/world/index.ts:185

Returns

unknown

---

PlanetSnapshot

Defined in: packages/sage/src/world/index.ts:150

Immutable Planet projection over a CelestialBody account.

Planet richness gameplay use: unverified. Version-matched program evidence does not establish a consuming activity or formula for the decoded richness values in details.resources. They are distinct from Asteroid richness used by Fleet mining and from separately decoded Claim Stake building resourceExtraction rates.

Example

declare const planet: PlanetSnapshot;
console.log(planet.details.resources);

Extends

• Omit<PlanetAccountData, "system">

Properties

address

readonly address: Address;

Defined in: packages/sage/src/world/index.ts:151

details

readonly details: WorldPlanetData;

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

Inherited from

Omit.details

game

readonly game: Address;

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

Inherited from

Omit.game

id

readonly id: number;

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

Inherited from

Omit.id

kind

readonly kind: "planet";

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

Inherited from

Omit.kind

lastSyncAtUnixSeconds

readonly lastSyncAtUnixSeconds: bigint;

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

Inherited from

Omit.lastSyncAtUnixSeconds

name

readonly name: string;

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

Inherited from

Omit.name

system

readonly system: EntityRef<"starSystem">;

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

systemSequenceId

readonly systemSequenceId: bigint;

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

Inherited from

Omit.systemSequenceId

version

readonly version: number;

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

Inherited from

Omit.version

Methods

toJSON()

toJSON(): unknown;

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

Returns

unknown

---

ResolvedStarbaseUpgradeMaterial

Defined in: packages/sage/src/world/starbase-status.ts:163

One upgrade material with its registry-resolved cargo definition.

Example

declare const material: ResolvedStarbaseUpgradeMaterial;
console.log(material.cargo.name, material.remaining);

Extends

• StarbaseUpgradeMaterial

Properties

cargo

readonly cargo: CargoDefinitionSummary;

Defined in: packages/sage/src/world/starbase-status.ts:164

cargoId

readonly cargoId: number;

Defined in: packages/sage/src/world/starbase-status.ts:66

Inherited from

StarbaseUpgradeMaterial.cargoId

complete

readonly complete: boolean;

Defined in: packages/sage/src/world/starbase-status.ts:70

Inherited from

StarbaseUpgradeMaterial.complete

crew

readonly crew: number;

Defined in: packages/sage/src/world/starbase-status.ts:71

Inherited from

StarbaseUpgradeMaterial.crew

deposited

readonly deposited: bigint;

Defined in: packages/sage/src/world/starbase-status.ts:68

Inherited from

StarbaseUpgradeMaterial.deposited

durationSeconds

readonly durationSeconds: number;

Defined in: packages/sage/src/world/starbase-status.ts:72

Inherited from

StarbaseUpgradeMaterial.durationSeconds

needed

readonly needed: bigint;

Defined in: packages/sage/src/world/starbase-status.ts:67

Inherited from

StarbaseUpgradeMaterial.needed

remaining

readonly remaining: bigint;

Defined in: packages/sage/src/world/starbase-status.ts:69

Inherited from

StarbaseUpgradeMaterial.remaining

---

ResolvedStarbaseUpgradeProgress

Defined in: packages/sage/src/world/starbase-status.ts:175

Upgrade progress whose materials carry resolved cargo definitions.

Example

declare const upgrade: ResolvedStarbaseUpgradeProgress;
console.log(upgrade.materials.map((material) => material.cargo.name));

Extends

• Omit<StarbaseUpgradeProgress, "materials">

Properties

complete

readonly complete: boolean;

Defined in: packages/sage/src/world/starbase-status.ts:90

Inherited from

StarbaseUpgradeProgress.complete

materials

readonly materials: readonly ResolvedStarbaseUpgradeMaterial[];

Defined in: packages/sage/src/world/starbase-status.ts:179

toLevel

readonly toLevel: WorldStarbaseLevel;

Defined in: packages/sage/src/world/starbase-status.ts:89

Inherited from

StarbaseUpgradeProgress.toLevel

---

StarbaseServiceAvailability

Defined in: packages/sage/src/world/starbase-status.ts:102

Whether one Starbase service is enabled at the current level.

Example

declare const service: StarbaseServiceAvailability;
if (service.available) console.log('enabled since', service.enabledFromLevel);

Properties

available

readonly available: boolean;

Defined in: packages/sage/src/world/starbase-status.ts:104

enabledFromLevel

readonly enabledFromLevel: WorldStarbaseLevel;

Defined in: packages/sage/src/world/starbase-status.ts:103

---

StarbaseStatus

Defined in: packages/sage/src/world/starbase-status.ts:123

Derived status of the shared Starbase nested in one StarSystem.

current pairs the stored hull and shield points with the maximums the current level configures. pendingHullPoints mirrors the stored pendingHp field as is: the pinned contract only names it, so the SDK makes no claim about when or how the program settles it into hullPoints. timing values are raw Unix seconds, as on the Fleet combat status; shield and hull settlement rules are likewise unqualified. upgrade is absent once the Starbase has reached its maximum level.

Example

declare const status: StarbaseStatus;
console.log(status.level, status.current.hullPoints, status.current.maxHullPoints);

Properties

atMaxLevel

readonly atMaxLevel: boolean;

Defined in: packages/sage/src/world/starbase-status.ts:130

current

readonly current: {
  hullPoints: number;
  maxHullPoints: number;
  maxShieldPoints: number;
  pendingHullPoints: number;
  shieldPoints: number;
};

Defined in: packages/sage/src/world/starbase-status.ts:133

hullPoints

readonly hullPoints: number;

maxHullPoints

readonly maxHullPoints: number;

maxShieldPoints

readonly maxShieldPoints: number;

pendingHullPoints

readonly pendingHullPoints: number;

shieldPoints

readonly shieldPoints: number;

kind

readonly kind: "starbaseStatus";

Defined in: packages/sage/src/world/starbase-status.ts:124

level

readonly level: WorldStarbaseLevel;

Defined in: packages/sage/src/world/starbase-status.ts:126

levelIndex

readonly levelIndex: number;

Defined in: packages/sage/src/world/starbase-status.ts:128

Ordinal from starbaseLevelIndex; the Central Space Station is 6.

levelInfo

readonly levelInfo: WorldStarbaseLevelInfoData;

Defined in: packages/sage/src/world/starbase-status.ts:132

Configured values for the current level, copied from the level table.

maxLevel

readonly maxLevel: WorldStarbaseLevel;

Defined in: packages/sage/src/world/starbase-status.ts:129

owner

readonly owner: WorldFaction;

Defined in: packages/sage/src/world/starbase-status.ts:125

services

readonly services: {
  localMarket: StarbaseServiceAvailability;
  repair: StarbaseServiceAvailability;
};

Defined in: packages/sage/src/world/starbase-status.ts:147

localMarket

readonly localMarket: StarbaseServiceAvailability;

repair

readonly repair: StarbaseServiceAvailability;

timing

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

Defined in: packages/sage/src/world/starbase-status.ts:140

builtOrDestroyedAtUnixSeconds

readonly builtOrDestroyedAtUnixSeconds: bigint;

When the Starbase was last built or destroyed.

lastCombatUpdateAtUnixSeconds

readonly lastCombatUpdateAtUnixSeconds: bigint;

shieldBreakDelayEndsAtUnixSeconds

readonly shieldBreakDelayEndsAtUnixSeconds: bigint;

When shield points may resume regenerating after reaching zero.

upgrade?

readonly optional upgrade?: StarbaseUpgradeProgress;

Defined in: packages/sage/src/world/starbase-status.ts:151

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/world/starbase-status.ts:152

Returns

unknown

---

StarbaseStatusSnapshot

Defined in: packages/sage/src/world/starbase-status.ts:193

Immutable shared Starbase status read for one StarSystem.

address is the StarSystem address: the nested Starbase has no account of its own. Read metadata comes from the StarSystem observation.

Example

declare const status: StarbaseStatusSnapshot;
console.log(status.systemName, status.upgrade?.materials[0]?.cargo.name);

Extends

• Omit<StarbaseStatus, "upgrade">

Properties

address

readonly address: Address;

Defined in: packages/sage/src/world/starbase-status.ts:197

atMaxLevel

readonly atMaxLevel: boolean;

Defined in: packages/sage/src/world/starbase-status.ts:130

Inherited from

StarbaseStatus.atMaxLevel

current

readonly current: {
  hullPoints: number;
  maxHullPoints: number;
  maxShieldPoints: number;
  pendingHullPoints: number;
  shieldPoints: number;
};

Defined in: packages/sage/src/world/starbase-status.ts:133

hullPoints

readonly hullPoints: number;

maxHullPoints

readonly maxHullPoints: number;

maxShieldPoints

readonly maxShieldPoints: number;

pendingHullPoints

readonly pendingHullPoints: number;

shieldPoints

readonly shieldPoints: number;

Inherited from

StarbaseStatus.current

kind

readonly kind: "starbaseStatus";

Defined in: packages/sage/src/world/starbase-status.ts:124

Inherited from

StarbaseStatus.kind

level

readonly level: WorldStarbaseLevel;

Defined in: packages/sage/src/world/starbase-status.ts:126

Inherited from

StarbaseStatus.level

levelIndex

readonly levelIndex: number;

Defined in: packages/sage/src/world/starbase-status.ts:128

Ordinal from starbaseLevelIndex; the Central Space Station is 6.

Inherited from

StarbaseStatus.levelIndex

levelInfo

readonly levelInfo: WorldStarbaseLevelInfoData;

Defined in: packages/sage/src/world/starbase-status.ts:132

Configured values for the current level, copied from the level table.

Inherited from

StarbaseStatus.levelInfo

maxLevel

readonly maxLevel: WorldStarbaseLevel;

Defined in: packages/sage/src/world/starbase-status.ts:129

Inherited from

StarbaseStatus.maxLevel

owner

readonly owner: WorldFaction;

Defined in: packages/sage/src/world/starbase-status.ts:125

Inherited from

StarbaseStatus.owner

services

readonly services: {
  localMarket: StarbaseServiceAvailability;
  repair: StarbaseServiceAvailability;
};

Defined in: packages/sage/src/world/starbase-status.ts:147

localMarket

readonly localMarket: StarbaseServiceAvailability;

repair

readonly repair: StarbaseServiceAvailability;

Inherited from

StarbaseStatus.services

system

readonly system: EntityRef<"starSystem">;

Defined in: packages/sage/src/world/starbase-status.ts:198

systemName

readonly systemName: string;

Defined in: packages/sage/src/world/starbase-status.ts:199

timing

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

Defined in: packages/sage/src/world/starbase-status.ts:140

builtOrDestroyedAtUnixSeconds

readonly builtOrDestroyedAtUnixSeconds: bigint;

When the Starbase was last built or destroyed.

lastCombatUpdateAtUnixSeconds

readonly lastCombatUpdateAtUnixSeconds: bigint;

shieldBreakDelayEndsAtUnixSeconds

readonly shieldBreakDelayEndsAtUnixSeconds: bigint;

When shield points may resume regenerating after reaching zero.

Inherited from

StarbaseStatus.timing

upgrade?

readonly optional upgrade?: ResolvedStarbaseUpgradeProgress;

Defined in: packages/sage/src/world/starbase-status.ts:200

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/world/starbase-status.ts:152

Returns

unknown

Inherited from

StarbaseStatus.toJSON

---

StarbaseUpgradeMaterial

Defined in: packages/sage/src/world/starbase-status.ts:65

One material a shared Starbase needs before it can reach its next level.

needed, deposited and remaining are raw cargo units. complete is true once deposited has reached needed. crew and durationSeconds describe one contribution of this material: a Starbase Player installs it through its own StarbaseUpgradeProcess, which the starbases entry reads separately.

Example

declare const material: StarbaseUpgradeMaterial;
console.log(material.cargoId, material.remaining);

Extended by

• ResolvedStarbaseUpgradeMaterial

Properties

cargoId

readonly cargoId: number;

Defined in: packages/sage/src/world/starbase-status.ts:66

complete

readonly complete: boolean;

Defined in: packages/sage/src/world/starbase-status.ts:70

crew

readonly crew: number;

Defined in: packages/sage/src/world/starbase-status.ts:71

deposited

readonly deposited: bigint;

Defined in: packages/sage/src/world/starbase-status.ts:68

durationSeconds

readonly durationSeconds: number;

Defined in: packages/sage/src/world/starbase-status.ts:72

needed

readonly needed: bigint;

Defined in: packages/sage/src/world/starbase-status.ts:67

remaining

readonly remaining: bigint;

Defined in: packages/sage/src/world/starbase-status.ts:69

---

StarbaseUpgradeProgress

Defined in: packages/sage/src/world/starbase-status.ts:88

Shared progress of a Starbase toward its next level.

complete is true when every listed material is fully deposited. The pinned contract states that the Starbase should then change level and reset the deposits; the program applies that change, the SDK only reports the stored state.

Example

declare const upgrade: StarbaseUpgradeProgress;
console.log(upgrade.toLevel, upgrade.complete);

Properties

complete

readonly complete: boolean;

Defined in: packages/sage/src/world/starbase-status.ts:90

materials

readonly materials: readonly StarbaseUpgradeMaterial[];

Defined in: packages/sage/src/world/starbase-status.ts:91

toLevel

readonly toLevel: WorldStarbaseLevel;

Defined in: packages/sage/src/world/starbase-status.ts:89

---

StarSystemAccountData

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

SDK-owned decoded StarSystem data.

Example

declare const system: StarSystemAccountData;
console.log(system.coordinates);

Extended by

• StarSystemSnapshot

Properties

celestialBodyAddresses

readonly celestialBodyAddresses: readonly Address[];

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

connections

readonly connections: readonly WorldConnectionData[];

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

coordinates

readonly coordinates: WorldCoordinates;

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

coordinatesRaw

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

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

Exact stored I8F56 coordinates for movement arithmetic.

x

readonly x: bigint;

y

readonly y: bigint;

game

readonly game: Address;

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

name

readonly name: string;

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

regionId?

readonly optional regionId?: number;

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

sequenceId

readonly sequenceId: bigint;

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

starbase?

readonly optional starbase?: WorldStarbaseData;

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

systemId

readonly systemId: number;

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

version

readonly version: number;

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

---

StarSystemSnapshot

Defined in: packages/sage/src/world/index.ts:124

Immutable, translated StarSystem snapshot including nested shared Starbase data.

Example

declare const system: StarSystemSnapshot;
console.log(system.name, system.coordinates);

Extends

• StarSystemAccountData

Extended by

• StarSystemView

Properties

address

readonly address: Address;

Defined in: packages/sage/src/world/index.ts:126

celestialBodyAddresses

readonly celestialBodyAddresses: readonly Address[];

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

Inherited from

StarSystemAccountData.celestialBodyAddresses

connections

readonly connections: readonly WorldConnectionData[];

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

Inherited from

StarSystemAccountData.connections

coordinates

readonly coordinates: WorldCoordinates;

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

Inherited from

StarSystemAccountData.coordinates

coordinatesRaw

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

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

Exact stored I8F56 coordinates for movement arithmetic.

x

readonly x: bigint;

y

readonly y: bigint;

Inherited from

StarSystemAccountData.coordinatesRaw

game

readonly game: Address;

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

Inherited from

StarSystemAccountData.game

kind

readonly kind: "starSystem";

Defined in: packages/sage/src/world/index.ts:125

name

readonly name: string;

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

Inherited from

StarSystemAccountData.name

regionId?

readonly optional regionId?: number;

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

Inherited from

StarSystemAccountData.regionId

sequenceId

readonly sequenceId: bigint;

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

Inherited from

StarSystemAccountData.sequenceId

starbase?

readonly optional starbase?: WorldStarbaseData;

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

Inherited from

StarSystemAccountData.starbase

systemId

readonly systemId: number;

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

Inherited from

StarSystemAccountData.systemId

version

readonly version: number;

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

Inherited from

StarSystemAccountData.version

Methods

toJSON()

toJSON(): unknown;

Defined in: packages/sage/src/world/index.ts:127

Returns

unknown

---

WorldAsteroidData

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

Fully translated Asteroid projection data.

Example

declare const asteroid: WorldAsteroidData;
console.log(asteroid.resources);

Properties

resources

readonly resources: readonly WorldAsteroidResourceData[];

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

---

WorldAsteroidResourceData

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

One translated Asteroid resource state.

Example

declare const resource: WorldAsteroidResourceData;
console.log(resource.amountMined);

Properties

amountMined

readonly amountMined: bigint;

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

cargoId

readonly cargoId: number;

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

miners

readonly miners: bigint;

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

richness

readonly richness: WorldFixedValue;

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

---

WorldClaimStakeGroupData

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

One translated nested Claim Stake structure group.

Example

declare const group: WorldClaimStakeGroupData;
console.log(group.structures);

Properties

chronoAddresses

readonly chronoAddresses: readonly Address[];

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

key

readonly key: number;

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

offset

readonly offset: number;

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

structures

readonly structures: readonly WorldStructureData[];

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

---

WorldConnectionCosts

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

Unit-explicit warp-lane costs for one connected system.

Example

declare const costs: WorldConnectionCosts;
console.log(costs.level1Atlas);

Properties

cssAtlas

readonly cssAtlas: number;

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

cssRaw

readonly cssRaw: bigint;

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

level1Atlas

readonly level1Atlas: number;

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

level1Raw

readonly level1Raw: bigint;

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

level2Atlas

readonly level2Atlas: number;

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

level2Raw

readonly level2Raw: bigint;

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

level3Atlas

readonly level3Atlas: number;

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

level3Raw

readonly level3Raw: bigint;

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

level4Atlas

readonly level4Atlas: number;

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

level4Raw

readonly level4Raw: bigint;

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

level5Atlas

readonly level5Atlas: number;

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

level5Raw

readonly level5Raw: bigint;

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

---

WorldConnectionData

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

One StarSystem connection keyed by the connected system id.

Example

declare const connection: WorldConnectionData;
console.log(connection.systemId);

Properties

costs

readonly costs: WorldConnectionCosts;

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

systemId

readonly systemId: number;

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

---

WorldCraftingHabData

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

One nested Crafting Hab group retained as shared Starbase data.

Example

declare const hab: WorldCraftingHabData;
console.log(hab.structures);

Properties

chronoAddresses

readonly chronoAddresses: readonly Address[];

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

key

readonly key: number;

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

offset

readonly offset: number;

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

structures

readonly structures: readonly WorldStructureData[];

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

---

WorldFixedValue

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

A translated fixed-point world value retaining its exact source integer.

Example

const value: WorldFixedValue = { raw: 65_536n, value: 1 };

Properties

raw

readonly raw: bigint;

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

value

readonly value: number;

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

---

WorldPlanetData

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

Fully translated Planet projection data.

Example

declare const planet: WorldPlanetData;
console.log(planet.resources);

Properties

baseClaimStakePlacementFee

readonly baseClaimStakePlacementFee: readonly readonly WorldFixedValue[][];

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

Base placement fee per plot, indexed like claimStakePlots.

baseClaimStakeRentRate

readonly baseClaimStakeRentRate: readonly readonly WorldFixedValue[][];

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

Base rent rate per plot, indexed like claimStakePlots.

claimedPlots

readonly claimedPlots: readonly WorldClaimStakeGroupData[];

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

Placed Claim Stake groups keyed by plot row, the Starbase level index that also indexes claimStakePlots. Each group lists the stakes of every tier placed in that row and their placement chronology.

claimedPlotsUnsizedLength

readonly claimedPlotsUnsizedLength: number;

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

claimStakePlots

readonly claimStakePlots: readonly readonly number[][];

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

Plot counts indexed [starbaseLevelIndex][claimStakeTierIndex]: seven Starbase level rows (level-0 .. level-5, css) and five Claim Stake tier columns (one .. five).

providedTags

readonly providedTags: readonly number[];

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

resources

readonly resources: readonly WorldPlanetResourceData[];

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

subtype?

readonly optional subtype?: WorldPlanetSubtype;

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

Category from the current C4 numeric tag mapping. Undefined when absent, conflicting, or tagged as an asteroid; raw providedTags remain available. Unrelated tags do not suppress a recognized category. Shares the body’s account observation and cache; no separate definition read is performed.

Example

declare const planet: WorldPlanetData;
console.log(planet.subtype ?? 'unknown');

---

WorldPlanetResourceData

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

One translated Planet resource richness value.

Planet richness gameplay use: unverified. Version-matched program evidence does not establish a consuming activity or formula for this decoded Planet account value. It is distinct from Asteroid richness used by Fleet mining and from separately decoded Claim Stake building resourceExtraction rates.

Example

declare const resource: WorldPlanetResourceData;
console.log(resource.richness.value);

Properties

cargoId

readonly cargoId: number;

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

richness

readonly richness: WorldFixedValue;

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

---

WorldStarbaseData

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

Fully translated nested shared Starbase data.

Example

declare const starbase: WorldStarbaseData;
console.log(starbase.owner, starbase.level);

Properties

baseCraftingHabPlacementFee

readonly baseCraftingHabPlacementFee: readonly readonly WorldFixedValue[][];

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

baseCraftingHabRentRate

readonly baseCraftingHabRentRate: readonly readonly WorldFixedValue[][];

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

buildingTags

readonly buildingTags: readonly number[];

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

builtDestroyedAtUnixSeconds

readonly builtDestroyedAtUnixSeconds: bigint;

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

craftingHabPlots

readonly craftingHabPlots: readonly readonly number[][];

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

craftingHabs

readonly craftingHabs: readonly WorldCraftingHabData[];

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

craftingHabsUnsizedLength

readonly craftingHabsUnsizedLength: number;

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

hp

readonly hp: number;

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

lastCombatUpdateUnixSeconds

readonly lastCombatUpdateUnixSeconds: bigint;

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

level

readonly level: WorldStarbaseLevel;

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

localMarketEnableLevel

readonly localMarketEnableLevel: WorldStarbaseLevel;

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

locationTags

readonly locationTags: readonly number[];

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

maxLevel

readonly maxLevel: WorldStarbaseMaxLevelData;

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

owner

readonly owner: WorldFaction;

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

pendingHp

readonly pendingHp: number;

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

repairEnableLevel

readonly repairEnableLevel: WorldStarbaseLevel;

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

shieldBreakDelayExpiresAtUnixSeconds

readonly shieldBreakDelayExpiresAtUnixSeconds: bigint;

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

sp

readonly sp: number;

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

validRecipeIds

readonly validRecipeIds: readonly number[];

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

---

WorldStarbaseLevelData

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

One translated level inside the Starbase maximum-level union.

Example

declare const level: WorldStarbaseLevelData;
console.log(level.upgrades);

Properties

info

readonly info: WorldStarbaseLevelInfoData;

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

level

readonly level: WorldStarbaseLevel;

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

upgrades

readonly upgrades: readonly WorldStarbaseUpgradeData[];

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

---

WorldStarbaseLevelInfoData

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

Fully translated combat/economy values for one Starbase level.

Example

declare const info: WorldStarbaseLevelInfoData;
console.log(info.repairFeeAtlas);

Properties

damagePerRound

readonly damagePerRound: number;

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

hp

readonly hp: number;

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

repairAbility

readonly repairAbility: WorldFixedValue;

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

repairCost

readonly repairCost: WorldFixedValue;

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

repairEfficiency

readonly repairEfficiency: WorldFixedValue;

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

repairFeeAtlas

readonly repairFeeAtlas: number;

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

repairFeeRaw

readonly repairFeeRaw: bigint;

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

repairRate

readonly repairRate: WorldFixedValue;

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

shieldBreakDelaySeconds

readonly shieldBreakDelaySeconds: number;

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

shieldRechargeRate

readonly shieldRechargeRate: WorldFixedValue;

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

sp

readonly sp: number;

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

xp

readonly xp: WorldFixedValue;

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

---

WorldStarbaseMaxLevelData

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

Plain replacement for the generated StarbaseMaxLevel union.

Example

declare const maximum: WorldStarbaseMaxLevelData;
console.log(maximum.kind);

Properties

kind

readonly kind: WorldStarbaseLevel;

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

levels

readonly levels: readonly WorldStarbaseLevelData[];

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

---

WorldStarbaseUpgradeData

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

One cargo deposit requirement for an intermediate Starbase level.

Example

declare const upgrade: WorldStarbaseUpgradeData;
console.log(upgrade.cargoId);

Properties

cargoId

readonly cargoId: number;

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

crew

readonly crew: number;

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

deposited

readonly deposited: bigint;

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

durationSeconds

readonly durationSeconds: number;

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

needed

readonly needed: bigint;

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

---

WorldStructureData

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

One nested shared structure value from Starbase crafting-hab data.

Example

declare const structure: WorldStructureData;
console.log(structure.address);

Properties

address

readonly address: Address;

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

deactivationTimeUnixSeconds

readonly deactivationTimeUnixSeconds: bigint;

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

Type Aliases

CelestialBodyDiscoveryOptions

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

Defined in: packages/sage/src/world/index.ts:112

Options for discovering Celestial Bodies across the configured Game.

Example

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

---

CelestialBodySnapshot

type CelestialBodySnapshot =
  | PlanetSnapshot
  | AsteroidSnapshot;

Defined in: packages/sage/src/world/index.ts:208

A translated CelestialBody snapshot projected as a Planet or Asteroid.

Example

declare const body: CelestialBodySnapshot;
if (body.kind === 'planet') console.log(body.details.claimStakePlots);

---

ClaimStakeTier

type ClaimStakeTier = C4ClaimStakeTier;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:38

Claim Stake tier label, the column axis of Planet plot tables.

Example

const tier: ClaimStakeTier = 'two';

---

StarSystemDiscoveryOptions

type StarSystemDiscoveryOptions = Omit<DiscoveryRequest, "filters" | "strategy"> & {
  regionId?: number;
};

Defined in: packages/sage/src/world/index.ts:98

Options supported by galaxy-scale StarSystem discovery.

Type Declaration

regionId?

readonly optional regionId?: number;

Limits discovery to StarSystems whose fixed-width region field contains this unsigned 16-bit id.

Example

const options: StarSystemDiscoveryOptions = {
  commitment: 'confirmed',
  regionId: 3,
};

---

WorldFaction

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

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

Human-readable faction labels used by shared Starbase data.

Example

const faction: WorldFaction = 'mud';

---

WorldPlanetSubtype

type WorldPlanetSubtype =
  | "terrestrial"
  | "volcanic"
  | "barren"
  | "gas-giant"
  | "ice-giant"
  | "dark"
  | "oceanic";

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

Planet category interpreted from on-chain building tags using the verified C4 mapping.

Example

const subtype: WorldPlanetSubtype = 'ice-giant';

---

WorldStarbaseLevel

type WorldStarbaseLevel =
  | "level-0"
  | "level-1"
  | "level-2"
  | "level-3"
  | "level-4"
  | "level-5"
  | "css";

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

Human-readable Starbase level labels.

Example

const level: WorldStarbaseLevel = 'level-1';

Functions

claimStakeTierIndex()

function claimStakeTierIndex(tier): number;

Defined in: packages/sage/src/world/planet-claim-stake-plots.ts:60

Returns the zero-based column index of a Claim Stake tier.

Planet plot, base rent and base placement-fee tables are indexed [starbaseLevelIndex][claimStakeTierIndex]: seven Starbase level rows and five tier columns.

Parameters

Parameter	Type
tier	ClaimStakeTier

Returns

number

Example

declare const planet: PlanetSnapshot;
const level1TierTwo = planet.details.claimStakePlots[1]![claimStakeTierIndex('two')];

---

deriveStarbaseStatus()

function deriveStarbaseStatus(starbase): StarbaseStatus;

Defined in: packages/sage/src/world/starbase-status.ts:279

Derives the status of a shared Starbase from already-loaded StarSystem data.

This is pure and network-free: it needs neither the context nor the Game definitions registry, so galaxy-map readers can call it on every System they already hold. The result is a new deeply frozen value; the input is left untouched. Materials carry numeric cargo ids; use getStarbaseStatus when you want them resolved to cargo definitions.

Parameters

Parameter	Type
starbase	WorldStarbaseData

Returns

StarbaseStatus

Example

declare const system: StarSystemSnapshot;
if (system.starbase !== undefined) {
  const status = deriveStarbaseStatus(system.starbase);
  console.log(status.level, status.upgrade?.toLevel);
}

---

distanceBetweenStarSystems()

function distanceBetweenStarSystems(from, to): number;

Defined in: packages/sage/src/world/index.ts:789

Returns Euclidean distance between two SAGE coordinates.

Parameters

Parameter	Type
from	WorldCoordinates
to	WorldCoordinates

Returns

number

Example

const distance = distanceBetweenStarSystems({ x: 0, y: 0 }, { x: 3, y: 4 });

---

findCelestialBodyPda()

function findCelestialBodyPda(game, bodyId): Promise<Address>;

Defined in: packages/sage/src/world/index.ts:405

Derives the CelestialBody PDA for a Game and numeric body id.

Parameters

Parameter	Type
game	Address
bodyId	number

Returns

Promise<Address>

Example

declare const game: Address;
const address = await findCelestialBodyPda(game, 11);

---

findStarSystemPda()

function findStarSystemPda(game, systemId): Promise<Address>;

Defined in: packages/sage/src/world/index.ts:391

Derives the StarSystem PDA for a Game and numeric system id.

Parameters

Parameter	Type
game	Address
systemId	number

Returns

Promise<Address>

Example

declare const game: Address;
const address = await findStarSystemPda(game, 1);

---

getAllCelestialBodies()

function getAllCelestialBodies(ctx, options?): Promise<readonly CelestialBodySnapshot[]>;

Defined in: packages/sage/src/world/index.ts:683

Discovers every Celestial Body for the configured Game without system fan-out.

Uses one discovery response, with configured indexer precedence and otherwise targeted program-account filters. The context’s maxDiscoveryResults rejects an oversized response. Results reuse the address-keyed account cache; no Game definitions are loaded. Resource values are observations, not static catalogs.

Parameters

Parameter	Type
ctx	SageContext
options	CelestialBodyDiscoveryOptions

Returns

Promise<readonly CelestialBodySnapshot[]>

Example

declare const ctx: SageContext;
const bodies = await getAllCelestialBodies(ctx);
console.log(bodies.map(body => body.name));

---

getAsteroids()

function getAsteroids(
   ctx,
   systemAddress,
options?): Promise<readonly AsteroidSnapshot[]>;

Defined in: packages/sage/src/world/index.ts:768

Returns only Asteroid projections in one StarSystem.

Parameters

Parameter	Type
ctx	SageContext
systemAddress	Address
options?	ReadOptions

Returns

Promise<readonly AsteroidSnapshot[]>

Example

declare const ctx: SageContext;
declare const systemAddress: Address;
const asteroids = await getAsteroids(ctx, systemAddress);

---

getCelestialBodies()

function getCelestialBodies(
   ctx,
   systemAddress,
options?): Promise<readonly CelestialBodySnapshot[]>;

Defined in: packages/sage/src/world/index.ts:707

Traverses a StarSystem’s stored CelestialBody addresses with explicit reads.

Parameters

Parameter	Type
ctx	SageContext
systemAddress	Address
options?	ReadOptions

Returns

Promise<readonly CelestialBodySnapshot[]>

Example

declare const ctx: SageContext;
declare const systemAddress: Address;
const bodies = await getCelestialBodies(ctx, systemAddress);

---

getCelestialBody()

function getCelestialBody(
   ctx,
   address,
options?): Promise<CelestialBodySnapshot>;

Defined in: packages/sage/src/world/index.ts:541

Reads a required CelestialBody by account address.

Parameters

Parameter	Type
ctx	SageContext
address	Address
options?	ReadOptions

Returns

Promise<CelestialBodySnapshot>

Example

declare const ctx: SageContext;
declare const address: Address;
const body = await getCelestialBody(ctx, address);

---

getCelestialBodyById()

function getCelestialBodyById(
   ctx,
   bodyId,
options?): Promise<CelestialBodySnapshot>;

Defined in: packages/sage/src/world/index.ts:649

Derives and reads a CelestialBody by its Game-scoped numeric id.

Parameters

Parameter	Type
ctx	SageContext
bodyId	number
options?	ReadOptions

Returns

Promise<CelestialBodySnapshot>

Example

declare const ctx: SageContext;
const body = await getCelestialBodyById(ctx, 11);

---

getCelestialBodyCoordinates()

function getCelestialBodyCoordinates(
   ctx,
   bodyAddress,
options?): Promise<WorldCoordinates>;

Defined in: packages/sage/src/world/index.ts:804

Resolves a CelestialBody’s stored StarSystem relation to its coordinates.

Parameters

Parameter	Type
ctx	SageContext
bodyAddress	Address
options?	ReadOptions

Returns

Promise<WorldCoordinates>

Example

declare const ctx: SageContext;
declare const bodyAddress: Address;
const coordinates = await getCelestialBodyCoordinates(ctx, bodyAddress);

---

getPlanetClaimStakePlots()

function getPlanetClaimStakePlots(
   ctx,
   planet,
options?): Promise<PlanetClaimStakePlotsSnapshot>;

Defined in: packages/sage/src/world/index.ts:600

Reads one Planet and its StarSystem, then summarizes Claim Stake plot occupancy per Starbase level row and availability for every tier.

The Planet and System stay on the shared account cache; Claim Stake definitions load lazily through the registry. The program records stakes per Starbase level row, and every tier shares a row’s occupancy, so availability is per tier across the rows up to the System’s Starbase level, matching the placement planner’s check. A Planet whose System has no Starbase still lists its rows and plot limits by level, but no availability. An Asteroid address is rejected: only Planets carry Claim Stake plots.

Parameters

Parameter	Type
ctx	SageContext
planet	Address
options?	ReadOptions

Returns

Promise<PlanetClaimStakePlotsSnapshot>

Example

declare const ctx: SageContext;
declare const planet: Address;
const plots = await getPlanetClaimStakePlots(ctx, planet);
for (const tier of plots.tiers) {
  console.log(tier.tier, tier.available, tier.placementLevel);
}

---

getPlanetResources()

function getPlanetResources(
   context,
   planet,
options?): Promise<PlanetResourcesSnapshot>;

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

Reads one Planet resource observation and resolves every cargo definition.

The Planet stays on the shared CelestialBody account cache. Cargo definitions load lazily through the registry and do not imply that the body and catalog were observed atomically. Unknown cargo ids reject the whole read.

Parameters

Parameter	Type
context	SageContext
planet	Address
options?	ReadOptions

Returns

Promise<PlanetResourcesSnapshot>

Example

declare const ctx: SageContext;
declare const planet: Address;
const snapshot = await getPlanetResources(ctx, planet);
console.log(snapshot.resources[0]?.cargo.name);

---

getPlanets()

function getPlanets(
   ctx,
   systemAddress,
options?): Promise<readonly PlanetSnapshot[]>;

Defined in: packages/sage/src/world/index.ts:745

Returns only Planet projections in one StarSystem.

Parameters

Parameter	Type
ctx	SageContext
systemAddress	Address
options?	ReadOptions

Returns

Promise<readonly PlanetSnapshot[]>

Example

declare const ctx: SageContext;
declare const systemAddress: Address;
const planets = await getPlanets(ctx, systemAddress);

---

getStarbaseStatus()

function getStarbaseStatus(
   ctx,
   system,
   options?): Promise<
  | StarbaseStatusSnapshot
| undefined>;

Defined in: packages/sage/src/world/index.ts:447

Reads one StarSystem and derives the status of its shared Starbase.

Returns undefined when the System exists but has no Starbase; a missing System account still throws. The StarSystem stays on the shared account cache. Upgrade materials resolve lazily through the definitions registry, so a Starbase at its maximum level never loads the Game definitions.

Parameters

Parameter	Type
ctx	SageContext
system	Address
options?	ReadOptions

Returns

Promise< | StarbaseStatusSnapshot | undefined>

Example

declare const ctx: SageContext;
declare const system: Address;
const status = await getStarbaseStatus(ctx, system);
console.log(status?.level, status?.current.hullPoints);

---

getStarSystem()

function getStarSystem(
   ctx,
   address,
options?): Promise<StarSystemSnapshot>;

Defined in: packages/sage/src/world/index.ts:420

Reads a required StarSystem by account address.

Parameters

Parameter	Type
ctx	SageContext
address	Address
options?	ReadOptions

Returns

Promise<StarSystemSnapshot>

Example

declare const ctx: SageContext;
declare const address: Address;
const system = await getStarSystem(ctx, address);

---

getStarSystemById()

function getStarSystemById(
   ctx,
   systemId,
options?): Promise<StarSystemSnapshot>;

Defined in: packages/sage/src/world/index.ts:489

Derives and reads a StarSystem by its Game-scoped numeric id.

Parameters

Parameter	Type
ctx	SageContext
systemId	number
options?	ReadOptions

Returns

Promise<StarSystemSnapshot>

Example

declare const ctx: SageContext;
const system = await getStarSystemById(ctx, 1);

---

getStarSystems()

function getStarSystems(ctx, options?): Promise<readonly StarSystemSnapshot[]>;

Defined in: packages/sage/src/world/index.ts:515

Discovers StarSystems for the configured Game with stable targeted filters.

Parameters

Parameter	Type
ctx	SageContext
options	StarSystemDiscoveryOptions

Returns

Promise<readonly StarSystemSnapshot[]>

Example

declare const ctx: SageContext;
const systems = await getStarSystems(ctx, { regionId: 3 });

---

maybeGetCelestialBody()

function maybeGetCelestialBody(
   ctx,
   address,
   options?): Promise<
  | CelestialBodySnapshot
| undefined>;

Defined in: packages/sage/src/world/index.ts:626

Reads an optional CelestialBody by account address.

Parameters

Parameter	Type
ctx	SageContext
address	Address
options?	ReadOptions

Returns

Promise< | CelestialBodySnapshot | undefined>

Example

declare const ctx: SageContext;
declare const address: Address;
const body = await maybeGetCelestialBody(ctx, address);

---

maybeGetStarSystem()

function maybeGetStarSystem(
   ctx,
   address,
   options?): Promise<
  | StarSystemSnapshot
| undefined>;

Defined in: packages/sage/src/world/index.ts:466

Reads an optional StarSystem by account address.

Parameters

Parameter	Type
ctx	SageContext
address	Address
options?	ReadOptions

Returns

Promise< | StarSystemSnapshot | undefined>

Example

declare const ctx: SageContext;
declare const address: Address;
const system = await maybeGetStarSystem(ctx, address);

---

starbaseLevelIndex()

function starbaseLevelIndex(level): number;

Defined in: packages/sage/src/world/starbase-status.ts:48

Returns the zero-based ordinal of a Starbase level label.

Levels level-0 through level-5 map to 0 through 5 and the Central Space Station (css) ranks above them as 6. This is the row index used by Planet Claim Stake plot tables and Starbase Crafting Hab plot tables, and the order used to compare a Starbase level with a service enable level.

Parameters

Parameter	Type
level	WorldStarbaseLevel

Returns

number

Example

const unlocked = starbaseLevelIndex('level-3') >= starbaseLevelIndex('level-2');

References

WorldCoordinates

Re-exports WorldCoordinates