# Mini-map (hud.minimap)

## What it is for

Draws a world-space mini-map with overview or player-follow views, north-up or heading-up, zoom, routes, coloured entity markers and objectives, and reports clicks on the map to the game.

It needs `game.engine`; installing it brings them in.

## Turn it on

Install the kit in a project, then change a setting (the values shown are its defaults):

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "hud.minimap" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "hud.minimap",
                              config: { "visible": true, "mode": "overview" } }
```

## First example

The kit has no dedicated test yet; this installs it and sets two of its settings to their defaults.

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "hud.minimap" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "hud.minimap",
                              config: { "visible": true, "mode": "overview" } }
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `visible` | boolean | `true` |  |  |
| `mode` | string | `"overview"` | `overview`, `follow` |  |
| `orientation` | string | `"north"` | `north`, `player` |  |
| `shape` | string | `"circle"` | `circle`, `square` |  |
| `zoom` | number | `1` | 0.5–4 |  |
| `range` | number | `100` | 10–2000 | World metres across the view in follow mode at zoom 1. |
| `playerTag` | string | `"player"` |  |  |
| `markerTags` | array | `["racer", "objective", "marker"]` |  |  |
| `playerColor` | string | `"#ff934b"` |  |  |
| `markerColor` | string | `"#fff3d9"` |  |  |
| `zone` | boolean | `false` |  | The web view draws the zone of a zone kit (zone.storm) on the map: its edge now and, while it holds, where it closes in next. |

## Services, events, variables

- Service `hud.minimap`: snapshot(), configure(options), setLayer / removeLayer, setMarker / removeMarker, follow(entity), click(x, z, button) → minimap.clicked.
- Events emitted:
  - `minimap.clicked` (`x`, `z`, `button`) — The player clicked the map at that world point (web view).

## Hooks and modding

- Moddable settings: `visible`, `mode`, `orientation`, `shape`, `zoom`, `range`, `markerTags`, `playerColor`, `markerColor`, `zone`
- Moddable collections: `minimap_layers`
- Components: `map_marker`

## Engines

Declared targets: `web`, `godot`, `unity`, `unreal`, `rust`. `gripforge kit api hud.minimap` lists the exact settings and services of your version.

## Versions

Kit version 1.5.0.