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

> Scan patterns, fleet and character scanning state, and cooldowns.

Markdown source of https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/scanning/ — see https://docs-v0-5-0.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

Scanning is how fleets survey space for things worth finding. Like combat, it is
a capability-only entry, imported directly rather than reached through the root
client.

```ts
import {
  getFleetScanningState,
  getScanPatterns,
} from '@aephia/atlas-kit/scanning';
```

:::game[The pattern defines what a scan can find]
Scanning lets a fleet search its surroundings for useful finds. The selected
scan pattern says what the scan costs and which cargo or loot it may discover.
Some finds are more likely or more valuable than others, and a scan can also
come back empty. The fleet's location and scanning abilities help determine
what kind of result it gets.
:::

## Patterns are the catalog

A scan pattern is a definition: what a kind of scan does and what it costs.
Patterns are shared and stable, so read them once.

```ts
const patterns = await getScanPatterns(ctx);
```

> **Runnable example — Read scanning patterns and cooldown.** The scan pattern catalog, one fleet scanning state, and its derived cooldown. Run it in the browser at https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/scanning/.

## State is per fleet, and per character

Two projections, answering different questions:

```ts
const fleetState = await getFleetScanningState(ctx, fleetAddress);
const characterState = await getCharacterScanningState(ctx, profileAddress);
```

The fleet's state is about this fleet's scanning. The character's is the wider
picture across what they own — and note it starts from the **profile**
address, not the character's: the SDK derives the character from the profile
for you.

## Cooldowns are derived

```ts
const cooldown = deriveScanCooldownState(fleetState, nowUnixSeconds);
```

Note that this is a **plain function, not a read**. Cooldown is computed from
state you already have plus the pattern definitions — there is no account to
fetch that says "ready in 40 seconds".

That is a recurring shape in this SDK: anything time-dependent is derived at the
moment you ask, because storing it would mean storing something that is wrong a
second later.

:::game[One fleet cannot scan continuously]
After a scan, the fleet must wait before it can scan again. Different fleets
wait for different amounts of time because their ships and scanning abilities
are not the same. The chosen scan pattern can also make the wait longer or
shorter. This gives players a reason to build specialised scanning fleets and
to choose carefully when and where to use them.
:::

## Gotchas

**A cooldown is only as fresh as its inputs.** If you derive from a cached
snapshot, you are computing against that snapshot's age. Re-read before
deriving if precision matters.

**Not composed into the root client.** Import from `@aephia/atlas-kit/scanning`.

**Absent scanning state is normal.** A fleet that has never scanned has nothing
to report.

## Reference

- [`scanning`](/reference/scanning/) — every export in this entry
- [`fleets`](/guides/fleets/) — the fleet doing the scanning