# Configuration

c3r's settings live in plain Lua files in `c3r/config/`, read by both the server and every player's game. Edit a file and restart c3r, or change values live in game with `/c3rconfig` (admins). Every option is listed below with its default.

| File | What's in it |
|---|---|
| `main.lua` | Debug, duty, keys, the officer's voice |
| `stops.lua` | Picking the car, how it pulls over, the U modes, tests, running, felony stops |
| `people.lua` | Hidden truths, demeanours and records |
| `patrol.lua` | Staged violators, booking and police stations |
| `backup.lua` | AI backup units and the tow truck |
| `medical.lua` | First aid |
| `callouts.lua` | Callouts |

> [!TIP]
> Change a value with `/c3rconfig` and it's written into the file for you, comments and all, and goes live for everyone at once. Keys and command names need a restart.

## The basics

`main.lua`

**Config.Debug** `boolean` (default: `false`)
Extra logging in the server console and F8. Leave it off on a live server.

**Config.DutyCommand** `string` (default: `'duty'`)
The chat command that toggles your shift.

**Config.DutyKey** `string` (default: `'F11'`)
Opens the service screen.

**Config.DutyAce** `string | nil` (default: `nil`)
`nil` lets anyone go on duty. Set an ace (e.g. `'c3r.police'`) and grant it to restrict it:
```cfg
add_ace group.police c3r.police allow
```

**Config.TargetKey** `string` (default: `'LSHIFT'`)
In a police vehicle: the red circle ahead. Press again to cancel.

**Config.ModeKey** `string` (default: `'U'`)
During a stop: what the driver does.

**Config.InteractKey** `string` (default: `'E'`)
The contact wheel.

**Config.RadialKey** `string` (default: `'G'`)
Held: the vehicle wheel at a car, the dispatch wheel elsewhere.

**Config.RespondKey** `string` (default: `'Y'`)
Respond to a callout offer.

**Config.ObjectiveKey** `string` (default: `'BACK'`)
On a callout: hide or show the objective card.

**Config.LeaveCallKey** `string` (default: `'X'`)
Decline a callout offer; on a call, leave it.

**Config.WeaponWheelHold** `number` (default: `500`)
Milliseconds Tab must be held to open the weapon wheel while an ID is showing. A shorter tap hides or shows the ID.

**Config.Voice** `table` (default: `{ range = 20.0, volume = 1.0 }`)
The officer's spoken lines (asking for ID, Miranda rights, a search, the breathalyzer). `range` in metres, quieter further off; `volume` 0-1, 0 turns them off.

> [!NOTE]
> Keybinds are saved per player the first time they join. A changed default only reaches new players; others rebind it in **Settings → Key Bindings → FiveM → c3r**.

## Picking the car and pulling over

`stops.lua`

**Config.Target** `table`

| Field | Default | What it does |
|---|---|---|
| `distance` | `9.0` | Metres ahead of the patrol car the circle sits |
| `radius` | `2.6` | Metres: a car whose centre is this close to the circle is picked |
| `lose_distance` | `60.0` | Metres: let the picked car get this far away and it's let go |
| `color` | `{ 200, 72, 66 }` | The circle's colour (RGB) |

**Config.Pullover** `table`
Tuning knobs for how the AI pulls over. GTA's driving AI behaves differently on different roads; adjust these if drivers stop too far, too short, or in the lane.

| Field | Default | What it does |
|---|---|---|
| `ahead` | `30.0` | Metres ahead of where they were that they aim to stop |
| `kerb_gap` | `0.35` | Metres between the car's right side and the kerb once stopped |
| `kerb_inset` | `1.4` | Roads with no kerb: how far in from the road edge they stop |
| `straighten` | `7.0` | Metres of slow glide along the kerb onto the final spot |
| `glide` | `1.0` | How far out from the kerb they aim before that glide (stops nose-in parking) |
| `speed` | `7.0` | m/s while pulling over (about 15 mph) |
| `driving_style` | `16777259` | GTA driving flags: stop for cars and people, steer round parked cars, straight lines, no waiting at lights |
| `bend_style` | `786475` | On a bend: normal road-following driving |
| `timeout_ms` | `15000` | Give up steering for the kerb after this long and just stop |

**Config.CancelDistance** `number` (default: `150.0`)
Drive this many metres from the stop and it's cancelled.

