Documentation: 0.5.0 (source: v0.5.0).
# Combat

> Fleet combat status, loot, and the outlaw flag.

Markdown source of https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/combat/ — see https://docs-v0-5-0.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://docs-v0-5-0.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.
:::

## 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.

**This combat capability remains read-only.** It can tell you a fleet's combat
state, but it cannot start, resolve, or influence a fight. The existence of
action entries elsewhere does not imply that combat has a curated planner.

## Reference

- [`combat`](/reference/combat/) — every export in this entry
- [`fleets`](/guides/fleets/) — the fleet a status belongs to