# Configuration

Framework and inventory, your own overrides, keys, server.cfg settings and dispatch.

## Where to make changes

Settings are in the `wd_phone/config` folder, one file per feature. Each value is commented in its file. Change individual values rather than rewriting whole files, then restart Wolfden Phone on a test server and confirm the result before applying it to your live server.

Most files are shared: players' games can read them. These files are **server-only** and never reach players, so they are where keys, prices and hidden locations live:

| File | Holds |
| --- | --- |
| `server.lua` | Device IDs, PIN hashing and framework hooks |
| `media_server.lua` | The media host and its keys |
| `calls_server.lua` | The video call relay and its secrets |
| `dispatch.lua` | Dispatch integrations |
| `assist_server.lua` | Assist AI answers |
| `racing_server.lua` | Racing anti-cheat and police heat |
| `mobile_shops_server.lua` | Phone store locations, prices, stock and the black-market dealer |

Keys and secrets are best kept in `server.cfg` instead; see [Settings in server.cfg](#settings-in-servercfg).

The phone screen ships prebuilt in `web/dist`. You never need Node.js or a rebuild to change settings or text.

## Keep your changes in config/local

Instead of editing the shipped files, you can put your changes in your own Lua files in `config/local/`. They load after every shared config file, in alphabetical order, so a value set there wins over the default. An update replaces the shipped config files but never your `config/local/` files.

Write each change as an assignment onto the existing setting:

```lua config/local/my_server.lua
Config.OpenRestrictions.allowWhileCuffed = true
Config.Security.maxAttempts = 3
Config.Apps.bank.preinstalled = true
```

**Files in `config/local/` are sent to every player's game.** Never put API keys, secrets or anything players should not read there. Changes to the server-only files above go in `config/local/server/` instead, which loads on the server only, after all of them:

```lua config/local/server/my_server.lua
Config.MediaUpload.provider = 'self_hosted'
Config.MediaUpload.selfHostedPublicUrl = 'https://img.yourserver.com'
Config.MobileShops.catalogue.nova.price = 1500
```

The release ships an empty `_empty.lua` in each folder; leave it there.

Two exceptions: `config/client.lua` loads after `config/local/`, so edit it directly. And the list of phone items is built from `Config.PhoneModels` and `Config.DeviceColors` as `config/devices.lua` loads, so change models and colours in that file itself.

`config/local/` is also the place for content you add yourself, such as radio streams, songs or a map image; Wolfden Phone ships without any. See [Music & speakers](#/docs/wd_phone/music).

## Framework and inventory

Wolfden Phone runs on **Qbox, QBCore or ESX**, with **ox_inventory** on any of them or **qb-inventory 2.1 or newer** on QBCore. Both are picked automatically when the resource starts, so start your framework and inventory before `wd_phone`.

```lua config/shared.lua
Config.Framework = {
    name = 'auto',   -- auto, qbox, qbcore or esx
    ...
}

Config.Inventory = 'auto'   -- auto, ox_inventory or qb-inventory
```

- `auto` uses the first started of qbx_core, qb-core and es_extended, and ox_inventory when it is started, otherwise qb-inventory.
- To force one, change the value above or add `setr wd_phone:framework "esx"` or `setr wd_phone:inventory "qb-inventory"` to `server.cfg`. These two use `setr` because players' games need to read them too.
- ESX with ox_inventory needs `Config.CustomInventory = 'ox'` in your ESX config.
- ps-inventory and lj-inventory are not supported.

`phoneadmin selftest report` prints which framework and inventory were selected.

**ESX duty.** ESX versions without on-duty tracking count every employee as on duty (`esxDutyAlwaysOn = true`). This matters for police features such as [subscriber records](#/docs/wd_phone/subscriber-records) and the [forensic unlock](#/docs/wd_phone/nova-secure?section=forensic-unlock). For your own rules, set the framework hooks in `config/server.lua`: `isOnDuty`, `isDowned`, `hasDriverLicence` (for Rides) and `getGang` (for Shade crew rooms).

## Language, time and keys

```lua
-- config/shared.lua
Config.Locale = 'en'          -- the language new phones start in
Config.UseRealTime = true     -- false uses GTA game time
Config.DefaultUIScale = 1.0

-- config/client.lua
Config.OpenPhoneKey = 'M'
```

Edit these lines in their respective files; do not paste all of them into one file. Players who already have a saved FiveM keybind may need to rebind it in their game settings.

| Key | Default | Where to change it |
| --- | --- | --- |
| Open the phone | **M** | `Config.OpenPhoneKey` in `client.lua` |
| Use the phone / walk with it | **Left Alt** | `Config.PhoneCursorToggle` in `client.lua` |
| Answer / decline a call | **Y** / **N** | `Config.CallControls` in `communication.lua` |
| NovaBuds and Nova Studio noise control | **U** | `Config.NovaPods.noiseControl.key` in `novapods.lua` |
| Open Assist | Not bound | `Config.Assist.hotkey.key` in `assist.lua` |

Players can rebind all of them under FiveM → Settings → Key Bindings → FiveM.

The phone comes in twenty languages, chosen per phone in Settings → General → Language. All of its text can be reworded without a rebuild. See [Languages and wording](#/docs/wd_phone/apps?section=languages-and-wording).

## Who can use a phone?

Phones have no owner. Whoever holds a phone can use it, unless its PIN is set. The **Nova Account** signed in on a phone manages it: Locate, lost mode, remote erase, backups and transfer all go through the account. See [Nova Account & recovery](#/docs/wd_phone/device-operations).

With several phones in the inventory, the open key shows a menu to choose one. Set `Config.PhonePicker.alwaysAsk = false` in `client.lua` to reopen the last phone used instead.

## Opening restrictions

`Config.OpenRestrictions` in `shared.lua` controls when a phone can be opened:

```lua
Config.OpenRestrictions = {
    allowWhileDead = false,
    allowWhileCuffed = false,
    allowWhileSwimming = true,
}
```

`Config.Security` in the same file sets PIN lengths (4 or 6 digits), how many wrong PINs are allowed (5) and the lockout that follows (60 seconds).

## Settings in server.cfg

These settings go in `server.cfg` above `ensure wd_phone`. A value there replaces the one in the config file.

| Setting | What it does | Guide |
| --- | --- | --- |
| `setr wd_phone:framework "auto"` | Force a framework | [Above](#framework-and-inventory) |
| `setr wd_phone:inventory "auto"` | Force an inventory | [Above](#framework-and-inventory) |
| `set wd_phone:secret "..."` | Your own item-signing secret (optional) | [Admin tools](#/docs/wd_phone/admin?section=item-signatures) |
| `set wd_phone:bank "auto"` | The banking system Nova Wallet uses | [Wallet & payments](#/docs/wd_phone/wallet) |
| `set wd_phone:economy "bank"` | How carrier, shop and repair charges are paid | [Wallet & payments](#/docs/wd_phone/wallet) |
| `set wd_phone:dispatch "auto"` | The dispatch resource alerts go to | [Calls & messages](#/docs/wd_phone/communications?section=emergency-calls-and-dispatch) |
| `set FIVEMANAGE_MEDIA_API_KEY "..."` | The Fivemanage key for photos and videos | [Camera & media hosting](#/docs/wd_phone/media) |
| `set NOVA_TURN_SECRET "..."` | The coturn secret for video calls | [Video calls](#/docs/wd_phone/video-calls) |
| `set wd_phone:assist_key "..."` | The API key for Assist AI answers (off by default) | [Everyday & social apps](#/docs/wd_phone/productivity?section=ai-answers) |

For secrets and keys, always use `set`, never `setr`: `setr` sends the value to every player.

## Dispatch integrations

Emergency calls and Services requests can also go to your police and EMS dispatch resource. Wolfden Phone detects ps-dispatch, cd_dispatch, cd_dispatch3d, qs-dispatch, rcore_dispatch, core_dispatch and lb-tablet by itself. Its settings are in the server-only `config/dispatch.lua`, and `set wd_phone:dispatch` in `server.cfg` chooses the resource. [Emergency calls and dispatch](#/docs/wd_phone/communications?section=emergency-calls-and-dispatch) lists every setting and what an alert contains. Other dispatch resources can connect through an export; see [Exports & integrations](#/docs/wd_phone/exports).

## Feature settings

| What you want to change | File | Guide |
| --- | --- | --- |
| Phone models, colours and accent colours | `devices.lua`, `themes.lua` | [Phones & inventory](#/docs/wd_phone/devices) |
| Phone in the hand and screen glow | `client.lua` | [Phones & inventory](#/docs/wd_phone/devices?section=in-the-players-hand) |
| Phone stores and the black-market dealer | `mobile_shops.lua`, `mobile_shops_server.lua` | [Phones & inventory](#/docs/wd_phone/devices?section=phone-stores) |
| Wolfden Phone Secure: Burn Phone, Burn PIN, forensic unlock, number swap and rooms | `secure.lua` | [Wolfden Phone Secure](#/docs/wd_phone/nova-secure) |
| Apps, dock and widgets | `apps.lua` | [Apps & appearance](#/docs/wd_phone/apps) |
| Themes and wallpapers | `themes.lua` | [Apps & appearance](#/docs/wd_phone/apps) |
| Languages | `platform.lua` | [Apps & appearance](#/docs/wd_phone/apps?section=languages-and-wording) |
| Face Unlock (`Config.FaceId`) | `face_id.lua` | [Nova Account & recovery](#/docs/wd_phone/device-operations?section=pin-and-face-unlock) |
| SIMs, carriers, plans and mobile data | `sims.lua`, `carriers.lua`, `plans.lua` | [SIMs & carriers](#/docs/wd_phone/sims) |
| Carrier shop locations and prices | `shops.lua` | [SIMs & carriers](#/docs/wd_phone/sims) |
| Signal, cell towers and emergency numbers | `signal.lua`, `towers.lua` | [SIMs & carriers](#/docs/wd_phone/sims?section=cell-towers) |
| Police subscriber records and data center terminals | `records.lua` | [Subscriber records](#/docs/wd_phone/subscriber-records) |
| Calls, group calls, messages, NovaDrop and Wolfden Phone Secure retention | `communication.lua` | [Calls & messages](#/docs/wd_phone/communications) |
| Payphones | `payphones.lua` | [Calls & messages](#/docs/wd_phone/communications) |
| Radio | `radio.lua` | [Calls & messages](#/docs/wd_phone/communications) |
| Video call relay | `calls_server.lua` | [Video calls](#/docs/wd_phone/video-calls) |
| Dispatch integrations | `dispatch.lua` | [Calls & messages](#/docs/wd_phone/communications?section=emergency-calls-and-dispatch) |
| Camera, media host and gallery | `media.lua`, `media_server.lua`, `gallery.lua` | [Camera & media hosting](#/docs/wd_phone/media) |
| Music and Bluetooth speakers | `music.lua`, `speakers.lua` | [Music & speakers](#/docs/wd_phone/music) |
| Batteries, chargers and repair shops | `charging.lua` | [Batteries & accessories](#/docs/wd_phone/accessories) |
| NovaBuds and Nova Studio (`Config.NovaPods`) | `novapods.lua` | [Batteries & accessories](#/docs/wd_phone/accessories) |
| Wi-Fi routers, public Wi-Fi and Personal Hotspot | `wifi.lua` | [Batteries & accessories](#/docs/wd_phone/accessories) |
| Flashlight | `flashlight.lua` | [Apps & appearance](#/docs/wd_phone/apps) |
| Wallet, bank and charges | `banking.lua` | [Wallet & payments](#/docs/wd_phone/wallet) |
| Echo, Snapgram and Ember | `social.lua`, `snapgram.lua`, `ember.lua` | [Everyday & social apps](#/docs/wd_phone/productivity) |
| Calendar, Notes, Mail and Maps | `productivity.lua`, `mail.lua`, `maps.lua` | [Everyday & social apps](#/docs/wd_phone/productivity) |
| News, Arcade and Assist | `news.lua`, `arcade.lua`, `assist.lua`, `assist_server.lua` | [Everyday & social apps](#/docs/wd_phone/productivity) |
| Jobs, services and businesses | `services.lua`, `commerce.lua` | [Everyday & social apps](#/docs/wd_phone/productivity) |
| Clips, Clips Live and the creator economy | `clips.lua`, `creators.lua` | [Clips](#/docs/wd_phone/clips) |
| Shade | `shade.lua` | [Shade](#/docs/wd_phone/shade) |
| Racing | `racing.lua`, `racing_server.lua` | [Racing](#/docs/wd_phone/racing) |
| Rides, Bites, Garage and Homes | `rides.lua`, `bites.lua`, `garage.lua`, `homes.lua` | [City apps](#/docs/wd_phone/city-apps) |
| Nova Accounts and app logins | `accounts.lua` | [Nova Account & recovery](#/docs/wd_phone/device-operations) |
| Backups, Locate and admin tools | `platform.lua` | [Admin tools](#/docs/wd_phone/admin) |

All file names in the table are relative to `wd_phone/config/`.

## Keep your settings during updates

An update replaces the shipped config files and language files. What you keep in `config/local/`, `config/local/server/` and the two language `overrides/` folders stays yours: back those folders up before every update.

If you edited shipped config files directly, merge your values into the new files instead of copying your old files over them. New releases may add settings that new features need. See [Updating Wolfden Phone](#/docs/wd_phone/upgrading).