Oxide Studios

Step-by-step setup for oxide-carplay.

Prerequisites

Required resources

Resource	Purpose
`ox_lib`	Locale, callbacks, animation helpers
`o-link`	Character lookup, item registration, inventory, progress bar, notifications, weather/time
`xsound`	Vehicle-based 3D audio playback

`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

No database required

oxide-carplay uses FiveM KVP storage. No SQL import is required.

Current KVP usage:

saved playlists per character
saved CarPlay settings per character

Installation Steps

1. Place the resource

Place oxide-carplay inside your server's resources folder.

2. Add startup order

Start dependencies before the resource:

ensure ox_lib
ensure o-link
ensure xsound
ensure oxide-carplay

3. Review configuration

Configuration is split across:

shared/config.lua
shared/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 = 500

See CONFIGURATION.md for the full reference, including mini-player and jailbreak settings.

4. 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 = false

5. Add the item to your inventory resource if needed

Examples:

ox_inventory - add to data/items.lua

['carplayjb_usb'] = {
    label = 'Suspicious USB',
    weight = 100,
    stack = false,
    description = 'A USB drive with custom firmware. Looks like it could modify vehicle systems.',
},

qb-inventory - 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-carplay/carplayjb_usb.png if your inventory UI uses item icons.

Verification

Start the server and confirm ox_lib, o-link, xsound, and oxide-carplay load without dependency errors.
Join the server, enter any vehicle seat, and press M to open CarPlay.
Paste a standard YouTube URL and verify metadata loads and audio plays.
Close the UI while music is playing and verify the mini-player appears if enabled.
Have a second player enter the same vehicle and verify passenger playback syncs.
Open the Map screen and verify tiles load, position updates, and Quick Nav sets a waypoint.
If jailbreak is enabled, use the configured USB item in a vehicle and verify the progress bar, minigame, and success notification work.

Notes for UI developers

The packaged web/dist build is already included and referenced by the manifest. Rebuilding the UI is only necessary if you edit files under web/src.

Next Steps

FEATURES.md
CONFIGURATION.md
TROUBLESHOOTING.md

Installation