Installation

3 min readUpdated Today

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
  2. Extract to your resources folder as ml_custommap
  3. Add to server.cfg:
server.cfg
1ensure oxmysql
2ensure ox_lib
3ensure ml_bridge
4ensure ml_custommap
Load Order

ml_custommap must start AFTER ml_bridge and oxmysql.

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)
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.

  • 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.