# Map
This file is responsible for the TMap positioning system.
It was made from scratch by Torwent but heavily inspired in the original
TWalker by [slacky](https://slacky.one/) and it's future iterations made by
Olly.
Without them, this wouldn't be possible.

For a online interactive map you can visit
[WaspScripts map](https://map.waspscripts.com/)

For something simpler and much closer to the original
[slacky](https://slacky.one/) walker check out {ref}`Image Map`.

For debugging purposes you can use `{$DEFINE WL_DEBUG_MAP}` before including
{ref}`WaspLib`.


- - -

## TPosition
Record holding a player's full position:
- X, Y coordinate
- Z which is the player height on the current heightmap
- Plane which is the player's current plane if several planes are being used.


- - -

## TMap
Record responsible for positioning.


- - -

## Map.AddLocalFilter
```pascal
procedure TMap.AddLocalFilter(filter: TBox; inside: Boolean);
```
Adds a position filter to the `TMap`.

This is a way to making it impossible for you to get positions inside of the
`filter` boxes your `TMap` has.

It's useful to understand the different between local and global coordinates to
know if you should use this or {ref}`Map.AddGlobalFilter` instead.


- - -

## Map.AddGlobalFilter
```pascal
procedure TMap.AddGlobalFilter(regionIdx: Int32; filter: TBox; inside: Boolean);
```
Adds a position filter to the `TMap`.

This is a way to making it impossible for you to get positions inside of the
`filter` boxes your `TMap` has.

It's useful to understand the different between local and global coordinates to
know if you should use this or {ref}`Map.AddLocalFilter` instead.


- - -

## Map.InternalSetup
```pascal
procedure TMap.InternalSetup();
```
Internal TMap setup method.
This is caleld automatically for you and you shouldn't need to call it.


- - -

## Map.Setup
```pascal
procedure TMap.SetupEx(boxes: TBoxArray; planes: TIntegerArray = [0]; downscale: UInt32 = 8);
procedure TMap.Setup(chunks: TMapChunkArray; downscale: UInt32 = 8);
procedure TMap.Setup(echunks: set of EChunk; downscale: UInt32 = 8); overload;
```
Sets up a {ref}`TMap`.


- - -

## Map.Add
```pascal
procedure TMap.AddEx(boxes: TBoxArray; planes: TIntegerArray = [0]; downscale: UInt32 = 8);
procedure TMap.Add(chunks: TMapChunkArray; downscale: UInt32 = 8);
procedure TMap.Add(echunks: set of EChunk; downscale: UInt32 = 8); overload;
```
TMap to add maps to an already setup TMap.


- - -

## Map.ScaledSearch
```pascal
function TMap.ScaledSearch(img: TImage): TPointArray;
```
Internal TMap method used to get an initial TPointArray of possible positions.
This is performed in a downscaled map with a downscaled minimap.
This is very innacurate by itself but by ruling down most of the map
in a downscaled search before doing a full sized search speed has a dramatic boost.
You probably won't ever need to call this directly.


- - -

## Map.Position
```pascal
function TMap.Position(): TPoint;
function TMap.FullPosition(): TPosition;
```
Returns the players current position on the loaded map.
`TMap.FullPosition()` also returns the current Z level.

Example:
```pascal
WriteLn(Map.Position());
WriteLn(Map.Similarity); // Check to see the match percentage if needed
```


- - -

## Map.Height
```pascal
function TMap.Height(pt: TPoint; global: Boolean = True): Single;
```
Returns the height of the player at the specified coordinate if there's a heightmap loaded.
If `pt` is `Default(TPoint)` then we will use our current position.
`global` decides wether the coordinate is converted to {ref}`global points` or if it's meant to be used
as internal {ref}`local points`.

Example:
```pascal
WriteLn Map.Height();
```


- - -

## Map.DebugPosition
```pascal
function TMap.DebugPosition(): TPoint;
```
Debugs the player position in the currently loaded map.

Example:
```pascal
Map.Setup(...);
while True do
  Map.DebugPosition();
```


- - -

## Map.DebugHeight
```pascal
procedure TMap.DebugHeight(img: TImage; dots: EDots);
procedure TMap.DebugHeight(dots: EDots = [EDot.PLAYER..EDot.ITEM]); overload;
```
Debugs the heightmap by projecting the outline of every tile around the player onto the
{ref}`MainScreen`.

Example:
```pascal
{$I WaspLib/main.simba}
begin
  Map.Setup([EChunk.VARROCK]);
  while True do
  begin
    Options.GetZoomLevel(False);
    Map.DebugHeight();
  end;
end.
```

```{figure} ../../images/mm2ms_height.gif
```


- - -

## Map variable
Global {ref}`TMap` variable.