Configuration

All user-facing configuration lives in config.lua (escrow-ignored, buyer-editable). The file loads first in the manifest so framework auto-detection runs before the guarded framework files.

Core Settings

Config.Framework = 'auto'   -- 'auto' | 'qb' | 'qbx' | 'esx'

auto (default): Detects running framework at startup (qbx → qb-core → es_extended).
qb: QBCore (qb-core).
qbx: QBox (qbx_core).
esx: ESX Legacy (es_extended).

Tip: Set explicitly if you run multiple framework resources or want to skip auto-detection.

UI & Keybinds

Config.UI = {
    openCommand = 'carplay',          -- Command name (also the keybind ID)
    openDescription = 'Open CarPlay', -- Keybind description in GTA settings
    defaultKey = 'F6',                -- Default key (remappable in Controls)
}

openCommand registers /carplay and a keybind. Players can rebind in Settings → Key Bindings → FiveM.
The command toggles the UI (open if closed, close if open).

CarPlay Feature Configuration

Config.CarPlay = {
    requireDriverSeat = true,         -- Only driver can open
    defaultApp = 'home',              -- 'home' | 'music' | 'vehicle' | 'navigation' | 'radio' | 'phone' | 'messages' | 'settings'
    defaultLayout = 'cluster',        -- 'cluster' | 'desktop' | 'mobile' (player can override in Settings app)
    apps = {                          -- Toggle apps in the dock (false = hidden)
        home = true,
        music = true,
        navigation = true,
        vehicle = true,
        radio = true,
        phone = true,
        messages = true,
        settings = true,
    },
    tablet = {
        position = 'bottom-right',    -- 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' | 'bottom-center' | 'center'
    },
    speedUnit = 'mph',                -- 'mph' | 'kmh'
    disabledVehicleClasses = { 8, 13, 14, 15, 16 }, -- Bikes, cycles, boats, aircraft, helicopters
    settingsScope = 'plate',          -- 'plate' (per-vehicle) | 'player' (per-character)
    ownership = {
        enabled = true,               -- false = persist all vehicles without ownership check
        tableName = nil,              -- nil = auto: 'player_vehicles' (qb/qbx) or 'owned_vehicles' (esx)
        plateColumn = 'plate',
        fallbackOwned = true,         -- true = treat as owned when DB unavailable
    },
}

`apps` Table

Each key matches an AppId in the NUI (home, music, navigation, vehicle, radio, phone, messages, settings). Set false to remove from the dock entirely.

`settingsScope`

plate (default): Each vehicle remembers its own layout, last app, music prefs, etc. Keyed by normalized license plate. Owned vehicles persist to browser localStorage (durable). NPC/unowned vehicles stay in server memory KV cache only (cleared on restart).
player: One preference set follows the character (citizenid/license) across all vehicles. Always persists to localStorage.

`ownership` (only matters when `settingsScope = 'plate'`)

enabled = false → skip ownership check, persist everything.
tableName / plateColumn → override the DB table/column if your schema differs.
fallbackOwned = true (default) → if oxmysql isn’t started or the query errors, assume owned so players don’t lose settings on misconfigured servers.

Music App

Config.Music = {
    defaultVolume = 0.5,          -- 0.0 - 1.0
    positional = true,            -- true = 3D audio at vehicle (passengers/nearby hear it)
    audibleDistance = 5.0,        -- Max distance for positional audio (GTA units)
    autoAdvance = true,           -- Auto-play next track when current ends
    pollInterval = 500,           -- UI state poll interval (ms) while UI open
}

Requires xsound (hard dependency in fxmanifest.lua).
Plays direct audio URLs (.mp3, .ogg, .m3u8, etc.) and YouTube links (resolved by xsound’s IFrame API).
positional = true uses xsound’s PlayUrlPos with source = -1 (broadcast to all clients) so each client’s 3D audio engine renders proximity. false uses PlayUrl with the player’s source (local only).
audibleDistance maps to xsound’s Distance export.

Vehicle App

Config.Vehicle = {
    pollInterval = 500,              -- UI state poll interval (ms)
    engineHealthEnabled = true,      -- Show engine damage gauge (0-100%)
    bodyHealthEnabled = true,        -- Show body/chassis condition gauge (0-100%)
    fuelSource = 'auto',             -- 'auto' | 'native' | '<system_key>' | 'custom'
    fuelExport = nil,                -- { resource = 'my_fuel', method = 'GetFuel' } when fuelSource = 'custom'
}

`fuelSource` Options

Value	Behavior
`'auto'` (default)	Probe running resources in priority order: `ox_fuel`, `cdn-fuel`, `ps-fuel`, `LegacyFuel`, `qb-fuel`, `qb-sna-fuel`, `lj-fuel`, `lc_fuel`, `LNS_Fuel`, `okokGasStation`, `frfuel`. First match wins. Falls back to native.
`'native'`	Always use `GetVehicleFuelLevel` (GTA native). Ignores fuel resources.
`'<system_key>'`	Pin a specific system from the auto-detect list (e.g., `'ox_fuel'`, `'ps-fuel'`).
`'custom'`	Use `Config.Vehicle.fuelExport = { resource = '...', method = '...' }`. The export receives the vehicle entity as its only argument and must return 0-100.

