Custom Apps

Write your own resource, register an app, and it appears on the headset’s home screen. Opening it loads your page into a window. RoadVR is not modified in the process, so an update overwrites nothing of yours.

Working examples

Two complete, running app resources ship in examples/: roadvr_exampleapp, which reads the game through its own Lua, and roadvr_mediaapp — the Media app itself, which needs almost no Lua and does everything through the SDK instead.

Why a page and not a component

RoadVR’s interface is one compiled Vue bundle. Your resource cannot add a component to a build that shipped before your resource existed — so your app is loaded as a page in a frame instead. That is the better deal anyway. Inside the frame you use whatever you like, plain HTML or a framework, and a crash in your app cannot take the headset down with it.

The three exports

exports.roadvr:registerRoadVrApp({
    id     = 'myres_shop',          -- unique, prefix it with your resource name
    page   = 'ui/index.html',       -- a file in YOUR resource
    name   = 'Shop',                -- shown under the icon
    icon   = 'ui/icon.png',         -- a file in YOUR resource
    size   = { w = 1.1, h = 0.7 },  -- metres, not pixels
})

exports.roadvr:unregisterRoadVrApp('myres_shop')

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

registerRoadVrApp

string

required

Unique across the whole server. Prefix it with your resource name.

string

required

A file in your resource, e.g. ui/index.html. The full address — https://cfx-nui-<your-resource>/<file> — is built for you, so it cannot point somewhere else by accident. Put the file in your own files {} block.

string

Shown under the icon. Defaults to the id.

string | table

A file in your resource, e.g. ui/icon.png — or a pair of tones, see Two icons below.

table

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

Window size in metres. Not pixels — see Writing the page.

boolean

default:"false"

Keep it off the home screen and open it yourself with openRoadVrPanel(id).

boolean

false when the id already belongs to another resource — nobody gets to replace someone else’s window.

string

Why it failed, when it did.

Two icons, if you want the setting to work

icon may be a pair instead of one file:

icon = { dark = 'ui/icon-dark.svg', light = 'ui/icon-light.svg' },

Settings has an icon style — dark, light, or following the interface theme — and every built-in app ships both tones for it. One file name is fine and is what most apps want; it simply shows under either setting. A pair makes your icon follow the player’s choice the same way the rest of the home screen does. The recipe the built-in set uses: dark is a near-black tile with the glyph in the app’s own colour, light is a tile carrying that colour as a gradient with a white glyph.

Name both files in your files {} block. A file RoadVR asks for that is not listed is a missing icon and nothing that says so.

Give only one side of the pair and the other falls back to it, so half a pair is still an icon under both settings rather than a gap under one.

sendToRoadVrApp

boolean

false while the window is closed. That is normal, not an error — your resource has no idea whether the player has your app open.

Building the resource

Declare your files

fxmanifest.lua

fx_version 'cerulean'
game 'gta5'

-- No ui_page. The page is rendered by RoadVR inside a headset window, so
-- this resource never shows a NUI of its own — it only serves the files.
files {
    'ui/index.html',
    'ui/icon.png',
}

client_scripts { 'client.lua' }

dependencies { 'roadvr' }

client.lua

CreateThread(function()
    -- A moment for RoadVR to have built its own tables. The manifest
    -- dependency guarantees the order of starting, not of the first frame.
    Wait(500)

    local ok, err = exports.roadvr:registerRoadVrApp({
        id   = 'myres_shop',
        name = 'Shop',
        page = 'ui/index.html',
        icon = 'ui/icon.png',
        size = { w = 1.1, h = 0.7 },
    })

    if not ok then
        print(('^1[myres_shop]^7 registration failed: %s'):format(err or 'unknown'))
    end
end)

Start it

server.cfg

ensure myres_shop

Put the headset on and your icon is on the home screen.

Talking to your own Lua

Nothing is needed from RoadVR for this. FiveM routes https://<your-resource>/<callback> by resource name, no matter which page fires the request, so inside the frame a plain fetch reaches your own RegisterNUICallback:

const res = await fetch('https://myres_shop/getPlayerInfo', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json; charset=UTF-8' },
  body: JSON.stringify({}),
})

RegisterNUICallback('getPlayerInfo', function(_, cb)
    cb({ health = GetEntityHealth(PlayerPedId()) - 100 })
end)

The one direction you cannot do alone is inbound. Your own SendNUIMessage would go to your own frame, and that one is never rendered. Use sendToRoadVrApp instead.

Talking to RoadVR itself

Your own Lua tells you about your world. The SDK tells you about the headset: which theme is on, which language the player picked, how big your window is, whether it is focused — and, the one that matters most, that it is about to close.

<script src="https://cfx-nui-roadvr/public/sdk/roadvr.js"></script>

The path is relative to the RoadVR resource, so public/ belongs in it. There is nothing to add to your own files {} block — the file is served by RoadVR, so there is no copy in your resource that can go stale.

;(async function () {
  // Opened straight in a browser the cfx-nui- address does not resolve at all.
  if (!window.RoadVr) return

  const ctx = await RoadVr.ready()

  RoadVr.applyTheme()          // your page now uses RoadVR's colours

  RoadVr.on('theme', (t) => console.log(t.light ? 'light' : 'dark'))
  RoadVr.on('resize', ({ width, height }) => layout(width, height))
  RoadVr.on('close', () => save())
})()

Full SDK reference

Every field, every event, every function

