# Installation

> Setup guide for ML Survival Kit

Category: SURVIVAL KIT · Source: https://miciomods.it/docs/ml-custommap-installation · Last updated: 2026-07-28

## Overview

`ml_custommap` replaces the default GTA minimap with a custom paper-map UI, a horizon compass HUD, and an in-world 3D waypoint system. Maps are plain image files in the `maps/` folder. Player markers, radius zones, labels, and pasted images persist either in item metadata or in a MySQL table. Fog of war tracks discovery per player, in the background, even with the map closed.

## Quick Start

1. Download from [CFX Portal](https://portal.cfx.re)
2. Extract to your `resources` folder as `ml_custommap`
3. Add to `server.cfg`:

**server.cfg**

```cfg
ensure oxmysql
ensure ox_lib
ensure ml_bridge
ensure ml_custommap
```

> **WARNING:** Load Order
>
> `ml_custommap` must start AFTER `ml_bridge` and `oxmysql`.

> **WARNING:** Resource Name
>
> The resource folder must be named exactly `ml_custommap`. The script validates this on start and locks itself if mismatched.

## Database

The table is created automatically on first start:

`ml_custommap_data`: Stores player markers, radii, labels, pasted images, and fog-of-war discovery bitmask. One row per serial (item metadata or license-based key)

## Item Registration

Register the map item(s) in your inventory system. The default config uses a single item:

- `tourist_map`: Opens the tourist map

When `Config.ItemMode = 'multi'`, every key in `Config.Items` must exist as an inventory item. When `Config.ItemMode = 'single'`, `Config.SingleItem` is the single item that unlocks map + compass.

The compass item is separate when `ItemMode = 'multi'`:

- `compass`: Shows the horizon compass HUD (configurable via `Config.Compass.item`)

> **TIP:** No Items Needed
>
> Set `Config.ItemMode = 'none'` to skip item checks entirely. Players always have access to the map and compass.

## Map Images

Drop image files into the `maps/` folder:

- `tourist_map.webp` (the bundled map), or any custom PNG / WEBP / JPG
- Any dimensions, any aspect ratio
- File paths are referenced from `Config.Maps[mapId].image`

## Commands & Keybinds

### Player

Input: Action

`P` (keybind `ml_custommap_open`): Open the map: rebindable via GTA keybind settings

`ESC`: When `Config.Keybind.disablePauseMenu = true`, opens a minimal settings frontend instead of the pause menu

### Staff

Command: Permission: Description

`/mapcalibrate [mapId]`: `Config.CalibrationCommand.permission`: Opens the calibration overlay

`/mapcalibrate done`: same: Finalizes the session, copies values to clipboard (subcommand name configurable)

`/mapcalibrate reset`: same: Discards the current calibration session (subcommand name configurable)

`/addblip [mapId]`: `Config.AdminCommand.permission`: Opens the map in admin mode to place default markers

`/nativemap`: `Config.NativeMap.staffPermission`: Toggles the native GTA map ON/OFF for the calling staff member only

Command names (`mapcalibrate`, `addblip`, `nativemap`) are configurable.

### Debug

Available only when `Config.Debug = true`:

`/map [mapId]`: Opens any map without requiring an item

`/compass`: Toggles the compass HUD on/off

`/mapclose`: Closes the map immediately

## Verify

After starting, the resource loads with no errors in the console.

Run `/mapcalibrate` (admin permission required) to open the calibration overlay for the default map. Run `/addblip` to place default markers visually and copy their config block to clipboard.

**Troubleshooting**

- **Map opens empty / black screen**: The file referenced in `Config.Maps[mapId].image` does not exist in `maps/`. Check the filename.
- **Markers are in the wrong position**: Calibration values don't match the image. Run `/mapcalibrate <mapId>` and paste the result into `Config.Maps[mapId].calibration`.
- **Fog reveal is tiny or gigantic**: `Config.FogOfWar.revealRadius` is measured in meters. On small stylized images use the per-map `fogRevealRadius` override.
- **`SCRIPT ERROR: attempt to call a nil value (method 'byte')`**: A binary blob in the `discovered` column. Run `UPDATE ml_custommap_data SET discovered = NULL;` and restart.
- **Native GTA map still visible**: `Config.HideDefaultMinimap` is `false` or `Config.NativeMap.allowEveryone` is `true`.