Installation

4 min readUpdated 2 weeks ago

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
1ensure oxmysql
2ensure ox_lib
3ensure ml_bridge
4ensure 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
1Config.MinimapControl = true
2Config.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.