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

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

## Interfaces

<a id="characterscanningstatesnapshot"></a>

### CharacterScanningStateSnapshot

Defined in: [packages/sage/src/scanning/index.ts:149](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L149)

Focused read-only scanning projection of one derived Character.

#### Example

```ts
declare const state: CharacterScanningStateSnapshot;
console.log(state.dataRunnerXp.level, state.modifiers.power.value);
```

#### Properties

<a id="character"></a>

##### character

```ts
readonly character: EntityRef<"character">;
```

Defined in: [packages/sage/src/scanning/index.ts:151](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L151)

<a id="datarunnerxp"></a>

##### dataRunnerXp

```ts
readonly dataRunnerXp: CharacterXpCategoryData & {
  sequenceId: number;
};
```

Defined in: [packages/sage/src/scanning/index.ts:153](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L153)

###### Type Declaration

###### sequenceId

```ts
readonly sequenceId: number;
```

<a id="kind"></a>

##### kind

```ts
readonly kind: "characterScanningState";
```

Defined in: [packages/sage/src/scanning/index.ts:150](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L150)

<a id="modifiers"></a>

##### modifiers

```ts
readonly modifiers: {
  cooldown: ScanFixedValueData;
  power: ScanFixedValueData;
  sequenceId: number;
};
```

Defined in: [packages/sage/src/scanning/index.ts:156](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L156)

###### cooldown

```ts
readonly cooldown: ScanFixedValueData;
```

###### power

```ts
readonly power: ScanFixedValueData;
```

###### sequenceId

```ts
readonly sequenceId: number;
```

<a id="profile"></a>

##### profile

```ts
readonly profile: EntityRef<"profile">;
```

Defined in: [packages/sage/src/scanning/index.ts:152](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L152)

<a id="researchtagids"></a>

##### researchTagIds

```ts
readonly researchTagIds: readonly number[];
```

Defined in: [packages/sage/src/scanning/index.ts:161](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L161)

#### Methods

<a id="tojson"></a>

##### toJSON()

```ts
toJSON(): unknown;
```

Defined in: [packages/sage/src/scanning/index.ts:162](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L162)

###### Returns

`unknown`

***

<a id="fleetscanningstatesnapshot"></a>

### FleetScanningStateSnapshot

Defined in: [packages/sage/src/scanning/index.ts:128](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L128)

Focused read-only scanning projection of one Fleet.

#### Example

```ts
declare const state: FleetScanningStateSnapshot;
console.log(state.stats.power, state.cooldownEndsAtUnixSeconds);
```

#### Properties

<a id="cooldownendsatunixseconds"></a>

##### cooldownEndsAtUnixSeconds

```ts
readonly cooldownEndsAtUnixSeconds: bigint;
```

Defined in: [packages/sage/src/scanning/index.ts:132](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L132)

<a id="fleet"></a>

##### fleet

```ts
readonly fleet: EntityRef<"fleet">;
```

Defined in: [packages/sage/src/scanning/index.ts:130](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L130)

<a id="kind-1"></a>

##### kind

```ts
readonly kind: "fleetScanningState";
```

Defined in: [packages/sage/src/scanning/index.ts:129](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L129)

<a id="ownerprofile"></a>

##### ownerProfile

```ts
readonly ownerProfile: EntityRef<"profile">;
```

Defined in: [packages/sage/src/scanning/index.ts:131](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L131)

<a id="stats"></a>

##### stats

```ts
readonly stats: {
  bonus: number;
  cooldownSeconds: number;
  cost: number;
  power: number;
};
```

Defined in: [packages/sage/src/scanning/index.ts:133](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L133)

###### bonus

```ts
readonly bonus: number;
```

###### cooldownSeconds

```ts
readonly cooldownSeconds: number;
```

###### cost

```ts
readonly cost: number;
```

###### power

```ts
readonly power: number;
```

#### Methods

<a id="tojson-1"></a>

##### toJSON()

```ts
toJSON(): unknown;
```

