@aephia/atlas-kit

Community-maintained TypeScript SDK for Star Atlas SAGE C4 on the z.ink chain: gameplay-oriented reads, fully translated game state, inert action Plans, and typed, remedy-oriented errors.

[!IMPORTANT] This is an unofficial community project. It is not maintained by ATMTA or the Star Atlas development team.

Install

npm install @aephia/atlas-kit @solana/kit@^6.1.0

@solana/kit is a peer dependency. Do not confuse this package with the @staratlas/sage package, which targets the previous version of the game and is API-incompatible with SAGE C4.

Quickstart

The batteries-included client returns already-loaded entity views:

import { createSageClient } from '@aephia/atlas-kit';
import { createSolanaRpc } from '@solana/kit';

const rpc = createSolanaRpc('https://testnet-rpc.z.ink');
const sage = createSageClient({ cluster: 'zink-ptr', rpc });

const character = await sage.characters.forProfile(profileAddress);
const fleets = await character.fleets.all();
const fleet = fleets[0];
if (!fleet) throw new Error('The Profile has no Fleets.');

console.log(fleet.name); // a trimmed string, not a padded byte array
console.log(fleet.state); // a discriminated union with named fields
console.log(fleet.ships); // registry-resolved ship summaries

Size-sensitive applications import only the capability entries they need — a galaxy-map application importing @aephia/atlas-kit/world ships no fleet, market, or crafting code:

import { createSageContext } from '@aephia/atlas-kit/client';
import { getStarSystems } from '@aephia/atlas-kit/world';

const ctx = createSageContext({ cluster: 'zink-ptr', rpc });
const systems = await getStarSystems(ctx);

Entry points

| Entry point | Purpose | | ------------------------------------- | -------------------------------------------------------------------- | | @aephia/atlas-kit | Loaded traversal across selected gameplay domains | | @aephia/atlas-kit/bindings | Raw generated C4 clients as an explicit escape hatch | | @aephia/atlas-kit/cargo | Cargo definitions, pods, inventory, and capacity | | @aephia/atlas-kit/cargo/actions | Fleet/Starbase and within-Fleet cargo transfer planning | | @aephia/atlas-kit/claim-stakes | Claim Stake reads, discovery, lifecycle, and production | | @aephia/atlas-kit/client | Context, cache, provenance, subscriptions, and errors | | @aephia/atlas-kit/combat | Combat configuration, Fleet combat state, Loot, and Outlaws | | @aephia/atlas-kit/crafting | Recipes, Crafting Habs, Processes, and production state | | @aephia/atlas-kit/factions | Faction identity, economics, diplomacy, and territory | | @aephia/atlas-kit/fleets | Fleets, composition, movement state, and relationships | | @aephia/atlas-kit/fleets/actions | Inspectable Fleet movement and arrival-settlement planners | | @aephia/atlas-kit/identity | Wallet, Profile, Character, progression, and research reads | | @aephia/atlas-kit/loyalty | Loyalty epochs, contributions, banks, and lifecycle | | @aephia/atlas-kit/markets | Local Market orders, maker state, and discovery | | @aephia/atlas-kit/mining | Deposits, active mining, extraction, and cargo outputs | | @aephia/atlas-kit/planning | Plans/PlanSequences, assembly, signer-free simulation, and execution | | @aephia/atlas-kit/scanning | Scan patterns, cooldowns, stats, and Character state | | @aephia/atlas-kit/rewards | ATLAS reward configuration, treasuries, and commitments | | @aephia/atlas-kit/starbases | Player-local Starbase state, facilities, and upgrades | | @aephia/atlas-kit/starbases/actions | Address-only StarbasePlayer registration planning | | @aephia/atlas-kit/world | Game, regions, systems, bodies, and world projections |

Scope and guarantees

• Bounded write interaction. The planning entry creates and combines inspectable signer-free data, then assembles it after fetching one recent blockhash through the optional write transport. Execution accepts external Kit signers, re-checks freshness before signing, submits exactly once, confirms to a typed outcome, and invalidates affected cache entries only on confirmed success. No signer or key material is retained by the context. The Fleet actions entries plan all five bounded movement transitions, Fleet arrival settlement, and D048's focused cargo/Starbase transfers without write RPC; simulatePlan accepts only an address-valued assembly policy and never invokes a signer. Remaining capability planners do not ship yet. Treat every unknown outcome as possibly submitted and never retry it automatically; execution can incur fees or move assets.
• Fail-closed Plan sequences. A PlanSequence is a non-atomic itinerary of caller-owned lazy steps. Capability callbacks report waiting or return one freshly prepared Plan only when reached; every transaction needs fresh authorization. Persist the caller-owned checkpoint after every acknowledged save, and present the fresh Plan again through onBeforeSign. Never persist a signer or secret, blindly retry, or automatically resume an unknown, identity-mismatched, or confirmation-unverifiable checkpoint. Observable public signatures can be reconciled against chain confirmation; an opaque combined sign/send interruption remains unresolved.
• Validated. Every account read is checked for program owner, discriminator, and shape before decoding; indexer results are hints until verified against direct chain state.
• Translated. No raw binding shapes: names are strings, enums are string-literal unions, ATLAS amounts carry unit-explicit fields with raw bigint precision preserved, and every snapshot is JSON.stringify-safe.
• AI-legible. Every public symbol ships a compiling TSDoc example, and the repository publishes llms.txt / llms-full.txt artifacts.

Releases and changelog

Versions are released automatically from Conventional Commits; every release publishes generated notes on the GitHub releases page and appends to the repository CHANGELOG.

Documentation

Full documentation, architecture, and the consumer agent guide live in the repository: see docs/PUBLIC_API.md and docs/CONSUMER_AGENT_GUIDE.md.

License

Apache-2.0. Copyright Aephia contributors.