> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awokenlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Map

# Map

The atlas image, its aspect ratio, and the game coords it represents are all set in `config.lua`. No HTML or JS edits needed.

```lua theme={"dark"}
Config.map = {
    image       = 'assets/map.png',
    aspectRatio = { width = 1600, height = 2400 },
    worldBounds = { minX = -4279, maxX = 4966, minY = -5173, maxY = 8456 },
}
```

## Swap the atlas

### Replace in place

`html/assets/map.png` is not escrow-locked. Overwrite it and restart. If the new image is the same dimensions as the default, no other change is needed.

### Or use a different file path

```lua theme={"dark"}
Config.map.image = 'assets/my-custom-map.png'
```

Drop the new image at `html/assets/my-custom-map.png`. Relative paths resolve inside `html/`.

### Or host externally

```lua theme={"dark"}
Config.map.image = 'https://your-cdn.com/map.png'
```

Handy if you want to swap the atlas without redeploying.

## Match the aspect ratio

If the image is a different size:

```lua theme={"dark"}
Config.map.aspectRatio = { width = 1024, height = 1024 }
```

Used to compute the map frame's on-screen aspect so nothing stretches or letter-boxes.

## Calibrate pin positions

```lua theme={"dark"}
Config.map.worldBounds = { minX = -4279, maxX = 4966, minY = -5173, maxY = 8456 }
```

If pins drift after swapping the image:

1. Pick a known landmark (e.g. LSIA at `(-1037, -2737)`).
2. Compare where its pin lands vs where you can see it on the image.
3. Nudge:
   * Pin too far **left** → decrease `minX` **and** `maxX`
   * Pin too far **right** → increase both
   * Pin too **high** → increase `minY` **and** `maxY`
   * Pin too **low** → decrease both
4. Repeat with a landmark in a different corner. If that one's off, narrow or widen only the X or Y range.

### Calibration wizard

Set `Config.debug = true` and open the selector. A calibration badge appears top-right with two modes:

* **Single-click** any empty spot on the map → prints a `pin = { x = %, y = % }` snippet for that spot
* **Two-point wizard** — click Legion Square, then Sandy Shores → computes a full `worldBounds` block ready to paste

Right-click cancels the wizard.

## Cache note

Swapping `map.png` in place may serve the old cached image until the resource is restarted. To bust the cache without a restart, rename the file and update `Config.map.image`, or host externally and use a query string (`?v=2`).