Client API

Every export below is client-side and lives in API.lua inside the resource. That file is in escrow_ignore, so you can read the source of anything on this page.

Headset

isRoadVrActive

Is the headset currently on?

boolean

true while the player is wearing it.

local active = exports.roadvr:isRoadVrActive()

getRoadVrState

The state machine, as a string.

string

One of off, booting, passthrough, focus, shutdown.passthrough is windows floating while the player moves normally. focus is the mode in which the mouse is free and the player can click.

if exports.roadvr:getRoadVrState() == 'focus' then
    -- the player is clicking something right now
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)

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.

number

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

string | nil

nil when the headset is off.

local panelId = exports.roadvr:openRoadVrPanel('media', {
    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 with a working example: Custom Apps.

registerRoadVrApp

table

required

Show Properties

string

required

Unique. Prefix it with your resource name.

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.

string

'body' or 'world'.

boolean

default:"false"

Keep it off the home screen and open it yourself.

boolean

false when the id already belongs to another resource.

string

Why it failed.

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

unregisterRoadVrApp

Not needed on resource stop — that is cleaned up on its own.

exports.roadvr:unregisterRoadVrApp('myres_shop')

sendToRoadVrApp

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

boolean

false while the window is closed — 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 with a working example: 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.

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.

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

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

Client API

Client API

Headset

isRoadVrActive

getRoadVrState

putVisorOn

takeVisorOff

Panels

openRoadVrPanel

closeRoadVrPanel

Custom apps

registerRoadVrApp

unregisterRoadVrApp

sendToRoadVrApp

Custom widgets

registerRoadVrWidget

unregisterRoadVrWidget

sendToRoadVrWidget

getRoadVrWidgetInstances

Talking to a page from inside the frame

JavaScript SDK

​Client API

​Headset

​isRoadVrActive

​getRoadVrState

​putVisorOn

​takeVisorOff

​Panels

​openRoadVrPanel

​closeRoadVrPanel

​Custom apps

​registerRoadVrApp

​unregisterRoadVrApp

​sendToRoadVrApp

​Custom widgets

​registerRoadVrWidget

​unregisterRoadVrWidget

​sendToRoadVrWidget

​getRoadVrWidgetInstances

​Talking to a page from inside the frame

JavaScript SDK

Client API

Headset

isRoadVrActive

getRoadVrState

putVisorOn

takeVisorOff

Panels

openRoadVrPanel

closeRoadVrPanel

Custom apps

registerRoadVrApp

unregisterRoadVrApp

sendToRoadVrApp

Custom widgets

registerRoadVrWidget

unregisterRoadVrWidget

sendToRoadVrWidget

getRoadVrWidgetInstances

Talking to a page from inside the frame