Features

Overview of the current oxide-carplay gameplay flow and systems.

Access and UI Flow

Players can open CarPlay with the carplay command or the configured keybind while inside a vehicle.

Current screens:

• Home
• Music
• Map
• Settings

If music is still playing when the main UI closes, the floating mini-player can remain visible when enabled.

Music Playback

Supported input

The main playback flow expects standard YouTube video URLs such as:

• https://www.youtube.com/watch?v=...
• https://youtu.be/...

The server validates that URL metadata requests only target YouTube domains before calling external providers.

Metadata providers

Provider	Usage
noembed.com	Single-video title and thumbnail lookup
pipedapi.kavin.rocks	Playlist import lookup
inv.nadeko.net	Playlist import fallback

Playback controls

Players can:

• play a pasted URL
• pause and resume
• change volume
• skip to next track
• toggle repeat mode

Repeat modes:

• off
• repeat
• once

Queue and Playlists

Queue behavior

• queue size is capped by Config.CarPlay.MaxQueueSize
• tracks can be added, removed, or played directly from queue
• when nothing is playing, imported or loaded queue content can auto-start playback
• queue state is synchronized through the vehicle statebag

Playlists

Playlists are stored per character using resource KVP storage.

Players can:

• save a playlist
• overwrite an existing playlist
• load a playlist into queue
• append playlist tracks to queue
• delete a playlist

Limits:

• playlists per character: Config.CarPlay.MaxPlaylists
• tracks saved in a playlist: Config.CarPlay.MaxPlaylistTracks

Playlist imports

YouTube playlist imports:

• extract the list= ID from the pasted URL
• fetch up to 50 playlist entries from external providers
• still stop at the local queue cap if the queue fills first

3D Audio and Passenger Sync

Playback is handled through xsound and tied to the active vehicle.

Audio behavior

• sound position updates follow the vehicle
• outside listeners hear distance-based falloff
• sealed vehicles use AudioRangeClosed and VolumeMultClosed
• more open vehicles project sound further and louder
• speed adds extra effective range through SpeedRangeBonus

Sync model

Vehicle playback state is stored in the oxide:carplay statebag and includes current track data, queue, volume, repeat mode, and jailbreak flag.

This allows:

• passengers in the same vehicle to stay synchronized
• nearby clients to detect playing vehicles
• proximity-based recovery when local audio falls out of sync

Playback ownership

• playback is tied to the active vehicle rather than the open UI
• leaving the vehicle or moving too far away clears local playback state
• mini-player visibility is local and does not affect the shared statebag

Map and Navigation

The Map screen uses packaged tile images and live client updates.

Displayed data:

• player position
• player heading marker
• street and cross-street
• zone name
• current weather from olink.weather.GetWeather()
• current time from olink.weather.GetTime()

Quick Nav

Quick Nav buttons exist for:

• gas
• store
• garage

Each button sets a waypoint to the nearest configured location in that category.

POI markers

The map also renders markers for configured location groups and, when the vehicle has been jailbroken, the configured jailbreak POIs.

Jailbreak POIs:

• appear as map markers
• do not use a dedicated Quick Nav button
• are visible only for a jailbroken vehicle state

Jailbreak System

The jailbreak system is optional and can be disabled entirely.

Flow

1. The player uses the configured jailbreak item while seated in a vehicle.
2. o-link registers the item as usable and starts the flow.
3. A progress bar opens with movement, vehicle, and combat disabled.
4. On success, the circuit-trace NUI minigame starts.
5. If the minigame is completed, the resource marks the current vehicle as jailbroken.
6. If configured, the USB item is removed on successful completion.

Scope

• jailbreak is per vehicle entity, not global
• a vehicle already marked jailbroken cannot be jailbroken again
• successful jailbreak reveals the configured POI markers on that vehicle's map state

Settings and Mini-Player

The Settings screen stores per-character UI preferences through resource callbacks.

Current saved preferences:

• accent/theme color
• mini-player enabled state
• mini-player position
• default volume
• album art spin

Mini-player

When enabled, the floating mini-player appears after closing the main UI while playback continues.

Dedicated keybinds:

• pause/resume
• next track
• toggle repeat mode

These defaults come from Config.CarPlay.MiniPlayer, but players can also save their preferred mini-player position and enabled state.

Persistence Model

Current persistence boundaries:

• playlists: per character
• saved settings: per character
• jailbreak state: per vehicle statebag
• current playback state: per active vehicle statebag

Next Steps

• INSTALLATION.md
• CONFIGURATION.md
• TROUBLESHOOTING.md