Configuration

Main settings

Edit shared/config.lua for map images, item bindings, DUI settings, fog, the compass, minimap and commands. Server validation limits remain in server/security.lua.

1Config.Debug = false
2Config.Locale = 'en'
3Config.StorageMode = 'metadata'
4Config.SaveInterval = 120

• Debug enables developer commands and logs. FogOfWar.bypassDebug controls whether debug mode hides fog.
• Locale selects a file from locales/.
• StorageMode = 'metadata' stores a serial on each map item. Its annotations and fog remain in MySQL. 'database' stores progress by player identifier and map ID.
• SaveInterval sets the periodic save interval in seconds.

Items and access

1Config.ItemMode = 'multi'
2Config.SingleItem = 'survival_kit'
3Config.DefaultMapId = 'tourist'

• multi uses the item bindings in Config.Items and a separate compass item.
• single uses Config.SingleItem for the default map and compass.
• none allows access without inventory items. Config.DefaultMapId is the fallback map.

1Config.Items = {
2    ['tourist_map'] = 'tourist',
3    ['dui_map'] = { map = 'mappa', mode = 'dui' },
4    ['satellite_map'] = 'satellite',
5    ['satellite_map_dui'] = { map = 'satellite', mode = 'dui' },
6    ['road_map'] = 'road',
7    ['road_map_dui'] = { map = 'road', mode = 'dui' },
8    ['atlas_map'] = 'atlas',
9    ['atlas_map_dui'] = { map = 'atlas', mode = 'dui' },
10    ['treasure_map'] = 'del_perro_treasure',
11    ['treasure_map_dui'] = { map = 'del_perro_treasure', mode = 'dui' },
12}

A string binding opens the UI. A table with mode = 'dui' opens the same map system on the held paper prop. Register each item in the inventory. Use the item directly when you need a particular map or mode; P uses the first eligible item found.

The four full-world designs have UI and DUI bindings. The Del Perro treasure map is a regional example. The tourist UI uses map ID tourist; its DUI binding uses mappa, which has a separate coordinate plane for the same image.

[figure]

DUI maps

DUI draws the interactive map onto a paper prop in the game world. The player can pan, zoom, place annotations and set waypoints on the held sheet. The prop, viewing camera and light are configured under Config.DuiMaps.

1Config.DuiMaps.enabled = true
2Config.DuiMaps.resolution = { width = 900, height = 1024 }
3Config.DuiMaps.textScale = 1.2
4Config.DuiMaps.background = 'transparent'
5Config.DuiMaps.renderMode = 'unlit'
6Config.DuiMaps.sunCompensation = false

• resolution sets the DUI texture size. Scale width and height together to retain the aspect ratio. This does not change the source image or its calibration.
• textScale changes text and panel size independently of the texture resolution.
• background controls the area outside the map artwork.
• renderMode = 'unlit' keeps the map readable in sunlight. 'material' uses the shader of the prop.
• sunCompensation reduces map and interface brightness in daylight.
• prop sets the streamed model, its texture dictionary and replaced textures, attachment bone, offsets, rotation and animation. noGravity disables gravity for the held prop. anim.freeze holds the animation at a point from 0.0 to 1.0, and nil plays it normally.
• camera.mode accepts manual, face or auto. Manual mode uses offset and rot; face mode uses fill and roll to frame the sheet.
• camera.fov sets the viewing field of view and transition sets the blend duration in milliseconds. In face mode, fill controls the size of the sheet on screen.
• camera.eyeBack and camera.eyeUp place an over-the-shoulder camera, used only when the mode is neither face nor manual.

Keep the bundled prop settings when using the supplied model. For a different placement, enable debug mode and run /duistudio <mapId>. Use Tab to switch between the camera and prop, then Enter to copy the values into Config.DuiMaps.

Map images and calibration

Config.Maps contains the UI and DUI image definitions. Every entry has a unique ID, a label, an image filename, a coordinate plane, calibration values and zoom limits.

1Config.Maps['del_perro_treasure'] = {
2    label = 'Del Perro Treasure Map (Test)',
3    image = 'del_perro_treasure.webp',
4    imageWidth = 1254,
5    imageHeight = 1254,
6    calibration = {
7        scaleX = 1.14654,
8        offsetX = 2448.05,
9        scaleY = -1.14664,
10        offsetY = -598.61,
11        imageSize = 1254,
12    },
13    fogRevealRadius = 37.5,
14    fogCellSize = 21,
15    defaultZoom = 6.8,
16    maxZoom = 8.0,
17    minZoom = 0.35,
18    containerBackground = false,
19}

• label is the displayed map title; image points to the file in maps/.
• imageWidth and imageHeight define the coordinate plane used by the viewer. They must agree with the calibration. They normally match the image dimensions; the bundled tourist UI uses an 814 by 1222 logical plane for its larger source image.
• scaleX and scaleY convert world units to image coordinates. scaleY is usually negative because north is up on the image.
• offsetX and offsetY place the world origin on the image. imageSize records the reference width used for calibration.
• defaultZoom, minZoom and maxZoom set the opening zoom and its limits.
• fogRevealRadius overrides the global discovery radius for this map, in meters.
• fogCellSize sets the fog grid cell size of this map in image pixels. Keep it unchanged on a map players have already explored.
• containerBackground draws a solid background behind the artwork.

