Configuration

Reference for the current oxide-carplay config and persisted settings layout.

Config File Map

File	Purpose
shared/config.lua	General settings
shared/config/carplay.lua	CarPlay, mini-player, Quick Nav, jailbreak
locales/en.json	Player-facing strings and keybind labels
server/main.lua	Saved settings and playlist persistence callbacks

General Settings

File: shared/config.lua

Setting	Type	Default	Description
Config.Debug	boolean	false	Enable debug logging with [oxide-carplay] prefix

CarPlay Settings

File: shared/config/carplay.lua

Setting	Type	Default	Description
Config.CarPlay.Enabled	boolean	true	Enable the main CarPlay system
Config.CarPlay.Keybind	string	'M'	Key used for the carplay command
Config.CarPlay.KeybindDescription	string	'keybind.carplay'	Locale key for the main keybind label
Config.CarPlay.DefaultVolume	number	50	Default playback volume
Config.CarPlay.MaxQueueSize	number	20	Maximum queue size
Config.CarPlay.AudioRange	number	12.0	Open-vehicle hearing range
Config.CarPlay.AudioRangeClosed	number	2.0	Closed-vehicle hearing range
Config.CarPlay.VolumeMultClosed	number	0.15	Volume multiplier for sealed vehicles
Config.CarPlay.SpeedRangeBonus	number	0.25	Extra hearing range added from vehicle speed
Config.CarPlay.PositionUpdateInterval	number	150	xsound position update interval in ms
Config.CarPlay.ProximityScanInterval	number	2000	Nearby playback scan interval in ms
Config.CarPlay.MaxPlaylists	number	10	Maximum saved playlists per character
Config.CarPlay.MaxPlaylistTracks	number	50	Maximum tracks per saved playlist
Config.CarPlay.MapUpdateInterval	number	500	Map data refresh interval in ms

Audio behavior

• AudioRange and AudioRangeClosed determine how far playback can be heard outside the vehicle.
• VolumeMultClosed controls how muffled the vehicle sounds when doors and windows are closed.
• SpeedRangeBonus increases effective range as vehicle speed rises.
• The resource handles attenuation itself and uses xsound mainly for 3D positioning and playback.

Mini-Player Settings

File: shared/config/carplay.lua

Config.CarPlay.MiniPlayer controls the floating player shown after closing the main UI while music is still playing.

Setting	Type	Default	Description
Enabled	boolean	true	Enable the floating mini-player
Position	string	'bottom-right'	Default mini-player position
PauseKey	string	'Y'	Pause/resume keybind default
NextKey	string	'U'	Next-track keybind default
RepeatKey	string	'I'	Repeat-mode keybind default

Allowed default positions:

• top-left
• top-right
• bottom-left
• bottom-right
• bottom-center

Quick Nav Locations

File: shared/config/carplay.lua

Config.CarPlay.QuickNav defines marker and waypoint groups used by the map screen.

Group	Default State	Description
gas	populated	Gas station locations
store	empty	Convenience store locations for your server
garage	populated	Garage locations

Behavior:

• the map screen renders these as markers
• Quick Nav buttons exist for gas, store, and garage
• pressing a Quick Nav button sets a waypoint to the nearest configured location in that category

Jailbreak Settings

File: shared/config/carplay.lua

Setting	Type	Default	Description
Config.Jailbreak.Enabled	boolean	true	Enable the jailbreak feature
Config.Jailbreak.RequiredItem	string	'carplayjb_usb'	Item required to start jailbreak
Config.Jailbreak.RemoveItem	boolean	true	Remove 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'	Circuit-trace difficulty
Config.Jailbreak.ProgressLabel	string	'config.progress_jailbreaking'	Locale key for progress bar label

Difficulty values

• easy
• medium
• hard

Jailbreak POIs

Config.Jailbreak.POIs defines the extra POI markers shown on the map after a successful jailbreak.

Important:

• these are revealed as map markers, not as a normal Quick Nav button category
• the default coordinates in the config are placeholder/example coordinates and should be replaced for production use
• jailbreak state is stored on the current vehicle's statebag, so each vehicle must be jailbroken separately

Persisted Player Settings

File: server/main.lua

The resource also stores per-character player preferences through KVP-backed callbacks. These are not server-owner config values.

Setting	Type	Default	Description
themeColor	string	'#1DB954'	UI accent color
miniPlayerEnabled	boolean	true	Whether the floating mini-player should show
miniPlayerPosition	string	'bottom-right'	Saved preferred mini-player position
albumArtSpin	boolean	true	Spin album art while a track is playing
defaultVolume	number	50	Preferred default volume when nothing is currently playing

Playlist Persistence

File: server/main.lua

Playlists are stored per character under resource KVP keys in the form:

carplay:char:{characterId}

Limits enforced by the current code:

• max playlists per character: Config.CarPlay.MaxPlaylists
• max saved tracks per playlist: Config.CarPlay.MaxPlaylistTracks
• playlist names are sanitized and trimmed before saving

Locale and Keybind Strings

File: locales/en.json

Notable locale groups:

Prefix	Description
nui.*	Main UI labels, weather labels, nav labels, settings labels, jailbreak text
config.*	Configurable progress-bar label
keybind.*	Main CarPlay and mini-player keybind labels

Current keybind locale keys:

• keybind.carplay
• keybind.carplay_mp_pause
• keybind.carplay_mp_next
• keybind.carplay_mp_repeat

Next Steps

• INSTALLATION.md
• FEATURES.md
• TROUBLESHOOTING.md