# Installation

> Install the resource, register the UI and DUI items, and choose the native minimap style.

Category: CARTOGRAPHY · Source: https://miciomods.it/docs/ml-custommap-installation · Last updated: 2026-10-05

## Install the resource

Cartography provides four full-world map designs: Custom Tourist, Satellite, Road and Atlas. Each has a UI item and an interactive DUI item that displays the map on a paper prop held by the player. The Del Perro treasure image is a separate regional example.

1. Download the resource from CFX Portal and extract it into your server resources.
2. Keep the resource folder named `ml_custommap`.
3. Start your framework and inventory, then the required resources in this order:

**server.cfg**

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

1. Register the map items in your inventory and copy their icons from `_INSTALL/images`.
2. Review `shared/config.lua`, including the item access mode and server minimap style.

Keep `ml_custommap` running before players connect when using its native minimap. Stopping and starting a streaming resource while a client is already in game can leave the minimap incomplete. Reconnect with the resource running if this happens.

## Database

The resource creates `ml_custommap_data` automatically on startup. MySQL stores markers, radius zones, text labels, pasted images and fog progress. In metadata mode, the map item carries the serial that identifies its database row.

## Map items and icons

- Custom Tourist: `tourist_map` opens the UI; `dui_map` opens the held paper map.
- Satellite: `satellite_map` opens the UI; `satellite_map_dui` opens the held paper map.
- Road: `road_map` opens the UI; `road_map_dui` opens the held paper map.
- Atlas: `atlas_map` opens the UI; `atlas_map_dui` opens the held paper map.
- Del Perro treasure example: `treasure_map` opens the UI; `treasure_map_dui` opens the held paper map.

Use `_INSTALL/items.lua` as the inventory reference. Map items are non-stackable so each item can carry its own serial. Each of the ten map items has a separate PNG icon with the same item name. Folded maps identify the UI versions; open sheets identify the DUI versions.

In `multi` mode, the separate `compass` item controls compass access. In `single` mode, `Config.SingleItem` unlocks the default map and compass. In `none` mode, neither requires an item.

## Choose the server minimap

**shared/config.lua**

```lua
Config.MinimapControl = true
Config.MinimapStyle = 'custom'
```

Choose `custom`, `satellite`, `road` or `atlas` for `Config.MinimapStyle`. This is one native radar style for the server. It does not change the image or display mode assigned to each inventory item. Apply style changes before players connect.

## Map images

The bundled images use WebP. Satellite, Road and Atlas are 8192 by 8192 pixels; the tourist image is 4096 by 6144 pixels. The Del Perro example is 1254 by 1254 pixels and demonstrates a map limited to one area. Its trail and red X are artwork, with no quest or reward attached.

Both UI and DUI modes use the configured image. `Config.DuiMaps.resolution` sets the separate rendered surface on the held prop. Custom PNG, JPG and WebP files belong in `maps/` and need a matching entry in `Config.Maps`.

## Player controls

- Use a map item to open its assigned design and display mode.
- `P` opens the first eligible map item found. It does not open a map selection menu. Players can rebind it in the FiveM keybind settings.
- Drag to move the map and use the mouse wheel to zoom. Right-click the map to create annotations.
- With `Config.Keybind.disablePauseMenu = true`, `ESC` opens the settings frontend when the map is closed.

## Staff tools

- `/mapcalibrate <mapId>` collects world-to-image alignment points. `/mapcalibrate done` computes the values; `/mapcalibrate reset` clears the session.
- `/addblip <mapId>` opens marker placement for `Config.DefaultMarkers` and copies each entry to the clipboard.
- `/nativemap` toggles native map access for eligible staff, according to `Config.NativeMap`.

The main command names and permission groups are configurable. With `Config.Debug = true`, `/map <mapId>` tests the UI, `/duimap <mapId>` tests the held map, and `/mapclose` closes the current map. The server checks staff permission for `/map`.

## Check the setup

Check the server and client consoles for resource or database errors. Use each registered map item to confirm its image and display mode. If positions do not match the roads, calibrate that map ID before using its waypoints.

If the paper prop or camera needs adjustment, enable debug mode and use `/duistudio <mapId>`. The tool copies the camera and prop placement values for `Config.DuiMaps`.