# Configuration

> Configure map items, the held DUI map, four minimap styles, fog, compass and waypoints.

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

## 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`.

**shared/config.lua**

```lua
Config.Debug = false
Config.Locale = 'en'
Config.StorageMode = 'metadata'
Config.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

**shared/config.lua**

```lua
Config.ItemMode = 'multi'
Config.SingleItem = 'survival_kit'
Config.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.

**shared/config.lua**

```lua
Config.Items = {
    ['tourist_map'] = 'tourist',
    ['dui_map'] = { map = 'mappa', mode = 'dui' },
    ['satellite_map'] = 'satellite',
    ['satellite_map_dui'] = { map = 'satellite', mode = 'dui' },
    ['road_map'] = 'road',
    ['road_map_dui'] = { map = 'road', mode = 'dui' },
    ['atlas_map'] = 'atlas',
    ['atlas_map_dui'] = { map = 'atlas', mode = 'dui' },
    ['treasure_map'] = 'del_perro_treasure',
    ['treasure_map_dui'] = { map = 'del_perro_treasure', mode = 'dui' },
}
```

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.

![Custom Tourist, Satellite, Road and Atlas designs in the map viewer.](https://cdn.sanity.io/images/spkq08dw/production/c1b0548983e6bb03a65401ad95c20165cc94abef-2560x1440.webp)

_The four full-world map designs. Each has separate UI and DUI item bindings._

## 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`.

**shared/config.lua**

```lua
Config.DuiMaps.enabled = true
Config.DuiMaps.resolution = { width = 900, height = 1024 }
Config.DuiMaps.textScale = 1.2
Config.DuiMaps.background = 'transparent'
Config.DuiMaps.reapplyInterval = 750
Config.DuiMaps.sunCompensation = true
```

- `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.
- `reapplyInterval` sets how often the resource reclaims the prop texture during interaction, in milliseconds.
- `sunCompensation` reduces map and interface brightness in daylight.
- `prop` sets the streamed model, replaced textures, attachment bone, offsets, rotation and animation. `noGravity` disables gravity for the held prop.
- `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.
- `light` controls the front light, including its color, range, intensity and position.

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.

**shared/config.lua**

```lua
Config.Maps['del_perro_treasure'] = {
    label = 'Del Perro Treasure Map (Test)',
    image = 'del_perro_treasure.webp',
    imageWidth = 1254,
    imageHeight = 1254,
    calibration = {
        scaleX = 1.14654,
        offsetX = 2448.05,
        scaleY = -1.14664,
        offsetY = -598.61,
        imageSize = 1254,
    },
    fogRevealRadius = 75,
    defaultZoom = 0.8,
    maxZoom = 8.0,
    minZoom = 0.35,
    containerBackground = false,
}
```

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

**shared/config.lua**

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

Config.RadarControl = {
    enabled = true,
    itemCheckRate = 5000,
}

Config.RadarPosition = {
    diameterPx = 213.12,
    bottomMarginPx = 25,
    rightMarginPx = 79,
}
```

- `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. `ml_hud` is not required. 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

**shared/config.lua**

```lua
Config.NativeMap = {
    allowEveryone = false,
    allowStaff = true,
    staffPermission = nil,
    command = 'nativemap',
}
```

`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

**shared/config.lua**

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

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`. Use the configured main command name if you rename `mapcalibrate`.

## Fog of war

**shared/config.lua**

```lua
Config.FogOfWar = {
    enabled = true,
    revealRadius = 100,
    bypassAdmin = true,
    bypassDebug = true,
}
```

`enabled` turns discovery tracking and fog display on or off. `revealRadius` is the global radius in meters; each map can override it through `fogRevealRadius`. The staff map editor shows the full image. `bypassDebug` hides fog when debug mode is enabled. `bypassAdmin` is present in the config but is not read by the current fog logic.

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.