> For the complete documentation index, see [llms.txt](https://docs.lostdev.store/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lostdev.store/races/configuration.md).

# Configuration

All settings live in `config/config.lua`. Every option has a sensible default — you only need to change what's relevant to your server. Text shown to players lives in `config/locales/*.lua`, not in this file (see the note at the bottom of this page).

## General

| Key                              | Description                                                                                    |
| -------------------------------- | ---------------------------------------------------------------------------------------------- |
| `Config.Enabled`                 | Master on/off switch for the whole resource.                                                   |
| `Config.Debug`                   | Verbose console logging for troubleshooting.                                                   |
| `Config.DebugCommand`            | Command name (default `racedebug`) used for debug output, admin-only.                          |
| `Config.Locale`                  | Which file under `config/locales/` to load (`en`, `pt`, ...).                                  |
| `Config.DatabaseOverridesConfig` | If `true`, a DB-saved route with the same key wins over a `Config.Routes` entry with that key. |

## Framework & Identity

See [Framework & Identity](/races/integrations/framework.md) for full details on `Config.Framework` and `Config.Identity`.

## Notifications

`Config.Notifications.system` selects how in-game notifications are shown: `'ox'` (ox\_lib), `'native'` (your framework's own notify), or `'custom'`.

## UI

| Key                            | Description                                                                                                               |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `Config.UI.hudPosition`        | Where the racing HUD anchors on screen (`top-left`, `bottom-right`, etc).                                                 |
| `Config.UI.checkpointFeedback` | `'notify'`, `'sound'`, `'both'`, or `'none'` on checkpoint pass.                                                          |
| `Config.UI.checkpointSound`    | Native sound name/set used for the above.                                                                                 |
| `Config.UI.useSharedTablet`    | If `ld_tablet` is running, register a "Races" app inside it instead of (or alongside) the standalone `/races` command/UI. |

## Admin

| Key                          | Description                                                                          |
| ---------------------------- | ------------------------------------------------------------------------------------ |
| `Config.Admin.enabled`       | Turns the admin/route-creator tools on or off entirely.                              |
| `Config.Admin.permission`    | ACE permission required (checked via your framework or ox\_lib, depending on setup). |
| `Config.Admin.allowedGroups` | Framework group names that are always allowed (e.g. `admin`, `god`).                 |
| `Config.Admin.commands`      | Enable the `race_*` chat commands used by the route creator.                         |
| `Config.Admin.nui`           | Enable the admin panel inside the NUI.                                               |
| `Config.Admin.exportConfig`  | Allow exporting a drafted route as a Lua snippet (`race_export`).                    |
| `Config.Admin.saveDb`        | Allow saving drafted routes straight to the database (`race_save`).                  |
| `Config.Admin.writeFile`     | Allow writing exported routes to a file on disk (off by default).                    |
| `Config.Admin.writeFilePath` | Output path used when `writeFile` is enabled.                                        |

See [Admin Guide](/races/admin-guide.md) for how these are actually used in-game.

## Interaction (world prompt, marker, blip)

`Config.Interaction` controls the `[E]` interact prompt at each race's start point, the ground marker drawn there, and its map blip — including the optional **route preview** blips (numbered checkpoint blips a player can toggle on to scout a track before starting).

## Lobby

`Config.Lobby` controls player counts, lobby timeout, ready-checks, host privileges, and entry fees:

| Key                         | Description                                                           |
| --------------------------- | --------------------------------------------------------------------- |
| `minPlayers` / `maxPlayers` | Lobby size bounds.                                                    |
| `maxLobbySeconds`           | Auto-cancel a lobby that never starts.                                |
| `readySystem`               | Require players to ready up before the host can start.                |
| `allowHostStart`            | Let the host force-start once minimums are met.                       |
| `cancelIfEmpty`             | Cancel the lobby if everyone leaves.                                  |
| `refundEntryOnCancel`       | Refund entry fees on a cancelled lobby.                               |
| `removeIfLeavesStartZone`   | Kick a player from the lobby if they wander off before start.         |
| `transferHostOnLeave`       | Hand host to another player if the host leaves.                       |
| `entryFeeAccount`           | Which account (`bank`, `cash`, ...) entry fees are charged/paid from. |

## Requirements & Start System

`Config.Requirements` sets fallback minimum on-duty police counts for illegal races when a route doesn't specify its own. `Config.StartSystem` controls grid vs. same-point starts, grid ordering, the pre-race countdown (including the scaleform 3-2-1-GO overlay and its sounds), and freezing players during it.

## Collision & Buckets

`Config.Collision` disables collision between racers during a run (with a refresh interval and max distance). `Config.Buckets` optionally routes race participants into isolated routing buckets per race (ranked/solo/casual/illegal toggles independently) so races don't visually interfere with the open world.

## Anti-abuse

`Config.AntiAbuse` is the server-authoritative anti-cheat layer: blocking dead/handcuffed/jailed/police players from racing, requiring a vehicle, disqualifying on vehicle-swap or exit, route-distance and checkpoint-radius sanity checks, a minimum race time, a max average speed, and a per-route cooldown. These are enforced server-side regardless of what the client sends.

## Markers

`Config.Markers` controls the in-race checkpoint and finish-line marker visuals (shape, scale, color, layering). `Config.Markers.start` is a separate, disabled-by-default marker at the actual start point during the race itself (distinct from the world marker in `Config.Interaction.marker`, which is always shown while browsing races).

## Rewards

`Config.Rewards` sets cash payout by finishing position, XP per race, medal bonuses (gold/silver/bronze, flat or percent), personal-record and global-record bonuses, and a percentage discount on route cooldowns for well-performing runs.

## Leaderboard

`Config.Leaderboard` toggles which leaderboard views are available (solo/multiplayer, weekly/monthly/global, by class, by vehicle, personal best) and default/max row limits.

## Ghost

`Config.Ghost` controls ghost recording/playback: which modes save/show ghosts, whether players can toggle it, sampling rate and resolution, max stored samples, visual alpha, and traffic-collision suppression while a ghost replays through the world.

## Illegal races

`Config.Illegal.dispatch` sets the alert radius (in game units) used when broadcasting an illegal race to nearby dispatch listeners. Per-route dispatch chance and wanted-crime text are set per race (via the route creator or `Config.Routes`), not here.

## Logs

`Config.Logs` optionally sends race events to a Discord webhook.

## Routes

`Config.Routes` is where routes can be hard-coded directly in Lua (as an alternative or addition to routes saved via the in-game editor to the database). In practice, most server owners will manage routes entirely through `/racecreator` — see [Creating Routes](/races/route-creator.md).

***

## A note on locales

All player-facing text (notifications, UI labels, error messages) lives in `config/locales/en.lua` (and `pt.lua`) — not in the config file or the code.

{% stepper %}
{% step %}

### Copy the locale file

Copy `en.lua` to a new file under `config/locales/`.
{% endstep %}

{% step %}

### Translate its values

Translate the copied file's values.
{% endstep %}

{% step %}

### Set the locale

Set `Config.Locale` to match .
{% endstep %}
{% endstepper %}


---

# 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.lostdev.store/races/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.