Documentation: 0.5.0 (source: v0.5.0).
# Starmap

> Star systems, planets, and asteroids — the places everything else happens in.

Markdown source of https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/world/ — see https://docs-v0-5-0.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

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.

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

:::game[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:

```ts
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.

> **Runnable example — Read a star system.** Look a system up by its numeric id and list what orbits it. Run it in the browser at https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/world/.

## Getting from a fleet to its system

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

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

That indirection is deliberate — see [fleets](/guides/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:

```ts
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.

:::game[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:

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

Travelling a lane is a fleet move — `planFleetWarpLane` in
[Warp & subwarp](/guides/moving-a-fleet/) — and the fee a character actually
pays can shrink with [Council Rank](/guides/council-rank/) research.

## Bodies: planets and asteroids

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

```ts
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.

:::note[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](/reference/starbases/).

```ts
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`](/reference/world/) — every export in this entry
- [`starbases`](/reference/starbases/) — player state at a starbase
- [`mining`](/reference/mining/) — what asteroids are for