Client API

Every export below is client-side. Apart from the three headset exports, they live in API.lua inside the resource. That file is in escrow_ignore, so you can read the source of everything from Panels down. The one server-side export, registerRoadVrGame, is documented in the Game SDK.

Headset

isRoadVrActive

Is RoadVR running for this player?

boolean

true whenever the state is anything but off — including while the headset is still booting or already shutting down. Test getRoadVrState() for 'passthrough' if you need to know the player can act right now.

local active = exports.roadvr:isRoadVrActive()

getRoadVrState

The state machine, as a string.

string

off, booting, passthrough, focus or shutdown — and a few more that hold the cursor while a feature runs: widgets (the widget editor), beat, minigolf, shooter and game. More may be added.passthrough is windows floating while the player moves normally. focus is the mode in which the mouse is free and the player can click.

-- Test for the one state you need rather than listing the others: the next
-- state RoadVR adds would otherwise be a bug in your code.
if exports.roadvr:getRoadVrState() == 'passthrough' then
    -- the player can move and act normally
end

putVisorOn

Puts the visor on another ped’s head.

number

required

The ped handle to fit the visor to.

table | nil

A handle you keep for takeVisorOff. nil when nothing was possible on that ped.

local handle = exports.roadvr:putVisorOn(somePed)
if not handle then return end

This exists for scene work — actors who should be wearing the headset without the calling resource having to know anything about head bones, offsets or addon clothing. It does not start a session for that ped.

takeVisorOff

table

required

The handle putVisorOn returned.

exports.roadvr:takeVisorOff(handle)

Notifications

showRoadVrNotification

Shows a notification card in the headset — the same card RoadVR’s own messages use, collected in the Control Centre.

table

required

Show Properties

string

Up to 160 bytes.

string

Up to 4000 bytes. description is accepted as another name for it.

number

Milliseconds, held between 1000 and 30000.

boolean

true when the headset took the notification. false when nobody is wearing one, the headset is still booting or shutting down, or there is no text — show your normal notification then.

local handled = exports.roadvr:showRoadVrNotification({
    title = 'Garage',
    message = 'Your car has been repaired.',
    duration = 6000,
})

if not handled then
    -- your usual notification
end

Text is plain. GTA colour codes such as ~r~ and HTML tags are removed; ~n~ and <br> become line breaks. Over-long text is cut at the limit.

Panels

openRoadVrPanel

Opens a window for a registered app.

string

required

A registered app id — one of RoadVR’s own, or one you registered yourself.

table

Show Properties

string

'body' follows the player, 'world' stays put. Omit it and the player’s own setting decides — which is usually what you want.

table

default:"{ w = 1.2, h = 0.75 }"

Window size in metres. The size an app was registered with is not used here — only the home screen applies it — so pass it again.

number

How far in front of the player it opens, in metres.

string | nil

nil when the headset is off. If the same app is already open, that window is closed and the new one gets a new id. At Config.MaxPanels the oldest window is closed to make room.

local panelId = exports.roadvr:openRoadVrPanel('myres_shop', {
    anchor   = 'world',
    size     = { w = 1.6, h = 0.9 },
    distance = 2.5,
})

closeRoadVrPanel

string

required

The id openRoadVrPanel returned.

exports.roadvr:closeRoadVrPanel(panelId)

Custom apps

Full guide: Custom Apps.

registerRoadVrApp

table

required

Show Properties

string

required

Unique. Prefix it with your resource name, and never reuse the id of a built-in app — shooter, reminders and darts are refused outright.

string

required

A file in your resource, e.g. 'ui/index.html'.

string

default:"the id"

Shown under the icon.

string | table

A file in your resource, e.g. 'ui/icon.png' — or a pair, { dark = 'ui/icon-dark.svg', light = 'ui/icon-light.svg' }, to follow the player’s icon style the way the built-in apps do. Name every file you pass in your own files {} block.

table

default:"{ w = 1.2, h = 0.75 }"

Metres. Applied when the app is opened from the home screen.

boolean

default:"false"

Keep it off the home screen and open it yourself.

boolean

false when the id already belongs to another resource or is refused. Registering again from your own resource replaces your earlier definition.

string

'definition is not a table', 'missing id', 'missing page', 'reserved built-in id' or 'id "<id>" already belongs to <resource>'.

local ok, err = exports.roadvr:registerRoadVrApp({
    id   = 'myres_shop',
    page = 'ui/index.html',
    name = 'Shop',
})

unregisterRoadVrApp

Removes the app and closes its window if it is open. Not needed on resource stop — that is cleaned up on its own.

boolean

false when the id is not yours.

exports.roadvr:unregisterRoadVrApp('myres_shop')

sendToRoadVrApp

Sends data into your app’s window. It arrives as a message event carrying { source: 'roadvr', ...payload }.

boolean

true when the id is yours, false when it is not. A message to a closed window is dropped quietly — normal, not an error. Your resource has no idea whether the player has your app open.

exports.roadvr:sendToRoadVrApp('myres_shop', { type = 'tick', speed = 42 })

Custom widgets

Full guide: Custom Widgets.

registerRoadVrWidget

table

required

Show Properties

string

required

Unique. Prefix it with your resource name.

string

required

A file in your resource, e.g. 'ui/widget.html'.

string

default:"the id"

Shown under the tile in the widget bar.

string

A file in your resource.

number

default:"0.34"

Metres of width. The height follows from aspect.

number

