Custom Markers

Call four exports and a label, arrow, outline or path appears in the world for the player wearing the headset. There is nothing to register up front — a marker exists from the moment you add it.

Working example

examples/roadvr_examplemarkers is a complete, runnable resource. /track annotates the nearest vehicle with all four kinds at once, and every line of it is commented.

What a marker is

An annotation on the world, not a window. It has no buttons, no page and no frame — a marker is a shape and, for some kinds, a line of your own text, placed at a point, on an entity, or along a line of points.

Only the player in whose client you call the export sees it. RoadVR holds no state across players and sends nothing to anyone else.If a mechanic job should show its marker to every mechanic on duty, that fan-out is your resource’s decision, made in your own server-to-client call. RoadVR places a marker; it does not distribute one.

The four kinds

kind	needs	text	notes
`label`	`pos` or `entity`	required	Floating text, always facing the player
`arrow`	`pos` or `entity`	optional, shown as a caption	Stands above its point and aims down at it, like a waypoint — never away from the player
`outline`	`entity`	—	A box around the entity, sized and rotated to it automatically
`path`	`points`, at least two `vector3`	—	A line through the points

outline needs nothing but entity. RoadVR reads the model’s dimensions once and turns the box with the entity’s heading every frame — you never pass a size.

Your first marker

Two calls and a vehicle has an outline with a label beside it. This assumes veh is a vehicle handle you already hold:

client.lua

local outline, err = exports.roadvr:addRoadVrMarker({
    kind   = 'outline',
    entity = veh,
})

if not outline then
    print(('outline failed: %s'):format(err))   -- the reason says what is missing
    return
end

local label = exports.roadvr:addRoadVrMarker({
    kind   = 'label',
    entity = veh,
    text   = 'Engine: worn serpentine belt',
})

-- later, when the job is done
exports.roadvr:removeRoadVrMarker(outline)
exports.roadvr:removeRoadVrMarker(label)

Both hang on the entity, so RoadVR moves them with the vehicle and drops them by itself when it despawns.

A marker on an entity cleans itself up. A marker on coordinates does not — nothing but your resource will ever remove it. That difference is the one thing worth keeping in mind while you write the tick that maintains them.

The four exports

--- @return string|nil id, string? error
local id, err = exports.roadvr:addRoadVrMarker({
    kind         = 'label',      -- 'label' | 'arrow' | 'outline' | 'path'
    pos          = vec3(0,0,0),  -- a fixed point in the world
    entity       = veh,          -- or an entity it follows. Never both.
    points       = { a, b },     -- 'path' only, at least two vector3
    text         = 'Hello',      -- 'label' needs one, 'arrow' may have one
    color        = '#ff9f0a',    -- default is the player's accent colour
    throughWalls = false,        -- behaves like a window
    fadeDistance = 60.0,         -- metres, capped by Config.Markers.cullDistance
})

--- Every field of addRoadVrMarker except kind, which is fixed at creation.
--- @return boolean ok, string? error
local ok, err = exports.roadvr:updateRoadVrMarker(id, { text = 'Fixed' })

--- @return boolean
exports.roadvr:removeRoadVrMarker(id)

--- All of your own. Not needed on resource stop — that is cleaned up for you.
--- @return number how many were removed
local removed = exports.roadvr:clearRoadVrMarkers()

Fields worth calling out

string

required

Cannot be patched. Everything else can — including entity, which re-targets an outline and measures the new model, and throughWalls, which can be flipped after the marker already exists.

vector3 / number

A marker has one place, not two. Patching pos onto a marker that follows an entity detaches it; patching entity onto a fixed one takes its pos away. An outline lives on its entity and refuses a pos outright.

string

Your text, localised by you. RoadVR adds no words of its own to a marker.

number

Metres. Leave it out — or ask for more than Config.Markers.cullDistance allows — and you get that ceiling instead. The marker stays fully opaque until 80% of its fade distance, then fades to nothing at it.

removeRoadVrMarker and updateRoadVrMarker return false quietly on a handle RoadVR does not know. That is deliberate: cleanup after a RoadVR restart calls these on handles that are already gone, and that should not fill the console with warnings.

When RoadVR restarts

Markers are not persisted and do not survive a RoadVR restart — ensure roadvr from the console, a crash, a script update. This is the one pitfall everyone hits once: your resource kept running, the vehicle is still there, but the outline and label are simply gone, because RoadVR’s marker registry started over from empty.

client.lua

-- Add them again from whatever state you already keep. RoadVR does not
-- remember your handles either, so there is nothing to reconcile — just add.
AddEventHandler('onClientResourceStart', function(resource)
    if resource ~= 'roadvr' then return end
    restoreMyMarkers()
end)

The limits

boolean

default:"true"

false switches the whole export surface off — addRoadVrMarker then returns nil for everyone, not just for you.

number

default:"32"

A per-resource ceiling. Go over it and the request is refused, rather than the oldest marker quietly making room.

number

default:"120.0"

Metres. The server owner’s ceiling on fadeDistance, and also where a marker stops being drawn at all regardless of what any resource asked for.

If nothing appears

Is a headset actually on?

A marker draws for the wearer only. Nobody wearing one is nobody seeing one.

Is Config.Markers.enabled still true?

Check the server’s config.lua — it is a server-owner switch.

Read the second return value

A bad definition returns nil, reason, and the reason string says which:

a missing entity on an outline
no text on a label
fewer than two points on a path
an unknown kind
pos and entity passed together
an entity that does not exist — a 0 from GetVehiclePedIsIn on a ped who is on foot is the usual one
a pos that is not a vector3
the resource already holding Config.Markers.maxPerResource markers

Custom Apps

A window on the home screen

Custom Widgets

Your page on a wall

Custom Games

A multiplayer session with a lobby

Client API

Every Lua export in one place

Home

RoadVR

RoadPhone Pro

RoadPhone

RoadPad

RoadCarRadio

RoadPods

RoadBackup

Custom Markers

Custom Markers

Working example

What a marker is

The four kinds

Your first marker

The four exports

Fields worth calling out

When RoadVR restarts

The limits

If nothing appears

Custom Apps

Custom Widgets

Custom Games

Client API

​Custom Markers

Working example

​What a marker is

​The four kinds

​Your first marker

​The four exports

​Fields worth calling out

​When RoadVR restarts

​The limits

​If nothing appears

​Related

Custom Apps

Custom Widgets

Custom Games

Client API

Custom Markers

What a marker is

The four kinds

Your first marker

The four exports

Fields worth calling out

When RoadVR restarts

The limits

If nothing appears

Related