Configuration

config/main.lua explained — channels, blips, map sprites, performance.

All gameplay settings live in config/main.lua. Vehicle icon overrides are in config/vehicles.lua.

Open config/main.lua in an editor and change only what you need — the file is commented, but this page is the short version.

---

Setup

setup = {
    debug = 1,           -- 0 = off, 1 = errors, higher = more logs (use 1 in production)
    checkVersion = true,
    notify = 'auto',     -- or ox_lib, lt-ui, esx_notify, etc.
},

Option	What it does
debug	Console noise. Keep at 1 on a live server unless you are troubleshooting.
checkVersion	Warns if a newer release exists.
notify	auto picks a notify resource that is running. Override if you run several.

---

General

Option	Default	Notes
locale	'en'	Also: tr, de, fr, es, pt-br, pl, ru, it — files in locales/
item	'gps'	Must match your inventory item name
movement	true	Walk while the GPS menu is open
mapSystem	true	false = no map page on the device
maxChannels	500	Highest frequency number allowed
waterPunishment	'wrongCoords'	'removeItem' = GPS breaks and is removed when swimming on a channel
useDefaultNotify	false	true = framework notify instead of NUI toasts
maxCallsignLength	4
maxUsernameLength	20
fovCones	true	Master switch for heading cones on blips

Sync (minimap blips):

Option	Default	Notes
refreshRate	2000	Base sync interval (ms) — lower = smoother, heavier
updateDistance	5.0	Meters moved before a position update is sent
updateRotation	35.0	Degrees turned (while still) before heading sync
headingIndicators	true	Show direction on blips

---

How frequencies work

There are three kinds of channels. Think of them as layers:

1. Reserved (config) — IDs listed in channels = { [1] = { ... }, [2] = { ... } }. Job-restricted, settings per channel. Example: police on channel 1.

2. Public — If publicChannels.enabled = true, frequencies 1 … publicChannels.number (default 100) are open to everyone, unless that ID is already taken by a reserved channel.

3. Password / custom — Frequencies above the public range (up to maxChannels) can be created in-game with a password. Players set options like callsigns when creating them.

publicChannels = {
    enabled = true,
    number = 100,
    settings = { ... },  -- defaults for auto-created public channels
},

Channel name can be a locale key ('channels.police_department') or plain text ('LSPD Tac 1').

Restricted channel example

channels = {
    [1] = {
        name = 'channels.police_department',
        jobs = { ['police'] = 'BP_Police' },  -- job => blip profile key
        settings = {
            dutyOnly = false,
            customizeCallsign = true,
            createCustomBlips = true,
            fovCones = true,
            enableSiren = true,
            sendPanicSignal = true,
            -- ...
        },
    },
},

jobs can be:

• Map — { ['police'] = 'BP_Police' } → job check + blip profile BP_Police

• Array — { 'police', 'ambulance' } → job check only, global blip styles

Channel settings (per channel)

Setting	Meaning
dutyOnly	Must be on duty to join
showDuty	Show duty status in the member list
customizeUsername	Player can set a display name
customizeCallsign	Callsign shown on blips / UI
customizeBlipVisibility	Player can hide their blip from others
customizeBlipColor	Player can pick blip color
createCustomBlips	Shared markers on the device map
fovCones	Heading cone on blips (also needs global fovCones)
enableSiren	Emergency lights sync; optional color pulse with darkColor
sendPanicSignal	Panic button in UI
displayJobOnBlip	Short job tag on blip label (e.g. PD)

---

Blips on the minimap

Blip profiles

Profiles are not applied automatically. Attach them via jobs:

blipProfiles = {
    ['BP_Police'] = {
        label = 'Police Department',
        shortName = 'PD',
        color = '#4DBBFF',
        blips = {
            color = 38,
            darkColor = 76,  -- used with enableSiren pulse
        },
    },
},

Global blip states

Default sprites/colors by what the player is doing:

blips = {
    foot = { sprite = 1 },
    vehicle = { sprite = 225 },
    boat = { sprite = 427 },
    -- plane, motorcycle, bike, helicopter, dead ...
},
blipDefaults = { size = 0.8, shortRange = true },

Which config wins?

When the game draws a minimap / world blip, settings are merged in this order (first match per field):

1. Channel blips (on that channel entry in config)

2. Blip profile blips (from jobs mapping)

3. Global blips[state]

4. blipDefaults

You can override per channel:

[1] = {
    -- ...
    blips = {
        color = 3,
        states = { vehicle = { sprite = 41, size = 0.5 } },
    },
},

Panic blip

panicBlip = {
    sprite = 161,
    color = 1,
    size = 1.25,
    deleteAfter = 45000,  -- ms on map
    cooldown = 20,        -- seconds between panics
},

Other blip limits

Option	Default
maxCustomBlips	2 per player on channels that allow custom map blips
sirenTickMs	1000 — how often siren color alternates

---

NUI map sprites (GPS screen)

Two different systems. Changing sprite in config/main.lua updates minimap / world blips only. The map inside the GPS device uses image files on disk.

The device map loads icons from:

web/build/blips/{spriteNumber}.png

(or .gif if PNG is missing)

So if you set vehicle = { sprite = 999 } in config:

1. Minimap may show sprite 999 (GTA blip).

2. The GPS map will look for web/build/blips/999.png.

3. If that file does not exist, the icon on the NUI map will be wrong or missing.

To add or change a map icon:

1. Open web/build/blips/ and look at existing files (e.g. 1.png, 225.png).

2. Copy one as a template.

3. Rename it to your sprite number: 999.png.

4. Replace the image (keep it small, similar size to the others).

5. Restart 0r-gps.

mapSystem = false turns off the map page entirely — no device map, no custom blips UI.

---

Performance

If the server feels heavy with many players on one frequency:

Smoother

• Lower refreshRate (e.g. 1500)

• smoothBlips.enabled = true

• Lower updateDistance / updateRotation

Lighter

• Raise refreshRate (e.g. 2500+)

• smoothBlips.enabled = false

• Raise updateDistance / updateRotation

• Tune or disable dynamicRefreshRate

smoothBlips = {
    enabled = true,
    tickMs = 100.0,
    -- alphaPos, alphaRot, snap, teleportSnap ...
},

dynamicRefreshRate = {
    enabled = true,
    tiers = {
        { members = 5,  refreshRate = 1050 },
        { members = 10, refreshRate = 1500 },
        -- ...
    },
},

More members on a channel → higher refresh interval when dynamicRefreshRate is on.

---

Vehicle icons on the Members page

If a vehicle shows the wrong icon in the GPS UI (not on the map), fix it in config/vehicles.lua:

return {
    ['policeb'] = 'motorcycle',
}

Classes: vehicle, motorcycle, boat, plane, helicopter, bike.

---

Locales

Set locale = 'en' (or another code). Edit strings in locales/*.json. Channel names can use keys under "channels" in those files.

Player favorites and customization are stored in data/favorites.json and data/customization.json on the server.