> For the complete documentation index, see [llms.txt](https://docs.0resmon.org/0resmon/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.0resmon.org/0resmon/0resmon-1/0r-resources/0r-gps-v3/configuration.md).

# Configuration

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

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

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

{% hint style="info" %}
Channel `name` can be a locale key (`'channels.police_department'`) or plain text (`'LSPD Tac 1'`).
{% endhint %}

### Restricted channel example

```lua
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`:

```lua
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:

```lua
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:

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

### Panic blip

```lua
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)

{% hint style="warning" %}
**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.
{% endhint %}

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:

{% columns %}
{% column %}
**Smoother**

* Lower `refreshRate` (e.g. `1500`)
* `smoothBlips.enabled = true`
* Lower `updateDistance` / `updateRotation`
  {% endcolumn %}

{% column %}
**Lighter**

* Raise `refreshRate` (e.g. `2500+`)
* `smoothBlips.enabled = false`
* Raise `updateDistance` / `updateRotation`
* Tune or disable `dynamicRefreshRate`
  {% endcolumn %}
  {% endcolumns %}

```lua
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`**:

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.0resmon.org/0resmon/0resmon-1/0r-resources/0r-gps-v3/configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.