# Map Data Loader
Everything {ref}`TMapChunkLoader` needs before it can draw a map: ground colours, object
definitions, and the sprites for map scenes and area icons.

Load it once - see {ref}`TMapDataLoader.Load` - not per chunk.


- - -

## MapDataLoader.LoadUnderlays
```pascal
procedure TMapDataLoader.LoadUnderlays();
```
Loads every ground underlay definition, caching the underlay archive first if it has not been
already.


- - -

## MapDataLoader.LoadOverlays
```pascal
procedure TMapDataLoader.LoadOverlays();
```
Loads every ground overlay definition, caching the overlay archive first if it has not been
already.


- - -

## MapDataLoader.LoadObjects
```pascal
procedure TMapDataLoader.LoadObjects();
```
Loads every world object definition, caching the object archive first if it has not been already.

This is the slowest part of {ref}`TMapDataLoader.Load` by some distance - there are tens of
thousands of them, and the map renderer needs any of them to be reachable by id.


- - -

## MapDataLoader.LoadAreas
```pascal
procedure TMapDataLoader.LoadAreas();
```
Loads every map area definition, caching the area archive first if it has not been already.


- - -

## MapDataLoader.LoadSpriteArchive
```pascal
function TMapDataLoader.LoadSpriteArchive(archiveId: Integer): TSpriteDefinitionArray;
```
Every frame of one sprite archive.

Sprite archives are read straight out of the index rather than through
{ref}`TCacheIndex.Cache`, so that pulling in a handful of icons does not mean decompressing all
of them. A negative id, a missing archive or an empty one all come back as an empty array.


- - -

## MapDataLoader.LoadMapScenes
```pascal
procedure TMapDataLoader.LoadMapScenes();
```
Loads the map scene sprites - the little pictures the minimap draws in place of certain objects,
such as staircases, altars and furnaces.


- - -

## MapDataLoader.LoadAreaIcons
```pascal
procedure TMapDataLoader.LoadAreaIcons();
```
Loads the icon of every area that has one, indexed to line up with `Areas`.

{ref}`TMapDataLoader.LoadAreas` has to have run first, since it is the area definitions that say
which sprite each icon comes from.


- - -

## MapDataLoader.LoadSpriteFrame
```pascal
function TMapDataLoader.LoadSpriteFrame(archiveId, frame: Integer): TSpriteDefinition; static;
```
A single frame of a sprite archive, for when the whole archive is not wanted. A missing archive
or frame comes back blank.


- - -

## MapDataLoader.LoadTextures
```pascal
procedure TMapDataLoader.LoadTextures();
```
Loads every texture definition, caching the texture index first if it has not been already.

The map renderer only wants their average colours, which is what a textured ground overlay is
drawn as.


- - -

## MapDataLoader.BuildOverlayColors
```pascal
procedure TMapDataLoader.BuildOverlayColors();
```
Works out the colour each ground overlay is drawn as on the minimap.

It depends only on the overlay - its secondary colour, its texture's average colour, or its own
colour, in that order - so it is settled per overlay here instead of per tile of every plane of
every region.

This is the one part of {ref}`TMapDataLoader.PrepareForRendering` that reads the palette, which
is why it is separate: {ref}`TMapChunkLoader.EnsureColorsCurrent` runs it again on its own when
the brightness changes.


- - -

## MapDataLoader.PrepareForRendering
```pascal
procedure TMapDataLoader.PrepareForRendering();
```
Works out everything the map renderer would otherwise derive over and over from data that never
changes once loaded. Run at the end of {ref}`TMapDataLoader.Load`, after every definition it
reads is in place.

Three things are settled here: the overlay colours {ref}`TMapDataLoader.BuildOverlayColors`
works out, the map scene sprites made fully opaque with a fully transparent pixel flattened to
`0` so that drawing one is a copy, and
one {ref}`TImage` per area icon so that drawing the same icon in a dozen regions does not build
a dozen images of it.


- - -

## MapDataLoader.Load
```pascal
procedure TMapDataLoader.Load();
```
Loads everything {ref}`TMapChunkLoader` needs to draw a map: ground colours, object definitions,
and the sprites for map scenes and area icons.

This caches the config archives it reads and every texture, so it takes a while and a few hundred
megabytes. Do it once before rendering rather than per chunk.

Example:
```pascal
CacheReader := TCacheReader.Create();
CacheReader.Indices[ECacheIndex.MAPS].Cache();
chunkLoader.MapData.Load();
```