Skip to content
Atlas Kit
Next — unreleased

Cargo

View as Markdown

Cargo is what a fleet carries: ore it has mined, fuel it burns, components for crafting, ammunition. Reading it is one relationship step from the fleet.

const inventory = await fleet.inventory.get();


for (const item of inventory.cargoHold.items) {
  console.log(item.mint, item.quantityRaw);
}

Quantities are bigint

Section titled “Quantities are bigint”

Every quantity is a bigint, never a number:

item.quantityRaw; // 713n

This is not pedantry. Game amounts routinely exceed what a JavaScript number holds exactly, and once a value passes that threshold, arithmetic silently produces the wrong answer with no error anywhere. Rounding somebody’s ore count by a few units because the value crossed 2^53 is worse than making you type n.

If you need to display a quantity, convert at the edge:

const display = item.quantityRaw.toString();

Do the arithmetic in bigint and convert only when rendering.

Moving cargo

Section titled “Moving cargo”

Reading tells you what is where; moving it is the first write most applications need. Like every write it follows the Plan flow — creating a Plan changes nothing until it is signed and executed. If this is your first write, read How Atlas Kit changes the game before continuing.

Between a docked fleet and your own storage at that starbase, the planner is planFleetTransferCargoAtStarbase. You state the direction and exactly what moves, per hold:

import type { PlanAuthorization } from '@aephia/atlas-kit/cargo/actions';
import { planFleetTransferCargoAtStarbase } from '@aephia/atlas-kit/cargo/actions';


const authorization = {
  profile: fleet.ownerProfile.address,
  authority: authoritySigner.address,
  keyIndex: 0,
} satisfies PlanAuthorization;


const stored = base.cargo.items[0];
if (stored !== undefined) {
  const plan = await planFleetTransferCargoAtStarbase(ctx, fleet, {
    authorization,
    direction: 'toFleet',
    amounts: { cargoHold: [{ cargoId: stored.id, amount: 1n }] },
  });
  console.table(plan.describe());
}

The fleet must already be docked — the planner refuses anything else, because that is the only state in which the game allows the transfer. Amounts are the same raw bigint quantities you read: cargoHold takes a list of cargo ids and amounts, while ammo and fuel are single quantities because those holds each carry one resource.

planFleetTransferCargoWithinFleet is the same idea inside one fleet: it moves one exact quantity between the fleet’s own holds (ammo, fuel, or cargoHold), named rather than addressed, so restocking ammunition from the general hold is one explicit call.

Both planners validate what they can prove from current state — ownership, fleet state, the holds involved — and produce the same inspectable Plan that every write uses. Signing and executing it works exactly as in Warp & subwarp.

Raw amounts and definitions

Section titled “Raw amounts and definitions”

quantityRaw is exactly what the chain stores. Turning it into something human-facing — a resource name, a decimal amount — needs the cargo definitions from the Game account, which the SDK loads and caches for you.

The mint on each item is the resource’s identity. Match it against the registry’s cargo definitions to get the name and its properties.

Cargo catalog

Section titled “Cargo catalog”

Read cargo names and properties independently of anyone’s inventory:

import {
  getCargoDefinition,
  listCargoDefinitions,
} from '@aephia/atlas-kit/cargo';


const definitions = await listCargoDefinitions(ctx);
const first = definitions[0];
if (first !== undefined) {
  const definition = await getCargoDefinition(ctx, first.id);
  console.log(definition.name, definition.mint);
}

The listing and by-id reads share the same immutable definitions in the loaded cargo section. They describe kinds of cargo; owned quantities still come from inventory reads. See Definition catalogs for preload, persistence, and section refresh behavior.

Gotchas

Section titled “Gotchas”

A fleet has more than one hold. cargoHold is the general one; fuel and ammunition are tracked separately, because the game treats them separately. Reading only cargoHold will miss them.

Capacity is not a single number. What a fleet can carry depends on its ships and their cargo pods, which come from the Game definitions rather than from the fleet account itself.

An empty items array is normal. A fleet that has just unloaded carries nothing. That is not an error and not a missing read.

Reference

Section titled “Reference”