Definition catalogs

Definition catalogs describe game configuration: what a ship configuration, building, or cargo type means. They are separate from observed account state, such as a Fleet’s current stats or an asteroid’s mining counters.

Read the catalog you need

These functions take your ctx as their first argument. Getters take a numeric definition ID; listing functions return immutable arrays.

Catalog	Lookup	List	Entry point
Ship configurations	resolveShip	listShipConfigurations	root
Cargo	getCargoDefinition	listCargoDefinitions	cargo
Claim Stakes	getClaimStakeDefinition	listClaimStakeDefinitions	claim-stakes
Claim Stake buildings	getClaimStakeBuildingDefinition	listClaimStakeBuildingDefinitions	claim-stakes
Crafting Habs	getCraftingHabDefinition	listCraftingHabDefinitions	crafting
Hab buildings	getHabBuildingDefinition	listHabBuildingDefinitions	crafting

Entry names are relative to @aephia/atlas-kit. Ship listing functions are also available from @aephia/atlas-kit/fleets. listShipConfigurationsByMint(ctx, mint) selects all configurations belonging to one ship mint in the selected deployment. Configuration stats are distinct from effective Fleet stats. See the Fleet guide.

Within a retained section generation, by-ID and listing routes reuse the same canonical immutable definition objects. Repeating a listing reuses its frozen array. There is no need to copy the catalog into a second application cache just to avoid repeating a read.

The registry loads lazily from the Game account. Reading one catalog does not retain every catalog. A later request for an unloaded section can therefore require another Game fetch and decode. Lookups can check an expected section sequence and report RegistryOutOfSyncError when the required generation is unavailable; an ahead caller can invalidate the section for a subsequent reload. A sequence ID identifies an observed generation; it does not prove that no newer on-chain configuration exists. Account defaultMaxAgeMs is not a catalog refresh timer.

Preload a known set of catalogs

Use the named root export when you know which catalogs a screen or job needs:

import { preloadDefinitions, readMeta } from '@aephia/atlas-kit';

const loaded = await preloadDefinitions(ctx, [
  'ships',
  'claimStakes',
  'buildings',
]);
for (const section of readMeta(loaded)!.sections) {
  console.log(section.section, section.sequenceId, section.observation);
}

Supported section names are ships, cargo, claimStakes, buildings, craftingHabs, habBuildings, xp, and research. Preload uses the same registry as lazy reads. Usable retained or compatible stored sections need no new Game read. Missing selected sections share a validated Game fetch and decode when they can load together; incompatible work already in flight can require a subsequent read.

Preloading warms selected sections; it does not request freshness or promise one observation shared by all sections. Inspect each section’s metadata. Restored sections without source provenance report availability: 'unavailable' instead of inventing a slot or commitment. There is no aggregate slot.

Optional persistence in browsers and Node.js

The default registry is in memory and belongs to its context. Applications can supply an asynchronous registrySnapshotStore when creating the context to retain supported sections across sessions. Implement the RegistrySnapshotStore contract with storage appropriate to your application, such as IndexedDB in a browser or a file/database in a Node.js tool. The shared SDK runtime does not import browser storage or Node.js filesystem APIs.

Store the entire supplied section snapshot using its versioned JSON encoding; do not strip its schema or sequence information or substitute a public snapshot’s toJSON() result.

Section	Persisted encoding
Ships	Version 2
Cargo	Version 1
Claim Stakes and their buildings	Separate version 2 sections
Crafting Habs and their buildings	Separate version 2 sections
XP and research	Not persisted

Incompatible or malformed stored sections are cache misses and reload lazily. A store whose load operation throws produces a ProviderError; save failures are best effort. A stored sequence is not evidence of current on-chain freshness. Persistence of these catalogs does not provide generic restoration of Fleet or world account snapshots.

World and resource reads remain account reads

Star systems, planets, and asteroids use the address-keyed account cache and its freshness controls. Resource projections reuse their body account; they do not have a second catalog cache. A planet exposes resource richness, while an asteroid also exposes changing amountMined and miners counters. Preloading Game definitions does not fetch the galaxy.

See Starmap for existing discovery routes and resource reads, and Caching and provenance for account freshness.