Skip to content
Atom Core

Atom Core SDK

A cool SDK to interact with the StarAtlas sage game.

Installation

You can install atom using your preferred package manager

pnpm add @hexon-studio/atom-core

Usage

// Initialize SDK
const api = createAtom({
  rpcUrl: YOUR_RPC_URL,
  playerProfile: new PublicKey(""),
  owner: new PublicKey(""),
  keypair: "your_keypair_here"
})


await api.init()


// Get fleet info
const fleet = await api.fleet.getFleet(FLEET_NAME)


// Start mining operation
const signatures = await api.fleet.startMining({
  fleet: FLEET_NAME,
  resource: RESOURCE_NAME
})


// Cleanup
await api.dispose()

Error Handling

All API methods return promises that never rejects. A typed error will be returned in the response object.

const { status, data, error } = await api.fleet.startMining({
    fleet: FLEET_NAME,
    resource: RESOURCE_NAME
})


  if (status === "error") {
    console.error("Error:", error)
    return
  }


  console.log("Success", data)

All possible errors are exported from the SDK:

import { ... } from "@hexon-studio/atom-core/errors"

Cleanup

Always dispose the API when done:

await api.dispose()

This ensures proper cleanup of resources and connections.

API

The SDK is organized into several namespaces:

Core API

Fleet Operations

Starbase Operations

Utility Namespaces

  • pdas - Program Derived Address utilities
  • accounts - Account management utilities

PDAs API Methods

The pdas object provides methods to find various program derived addresses:

const { pdas } = api

Available PDA finders:

  • findCargoPodPda
  • findCraftableItemPda
  • findCraftingInstancePda
  • findCraftingProcessPda
  • findFleetPdaByName
  • findMineItemPda
  • findProfileFactionPda
  • findResourcePda
  • findSagePlayerProfilePda
  • findSectorPdaByCoordinates
  • findStarbasePdaByCoordinates
  • findStarbasePlayerPda
  • findUserPointsPda

Account Fetching Methods

The accounts namespace provides methods to fetch various game accounts:

const { accounts } = api

Game Accounts

  • fetchGameAccount(gamePublicKey: PublicKey) - Fetch the game account
  • fetchFleetAccount(fleetPubkey: PublicKey) - Fetch a fleet account by its public key
  • fetchFleetAccountByNameOrAddress(fleetNameOrAddress: string | PublicKey) - Fetch a fleet account by name or address
  • fetchFleetAccountsByPlayerProfile() - Fetch all fleet accounts owned by the configured player profile
  • fetchMineItemAccount(mineItemPubkey: PublicKey) - Fetch a mine item account
  • fetchPlanetAccount(planetPubkey: PublicKey) - Fetch a planet account
  • fetchResourceAccount(resourcePubkey: PublicKey) - Fetch a resource account
  • fetchSectorAccount(sectorPubkey: PublicKey) - Fetch a sector account
  • fetchStarbaseAccount(starbasePubkey: PublicKey) - Fetch a starbase account
  • fetchStarbasePlayerAccount(starbasePlayerPubkey: PublicKey) - Fetch a starbase player account

Cargo Accounts

  • fetchCargoPodAccount(cargoPodPublicKey: PublicKey) - Fetch a cargo pod account
  • fetchCargoTypeAccount(cargoTypePublicKey: PublicKey) - Fetch a cargo type account
  • fetchCargoStatsDefinitionAccount(cargoStatsDefPublicKey: PublicKey) - Fetch cargo stats definition account

Crafting Accounts

  • fetchCraftingFacilityAccount(facility: PublicKey) - Fetch a crafting facility account
  • fetchCraftingProcessAccount(process: PublicKey) - Fetch a crafting process account
  • fetchRecipeAccount(recipe: PublicKey) - Fetch a recipe account

Player Profile Accounts

  • fetchPlayerProfileAccount(playerProfilePublicKey: PublicKey) - Fetch a player profile account

All account fetching methods return a promise that resolves to the account data or rejects with an error if the account could not be found or accessed.

Example usage:

// Fetch a fleet account
const fleet = await api.accounts.fetchFleetAccount(fleetPubkey)


// Fetch all fleets owned by the player
const fleets = await api.accounts.fetchFleetAccountsByPlayerProfile()


// Fetch a starbase account
const starbase = await api.accounts.fetchStarbaseAccount(starbasePubkey)

api.init()

Initialize the SDK. Must be called before using any other methods.

api.dispose()

Clean up resources and connections. Should be called when done using the SDK.

api.fleet.dock(fleet)

Dock a fleet at the current starbase. The fleet should be in Idle state and should be owned by the configured player.

api.fleet.undock(fleet)

Undock a fleet from the current starbase. The fleet should be in StarLoadingBay state and should be owned by the configured player.

api.fleet.loadCargo({ fleet, items })

Load cargo resource to a fleet. The fleet should be in StarLoadingBay state and should be owned by the configured player.

The items param is an array of objects with the following structure:

{
  resourceMint: PublicKey,
  mode: "fixed" | "max" | "min" | "min-and-fill"
  amount: number,
  cargoPodKind: "ammo_bank" | "fuel_tank" | "cargo_hold"
}

Load modes

Each load mode has a different behavior:

  • fixed - Load a fixed amount of resource
  • max - Load the maximum amount of resource
  • min - Load the minimum amount of resource
  • min-and-fill - Load the minimum amount of resource and fill the rest with other resources

api.fleet.unloadCargo({ fleet, items })

Unload cargo resource from a fleet to a starbase hangar. The fleet should be StarbaseLoadingBay state and should be owned by the configured player.

The items param is an array of objects with the following structure:

{
  resourceMint: PublicKey,
  mode: "fixed" | "max"
  amount: number,
  cargoPodKind: "ammo_bank" | "fuel_tank" | "cargo_hold"
}

Unload modes

Each load mode has a different behavior:

  • fixed - Load a fixed amount of resource
  • max - Load the maximum amount of resource

api.starbase.loadCrew({ fleet, crewAmount })

Load a number of crew staff to a fleet. The fleet should be in StarbaseLoadingBay state and should be owned by the configured player.

api.starbase.unloadCrew({ fleet, crewAmount })

Unload a number of crew staff from a fleet. The fleet should be in StarbaseLoadingBay state and should be owned by the configured player.

api.fleet.warp({ fleet, targetSector })

Start a warp to a target sector. The fleet should be in Idle state and should be owned by the configured player.

api.fleet.subwarp({ fleet, targetSector })

Start a subwarp to a target sector. The fleet should be in Idle state and should be owned by the configured player.

api.starbase.startCrafting({ crew, starbase, quantity, recipe })

Start to craft a recipe on a starbase. The starbase should have enough resources and enough crew members to craft the recipe.

api.starbase.stopCrafting({ craftingId, starbase, recipe })

Stop a crafting process on a starbase. The starbase should have a crafting process running.