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.

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