Defined in: [packages/sage/src/scanning/index.ts:139](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L139)

###### Returns

`unknown`

***

<a id="scanpatterncost"></a>

### ScanPatternCost

Defined in: [packages/sage/src/scanning/index.ts:75](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L75)

One cargo-backed scan cost.

#### Example

```ts
declare const cost: ScanPatternCost;
console.log(cost.cargo.name, cost.multiplier.value);
```

#### Properties

<a id="cargo"></a>

##### cargo

```ts
readonly cargo: CargoDefinitionSummary;
```

Defined in: [packages/sage/src/scanning/index.ts:76](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L76)

<a id="multiplier"></a>

##### multiplier

```ts
readonly multiplier: ScanFixedValueData;
```

Defined in: [packages/sage/src/scanning/index.ts:77](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L77)

***

<a id="scanpatternlootoutcome"></a>

### ScanPatternLootOutcome

Defined in: [packages/sage/src/scanning/index.ts:87](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L87)

One cargo-backed scan outcome and its research-tag requirements.

#### Example

```ts
declare const outcome: ScanPatternLootOutcome;
console.log(outcome.output.name, outcome.researchRequirementTagIds);
```

#### Properties

<a id="output"></a>

##### output

```ts
readonly output: CargoDefinitionSummary;
```

Defined in: [packages/sage/src/scanning/index.ts:88](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L88)

<a id="outputamountraw"></a>

##### outputAmountRaw

```ts
readonly outputAmountRaw: bigint;
```

Defined in: [packages/sage/src/scanning/index.ts:89](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L89)

<a id="researchrequirementtagids"></a>

##### researchRequirementTagIds

```ts
readonly researchRequirementTagIds: readonly number[];
```

Defined in: [packages/sage/src/scanning/index.ts:93](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L93)

<a id="rollweight"></a>

##### rollWeight

```ts
readonly rollWeight: ScanFixedValueData;
```

Defined in: [packages/sage/src/scanning/index.ts:91](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L91)

<a id="threshold"></a>

##### threshold

```ts
readonly threshold: ScanFixedValueData;
```

Defined in: [packages/sage/src/scanning/index.ts:90](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L90)

<a id="xpvalue"></a>

##### xpValue

```ts
readonly xpValue: ScanFixedValueData;
```

Defined in: [packages/sage/src/scanning/index.ts:92](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L92)

***

<a id="scanpatternsnapshot"></a>

### ScanPatternSnapshot

Defined in: [packages/sage/src/scanning/index.ts:103](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L103)

Immutable, definition-resolved ScanPattern catalog entry.

#### Example

```ts
declare const pattern: ScanPatternSnapshot;
console.log(pattern.name, pattern.loot.length);
```

#### Properties

<a id="address"></a>

##### address

```ts
readonly address: Address;
```

Defined in: [packages/sage/src/scanning/index.ts:105](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L105)

<a id="blankweight"></a>

##### blankWeight

```ts
readonly blankWeight: ScanFixedValueData;
```

Defined in: [packages/sage/src/scanning/index.ts:112](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L112)

<a id="blankxpvalue"></a>

##### blankXpValue

```ts
readonly blankXpValue: ScanFixedValueData;
```

Defined in: [packages/sage/src/scanning/index.ts:113](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L113)

<a id="bump"></a>

##### bump

```ts
readonly bump: number;
```

Defined in: [packages/sage/src/scanning/index.ts:107](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L107)

<a id="cooldownmultiplier"></a>

##### cooldownMultiplier

```ts
readonly cooldownMultiplier: ScanFixedValueData;
```

Defined in: [packages/sage/src/scanning/index.ts:111](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L111)

<a id="costs"></a>

##### costs

```ts
readonly costs: readonly ScanPatternCost[];
```

Defined in: [packages/sage/src/scanning/index.ts:115](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L115)

<a id="game"></a>

##### game

```ts
readonly game: EntityRef<"game">;
```

Defined in: [packages/sage/src/scanning/index.ts:110](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L110)