The events, briefly

Event	When
`theme`	light/dark toggled, accent or icon set changed
`locale`	the player switched interface language
`world`	weather and clock tick — only after `watch('world')`
`placement`	how far your window stands away — only after `watch('placement')`
`focus` / `blur`	your window became, or stopped being, the focused one
`visible` / `hidden`	pause menu, map, cinema screen, fast head turn
`resize`	your window was dragged to a new size
`anchor`	your window switched between following the player and staying put
`action`	one of your ornament buttons was pressed
`close`	your window is going away
`message`	a push from your own Lua, i.e. `sendToRoadVrApp`

Every on() returns its counterpart:

const off = RoadVr.on('theme', paint)
off()

Two things worth knowing about

watch('placement') tells you how far your window is standing from the player’s head, in metres, four times a second and only while it changes. It is what the Media app turns its volume down with as somebody walks away.

RoadVr.watch('placement')
RoadVr.on('placement', ({ distance }) => fade(distance))

setActions() hangs up to three buttons in your window’s ornament, left of the close button — the place for a control that has to stay reachable while your page cannot offer one, over a video or a map.

RoadVr.setActions([
  { id: 'back', label: 'Back', icon: 'solar:alt-arrow-left-bold', onSelect: showList },
])

The SDK is optional. A page that only wants pushes from its own Lua can keep using a raw listener — everything RoadVR forwards carries source: 'roadvr':

window.addEventListener('message', (e) => {
  if (e.data?.source !== 'roadvr') return
  console.log(e.data.type, e.data.speed)
})

Writing the page

The window renders at a fixed 1280×800 CSS pixels whatever its size in metres. Sizes look oversized in a browser on purpose; that is the same scale every built-in app uses.

Keep the background transparent

RoadVR’s glass sits behind your page. A background colour on body shows up as a rectangle inside the rounded window.

html, body { background: transparent; }

Hide the cursor

The headset draws its own pointer, and the system cursor would appear next to it.

* { cursor: none; }

Do not scroll

Set overflow: hidden and make your page fit its window. A scrollbar down the side of a floating pane looks like a fault, and the wheel is taken anyway — it moves the window closer and further away.

html, body { overflow: hidden; height: 100%; margin: 0; }

Make sure nothing can be selected

RoadVR sets user-select: none on its own panels, but that rule stops at the frame boundary. Your page is its own document and starts from the default, which is selectable — so dragging across your window paints it blue while the headset draws its own pointer next to the smear.RoadVR cannot do this for you. Set it yourself:

html, body { user-select: none; -webkit-user-select: none; }

/* The one exception, and the same one RoadVR makes for itself: a field you
   type into is unusable without a caret and a selection. */
input, textarea { user-select: text; -webkit-user-select: text; }

Take RoadVR's colours

Point your own variables at RoadVR’s, with a fallback so the page still opens in a browser:

:root {
  --text: var(--vr-text, rgba(255, 255, 255, 0.96));
  --dim: var(--vr-text-dim, rgba(255, 255, 255, 0.55));
  --fill: var(--fill-idle, rgba(255, 255, 255, 0.13));
  --accent: var(--vr-accent, #0a84ff);
}

Then call RoadVr.applyTheme() once and the page follows the player switching theme, without knowing a single colour value.

Lifecycle

Register once at resource start. There is no need to unregister on stop — RoadVR notices your resource going away, removes the app and closes its window. Registration survives the headset being taken off and put back on. The list is kept on the Lua side and pushed to the interface again on every boot, so a resource that started long before anyone put a headset on still shows up.

Trying the examples

ensure roadvr_exampleapp

Put the headset on and the Example icon is on the home screen. It shows your street, health and armour on request, receives a speed reading pushed once a second, honks the horn of the vehicle you are in — and, in its second column, reports everything the headset tells it through the SDK.

ensure roadvr_mediaapp

The Media app, as an ordinary resource of its own. It is the other shape: almost no Lua at all — one registerRoadVrApp call and nothing else — with every runtime detail coming through the SDK instead. It is also the one to read for watch('placement') and setActions(), both of which it uses for real.

roadvr_mediaapp registers under the id media, which is the id the built-in Media app used. Starting it takes that place over rather than adding a second icon, so openRoadVrPanel('media') keeps working either way.

Home

RoadVR

RoadPhone Pro

RoadPhone

RoadPad

RoadCarRadio

RoadPods

RoadBackup

Custom Apps

Custom Apps

Working examples

Why a page and not a component

The three exports

registerRoadVrApp

Two icons, if you want the setting to work

sendToRoadVrApp

Building the resource

Talking to your own Lua

Talking to RoadVR itself

Full SDK reference

The events, briefly

Two things worth knowing about

Writing the page

Lifecycle

Trying the examples

​Custom Apps

Working examples

​Why a page and not a component

​The three exports

​registerRoadVrApp

​Two icons, if you want the setting to work

​sendToRoadVrApp

​Building the resource

​Talking to your own Lua

​Talking to RoadVR itself

Full SDK reference

​The events, briefly

​Two things worth knowing about

​Writing the page

​Lifecycle

​Trying the examples

Custom Apps

Why a page and not a component

The three exports

registerRoadVrApp

Two icons, if you want the setting to work

sendToRoadVrApp

Building the resource

Talking to your own Lua

Talking to RoadVR itself

The events, briefly

Two things worth knowing about

Writing the page

Lifecycle

Trying the examples