How it fits together

The SDK mirrors the game’s own structure. Once you can see that structure, most of the API follows from it.

The interactive version is coming

This page will become a clickable diagram where every node links to its guide. Until then, here is the same structure in text.

The spine

Most reads start from a player and walk down:

Wallet ──▶ Profile ──▶ Character ──▶ Fleet

A wallet may own a profile; a profile has one SAGE character; a character owns many fleets. A wallet cannot be turned into a profile by derivation — profiles are created by the player, so that step needs discovery or a known address.

What hangs off a fleet

Fleet ──┬──▶ cargo      (what it is carrying)
        ├──▶ mining     (what it is extracting, and how fast)
        ├──▶ scanning   (what it has surveyed)
        ├──▶ combat     (its combat status)
        └──▶ state      (docked, in transit, mining, …)

A fleet’s location lives inside its state, not as a standalone field, because where a fleet is depends on what it is doing.

What hangs off a profile

Profile ──┬──▶ factions   (allegiance, standing)
          ├──▶ loyalty    (epoch contributions, accumulated ATLAS)
          ├──▶ rewards    (treasuries, commitments)
          └──▶ starbases  (this player's state at each starbase)

The world

World ──┬──▶ star systems ──▶ starbases ──┬──▶ markets
        │                                  └──▶ crafting
        └──▶ planets & asteroids ──▶ claim stakes

Shared starbase data belongs to the world. A player’s own state at a starbase is separate, which is why starbases appear in both places.

Underneath everything

client   ── context, cache, provenance, subscriptions
registry ── the Game account's definitions: ships, cargo, recipes, XP
bindings ── the raw generated client (escape hatch)

The client owns the machinery every read shares. The registry holds the game’s static definitions — read once, reused everywhere. The bindings entry is the escape hatch for anything not yet adapted.

Why one account holds all the definitions

Ship stats, cargo types, crafting recipes, XP tables — all of it lives in a single large Game account rather than being spread across many. That is why the SDK loads and caches it once, in sections, rather than re-reading it per lookup.

Reading the map as API

Each arrow is a method, and each cluster is roughly an entry point:

const character = await sage.characters.forProfile(profileAddress);
const fleets = await character.fleets.all();
const inventory = await fleets[0].inventory.get();

Where a name appears in the map, there is usually an entry point of the same name — @aephia/sage/fleets, @aephia/sage/world, and so on. See the reference for the full list.