# Combat
Documentation: next (source: develop).

Install the preview: `pnpm add @aephia/atlas-kit@next`. These docs follow develop and may include changes not yet published to npm.

> Inspect combat state, Loot, and Outlaw Flags, then plan supported Fleet combat and Loot actions.

Markdown source of https://develop.atlas-kit-docs.pages.dev/guides/combat/ — see https://develop.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

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

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

const status = await getFleetCombatStatus(ctx, fleetAddress);
```

:::game[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.

> **Runnable example — Read combat configuration and a fleet.** The game combat configuration, and one fleet combat status. Run it in the browser at https://develop.atlas-kit-docs.pages.dev/guides/combat/.

## Loot

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

```ts
const loot = await getLootByProfile(ctx, profileAddress);
```

## The outlaw flag

```ts
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.

:::game[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](https://github.com/Aephia/atlas-kit/issues/620#issuecomment-5743697192)
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](/guides/moving-a-fleet/#sign-and-execute-once).

## 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`](/reference/combat/) — every export in this entry
- [`combat/actions`](/reference/combat/actions/) — supported combat and Loot planning
- [`fleets`](/guides/fleets/) — the fleet a status belongs to