# Configuration

> Configuration reference for ML Survival Kit

Category: SURVIVAL KIT · Source: https://miciomods.it/docs/ml-custommap-configuration · Last updated: 2026-07-28

## Overview

- `shared/config.lua`: Maps, items, compass, markers, waypoint, admin/calibration commands, fog of war

All security values (rate limits, validation caps) live in `server/security.lua` and are hardcoded: not customer-facing.

## Core

**shared/config.lua**

```lua
Config.Debug = false
Config.Locale = 'en'
Config.StorageMode = 'metadata'
Config.SaveInterval = 120
```

- `Debug`: Enables debug logging output and unlocks `/map`, `/compass`, `/mapclose` dev commands. When `true`, fog of war is also bypassed if `Config.FogOfWar.bypassDebug = true`.
- `Locale`: language key read from `locales/*.lua`.
- `StorageMode`: `'metadata'` stores a serial in the player's item metadata (one map per item), `'database'` keys by player license (one map per player per mapId).
- `SaveInterval`: Seconds between periodic batched auto-saves of dirty cache entries.

## Items & Access

**shared/config.lua**

```lua
Config.ItemMode = 'multi'
Config.SingleItem = 'survival_kit'
Config.DefaultMapId = 'tourist'

Config.Items = {
    ['tourist_map'] = 'tourist',
}
```

- `ItemMode`: Controls how map access is gated. `'multi'` = per-item (uses `Config.Items`). `'single'` = one item unlocks everything (uses `Config.SingleItem`). `'none'` = no item required.
- `SingleItem`: Item name used only when `ItemMode = 'single'`. Unlocks map AND compass.
- `DefaultMapId`: Map loaded when no specific item is used (keybind in `'none'` mode, debug commands).
- `Items`: Mapping `item_name → mapId`. Each key must correspond to a registered inventory item and a `Config.Maps[mapId]` entry.

## DUI Maps

A map can render on a physical paper prop held in first person instead of a fullscreen view. The player holds the prop up, the live map UI (pan, zoom, fog, markers, context menu) is drawn on the page, and clicks land on the paper. One surface is created and reused for the whole resource. Bind a map to this mode with a table value in `Config.Items`.

**shared/config.lua**

```lua
Config.Items = {
    ['tourist_map'] = 'tourist',
    ['dui_map']     = { map = 'mappa', mode = 'dui' },
}
```

- A string value opens the map fullscreen. A table value `{ map = '<mapId>', mode = 'dui' }` opens that map on the held prop.
- The same map image can be bound both ways with two different items.

**shared/config.lua**

```lua
Config.DuiMaps = {
    enabled = true,
    resolution = { width = 1024, height = 1024 },
    reapplyInterval = 750,
    prop = {
        model       = 'dgm_maps',
        textureDict = 'dgm_maps',
        texture     = 'mappa7_1',
        bone        = 60309,
        offset      = vector3(0.044, -0.001, -0.010),
        rotation    = vector3(13.600, 0.009, 0.500),
        anim = {
            dict   = 'amb@world_human_clipboard@male@idle_a',
            name   = 'idle_a',
            freeze = 0.0,
        },
    },
    camera = {
        fov        = 59.6,
        mode       = 'manual',
        offset     = vector3(0.050, 0.115, 0.515),
        rot        = vector3(-36.188, 2.800, -349.695),
        eyeBack    = 0.45,
        eyeUp      = 0.45,
        transition = 600,
    },
    light = {
        enabled   = true,
        color     = { r = 255, g = 250, b = 235 },
        range     = 1.9,
        intensity = 3.0,
        offset    = vector3(-0.12, 0.18, 0.66),
    },
}
```