default:"0.2"

Smallest width the wheel allows, in metres.

number

default:"0.8"

Largest width the wheel allows, in metres.

number

default:"1.0"

Width divided by height.

string

default:"recess"

'recess' sinks it into the wall, 'raised' stands it off.

string

default:"rounded"

'round' or 'rounded'. Recess only.

boolean

false when the id already belongs to another resource.

string

Why it failed, when it did.

local ok, err = exports.roadvr:registerRoadVrWidget({
    id   = 'myres_gauge',
    page = 'ui/widget.html',
    name = 'Gauge',
})

unregisterRoadVrWidget

Widgets already hanging are left on the wall. They are in the player’s profile, and a resource going away is not a reason to clear somebody’s room — they fall back to an unavailable plate until it returns.

boolean

false when the kind is not yours.

exports.roadvr:unregisterRoadVrWidget('myres_gauge')

sendToRoadVrWidget

Reaches every widget of this kind that is currently drawn. Arrives as { source: 'roadvr', widget: '<id>', ...payload }.

boolean

false when the kind is not yours.

exports.roadvr:sendToRoadVrWidget('myres_gauge', { rpm = 3400 })

getRoadVrWidgetInstances

Which widgets of your kind are on a wall right now.

table

A list of instance ids. An empty table is a normal answer — the player may simply not have hung one.

local ids = exports.roadvr:getRoadVrWidgetInstances('myres_gauge')

-- Check before you start sending. Nothing hanging means nothing to send to,
-- and that check is the difference between a widget that costs nothing when
-- unused and one that does not.
if #ids == 0 then return end

World markers

Full guide: Custom Markers. Markers do not survive a RoadVR restart — add them again in onClientResourceStart for roadvr.

addRoadVrMarker

table

required

Show Properties

string

required

'label', 'arrow', 'outline' or 'path'. Fixed once created.

vector3

A fixed point in the world. pos or entity, never both.

number

An existing entity the marker follows. Required for 'outline'.

table

'path' only: at least two vector3.

string

'label' needs one, 'arrow' may have one. Your text, localised by you.

string

default:"the player's accent"

'#rrggbb'.

boolean

default:"false"

false hides it behind geometry the way a window is hidden.

number

Metres, capped by Config.Markers.cullDistance.

string | nil

The marker’s handle, or nil with a reason as the second value.

local id, err = exports.roadvr:addRoadVrMarker({
    kind = 'label',
    pos = vector3(215.8, -810.1, 30.7),
    text = 'Meeting point',
})

updateRoadVrMarker

Patches any field except kind. A patch follows the same rules as a definition and fails with the same kind of reason.

boolean

false for an unknown handle — normal after a RoadVR restart — or a patch that breaks a rule, with the reason as the second value.

exports.roadvr:updateRoadVrMarker(id, { text = 'Meeting point — 2 min' })

removeRoadVrMarker

boolean

false for an unknown handle, quietly.

exports.roadvr:removeRoadVrMarker(id)

clearRoadVrMarkers

Removes all markers of your resource. Not needed on resource stop.

number

How many were removed.

exports.roadvr:clearRoadVrMarkers()

Talking to a page from inside the frame

Everything above is Lua. The other half — a page asking RoadVR about the theme, its window, or the fact that it is closing — is the JavaScript SDK.

JavaScript SDK

ready(), the context object, the events, applyTheme(), watch(), setActions() and close()

API documentation

RoadVR

RoadPhone Pro

RoadPhone

RoadPad

RoadCarRadio

Road Minigolf

RoadPark

Client API

Client API

Headset

isRoadVrActive

getRoadVrState

putVisorOn

takeVisorOff

Notifications

showRoadVrNotification

Panels

openRoadVrPanel

closeRoadVrPanel

Custom apps

registerRoadVrApp

unregisterRoadVrApp

sendToRoadVrApp

Custom widgets

registerRoadVrWidget

unregisterRoadVrWidget

sendToRoadVrWidget

getRoadVrWidgetInstances

World markers

addRoadVrMarker

updateRoadVrMarker

removeRoadVrMarker

clearRoadVrMarkers

Talking to a page from inside the frame

JavaScript SDK

​Client API

​Headset

​isRoadVrActive

​getRoadVrState

​putVisorOn

​takeVisorOff

​Notifications

​showRoadVrNotification

​Panels

​openRoadVrPanel

​closeRoadVrPanel

​Custom apps

​registerRoadVrApp

​unregisterRoadVrApp

​sendToRoadVrApp

​Custom widgets

​registerRoadVrWidget

​unregisterRoadVrWidget

​sendToRoadVrWidget

​getRoadVrWidgetInstances

​World markers

​addRoadVrMarker

​updateRoadVrMarker

​removeRoadVrMarker

​clearRoadVrMarkers

​Talking to a page from inside the frame

JavaScript SDK

Client API

Headset

isRoadVrActive

getRoadVrState

putVisorOn

takeVisorOff

Notifications

showRoadVrNotification

Panels

openRoadVrPanel

closeRoadVrPanel

Custom apps

registerRoadVrApp

unregisterRoadVrApp

sendToRoadVrApp

Custom widgets

registerRoadVrWidget

unregisterRoadVrWidget

sendToRoadVrWidget

getRoadVrWidgetInstances

World markers

addRoadVrMarker

updateRoadVrMarker

removeRoadVrMarker

clearRoadVrMarkers

Talking to a page from inside the frame