Installation
Step-by-step instructions for installing and configuring oxide-carplayer
Step-by-step setup for oxide-carplayer.
Prerequisites
Required resources
| Resource | Purpose |
|---|---|
oxmysql | Saves the map mode setting in the shared oxide_settings table |
ox_lib | Locale, callbacks, animation helpers |
o-link 1.8.0 or newer | Character lookup, item registration, inventory, progress bar, notifications, weather/time, and the shared map |
xsound | Vehicle-based 3D audio playback |
Car Player needs o-link 1.8.0 or newer. Older versions do not include the shared map files this resource loads.
o-link expectations
This resource depends on your server's o-link setup for:
- character identifiers used for KVP persistence
- usable item registration for the jailbreak USB
- inventory item checks and removal
- progress bar display during jailbreak
- player notifications
- weather and time data used on the map screen
- the shared map shown on the Home and Map screens, with mainland and Cayo Perico artwork, and the server-wide map mode default (see Shared map mode)
oxide-carplayer uses FiveM KVP storage for player data. No SQL import is required. Current KVP usage: saved playlists per character and saved Car Player settings per character. The only database value is the resource's map mode, stored in the shared oxide_settings table, which is created automatically on first start.
Installation
Place the resource
Place oxide-carplayer inside your server's resources folder.
Add startup order
Start dependencies before the resource:
ensure oxmysql
ensure ox_lib
ensure o-link
ensure xsound
ensure oxide-carplayerReview configuration
Configuration is split across:
shared/config.luashared/config/carplay.lua
Review shared/config/carplay.lua first. Key server-owner settings include:
Config.CarPlay.Enabled = true
Config.CarPlay.Keybind = 'M'
Config.CarPlay.DefaultVolume = 50
Config.CarPlay.AudioRange = 12.0
Config.CarPlay.MaxQueueSize = 20
Config.CarPlay.MaxPlaylists = 10
Config.CarPlay.MaxPlaylistTracks = 50
Config.CarPlay.MapUpdateInterval = 500See Configuration for the full reference, including mini-player and jailbreak settings.
Register the jailbreak item if you want that feature
The jailbreak flow requires the item named by Config.Jailbreak.RequiredItem to exist in the inventory system your o-link setup uses.
Default item name:
Config.Jailbreak.RequiredItem = 'carplayjb_usb'If you do not want the jailbreak feature, you can disable it:
Config.Jailbreak.Enabled = falseAdd the item to your inventory resource if needed
The entry is ready to paste in itemimages/ox_inventory_items.lua in the resource folder. Copy the ['carplayjb_usb'] entry into data/items.lua, above that file's final closing brace. If your file already has an item with the same name, keep only one copy.
['carplayjb_usb'] = { label = 'Suspicious USB', weight = 100, stack = false, close = true, description = 'A USB drive with custom firmware. Looks like it could modify vehicle systems.' },Add to shared/items.lua:
carplayjb_usb = {
name = 'carplayjb_usb',
label = 'Suspicious USB',
weight = 100,
type = 'item',
image = 'carplayjb_usb.png',
unique = true,
useable = true,
shouldClose = true,
description = 'A USB drive with custom firmware.',
},An item image is included at oxide-carplayer/itemimages/carplayjb_usb.png if your inventory UI uses item icons (for ox_inventory, copy it into ox_inventory/web/images/).
Verification
oxmysql, ox_lib, o-link, xsound, and oxide-carplayer load without dependency errors.M (or run /carplayer) to open Car Player.Interface files
The interface comes prebuilt in web/dist. There is nothing to build or install for it.
Updating from 1.x
Version 2.0.0 changes a few things server owners and players will notice:
- The open command is now
/carplayer. - The mini-player keybind commands are now
carplayer_mp_pause,carplayer_mp_nextandcarplayer_mp_repeat. - Because the commands were renamed, each player's custom Car Player keybinds reset to the defaults once. Players can set them again in FiveM's key binding settings.
- The map now comes from
o-link's shared map, with Cayo Perico support. Updateo-linkto 1.8.0 or newer before you start the new version.
o-link to 1.8.0 or newer.ensure line.oxide-carplayer folder and make sure ensure oxide-carplayer comes after oxmysql, ox_lib, o-link and xsound.Playlists and settings saved under the old folder name do not carry over, because FiveM stores them per resource name. Players will need to save their playlists and settings again.