- `enabled`: Master toggle for the DUI map mode.
- `resolution`: Render size of the surface in pixels. Higher is sharper but heavier on weaker clients; `1024` keeps the UI text readable on the angled prop.
- `reapplyInterval`: Milliseconds between re-claims of the prop texture while the map is open.
- `prop.model` / `textureDict` / `texture`: Prop model and the texture pair the live surface replaces. A list of candidate names is accepted for either field.
- `prop.bone`: Ped bone the prop attaches to.
- `prop.offset` / `rotation`: Position and rotation of the prop on the bone.
- `prop.anim.dict` / `name`: Hold animation. Set `dict = nil` to disable.
- `prop.anim.freeze`: Phase `0.0`: `1.0` to freeze the pose on a single frame so the prop stays still. `nil` plays the loop.
- `camera.mode`: `'manual'` uses `offset` + `rot`; any other value auto-frames from `eyeBack` / `eyeUp`.
- `camera.fov`: Field of view.
- `camera.offset`: Player-local camera position.
- `camera.rot`: Camera pitch, roll, and yaw. Yaw is relative to the player heading.
- `camera.transition`: Camera blend in/out time in milliseconds.
- `light.enabled`: Adds a light in front of the prop so the map stays readable at night.
- `light.color`: RGB (0-255).
- `light.range` / `intensity`: Light radius in meters and brightness.
- `light.offset`: Player-local light position. `x` left/right, `y` forward, `z` up.

> **TIP:** Tune the prop and camera in-game
>
> With `Config.Debug = true`, run `/duistudio <mapId>` to place the prop and camera together in a 3D preview. Press Tab to switch between camera and prop, then Enter to copy both blocks to your clipboard.

## Compass HUD

**shared/config.lua**

```lua
Config.Compass = {
    enabled = true,
    item = 'compass',
    itemCheckRate = 5000,
    fov = 180,
    maxDistance = 500,
    fadeStart = 350,
    showDistance = true,
    pollRate = 20,
    tickInterval = 5,
}
```

- `enabled`: Master toggle for the compass HUD.
- `item`: Required inventory item in `'multi'` mode.
- `itemCheckRate`: Milliseconds between inventory polls to show/hide the compass.
- `fov`: Compass field of view in degrees. `180` = semicircle, `360` = full horizon ring.
- `maxDistance`: Maximum world distance (meters) at which markers appear on the compass.
- `fadeStart`: Distance at which markers start fading out before disappearing at `maxDistance`.
- `showDistance`: Renders the distance label under each compass marker.
- `pollRate`: UI refresh interval in milliseconds.
- `tickInterval`: Game-tick interval for heading updates (lower = smoother, higher CPU).

## Maps

**shared/config.lua**

```lua
Config.Maps = {
    ['tourist'] = {
        label = 'Tourist Map',
        image = 'tourist_map.webp',
        imageWidth = 814,
        imageHeight = 1222,
        calibration = {
            scaleX = 0.09033,
            offsetX = 375.47,
            scaleY = -0.09054,
            offsetY = 760.5,
            imageSize = 814,
        },
        fogRevealRadius = 800,
        defaultZoom = 1.5,
        maxZoom = 8.0,
        minZoom = 0.3,
        containerBackground = false,
    },
}
```

- `label`: Display name shown in the map UI header.
- `image`: File in `maps/`. PNG, WEBP, or JPG.
- `imageWidth` / `imageHeight`: Exact pixel dimensions of the image.
- `calibration.scaleX` / `scaleY`: Pixels per world unit. `scaleY` is usually negative (GTA +Y = north but screen +Y = down).
- `calibration.offsetX` / `offsetY`: Pixel position of world origin on the image.
- `calibration.imageSize`: Reference dimension used during `/mapcalibrate`. Informational.
- `defaultZoom`: Initial zoom when the map opens.
- `maxZoom` / `minZoom`: Zoom bounds.
- `containerBackground`: Draws a solid background behind the map image (useful for non-rectangular paper shapes).

> **TIP:** Per-map fog radius
>
> Add `fogRevealRadius = 800` inside a map entry to override the global `Config.FogOfWar.revealRadius` for that map only. Useful on small stylized images where the default 100m halo is too small.