Use /mapcalibrate <mapId> for your own image. Satellite, Road and Atlas share dimensions, framing and projection, so they share calibration. A cropped or resized image needs adjusted calibration. Keep north up and preserve the positions of roads and landmarks.

Server minimap

1Config.MinimapControl = true
2Config.MinimapStyle = 'custom'
3Config.HideDefaultMinimap = true
4
5Config.RadarControl = {
6    enabled = true,
7    itemCheckRate = 5000,
8}
9
10Config.RadarPosition = {
11    diameterPx = 213.12,
12    bottomMarginPx = 25,
13    rightMarginPx = 79,
14}

• MinimapControl lets this resource manage radar styling, visibility and position. Set it to false when another resource owns the minimap.
• MinimapStyle selects custom, satellite, road or atlas for all players. It is independent of the image assigned to each map item. The selected style also applies to the native pause map when that map is available.
• HideDefaultMinimap suppresses vanilla map expansion and related HUD labels while the resource manages the radar.
• RadarControl.enabled enables radar visibility checks based on map access. itemCheckRate is the inventory polling interval in milliseconds.
• RadarPosition sets the circular radar diameter and its bottom and right margins at 1080p. These values scale with screen height; the layout also accounts for aspect ratio and the game safe zone.

The circular border belongs to this resource and follows the radar layout. Only the selected native style loads; a failed texture load leaves the custom style in place and permits up to three attempts.

Apply minimap style changes before players connect. Avoid another resource replacing the same radar textures. If a stop/start leaves an already connected client with an incomplete minimap, reconnect with ml_custommap running.

Native map access

1Config.NativeMap = {
2    allowEveryone = false,
3    allowStaff = true,
4    staffPermission = nil,
5    command = 'nativemap',
6}

allowEveryone keeps native map access enabled for everyone. allowStaff enables the staff toggle; staffPermission = nil uses any admin group accepted by ml_bridge. command sets its name without the slash. The toggle applies only to the calling player.

Compass

Config.Compass.enabled controls the horizon compass. In multi-item mode, item is the required inventory item. itemCheckRate sets its inventory check interval.

fov sets the displayed heading range. maxDistance, fadeStart and showDistance control default marker visibility and distance labels. pollRate controls UI refreshes; tickInterval controls heading update timing. The compass displays entries from Config.DefaultMarkers.

Markers, areas and player position

1Config.DefaultMarkers = {
2    { mapId = 'tourist', worldX = 200.0, worldY = -800.0, preset = 'camp', label = 'Base Camp' },
3}

Default markers are shared by players viewing that map ID. Each entry uses world coordinates, a preset ID and a label. /addblip <mapId> lets staff place them visually and copy their config entries.

MarkerPresets defines the marker IDs, labels, FontAwesome icons and colors offered by the editor. RadiusPresets defines area sizes in meters with fill and border colors. ExtraIcons extends the icon picker; DefaultColors sets its color palette.

PlayerDot.color, size, pulse and showHeading control the player marker, its ring animation and heading indicator.

UI prop and keybind

Config.MapProps controls the map prop and animation used with the UI view. Its enabled, model, dict, name, animation flags, bone and placement fields are separate from the DUI prop settings.

Config.Keybind.enabled registers the map keybind. key is its default key and description is the label in the FiveM keybind settings. Players can rebind it. With disablePauseMenu = true, the resource suppresses the regular pause controls and offers a settings frontend through ESC when the map is closed.

Waypoints

Config.Waypoint.useGtaWaypoint sets the native GTA waypoint. useBridgeWaypoint enables the 3D world waypoint through ml_bridge.

bridgeWaypointType accepts checkpoint, marker or blip. The color, size, draw distance and arrival removal distance use bridgeWaypointColor, bridgeWaypointSize, bridgeWaypointDrawDistance and bridgeWaypointRemoveDistance.

Staff commands

Config.AdminCommand controls /addblip; Config.CalibrationCommand controls /mapcalibrate. Each has an enabled toggle, a command name and a permission group. A nil permission uses any admin group accepted by ml_bridge.

The calibration completion and reset commands are /mapcalibrate done and /mapcalibrate reset, set by subDone and subReset. Use the configured main command name if you rename mapcalibrate.

Fog of war

1Config.FogOfWar = {
2    enabled = true,
3    revealRadius = 50,
4    cellSize = 8,
5    bypassAdmin = true,
6    bypassDebug = true,
7}

enabled turns discovery tracking and fog display on or off. revealRadius is the global radius in meters, and each map can override it with fogRevealRadius. cellSize is the default fog grid cell in image pixels, overridden per map by fogCellSize. The staff map editor shows the full image. bypassDebug hides fog when debug mode is enabled. bypassAdmin has no effect.

Discovery continues for the active map session while the map is closed. Opening a different item can switch that session. The reveal mask has soft edges, and the viewer reuses its cached mask while panning and zooming.

Changing map dimensions, calibration scale or the discovery radius can change the fog grid. Back up player data and reset the affected map's discovery before using a different grid.