Configuration

Config File Map

File	Settings	Purpose
shared/config.lua	Debug	Core settings and Config init
shared/config/carplay.lua	CarPlay, Jailbreak, QuickNav	Music player, audio, playlists, navigation, jailbreak

Core Settings

File: shared/config.lua

Basic resource configuration.

Setting	Type	Default	Description
Config.Debug	boolean	false	Enable debug console output

Config.Debug = false

CarPlay Settings

File: shared/config/carplay.lua

Configure the music player, audio system, and playlist limits.

Setting	Type	Default	Description
Config.CarPlay.Enabled	boolean	true	Enable or disable the CarPlay system
Config.CarPlay.Keybind	string	'M'	Key to open CarPlay (vehicle only)
Config.CarPlay.KeybindDescription	string	'keybind.carplay'	Locale key for keybind label
Config.CarPlay.DefaultVolume	number	50	Starting volume (0-100)
Config.CarPlay.MaxQueueSize	number	20	Maximum tracks in the queue
Config.CarPlay.AudioRange	number	12.0	Hearing distance in meters (open vehicle)
Config.CarPlay.AudioRangeClosed	number	2.0	Hearing distance in meters (closed vehicle)
Config.CarPlay.VolumeMultClosed	number	0.15	Volume multiplier when windows/doors closed
Config.CarPlay.SpeedRangeBonus	number	0.25	Extra audio range per unit of vehicle speed
Config.CarPlay.PositionUpdateInterval	number	150	3D audio position tracking interval in ms
Config.CarPlay.ProximityScanInterval	number	2000	Nearby vehicle music discovery interval in ms
Config.CarPlay.MaxPlaylists	number	10	Maximum saved playlists per character
Config.CarPlay.MaxPlaylistTracks	number	50	Maximum tracks per playlist
Config.CarPlay.MapUpdateInterval	number	500	Navigation map position refresh interval in ms

Config.CarPlay = {
    Enabled = true,
    Keybind = 'M',
    KeybindDescription = 'keybind.carplay',
    DefaultVolume = 50,
    MaxQueueSize = 20,
    AudioRange = 12.0,
    AudioRangeClosed = 2.0,
    VolumeMultClosed = 0.15,
    SpeedRangeBonus = 0.25,
    PositionUpdateInterval = 150,
    ProximityScanInterval = 2000,
    MaxPlaylists = 10,
    MaxPlaylistTracks = 50,
    MapUpdateInterval = 500,
}

Audio Tuning

Open vehicle range: When doors or windows are open, music is audible up to AudioRange meters away. At highway speeds, the effective range increases by SpeedRangeBonus per speed unit.

Closed vehicle muffling: When all doors and windows are closed, the hearing range shrinks to AudioRangeClosed and volume is scaled by VolumeMultClosed (15% of normal by default). This simulates muffled bass heard from inside a closed car.

Position tracking: The PositionUpdateInterval controls how often xsound positions update to follow the vehicle. Lower values give smoother audio tracking but use more CPU. 150ms is a good balance.

Quick Nav Locations

File: shared/config/carplay.lua

Configure the GPS waypoint locations for each Quick Nav category. Each entry is a vector3 coordinate. When a player taps a Quick Nav button, the system finds the closest location and sets it as their GPS waypoint.

Gas Stations

27 gas station locations are included by default, covering all of San Andreas.

Config.CarPlay.QuickNav = {
    gas = {
        vector3(49.4187, 2778.793, 58.043),
        vector3(263.894, 2606.463, 44.983),
        -- ... 25 more locations
    },
}

Stores

Empty by default. Add vector3 coordinates for convenience store locations:

Config.CarPlay.QuickNav.store = {
    vector3(25.7, -1347.3, 29.5),
    -- Add your store locations here
},

Garages

5 garage locations included by default:

Config.CarPlay.QuickNav.garage = {
    vector3(211.51, -934.81, 24.28),
    vector3(926.77, -2.92, 77.76),
    vector3(-324.70, -776.75, 32.96),
    vector3(274.29, -334.15, 44.92),
    vector3(-773.12, -2033.04, 8.88),
},

Add or remove locations to match your server's garage positions.

Jailbreak Settings

File: shared/config/carplay.lua

Configure the jailbreak system that unlocks hidden POI locations on the navigation map.

Setting	Type	Default	Description
Config.Jailbreak.RequiredItem	string	'carplayjb_usb'	Inventory item required to jailbreak
Config.Jailbreak.RemoveItem	boolean	true	Consume the item on successful jailbreak
Config.Jailbreak.Duration	number	8000	Progress bar duration in ms
Config.Jailbreak.AnimDict	string	'anim@amb@clubhouse@tutorial@bkr_tut_ig3@'	Animation dictionary
Config.Jailbreak.AnimName	string	'machinic_loop_mechandplayer'	Animation name
Config.Jailbreak.AnimFlags	number	16	Animation flags
Config.Jailbreak.Difficulty	string	'medium'	Minigame difficulty (easy, medium, hard)
Config.Jailbreak.ProgressLabel	string	'config.progress_jailbreaking'	Locale key for progress bar text

Config.Jailbreak = {
    RequiredItem = 'carplayjb_usb',
    RemoveItem = true,
    Duration = 8000,
    AnimDict = 'anim@amb@clubhouse@tutorial@bkr_tut_ig3@',
    AnimName = 'machinic_loop_mechandplayer',
    AnimFlags = 16,
    Difficulty = 'medium',
    ProgressLabel = 'config.progress_jailbreaking',
}

Difficulty Levels

Level	Description
easy	Fewer wires, simpler paths, more time
medium	Moderate wire count and complexity
hard	More wires, complex paths, less time

POI Locations

Hidden locations revealed on the map after a successful jailbreak. Add, remove, or modify vector3 coordinates:

Config.Jailbreak.POIs = {
    vector3(712.67, -962.49, 30.41),       -- Vinewood area
    vector3(-1054.71, -1587.40, 4.68),     -- LSIA warehouse
    vector3(1391.77, 3604.72, 38.94),      -- Sandy Shores
    vector3(2434.09, 4968.39, 46.81),      -- Grapeseed
    vector3(-56.49, 6341.61, 31.38),       -- Paleto Bay
    vector3(1087.02, -3195.87, -38.99),    -- Underground bunker
    vector3(-1170.65, -1571.40, 4.66),     -- Airport hangar
    vector3(486.18, -3339.85, 6.07),       -- Port of LS dock
}

Locale Strings

File: locales/en.json

All player-facing strings are driven by locale files using ox_lib's i18n system. Override or translate any string by editing locales/en.json or adding a new locale file (e.g., locales/es.json).

Key Categories

Prefix	Count	Description
nui.*	55	UI labels, buttons, status text
nui.weather_*	12	Weather type display names
nui.nav_*	4	Quick Nav category labels
keybind.*	1	Keybind display name
config.*	1	Progress bar label

Notable Keys

Key	Default Value	Description
nui.url_placeholder	'Paste YouTube URL or playlist...'	Input field placeholder text
nui.mini_player_idle	'Nothing playing'	Idle state mini player text
config.progress_jailbreaking	'Installing custom firmware...'	Jailbreak progress bar label
nui.jailbreak_success	'CarPlay jailbroken'	Success notification
nui.jailbreak_fail	'Jailbreak failed'	Failure notification