# Map NPCs
The NPCs of the loaded map: where each one spawns, what it's called, what it can be clicked for,
and what it looks like.

The game cache doesn't say where NPCs spawn, the server places them, so the spawns come from the
`files/npcspawns.txt` asset. Everything else is read out of the game cache, so it's always in step
with the game, and the NPCs of a region are only read once that region is part of the map.

Example:
```pascal
{$I WaspLib/main.simba}
var
  bankers: TEntityArray;
begin
  Map.Setup([EChunk.VARROCK]);
  bankers := TEntityArray.Create(Map.Walker, MapNPCs.GetByAction('Bank'));
end.
```


- - -

## TMapNPCData
One kind of NPC and every place it spawns on the loaded map.
- `ID` is the id it spawns as. `Name`, `Level`, `Category`, `Actions` and `MinimapDot` come from
  the definition it's shown as, which for an NPC that changes form is the first form with a name.
  `Actions` are the ones its right-click menu shows, in menu order, and `MinimapDot` says whether
  it has a dot on the minimap.
- `Coordinates` are where it spawns, as {ref}`Global points`.
- `Size` is how many tiles it covers on each side and `Height` how tall it is, in the game's
  units: a tile is `128`.
- `Colors` are the colours it is drawn in, most common first.

`Height` and `Colors` come from the NPC's models, which are only built when the NPC is asked for -
see {ref}`MapNPCs.Build`.


- - -

## TMapNPCs
Record holding the {ref}`TMapNPCData` of every NPC on the loaded map.
- `Definitions` are the definitions of `Data`, in the same order, for building their models.
- `Lookup` turns an NPC id into its place in `Data`, stored one higher so `0` means none.
- `Loaded` holds the chunks already read, as `x, y` with the plane packed in with them.
- `SpawnIDs`, `SpawnTiles` and `SpawnPlanes` are every line of the spawns file, and
  `SpawnChunks` the chunks they're in, packed like `Loaded`. `SpawnStarts` is where the run of
  lines of each of `SpawnChunks` starts, with one extra entry closing the last run.


- - -

## MapNPCs.LoadSpawns
```pascal
procedure TMapNPCs.LoadSpawns();
```
Internal method that reads the spawns file into the `Spawn` fields, once.

The file holds one `id plane x y` line per spawn, sorted so the spawns of each chunk are one run
of lines, which is what lets a chunk's spawns be found without searching them all.


- - -

## MapNPCs.Add
```pascal
procedure TMapNPCs.Add(id, plane: Integer; tile: TPoint);
```
Internal method that records one spawn of NPC `id` on `tile`, adding the NPC if it's the first
one. NPCs without a name, or that can't be interacted with, are left out.


- - -

## MapNPCs.Load
```pascal
procedure TMapNPCs.Load(var loader: TMapLoader);
procedure TMapNPCs.Load(); overload;
```
Reads the NPCs of every chunk `loader` has loaded that hasn't been read yet. Without a loader it
reads {ref}`Map`'s. The getters below call this, so it rarely needs calling directly.


- - -

## MapNPCs.Build
```pascal
procedure TMapNPCs.Build(idx: Integer);
```
Internal method that builds the models of `Data[idx]` with {ref}`TNPCModel` to fill in its
`Height` and `Colors`.

Only the colours that cover most of the NPC make it into `Colors`: the most common ones, until
`COVERAGE` of its faces are accounted for. The rest are slivers and rarely lit corners that would
only widen what a colour finder looks for.


- - -

## MapNPCs.GetByName
```pascal
function TMapNPCs.GetByName(name: String; amount: Integer = 0): TMapNPCDataArray;
```
Every NPC called `name`. Pass `amount` to stop after that many NPCs.

Example:
```pascal
WriteLn MapNPCs.GetByName('Banker');
```


- - -

## MapNPCs.GetByID
```pascal
function TMapNPCs.GetByID(id: Integer): TMapNPCData;
```
The NPC with the id `id`. It has no `Coordinates` if there is no such NPC on the map.


- - -

## MapNPCs.GetByAction
```pascal
function TMapNPCs.GetByAction(action: String; amount: Integer = 0): TMapNPCDataArray;
```
Every NPC with `action` in its right-click menu. Pass `amount` to stop after that many NPCs.

Example:
```pascal
WriteLn MapNPCs.GetByAction('Bank');
```


- - -

## MapNPCs.GetByAllActions
```pascal
function TMapNPCs.GetByAllActions(actions: TStringArray; amount: Integer = 0): TMapNPCDataArray;
```
Every NPC with all of `actions` in its right-click menu. Pass `amount` to stop after that many
NPCs.


- - -

## MapNPCs.Clear
```pascal
procedure TMapNPCs.Clear();
```
Forgets every NPC read so far, so the next getter reads the map again from scratch.


- - -

## MapNPCs variable
Global {ref}`TMapNPCs` variable, holding the NPCs of {ref}`Map`.