For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 1publicChannels.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.

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

Restricted channel example

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:

Global blip states

Default sprites/colors by what the player is doing:

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:

Panic blip

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)

The device map loads icons from:

(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

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:

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.

Last updated