<a id="id"></a>

##### id

```ts
readonly id: number;
```

Defined in: [packages/sage/src/scanning/index.ts:108](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L108)

<a id="kind-2"></a>

##### kind

```ts
readonly kind: "scanPattern";
```

Defined in: [packages/sage/src/scanning/index.ts:104](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L104)

<a id="loot"></a>

##### loot

```ts
readonly loot: readonly ScanPatternLootOutcome[];
```

Defined in: [packages/sage/src/scanning/index.ts:116](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L116)

<a id="name"></a>

##### name

```ts
readonly name: string;
```

Defined in: [packages/sage/src/scanning/index.ts:109](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L109)

<a id="noisemaps"></a>

##### noiseMaps

```ts
readonly noiseMaps: readonly ScanNoiseMapData[];
```

Defined in: [packages/sage/src/scanning/index.ts:117](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L117)

<a id="status"></a>

##### status

```ts
readonly status: "active" | "draft";
```

Defined in: [packages/sage/src/scanning/index.ts:114](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L114)

<a id="version"></a>

##### version

```ts
readonly version: number;
```

Defined in: [packages/sage/src/scanning/index.ts:106](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L106)

#### Methods

<a id="tojson-2"></a>

##### toJSON()

```ts
toJSON(): unknown;
```

Defined in: [packages/sage/src/scanning/index.ts:118](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L118)

###### Returns

`unknown`

## Type Aliases

<a id="scancooldownstate"></a>

### ScanCooldownState

```ts
type ScanCooldownState = 
  | {
  kind: "ready";
}
  | {
  kind: "cooldown";
  remainingSeconds: bigint;
};
```

Defined in: [packages/sage/src/scanning/index.ts:175](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L175)

Pure Fleet cooldown state at one explicit Unix timestamp.

#### Example

```ts
declare const fleet: FleetScanningStateSnapshot;
const state: ScanCooldownState = deriveScanCooldownState(
  fleet,
  1_700_000_000n,
);
```

***

<a id="scanfixedvalue"></a>

### ScanFixedValue

```ts
type ScanFixedValue = ScanFixedValueData;
```

Defined in: [packages/sage/src/scanning/index.ts:46](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L46)

Fixed-point scanning value with exact raw storage.

#### Example

```ts
const value: ScanFixedValue = { raw: 65_536n, value: 1 };
```

***

<a id="scannoisemap"></a>

### ScanNoiseMap

```ts
type ScanNoiseMap = ScanNoiseMapData;
```

Defined in: [packages/sage/src/scanning/index.ts:55](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L55)

One translated noise-map row used by a ScanPattern.

#### Example

```ts
declare const noise: ScanNoiseMap;
console.log(noise.seedOffset, noise.weight.value);
```

***

<a id="scanpatterndiscoveryoptions"></a>

### ScanPatternDiscoveryOptions

```ts
type ScanPatternDiscoveryOptions = Omit<DiscoveryRequest, "filters" | "strategy">;
```

Defined in: [packages/sage/src/scanning/index.ts:63](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L63)

Options supported by targeted ScanPattern catalog discovery.

#### Example

```ts
const options: ScanPatternDiscoveryOptions = { commitment: 'confirmed' };
```

## Functions

<a id="derivescancooldownstate"></a>

### deriveScanCooldownState()

```ts
function deriveScanCooldownState(fleet, atUnixSeconds): ScanCooldownState;
```

Defined in: [packages/sage/src/scanning/index.ts:478](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L478)