**Config.Modes** `table`
The U menu's driving modes.

| Field | Default | What it does |
|---|---|---|
| `speed` | `12.0` | m/s top speed while following in front or behind (about 27 mph) |
| `gap` | `4.0` | Metres they keep from your car while following |
| `steer_speed` | `8.0` | m/s top speed while you steer them (about 18 mph) |

## Stops, orders and running

`stops.lua`

**Config.Tests** `table` (default: `{ bac_limit = 0.08 }`)
The breathalyzer's legal limit.

**Config.Flee** `table`
Not everyone goes quietly. Chances are 0-1, per hidden truth; a truth that isn't listed never does it.

| Field | Default | What it does |
|---|---|---|
| `car` | `warrant 0.3, stolen 0.4, drugs 0.1, drunk 0.08, suspended 0.08, unlicensed 0.05` | Runs instead of pulling over |
| `foot` | `warrant 0.25, stolen 0.25, drugs 0.1` | Runs when ordered out, or when you go to cuff them |
| `bail` | `0.5` | A car chase ends: they run on foot instead of giving up |
| `refuse` | `0.35` | Rude, or with something to hide: refuses the first order to get out |
| `lose_distance` | `250.0` | Metres: further than this for 10 s and they got away |
| `catch_distance` | `2.5` | Metres: on foot, this close and they give up |

**Config.PaRange** `number` (default: `40.0`)
Metres shouted orders reach (the PA, a felony stop). Talking still needs you beside them.

**Config.Felony** `table`
Felony stop chances (0-1).

| Field | Default | What it does |
|---|---|---|
| `freeze` | `0.2` | Doesn't move the first time they're told (asked again, they do) |
| `run` | `warrant 0.3, stolen 0.3, drugs 0.15` | Bolts on foot instead (once) |
| `drive` | `stolen 0.2, warrant 0.15` | The driver floors it when the felony stop starts |

## Who you stop

`people.lua`

**Config.Secrets** `table`
How often each hidden truth comes up, as relative weights (any numbers; 0 turns one off).

| Truth | Default weight |
|---|---|
| `clean` | 40 |
| `nervous` | 10 |
| `unlicensed` | 8 |
| `suspended` | 8 |
| `expired` | 8 |
| `drunk` | 8 |
| `drugs` | 7 |
| `warrant` | 6 |
| `stolen` | 5 |

**Config.Demeanors** `table` (default: `polite 50, nervous 20, rude 15, chatty 15`)
How people come across, as relative weights.

**Config.PassengerSecrets** `table` (default: `clean 55, nervous 15, warrant 10, drugs 10, drunk 10`)
Passengers' own truths. They aren't driving, so no licence or papers truths.

**Config.FlagChance** `number` (default: `0.06`)
Chance anyone has a record flag (PROBATION, GANG AFFILIATION...).

**Config.BorrowedChance** `number` (default: `0.15`)
Chance the car belongs to a relative.

**Config.OwnerDrivesChance** `number` (default: `0.8`)
A car you've stopped before: chance its owner is at the wheel again.

## Patrol and booking

`patrol.lua`

**Config.Staged** `table`
Staged violators: a car near you starts driving to match its story.

| Field | Default | What it does |
|---|---|---|
| `enabled` | `true` | Turn staged violators on or off |
| `every` | `{ 180, 300 }` | Seconds between violators (random in range) |
| `lasts` | `90` | Seconds it keeps it up |
| `secrets` | `drunk 4, stolen 2, drugs 2, warrant 2, suspended 2, unlicensed 1, expired 1, clean 1` | Which truths get staged, as weights |

**Config.BookingRadius** `number` (default: `5.0`)
Metres: stop this close to a station with someone in custody and they're booked.

**Config.Stations** `table`
Where you can book prisoners. Each entry is `{ name, x, y, z }`. Defaults: Mission Row, Vespucci, Davis, La Mesa, Vinewood, Rockford Hills, Sandy Shores, Paleto Bay, Bolingbroke. Positions are approximate: move them to match your MLOs.
```lua
{ name = 'Mission Row', x = 441.0, y = -985.0, z = 30.7 },
```

## Backup and the tow truck

`backup.lua`

**Config.Backup** `table`

