# Region Loader
Loads regions on demand and keeps track of which ones are in memory.

Ground colours blend across region boundaries, so a region is never useful on its own - see
{ref}`TRegionLoader.LoadRegionAndNeighbors`.


- - -

## RegionLoader.BuildLookup
```pascal
procedure TRegionLoader.BuildLookup();
```
Builds the table that turns a region coordinate into an index into `Regions`.

It is a flat 256 by 256 array of indices rather than a search, since region coordinates are
bounded and small, and `-1` marks a coordinate with no region loaded. Already-built tables are
left alone; {ref}`TRegionLoader.LoadRegionAndNeighbors` keeps it up to date as it goes.


- - -

## RegionLoader.RegionCoordinateIndex
```pascal
function TRegionLoader.RegionCoordinateIndex(x, y: Integer): Integer;
```
The index in `Regions` of the region at region coordinates `x, y`, or `-1` if it is not loaded.


- - -

## RegionLoader.RegionFileData
```pascal
function TRegionLoader.RegionFileData(id, fileID: Integer; out data: TByteArray): Boolean; static;
```
The bytes of one file of region `id`'s map archive - file `0` is its terrain and file `1` its
objects - or False if the map index holds no such archive or file.

Both are looked up by index rather than through `Value`, so a region that is simply empty world -
which most region ids are - costs one probe of each table and no copying at all.

The map index has to be cached first.


- - -

## RegionLoader.LoadMapDef
```pascal
function TRegionLoader.LoadMapDef(id: Integer; out map: TMapDefinition): Boolean;
```
Decodes the terrain of region `id`, returning False if the map index holds nothing for it -
which is the normal case for the many region ids that are simply empty world.

The map index has to be cached first.


- - -

## RegionLoader.LoadLocDef
```pascal
function TRegionLoader.LoadLocDef(id: Integer; out locs: TLocationsDefinition): Boolean;
```
Decodes the object placements of region `id`, returning False if it has none.

A region that has terrain need not have objects, which is why this is separate from
{ref}`TRegionLoader.LoadMapDef`.


- - -

## RegionLoader.LoadRegion
```pascal
function TRegionLoader.LoadRegion(id: Integer; out region: TRegion): Boolean;
```
Builds one region from the cache: its terrain, and its objects if it has any. Returns False if
there is no such region.


- - -

## RegionLoader.LoadRegionAt
```pascal
function TRegionLoader.LoadRegionAt(regionX, regionY: Integer): Integer;
```
The index in `Regions` of the region at `regionX, regionY`, loading it first if it is not loaded
yet. Returns `-1` if there is no such region.


- - -

## RegionLoader.LoadRegionAndNeighbors
```pascal
function TRegionLoader.LoadRegionAndNeighbors(regionX, regionY: Integer): Boolean;
```
Loads the region at `regionX, regionY` along with the four next to it, and returns whether the
middle one exists.

The neighbours are needed because ground colours blend across region boundaries - without them
the map would show a seam at every edge. Regions already loaded are left alone, so calling this
per chunk while panning around only pays for what is new.


- - -

## RegionLoader.LoadAllRegions
```pascal
procedure TRegionLoader.LoadAllRegions();
```
Loads every region the cache has, reporting progress as it goes.

This is minutes of work and gigabytes of memory - it is for dumping the whole world, not for
rendering part of it. {ref}`TRegionLoader.LoadRegionAndNeighbors` is what a map viewer wants.