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

# Configuration

Public runtime configuration is split between three files:

| File                       | Scope                                                                                                                     |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `shared/config.lua`        | Framework selection, phone behavior, applications, database mappings, connectivity, camera, services, and feature limits. |
| `shared/server_config.lua` | Server-only API credentials. Never expose this file to the client.                                                        |
| `bridge/config.lua`        | Framework and external-resource mappings.                                                                                 |

Restart `src-phone` after changing Lua configuration.

## Core phone settings

| Setting                    | Default         | Purpose                                                                 |
| -------------------------- | --------------- | ----------------------------------------------------------------------- |
| `Config.Core`              | `qb`            | Framework bridge: `qb`, `qbox`, `esx`, `vrp`, or `standalone`.          |
| `Config.PhoneOpenKey`      | `F1`            | Default FiveM key mapping. Players may have an existing local override. |
| `Config.PhonePrefix`       | `555-`          | Prefix used when assigning phone numbers.                               |
| `Config.PhoneNumberLength` | `4`             | Random digits appended after the prefix.                                |
| `Config.MailDomain`        | `@sourcedevpro` | Domain appended to generated mail addresses.                            |
| `Config.DefaultWallpaper`  | URL             | Default wallpaper for a new profile.                                    |
| `Config.DefaultBrightness` | `80`            | Initial brightness percentage.                                          |
| `Config.WeatherUnit`       | `C`             | `C` or `F`.                                                             |
| `Config.WeatherLocation`   | `Los Santos`    | Home weather widget label.                                              |

Changing phone-number rules affects newly generated numbers. Existing values in `src_phone_data` are not rewritten automatically.

## Application availability

`Config.Apps` is the server-wide allowlist for built-in applications:

```lua
Config.Apps = {
    phone = true,
    messages = true,
    bank = true,
    garage = true,
    appstore = true,
}
```

Setting an application to `false` removes it from the home screen and App Store. This does not delete its database data. Re-enabling the application restores access to existing records.

Do not add a custom application ID to this table. External applications register through the `registerApp` export.

## Database mappings

`Config.Database` maps phone queries to your schema. The bundled `install.sql` already matches the defaults.

Only change these values when integrating an existing custom schema:

* `Config.Database.PhoneData`
* `Config.Database.Contacts`
* `Config.Database.Mail`
* `Config.Database.Messages`

Column mappings must be changed consistently. For example, changing only the contacts table name while leaving incompatible column names will allow the query to run but return invalid records.

## Garage and valet

`Config.Garage.Valet` controls whether the phone can deliver a stored vehicle:

| Setting             | Purpose                                   |
| ------------------- | ----------------------------------------- |
| `Enabled`           | Enables the valet action.                 |
| `Price`             | Amount charged before spawn.              |
| `Account`           | Framework money account, normally `bank`. |
| `SpawnRadius`       | Search radius for a valid spawn position. |
| `DriveSpeed`        | Valet driving speed.                      |
| `DriverPedModel`    | Ped model used by the valet.              |
| `Timeout`           | Delivery timeout in milliseconds.         |
| `BlacklistedModels` | Vehicles that cannot be delivered.        |
| `BlacklistedZones`  | Zone flags used to prevent delivery.      |

The SQL table and state mappings are configured separately under `BridgeConfig.Garage.SQL`.

## Phone prop

`Config.PhoneProp` controls the model attached to the player:

```lua
Config.PhoneProp = {
    Model = 'src_phone',
    Bone = 28422,
    Offset = vector3(0.0, 0.0, 0.0),
    Rotation = vector3(0.0, 0.0, 0.0),
    CameraOffset = vector3(0.0, -0.005, 0.0),
    CameraRotation = vector3(0.0, 0.0, 180.0),
}
```

The model must be streamed and available before testing offsets. Adjust one axis at a time and restart the resource after changing the model.

## Wi-Fi routers

`Config.Router` controls placeable routers and metered Wi-Fi:

* `Enabled`: enables placement and router UI.
* `InternetUsageEnabled`: enables quota enforcement.
* `Command`: placement command, default `setrouter`.
* `RequiredItem`, `ItemAmount`, `ConsumeItem`: inventory cost.
* `PropModel`, `FallbackPropModels`: placement object selection.
* `Range`: usable Wi-Fi radius.
* Network-name, password, and admin-password length rules.
* Login attempt and lockout limits.
* Initial data quota and purchasable packages.
* Per-action and active-stream usage costs.

`UsageCostsMb.music` and active-stream accounting can consume quota quickly. Test the configured values with the server's expected session length before release.

## Cellular data

`Config.Cellular` provides a player-owned fallback connection when Wi-Fi is unavailable:

* Initial plan name, quota, and validity.
* Money account used for purchases.
* Available packages.
* Per-action and streaming usage costs.
* Usage tick, flush, and rate-limit values.

When both systems are enabled, the web layer attempts authorized Wi-Fi first and cellular data second.

## Feature-specific sections

| Section                | Controls                                                           |
| ---------------------- | ------------------------------------------------------------------ |
| `Config.CryptoWallet`  | Tokens, fallback prices, bank account, refresh interval, and fees. |
| `Config.Camera.Selfie` | Selfie camera offset, rotation, and FOV limits.                    |
| `Config.News`          | Jobs allowed to publish and valid categories.                      |
| `Config.YellowPages`   | Listing categories.                                                |
| `Config.Services`      | Service IDs, jobs, labels, icons, and colors.                      |
| `Config.VoiceMemos`    | Duration, item count, and payload-size limits.                     |

## Bridge configuration

### Garage

Select the external garage, key, and fuel resources and verify the SQL mapping. `FuelSystem = 'auto'` uses bridge detection; use an explicit integration when detection is ambiguous.

### Calls

The default is:

```lua
BridgeConfig.Call.VoiceSystem = 'pma-voice'
```

Other listed bridge targets require a compatible implementation in the call bridge. A name in the config is not sufficient if the target resource API differs from the bridge code.

### Services

`BridgeConfig.Services` maps character and job columns for ESX, QB/QBox, and vRP service-directory lookups.

## Configuration change checklist

1. Confirm the value type and accepted range.
2. Check whether the setting belongs in shared config, server-only config, or bridge config.
3. Back up the changed file.
4. Restart `src-phone`.
5. Check server and client consoles.
6. Test with a new character and an existing character.
7. Test the affected feature with two players when it involves calls, messages, or sharing.