Generate calibration values in-game with `/mapcalibrate`. See the [F.A.Q.](#) for the full workflow.

## Default Markers

**shared/config.lua**

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

- `mapId`: Which map this marker belongs to.
- `worldX` / `worldY`: GTA world coordinates.
- `preset`: Must match an `id` in `Config.MarkerPresets`.
- `label`: Tooltip text on hover.

Default markers are visible to all players. Use `/addblip` to place them visually and copy the config entry to clipboard.

## Marker & Radius Presets

**shared/config.lua**

```lua
Config.MarkerPresets = {
    { id = 'camp',    label = 'Camp',         icon = 'fa-campground', color = '#22c55e' },
    { id = 'danger',  label = 'Danger Zone',  icon = 'fa-skull',      color = '#ef4444' },
    { id = 'loot',    label = 'Loot Spot',    icon = 'fa-gem',        color = '#a855f7' },
    { id = 'water',   label = 'Water Source', icon = 'fa-droplet',    color = '#3b82f6' },
    { id = 'shelter', label = 'Shelter',      icon = 'fa-house',      color = '#f59e0b' },
    { id = 'npc',     label = 'NPC',          icon = 'fa-user',       color = '#06b6d4' },
    { id = 'quest',   label = 'Quest',        icon = 'fa-scroll',     color = '#d4af37' },
    { id = 'custom',  label = 'Custom Pin',   icon = 'fa-map-pin',    color = '#e58c3b' },
}

Config.RadiusPresets = {
    { id = 'small',  label = 'Small (50m)',   defaultRadius = 50,  color = 'rgba(239,68,68,0.2)',  border = '#ef4444' },
    { id = 'medium', label = 'Medium (150m)', defaultRadius = 150, color = 'rgba(59,130,246,0.15)', border = '#3b82f6' },
    { id = 'large',  label = 'Large (300m)',  defaultRadius = 300, color = 'rgba(168,85,247,0.1)',  border = '#a855f7' },
}

Config.ExtraIcons = {}
Config.DefaultColors = { '#e58c3b', '#ef4444', '#22c55e', '#3b82f6', '#a855f7', '#f59e0b', '#06b6d4', '#ec4899' }
```

- `MarkerPresets`: Marker types shown in the player's marker creation modal. `id`, `label`, `icon` (FontAwesome class), `color` (hex).
- `RadiusPresets`: Radius zone types. `defaultRadius` is in meters. `color` is RGBA fill, `border` is hex outline.
- `ExtraIcons`: Additional FontAwesome classes available in the custom-icon picker.
- `DefaultColors`: Hex palette shown in the color picker.

## Player Dot

**shared/config.lua**

```lua
Config.PlayerDot = {
    color = '#e58c3b',
    size = 12,
    pulse = true,
    showHeading = true,
}
```

- `color`: Dot fill color.
- `size`: Dot diameter in pixels.
- `pulse`: Animated white ring expanding around the dot.
- `showHeading`: Renders the GPS-style vision cone pointing where the player faces.

## Map Prop & Animation

**shared/config.lua**

```lua
Config.MapProps = {
    enabled = true,
    model = 'prop_tourist_map_01',
    dict = 'amb@code_human_in_bus_passenger_idles@female@tablet@idle_a',
    name = 'idle_a',
    flags = { loop = true, move = true },
    bone = 28422,
    placement = { vector3(-0.05, 0, 0), vector3(0, 0, 0) },
}
```

- `enabled`: Attaches a physical map prop to the player while viewing.
- `model`: Prop model hash name.
- `dict` / `name`: Animation dictionary + clip.
- `flags.loop`: Loops the clip.
- `flags.move`: Allows walking with the prop.
- `bone`: Ped bone index for attachment.
- `placement`: `{ positionOffset, rotationOffset }` as vec3.

## Keybind

**shared/config.lua**

```lua
Config.Keybind = {
    enabled = true,
    key = 'P',
    description = 'Open Map',
    disablePauseMenu = true,
}
```

- `enabled`: Registers the ox_lib keybind to open the map.
- `key`: Default key. Players can rebind via GTA's keybind settings.
- `description`: Label shown in the GTA keybind UI.
- `disablePauseMenu`: When `true`, `P` stops opening the native pause menu. Pressing `ESC` while the map is closed opens a minimal settings frontend instead.

## Minimap & Native Map

**shared/config.lua**

```lua
Config.MinimapControl = true

Config.HideDefaultMinimap = true

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

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

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

- `MinimapControl`: Master switch for owning the game minimap. `true` reshapes the corner radar into the postal style and hides the native HUD components. `false` leaves the native minimap and HUD untouched, so the map, fog, compass and waypoints drop in beside another HUD.
- `HideDefaultMinimap`: Hides every frame the GTA radar, street names, vehicle name, and big-map toggle.
- `NativeMap.allowEveryone`: When `true`, suppression is skipped and every player keeps the native GTA map.
- `NativeMap.allowStaff`: When `true`, staff can toggle the native map for themselves with the command.
- `NativeMap.staffPermission`: Permission group required for the staff toggle. `nil` = any admin group.
- `NativeMap.command`: Command name (without `/`) for the toggle.
- `RadarControl.enabled`: Talks to `ml_hud` to show/hide the radar based on whether the player has a map item.
- `RadarControl.itemCheckRate`: Inventory poll interval in milliseconds.
- `RadarPosition.bottomMarginPx`: Pixel offset of the postal radar from the bottom of the screen.
- `RadarPosition.rightMarginPx`: Pixel offset of the postal radar from the right of the screen.

## Waypoints

**shared/config.lua**

```lua
Config.Waypoint = {
    useGtaWaypoint = true,
    useBridgeWaypoint = true,
    bridgeWaypointType = 'checkpoint',
    bridgeWaypointColor = '#f5a623',
    bridgeWaypointSize = 1.2,
    bridgeWaypointDrawDistance = 800.0,
    bridgeWaypointRemoveDistance = 5.0,
}
```

- `useGtaWaypoint`: Also sets the native GTA yellow marker.
- `useBridgeWaypoint`: Creates a 3D in-world waypoint via `ml_bridge`.
- `bridgeWaypointType`: `'checkpoint'`, `'marker'`, or `'blip'`.
- `bridgeWaypointColor`: Hex color of the 3D marker.
- `bridgeWaypointSize`: Size multiplier.
- `bridgeWaypointDrawDistance`: Meters at which the 3D marker starts rendering.
- `bridgeWaypointRemoveDistance`: Meters at which the waypoint auto-clears when the player arrives.

## Admin & Calibration Commands

**shared/config.lua**

```lua
Config.AdminCommand = {
    enabled = true,
    command = 'addblip',
    permission = nil,
}

Config.CalibrationCommand = {
    enabled = true,
    command = 'mapcalibrate',
    permission = nil,
    subDone = 'done',
    subReset = 'reset',
}
```

- `AdminCommand.enabled`: Registers the admin-mode marker placement command.
- `AdminCommand.command`: Command name (without `/`).
- `AdminCommand.permission`: Permission group required. `nil` = any admin group.
- `CalibrationCommand.enabled`: Registers the calibration command.
- `CalibrationCommand.subDone`: Subcommand that finalizes and copies the calibration block (e.g. `/mapcalibrate done`).
- `CalibrationCommand.subReset`: Subcommand that discards the current session (e.g. `/mapcalibrate reset`).

## Fog of War

**shared/config.lua**

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

- `enabled`: Master toggle. When `false`, the entire fog system is inactive.
- `revealRadius`: Default reveal radius in meters. Can be overridden per-map with `fogRevealRadius` inside a `Config.Maps` entry.
- `bypassAdmin`: Admins viewing the map in admin mode see the full map without fog.
- `bypassDebug`: When `Config.Debug = true`, fog is disabled.