Note: client/utils.lua is escrow-ignored — you can add unsupported fuel systems to the FUEL_SYSTEMS table there.

Config.Navigation = {
    pollInterval = 500,           -- UI state poll interval (ms)
    scanRadius = 4000.0,          -- Max search radius for nearby POIs (GTA units ≈ meters)
    maxResults = 12,              -- Cap results per category (nearest first)
    distanceUnit = 'mi',          -- 'mi' | 'km' (falls back to CarPlay.speedUnit)
    categories = {                -- Category ID → GTA blip sprite IDs
        fuel     = { blips = { 361 } },      -- Gas station
        hospital = { blips = { 153 } },      -- Hospital / medical
        ammo     = { blips = { 110 } },      -- Ammu-Nation
        police   = { blips = { 60, 137 } },  -- Police station / sheriff
        mechanic = { blips = { 446, 72 } },  -- LSC / mechanic
    },
}

No extra resources required — uses GTA natives: GetStreetNameAtCoord, GetEntitySpeed, GetEntityHeading, blip iteration (GetFirstBlipInfoId / GetNextBlipInfoId), SetNewWaypoint, DeleteWaypoint.
Categories map to vanilla map blip sprites. Add custom server blip sprites to the blips array for your own POIs.
ATMs have no persistent blip in GTA — not included by default (would need a coordinate list).

Radio App

Config.Radio = {
    defaultVolume = 0.5,          -- 0.0 - 1.0 for internet streams
    positional = true,            -- 3D audio at vehicle (same as Music)
    audibleDistance = 12.0,       -- Positional falloff distance
    browser = {
        enabled = true,           -- false = curated stations only
        server = 'https://de1.api.radio-browser.info', -- Radio Browser API mirror
        cacheSeconds = 300,       -- Server-side cache TTL
        limit = 40,               -- Max stations per fetch
        categories = { 'rock', 'pop', 'jazz', 'electronic', 'classical', 'news' }, -- Browse tabs (Radio Browser tags)
    },
    stations = {                  -- Curated internet stations (always available)
        { name = 'SomaFM Groove Salad',   url = 'https://ice1.somafm.com/groovesalad-128-mp3', genre = 'Ambient / Chill', bitrate = 128 },
        { name = 'SomaFM Drone Zone',     url = 'https://ice1.somafm.com/dronezone-128-mp3',  genre = 'Ambient', bitrate = 128 },
        { name = 'SomaFM Space Station',  url = 'https://ice1.somafm.com/spacestation-128-mp3', genre = 'Electronic', bitrate = 128 },
        { name = 'SomaFM Lush',           url = 'https://ice1.somafm.com/lush-128-mp3',        genre = 'Vocals / Chill', bitrate = 128 },
        { name = 'SomaFM DEF CON',        url = 'https://ice1.somafm.com/defcon-128-mp3',      genre = 'Electronic', bitrate = 128 },
        { name = 'SomaFM Secret Agent',   url = 'https://ice1.somafm.com/secretagent-128-mp3', genre = 'Spy / Lounge', bitrate = 128 },
        { name = 'SomaFM Indie Pop Rocks',url = 'https://ice1.somafm.com/indiepop-128-mp3',     genre = 'Indie / Pop', bitrate = 128 },
        { name = 'SomaFM Underground 80s',url = 'https://ice1.somafm.com/u80s-128-mp3',        genre = '80s / Alternative', bitrate = 128 },
    },
}

Two Audio Sources (Mutually Exclusive)

FM Presets — GTA’s built-in radio stations (SetRadioToStationName, GetPlayerRadioStationName). No extra resources.
Internet Radio — Live streams via xsound server exports (same pipeline as Music app). Curated stations work offline; browser adds thousands via Radio Browser API.

Selecting an FM preset stops any internet stream; starting an internet stream silences FM and stops the Music app.

Radio Browser API

enabled = false → only curated stations show.
server — a single API mirror (DNS round-robin api.radio-browser.info is flaky from PerformHttpRequest).
cacheSeconds — server-side in-memory cache shared across all players.
categories — tags passed to bytagexact/<tag> endpoint. Add/remove tags to change the browse tabs.

Locales

Player-facing strings live in locales/*.json (flat keys, %s placeholders only). lib.locale() is called once in config.lua after @ox_lib/init.lua. Do not call it again.

{
  "menu_opened": "CarPlay opened",
  "must_be_driver": "You must be in the driver seat to use CarPlay",
  "music_add_failed": "Couldn't add — check the link",
  "vehicle_engine_on": "Engine On",
  "nav_set_waypoint": "Set Waypoint",
  "settings_layout": "Interface Style",
  ...
}

Add new languages by creating locales/<locale>.json (e.g., fr.json, de.json). ox_lib picks the player’s locale automatically.

Note: This guide is written by a third party. If you find any incorrect or outdated information, please contact us on Discord so we can update it for you.