Combat

Combat is a capability-only entry: it is not composed into the root client, so you import it directly.

import {
  getFleetCombatStatus,
  getCombatConfiguration,
} from '@aephia/atlas-kit/combat';

const status = await getFleetCombatStatus(ctx, fleetAddress);

Combat compares two fleets

Combat starts with the ships, weapons, and defences in the attacking and defending fleets. The game works out whether attacks hit, whether they are critical hits, and how much damage the defender can block. Damage normally wears down shields before it harms the fleet’s hull. There is an element of chance, which means the stronger fleet may not always win.

Configuration and status are different reads

Configuration comes from the Game account: the rules combat runs by, shared by everyone and stable.

Status is one fleet’s current combat state, which changes.

Reading configuration once and status often is the right pattern — the SDK’s cache makes that cheap, since configuration is part of the Game definitions it already holds.

Loot

Loot accounts are what combat leaves behind. They have no derivable address, so finding loot you have no reference to needs discovery:

const loot = await getLootByProfile(ctx, profileAddress);

The outlaw flag

const flag = await getOutlawFlag(ctx, profileAddress, againstFaction);

Outlaw state is derived rather than stored as a simple boolean, and it may not exist for a given profile at all. Treat its absence as “not an outlaw” rather than as a failed read.

Outlaw status is faction-specific

The game tracks outlaw status separately for each faction. A player can therefore be marked as an outlaw to MUD without automatically having the same status with ONI or Ustur. The flag records when that status began and how long its PvP period lasts. If there is no flag for a player and faction, the game has no outlaw declaration recorded for that pair.

Planning supported combat actions

The separate @aephia/atlas-kit/combat/actions entry prepares inspectable Plans for applying a catalogued stimulant to an owned Fleet, attacking one Fleet or Starbase, and retrieving selected Loot. It does not predict or resolve combat locally: permission, range, randomness, rewards, damage, stimulant stacking, and final outcomes remain chain-authoritative.

Fleet attacks require the current Game-2 runtime, both existing canonical operator-Character Career XP budgets (schema 1, reconciled), and shared XP configuration. This applies to player and NPC attackers and defenders, including two Fleets sharing one operator. NPC classification still uses the Fleet marker, not its name or sidecars. Missing, unreconciled, sealed or unsupported state fails locally; repair it outside the Plan and recreate the attack. No initialization, funding, migration or fallback is performed.

Saved Plans retain the exact instruction bytes, addresses and roles. Hydration rejects missing or mismatched intent; execution revalidates both operator identities and XP eligibility before invoking any signer. Earned XP, bank balances and unrelated configuration economics may change. Recreate older Fleet-attack Plans that omit these safeguards.

#620’s qualification includes a genuine successful PTR attack and explicitly local deployed-program NPC controls accepted by the maintainer. The controls modified co-location, NPC markers and hit chance; they are not naturally eligible PTR coverage of every NPC pairing. Both budgets remain required even after a no-kill success: which XP state is consumed depends on the chain-authoritative outcome. No fixed XP yield, victory, damage or reward amount is promised.

Starbase attacks resolve canonical Democracy history and check daily eligibility. On Game version 2 they also require an existing reconciled Character XP budget and XP configuration. These accounts are checked again before signing; the planner does not initialize, fund or migrate them, or promise an XP amount. Recreate saved Starbase-attack Plans from older SDK versions. This compatibility route has offline coverage, not new live-chain qualification.

Storage paid from your Profile

Applying a stimulant to a stat that has no active effect yet grows the Fleet, and retrieving Loot can add a cargo-hold line for each cargo the hold lacks; the Fleet is paid for before the emptied Loot refunds its own storage. The game pays both from your Profile’s SOL vault with the signing key. Those Plans state the amount, apart from transaction fees; a Loot retrieval states an upper bound, since the Loot may hold less than you ask for. When it is positive, the key must be a Profile AUTH key or also hold drainSolVault, and your Profile needs that many lamports above its own rent reserve. Execution checks again before signing.

An attack can also take storage from your Profile: Loot created when cargo drops or rewards fall due, and the defender’s Fleet when the outcome changes it. Both depend on the chain-authoritative combat outcome, so the planner cannot state an amount and leaves the key and balance to the program. Use a Profile AUTH key or one that also holds drainSolVault for attacks, and keep the Profile funded; simulate to see the outcome.

Review and simulate the Plan before supplying external signers through the usual execution flow.

Gotchas

Not composed into the root client. sage.combat does not exist. Import from @aephia/atlas-kit/combat and pass the context, as shown above. The same is true of scanning, rewards, factions, and loyalty.

Combat status can be absent. A fleet that has never fought has nothing to report.

Combat reads and actions use separate entries. @aephia/atlas-kit/combat remains read-only; use @aephia/atlas-kit/combat/actions for the curated actions above. Those planners prepare explicit transactions, but they do not resolve combat locally or promise an outcome.

Reference

• combat — every export in this entry
• combat/actions — supported combat and Loot planning
• fleets — the fleet a status belongs to