| Field | Default | What it does |
|---|---|---|
| `spawn` | `{ 150.0, 210.0 }` | Metres from the scene a unit appears, out of sight |
| `speed` | `25.0` | m/s on lights and siren (others drive at 15) |
| `timeout` | `120` | Seconds to get there; stuck in traffic, it turns up anyway |
| `job_timeout` | `90` | Seconds the work at the scene may take before they pack up |
| `cover_minutes` | `5` | A cover unit stands by this long at most |
| `pursuit` | `{ light = 1, medium = 2, heavy = 3, max = 6 }` | Cars per pursuit request, and at most in one chase |
| `spikes` | `0.5` | In a chase, how often a request's first car lays a Stop Stick up ahead (needs `lwk_stopstick`) |

**Config.Backup.units** `table`
One entry per unit: `car` (spawn name), `crew` (ped models), and optionally `lights` and `muted`. Model names are from [FiveM's game references](https://docs.fivem.net/docs/game-references/).

| Unit | Default car | Default crew |
|---|---|---|
| `police` (transport) | `policet` | 2 × `s_m_y_cop_01` |
| `ambulance` | `ambulance` | 2 × `s_m_m_paramedic_01` |
| `fire` | `firetruk` | 2 × `s_m_y_fireman_01` |
| `coroner` | `speedo` | `s_m_m_doctor_01`, `s_m_m_scientist_01` |
| `mechanic` | `burrito3` | `s_m_y_xmech_01` |
| `roadservice` | `utillitruck3` | `s_m_y_xmech_02` |
| `animalrescue` | `pranger` | `s_m_y_ranger_01` |
| `taxi` | `taxi` | `a_m_y_stlat_01` |
| `cover` | `police3` | `s_m_y_cop_01` |
| `pursuit` | `police`, `police2`, `police3` (`cars = { }`) | 2 × `s_m_y_cop_01` |
| `air` | `polmav` | `s_m_y_pilot_01` |

Any unit (and the tow truck) can also set how it looks:

```lua
Config.Backup.units.cover.livery = 2                 -- the vehicle's livery
Config.Backup.units.cover.colours = { 111, 0 }       -- primary, secondary paint (GTA colour ids)
Config.Backup.units.cover.extras = { [1] = true }    -- vehicle extras on / off
Config.Backup.units.cover.outfit = { [11] = { 0, 0 } } -- crew clothing: component = { drawable, texture }
Config.Backup.units.cover.props = { [0] = { 1, 0 } } -- hats (0) and glasses (1)
```

Outfit components: 3 arms, 4 legs, 6 shoes, 8 undershirt, 9 vest, 11 jacket.

**Config.Tow** `table`

| Field | Default | What it does |
|---|---|---|
| `truck` | `'flatbed'` | The tow truck |
| `driver` | `'s_m_m_trucker_01'` | Its driver |
| `distance` | `120.0` | Metres behind the car it comes up the road from |
| `timeout_ms` | `90000` | Stuck this long, it turns up anyway |
| `tries` | `3` | Failed tows of the same car before it's just removed |

## First aid

`medical.lua`

**Config.Medical** `table`

| Field | Default | What it does |
|---|---|---|
| `cpr_chance` | `0.35` | Chance a CPR attempt brings someone back |
| `cpr_window` | `300` | Seconds after dying that CPR can still work |
| `cpr_seconds` | `15` | How long CPR takes |
| `paramedic_revive` | `0.4` | Paramedics bring back anyone they find dead, this often |

## Callouts

`callouts.lua`. The calls themselves are files in `c3r/callouts/` (see the [Callouts SDK](/docs/c3r/callouts-sdk)).

**Config.Callouts** `table`

| Field | Default | What it does |
|---|---|---|
| `enabled` | `true` | Turn callouts on or off |
| `every` | `{ 240, 480 }` | Seconds between new calls while anyone is on duty |
| `max_open` | `2` | Calls open at once |
| `min_distance` | `400.0` | A new call is at least this far (m) from the officer it's made near... |
| `max_distance` | `2500.0` | ...and no further than this |
| `expire` | `300` | Seconds a call nobody responds to stays open |
| `offer_window` | `30` | Seconds the offer card stays up |
| `arrive` | `40.0` | Metres from the call that count as on scene |
| `build` | `300.0` | Each person, car and prop is made when a unit gets this close (m) |
| `max_minutes` | `30` | A call still open after this long is cancelled |