Configuration

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

Config File Map

General Settings

File: shared/config.lua

Car Player Settings

File: shared/config/carplay.lua

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.

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.

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

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.

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

Shared map mode

File: shared/config.lua (first-start default only)

Config.MapMode picks how the maps on the Car Player Home and Map screens show the mainland and Cayo Perico. The map itself comes from o-link (1.8.0 or newer), which owns the artwork and calibration, so this setting only chooses a mode.

Config.MapMode = 'inherit'

Unlike the rest of this page, this one value is saved in the shared oxide_settings database table: shared/config.lua only seeds it on the first start, and the saved value wins after that. Change it live with oxide-carplayer:mapmode <value> from the server console, or /oxide-carplayer:mapmode <value> in game as an admin. Run it without a value to print the current mode to the server console.

inherit follows the server-wide default, which you set once for every Oxide resource with olink:mapmode <value> (combined, separate or disabled; o-link ships with combined). Open maps pick up a new mode without a restart.

Locale and Keybind Strings

File: locales/en.json

Notable locale groups:

Current keybind locale keys and the commands they label:

Next Steps