Configuration

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

1Config.Debug = false
2Config.Locale = 'en'
3Config.StorageMode = 'metadata'
4Config.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

1Config.ItemMode = 'multi'
2Config.SingleItem = 'survival_kit'
3Config.DefaultMapId = 'tourist'
4
5Config.Items = {
6    ['tourist_map'] = 'tourist',
7}

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

1Config.Items = {
2    ['tourist_map'] = 'tourist',
3    ['dui_map']     = { map = 'mappa', mode = 'dui' },
4}

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

1Config.DuiMaps = {
2    enabled = true,
3    resolution = { width = 1024, height = 1024 },
4    reapplyInterval = 750,
5    prop = {
6        model       = 'dgm_maps',
7        textureDict = 'dgm_maps',
8        texture     = 'mappa7_1',
9        bone        = 60309,
10        offset      = vector3(0.044, -0.001, -0.010),
11        rotation    = vector3(13.600, 0.009, 0.500),
12        anim = {
13            dict   = 'amb@world_human_clipboard@male@idle_a',
14            name   = 'idle_a',
15            freeze = 0.0,
16        },
17    },
18    camera = {
19        fov        = 59.6,
20        mode       = 'manual',
21        offset     = vector3(0.050, 0.115, 0.515),
22        rot        = vector3(-36.188, 2.800, -349.695),
23        eyeBack    = 0.45,
24        eyeUp      = 0.45,
25        transition = 600,
26    },
27    light = {
28        enabled   = true,
29        color     = { r = 255, g = 250, b = 235 },
30        range     = 1.9,
31        intensity = 3.0,
32        offset    = vector3(-0.12, 0.18, 0.66),
33    },
34}

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

Compass HUD

1Config.Compass = {
2    enabled = true,
3    item = 'compass',
4    itemCheckRate = 5000,
5    fov = 180,
6    maxDistance = 500,
7    fadeStart = 350,
8    showDistance = true,
9    pollRate = 20,
10    tickInterval = 5,
11}

• 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

1Config.Maps = {
2    ['tourist'] = {
3        label = 'Tourist Map',
4        image = 'tourist_map.webp',
5        imageWidth = 814,
6        imageHeight = 1222,
7        calibration = {
8            scaleX = 0.09033,
9            offsetX = 375.47,
10            scaleY = -0.09054,
11            offsetY = 760.5,
12            imageSize = 814,
13        },
14        fogRevealRadius = 800,
15        defaultZoom = 1.5,
16        maxZoom = 8.0,
17        minZoom = 0.3,
18        containerBackground = false,
19    },
20}

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

Generate calibration values in-game with /mapcalibrate. See the F.A.Q. for the full workflow.

Default Markers

1Config.DefaultMarkers = {
2    {
3        mapId = 'tourist',
4        worldX = 200.0,
5        worldY = -800.0,
6        preset = 'camp',
7        label = 'Base Camp',
8    },
9}

• 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

1Config.MarkerPresets = {
2    { id = 'camp',    label = 'Camp',         icon = 'fa-campground', color = '#22c55e' },
3    { id = 'danger',  label = 'Danger Zone',  icon = 'fa-skull',      color = '#ef4444' },
4    { id = 'loot',    label = 'Loot Spot',    icon = 'fa-gem',        color = '#a855f7' },
5    { id = 'water',   label = 'Water Source', icon = 'fa-droplet',    color = '#3b82f6' },
6    { id = 'shelter', label = 'Shelter',      icon = 'fa-house',      color = '#f59e0b' },
7    { id = 'npc',     label = 'NPC',          icon = 'fa-user',       color = '#06b6d4' },
8    { id = 'quest',   label = 'Quest',        icon = 'fa-scroll',     color = '#d4af37' },
9    { id = 'custom',  label = 'Custom Pin',   icon = 'fa-map-pin',    color = '#e58c3b' },
10}
11
12Config.RadiusPresets = {
13    { id = 'small',  label = 'Small (50m)',   defaultRadius = 50,  color = 'rgba(239,68,68,0.2)',  border = '#ef4444' },
14    { id = 'medium', label = 'Medium (150m)', defaultRadius = 150, color = 'rgba(59,130,246,0.15)', border = '#3b82f6' },
15    { id = 'large',  label = 'Large (300m)',  defaultRadius = 300, color = 'rgba(168,85,247,0.1)',  border = '#a855f7' },
16}
17
18Config.ExtraIcons = {}
19Config.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

1Config.PlayerDot = {
2    color = '#e58c3b',
3    size = 12,
4    pulse = true,
5    showHeading = true,
6}

• 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

1Config.MapProps = {
2    enabled = true,
3    model = 'prop_tourist_map_01',
4    dict = 'amb@code_human_in_bus_passenger_idles@female@tablet@idle_a',
5    name = 'idle_a',
6    flags = { loop = true, move = true },
7    bone = 28422,
8    placement = { vector3(-0.05, 0, 0), vector3(0, 0, 0) },
9}

• 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

1Config.Keybind = {
2    enabled = true,
3    key = 'P',
4    description = 'Open Map',
5    disablePauseMenu = true,
6}

• 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

1Config.MinimapControl = true
2
3Config.HideDefaultMinimap = true
4
5Config.NativeMap = {
6    allowEveryone = false,
7    allowStaff = true,
8    staffPermission = nil,
9    command = 'nativemap',
10}
11
12Config.RadarControl = {
13    enabled = true,
14    itemCheckRate = 5000,
15}
16
17Config.RadarPosition = {
18    bottomMarginPx = 25,
19    rightMarginPx  = 79,
20}

• 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

1Config.Waypoint = {
2    useGtaWaypoint = true,
3    useBridgeWaypoint = true,
4    bridgeWaypointType = 'checkpoint',
5    bridgeWaypointColor = '#f5a623',
6    bridgeWaypointSize = 1.2,
7    bridgeWaypointDrawDistance = 800.0,
8    bridgeWaypointRemoveDistance = 5.0,
9}

• 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

1Config.AdminCommand = {
2    enabled = true,
3    command = 'addblip',
4    permission = nil,
5}
6
7Config.CalibrationCommand = {
8    enabled = true,
9    command = 'mapcalibrate',
10    permission = nil,
11    subDone = 'done',
12    subReset = 'reset',
13}

• 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

1Config.FogOfWar = {
2    enabled = true,
3    revealRadius = 100,
4    bypassAdmin = true,
5    bypassDebug = true,
6}

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