Derives whether a Fleet scan cooldown is ready at an explicit timestamp.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `fleet` | [`FleetScanningStateSnapshot`](/reference/scanning/#fleetscanningstatesnapshot) |
| `atUnixSeconds` | `bigint` |

#### Returns

[`ScanCooldownState`](/reference/scanning/#scancooldownstate)

#### Example

```ts
declare const fleet: FleetScanningStateSnapshot;
const state = deriveScanCooldownState(fleet, 1_700_000_000n);
```

***

<a id="getcharacterscanningstate"></a>

### getCharacterScanningState()

```ts
function getCharacterScanningState(
   context, 
   profile, 
options?): Promise<CharacterScanningStateSnapshot>;
```

Defined in: [packages/sage/src/scanning/index.ts:418](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L418)

Derives one Character from Profile and returns focused scanning progression.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `context` | [`SageContext`](/reference/#sagecontext) |
| `profile` | [`Address`](/reference/#address-19) |
| `options?` | [`ReadOptions`](/reference/client/#readoptions) |

#### Returns

`Promise`\<[`CharacterScanningStateSnapshot`](/reference/scanning/#characterscanningstatesnapshot)\>

#### Example

```ts
declare const ctx: SageContext;
declare const profile: Address;
const state = await getCharacterScanningState(ctx, profile);
```

***

<a id="getfleetscanningstate"></a>

### getFleetScanningState()

```ts
function getFleetScanningState(
   context, 
   address, 
options?): Promise<FleetScanningStateSnapshot>;
```

Defined in: [packages/sage/src/scanning/index.ts:366](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L366)

Reads one Fleet and returns only its translated scanning state.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `context` | [`SageContext`](/reference/#sagecontext) |
| `address` | [`Address`](/reference/#address-19) |
| `options?` | [`ReadOptions`](/reference/client/#readoptions) |

#### Returns

`Promise`\<[`FleetScanningStateSnapshot`](/reference/scanning/#fleetscanningstatesnapshot)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: Address;
const state = await getFleetScanningState(ctx, fleet);
```

***

<a id="getscanpattern"></a>

### getScanPattern()

```ts
function getScanPattern(
   context, 
   patternId, 
options?): Promise<ScanPatternSnapshot>;
```

Defined in: [packages/sage/src/scanning/index.ts:284](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L284)

Derives and reads one required ScanPattern for the configured Game.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `context` | [`SageContext`](/reference/#sagecontext) |
| `patternId` | `number` |
| `options?` | [`ReadOptions`](/reference/client/#readoptions) |

#### Returns

`Promise`\<[`ScanPatternSnapshot`](/reference/scanning/#scanpatternsnapshot)\>

#### Example

```ts
declare const ctx: SageContext;
const pattern = await getScanPattern(ctx, 2);
```

***

<a id="getscanpatterns"></a>

### getScanPatterns()

```ts
function getScanPatterns(context, options?): Promise<readonly ScanPatternSnapshot[]>;
```

Defined in: [packages/sage/src/scanning/index.ts:344](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L344)

Discovers the configured Game's ScanPattern catalog with targeted filters.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `context` | [`SageContext`](/reference/#sagecontext) |
| `options?` | [`ScanPatternDiscoveryOptions`](/reference/scanning/#scanpatterndiscoveryoptions) |

#### Returns

`Promise`\<readonly [`ScanPatternSnapshot`](/reference/scanning/#scanpatternsnapshot)[]\>

#### Example

```ts
declare const ctx: SageContext;
const patterns = await getScanPatterns(ctx);
```

***

<a id="maybegetscanpattern"></a>

### maybeGetScanPattern()

```ts
function maybeGetScanPattern(
   context, 
   patternId, 
   options?): Promise<
  | ScanPatternSnapshot
| undefined>;
```

Defined in: [packages/sage/src/scanning/index.ts:314](https://github.com/Aephia/atlas-kit/blob/v0.5.0/packages/sage/src/scanning/index.ts#L314)

Derives and reads one optional ScanPattern for the configured Game.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `context` | [`SageContext`](/reference/#sagecontext) |
| `patternId` | `number` |
| `options?` | [`ReadOptions`](/reference/client/#readoptions) |

#### Returns

`Promise`\<
  \| [`ScanPatternSnapshot`](/reference/scanning/#scanpatternsnapshot)
  \| `undefined`\>

#### Example

```ts
declare const ctx: SageContext;
const pattern = await maybeGetScanPattern(ctx, 2);
```