Starmap

The world entry covers the map: star systems and the bodies inside them. It is the shared, static-ish layer that fleets move through and starbases sit in.

const system = await sage.systems.byId(systemId);
const bodies = await system.celestialBodies.all();

A star system is one point on the map

The Galia Expanse is divided into regions, and each region contains several star systems. The game records this galaxy on a flat map with two-dimensional coordinates. Each star system occupies one point, and its star, planets, asteroid belts, and starbase all belong to that same point even though the game interface spreads them out visually. Being in the same region only means being in the same broad area. A fleet is actually at a system when its coordinates match that point, or when it is docked at the starbase. Two fleets that merely look as if they are near the same system can still be at different coordinates and therefore not be in the same place.

Systems by id or by address

Systems have a numeric id as well as an account address, and you can read by either:

const byId = await sage.systems.byId(3);
const byAddress = await sage.systems.get(systemAddress);

The id is the friendlier handle when you already know which system you mean. The address is what other accounts reference, so it is what you will have when arriving from a fleet’s state.

Getting from a fleet to its system

A fleet’s location lives inside its state, so narrow first:

if (fleet.state.kind === 'docked') {
  const system = await sage.systems.get(fleet.state.system.address);
}

That indirection is deliberate — see fleets for why location is not a flat field.

Warp lanes

Systems are not floating islands — the starmap is a network, and warp lanes are its links. Every system lists its own:

const neighbours = system.connections.map((connection) => connection.systemId);

Each connection also carries the lane’s toll — an ATLAS cost per starbase level (connection.costs.level1Atlas through level5Atlas, plus the CSS tier) — so “what does this jump cost” is a read, not a guess.

Lanes are the faction highway

Warp lanes are the third way a fleet travels, alongside subwarp and coordinate warp — and the only one that jumps system to system. The lane network is also what makes regions neighbours: two systems are adjacent because a lane connects them. A lane only works when both ends are held by the same faction, and using one costs an ATLAS toll that depends on the starbase level at the gate.

Whether a lane is usable is a faction question: both ends must be held by the same faction, and a system’s controller is on its shared starbase data:

const controller = system.starbase?.owner; // 'mud' | 'oni' | 'ustur' | …

Travelling a lane is a fleet move — planFleetWarpLane in Warp & subwarp — and the fee a character actually pays can shrink with Council Rank research.

Bodies: planets and asteroids

Celestial bodies are the things inside a system worth interacting with:

const planets = await system.planets.all();
const asteroids = await system.asteroids.all();

Both are projections over the same underlying body accounts, filtered to the kind you asked for. Asteroids are where mining happens; planets are where claim stakes go.

There is no separate Star account

C4 does not model stars as their own accounts. A system’s star is part of the system, not a body you can read independently. If you are porting logic from an earlier generation of the game that expected one, that is why it is missing.

Starbases appear in two places

Shared starbase data — where it is, what level it is — belongs to the world. A player’s own state at that starbase is separate and lives in starbases.

const bases = await system.playerStarbases.all();

The split exists because the two have different lifetimes and different readers: the starbase itself is shared infrastructure, while your cargo sitting in it is yours.

Gotchas

systems.all() is a broad read. It exists, but it fetches a lot. Prefer reading the systems you actually need by id.

Bodies are not evenly distributed. A system may have no asteroids, or many. Write for both.

Coordinates are game-space, not screen-space. They position bodies relative to each other within the galaxy, and do not map onto any rendering directly.

Reference

• world — every export in this entry
• starbases — player state at a starbase
• mining — what asteroids are for