VR Realms
Discord Play free

Scripting API

Lua scripting Beta

Everything the VR Realms nodes can do, you can also type. Drop a VR Realms Script actor into your level, write Lua in it, and it runs when the world starts. Blueprints keep working exactly as before: Lua is a second way, for people who would rather write code than wire nodes.

Beta. The VR Realms Script actor is in the Creator Kit now: update your kit and search for it in Place Actors. Lua is still new, so tell us on Discord what breaks or what you miss. Lua scripts do not run on the standalone headsets (Steam Frame, Meta Quest) yet; on PC, in VR and on desktop, they do.

Your first scriptThe script windowHost or every machineText on a widgetLua in two minutesFrom Blueprints to LuaTestingBuild a gameWhen something goes wrongEvery node in LuaEventsTimers, objects, zonesExamplesWhat a script cannot do

Your first script

  1. In the Place Actors panel, search VR Realms Script and drag it anywhere into your level.
  2. In its Details, click Open Script Editor and type:
vrr.on_player_join(function(player)
  player:say("Hi " .. player.name .. ", welcome to my world!")
end)
  1. Save with Ctrl+S and play your world. A mistake shows as Script error: ... on the host's screen while Show Errors To Host is ticked.

Things in your level are found by their actor tag: select a mesh, then in Details under Actor, Tags, add BigGate. In the script, world.find("BigGate") gives it to you.

You can mix Lua and Blueprints. A script can run your Blueprints' custom events (obj:tell_everyone("MyEvent")) and fire the same channels as VRSend / VRWhen tags. Use several Script actors for several jobs: each one runs on its own.

The script window

Open Script Editor opens a big window of its own, which you can resize, maximize or move to a second screen.

  • Colours: keywords, text, numbers, comments, the vrr and world commands and function calls each have their own colour.
  • An error check while you type. The bottom line says No syntax errors or, for example, Line 5: '=' expected near 'x'. Go to the error jumps to that line.
  • Commands and starter scripts on the right: every command on this page and every example, with a search box. Hover one to see what it does, click it to add ready-to-run code where your cursor is.
  • Save (Ctrl+S) puts the text into the actor as one undo step. Playing saves for you, and closing with unsaved text asks first.
  • Suggestions while you type. After vrr., world., player. or x: a list shows the commands that fit; three letters of a name (annou) are enough, and picking one writes the whole call. Inside the brackets a hint shows how to call it. Up and Down to choose, Tab or Enter to take, Esc to close.
  • Line numbers, Ctrl+F to find (Enter or F3 for the next one, Shift for the one before) and Ctrl+G to go to a line.
  • Tab and Shift+Tab move every selected line four spaces in or out. The bottom right shows the line and column and how much of the 65,536 characters you have used.
  • Open in your own editor: VS Code, Notepad++, Visual Studio, the Windows default or a program you choose. A save there comes straight back into the window and the actor. In VS Code, the free Lua extension then suggests every VR Realms command too.

Host or every machine

The Run On setting is the Lua version of the (Local) and (Server) labels on the nodes.

Run OnMeaningUse it for
Host only (default)One copy, on the host. Its (Server) commands change the world for everyone.Game rules: points, teams, rounds, gates, races, chat commands.
Every player's machineA copy on each machine. vrr.me() is the person at that machine.What one person sees or does: a lantern in your hand, fades, input, saved text, vibration.
The same trap as in Blueprints. In an Every player's machine script, vrr.me() is a different person on every machine, so never use it to decide who the monster chases. (Server) commands only do something in the host's copy: vrr.is_host_copy() tells you which one you are in.

Showing text on a widget

A script does not make widgets itself. Your Blueprint holds the widget, and the script tells it what to show.

  1. Make a Widget Blueprint with a Text block. Tick Is Variable on the Text block and name it, for example Message.
  2. Make an actor Blueprint and add a Widget Component. Set its Widget Class to your widget and its Space to World (that is the one that reads well in a headset). Give the actor a tag, for example VisitsPanel, and place it in your level.
  3. In that actor's Event Graph, add a custom event ShowText with two inputs: Text (String) and Number (Float). From it: Widget (the component) → Get User Widget Object → Cast To your widget → Message → Set Text, with the string through To Text.
  4. In the script, find it by its tag and pick how far the call goes:
LuaWhere the event runsUse it for
panel:call("ShowText", text, number)This machine only. Nothing goes over the network.What one person should see, from an Every player's machine script: their visits, their best time.
panel:tell_everyone("ShowText", text, number)Every machine, through the host.What everyone sees, from a Host only script: a round timer, a scoreboard.
panel:tell_host("ShowText", text, number)The host only.Game rules that live in a Blueprint.
local panel = world.find("VisitsPanel")
panel:call("ShowText", "Hello, " .. vrr.me().name .. "!", 0)

The event may have any of the inputs Sender, Text and Number; they are matched by name, and the rest are left out. Only custom events of your own Blueprints can be run this way, never engine functions. The whole visits example is under Examples.

Lua in two minutes

local score = 0                      -- a variable (local = only in this script)
score = score + 1
local name = "Ana"
local text = "Hello " .. name        -- .. joins text
if score > 10 then                   -- if / elseif / else / end
  vrr.announce(text)
end
for i = 1, 3 do vrr.log(i) end       -- counts 1, 2, 3
local list = { "red", "blue" }       -- a list starts at 1
for i, team in ipairs(list) do vrr.log(i, team) end
local function double(x) return x * 2 end
player:say("hi")                     -- a colon calls a player's or object's command
vrr.after(5, function() vrr.announce("5 seconds later") end)   -- functions can be passed around

Plain Lua is all there: math (math.random, math.floor), string (text:sub, string.format), table (table.insert), utf8 and pcall.

From Blueprints to Lua

If you know Blueprints, you already know how a script thinks. The same ideas, side by side:

BlueprintLua
Event BeginPlayThe top of the script: it runs once when the world starts.
A variable (Integer, Float, String, Boolean)local score = 0, local name = "Ana", local open = false
Set a variablescore = score + 1
Custom event or functionlocal function give(player, n) player:add_points(n) end
Branchif score > 10 then ... else ... end
==, !=, AND, OR, NOT==, ~=, and, or, not
For Loopfor i = 1, 10 do ... end
For Each Loopfor i, item in ipairs(list) do ... end
While Loopwhile ... do ... end (keep loops short: one that never ends is stopped)
Array: Make, Add, Length, Getlocal list = { "red", "blue" }, table.insert(list, "green"), #list, list[1] (lists start at 1)
Maplocal best = {}, then best[player.id] = 12.5
Is Validif obj then ... end
Delayvrr.after(2, function() ... end)
Set Timer by Event (looping), Clear Timerlocal id = vrr.every(1, function() ... end), vrr.cancel(id)
Print Stringvrr.log("text") or print("text")
Append, Format Text"Hi " .. name, string.format("%.2f s", seconds)
Random Integer in Rangemath.random(1, 6)
Get All Actors With Tagworld.find_all("Coin") (world.find("Coin") for the first one)
Set Actor Hidden In Gameobj:hide(), obj:show()
Set Actor Locationobj:move_to(x, y, z)
On Component Begin Overlapobj:on_enter(function(player) ... end)
Realm Events: On Player Arrivedvrr.on_player_join(function(player) ... end)
Call a custom event on another Blueprintobj:call("Event") (this machine), obj:tell_everyone("Event") (all)

Testing

  • In the Creator Kit's Play, objects, timers, zones and vrr.log work, and errors show in the Output Log (Window, Output Log) as yellow LogVRRScript lines.
  • Commands about players (messages, points, joins, seats, animations, hands, input) need the game around them: Build, then Play Map in the Workshop panel runs your world in VR Realms itself.
  • Scripts do not run on the standalone headsets yet, so a world's Steam Frame and Quest copy plays without its scripts. Keep anything the world cannot work without in Blueprints for now, or tell headset players in the description.
  • vrr.log("...") and print(...) are the quickest way to see what a script is doing.

Build a game: collect the coins

A whole game from an empty level: coins lie around, walking into one takes it, the first to more than half of them wins, and a new round starts by itself.

  1. Make a coin. A Blueprint actor with a mesh (a flattened cylinder is fine) and a Sphere Collision a bit bigger than the mesh. On the sphere, tick Generate Overlap Events. On the actor, tick Replicates, so a hidden coin is hidden for everyone.
  2. Tag it. In the actor's Details, under Actor, Tags, add Coin.
  3. Place ten of them around your level (Alt + drag copies one).
  4. Add the script. Drop in a VR Realms Script actor, keep Run On on Host only (the host keeps the score for everyone), open the script window and click A complete game: collect the coins in the Starter scripts, or paste it:
local coins = world.find_all("Coin")
if #coins == 0 then
  vrr.log("No actors tagged Coin in this level")
  return
end
local to_win = math.floor(#coins / 2) + 1   -- more than half of them
local playing = false

local function new_round()
  for _, coin in ipairs(coins) do coin:show() end
  for _, p in ipairs(vrr.players()) do p:set_points(0) end
  playing = true
  vrr.announce("New round: collect " .. to_win .. " coins!", 4)
end

for _, coin in ipairs(coins) do
  coin:on_enter(function(player)
    if not playing then return end
    coin:hide()                        -- hidden also means no collision, so it counts once
    local total = player:add_points(1)
    player:say("Coins: " .. total .. " / " .. to_win, 2)
    if total >= to_win then
      playing = false
      vrr.announce(player.name .. " wins the coin hunt!", 6)
      vrr.after(10, new_round)
    end
  end)
end

vrr.on_player_join(function(player)
  player:say("Collect " .. to_win .. " coins to win!", 5)
end)

new_round()
  1. Test it. In the kit's Play you can already see the coins and errors in the Output Log, but players, points and messages need the game: use Play Map in the panel, which runs your built map in the real game (see Build a Map).

How it works: world.find_all("Coin") gives every coin once at the start. Each coin gets an on_enter zone, which hears the player who walked in. Hiding a coin also turns off its collision, so the same coin cannot count twice. Points are the world's own scoreboard, which every player already sees. vrr.after(10, new_round) waits ten seconds and then shows every coin again and sets the points back to zero.

Ideas to take it further: a sound or a sparkle when a coin is taken (coin:tell_everyone("Taken") to a custom event on the coin Blueprint), a time limit with vrr.every(1, ...), or coins that move to a new spot instead of hiding (coin:move_to(x, y, z)).

When something goes wrong

Errors show on the host's screen in the game (the first five, while Show Errors To Host is ticked) and always in the log. In the kit, open Window, Output Log: script errors are yellow LogVRRScript lines and your own vrr.log lines start with [Script. Type Script into the log's search box to see only those.

You seeWhat it meansWhat to do
attempt to index a nil value (local 'gate')You used something that is not there. Most often world.find found no actor with that tag.Check the tag in the actor's Details (tags are case-sensitive). Players and things a player is holding are never found. Guard it: if gate then ... end.
attempt to call a nil value (method 'sya')A command with that name does not exist: usually a typo.Check the spelling against this page, or click the command in the script window's list.
'end' expected (to close 'function' at line 3) near <eof>A function, if, for or while has no end.The script window shows the line while you type. Every block needs its own end.
call: 'BP_Panel_C_0' has no custom event called 'ShowText'The Blueprint has no custom event with exactly that name.Use a Custom Event node (not a function) and the same spelling in both places.
call: 'X' lives outside the Workshop folderThe event belongs to a Blueprint that is not part of your item, such as one of the engine's.Only custom events of your own Blueprints can be called.
the script was stopped: it ran too long without stoppingA loop that never ends, or more than about 2 million steps in one frame.Give every while a way out. Spread big jobs over time with vrr.every. A stopped script stays stopped until the world starts again.
the script was stopped: it took too long in one frameThe same, measured in time (a quarter of a second).The same fixes. Very long texts make every step slower.
the script was stopped: it used too much memoryThe script held more than 16 MB.Do not keep everything forever: set tables you no longer need to nil, and keep texts short.
this text pattern takes too longA text pattern with many .- or * over a long text.Make the pattern simpler, or search a shorter piece of text.
too many timers at once (at most 64)Timers that are never cancelled pile up.Keep the id from vrr.every and vrr.cancel(id) it when you are done.
__gc is not allowed in VR Realms scriptsA metatable with a __gc field.Clean up yourself instead, for example when a round ends.

Nothing happens and there is no error?

  • In the kit: commands about players (messages, points, joins, seats, animations) do nothing there. Use Play Map.
  • Only the host sees it: tick Replicates on the object you hide or move. set_text changes the text on the machine running the script only.
  • A zone never fires: its collision needs Generate Overlap Events, and it must be big enough for a body to walk into.
  • Commands stop working for a moment: you hit a rate limit (see below). Commands give back false when you send too many too fast.
  • Run On: a Host only script runs once, on the host. For something each player sees on their own machine (vrr.me(), input, saved text), use Every player's machine.

Every node in Lua

All the nodes of the VR Realms category, grouped as on the Nodes page. player is a player you got from an event or from vrr.players(); obj is something from world.find. Parts in [square brackets] can be left out.

Player

LuaNodeRunsNote
vrr.me()Get Local PlayerAny machineThe player at this machine. nil on a dedicated server. Use it in Every player's machine scripts.
player:hand_position("left" | "right")Get Player HandAny machineWhere the hand is ({x, y, z}). Desktop players have hands too: where the game holds them, not tracked, and not sent to other machines. To hold something, use obj:attach_to.
player:head_position()Get Player HeadAny machineWhere the head is.
player:in_vr()Is Player In VRAny machine
player:on_desktop()Is Player On DesktopAny machine
player.nameGet Player NameAny machineA field, kept up to date.
player:is_me()Is My PlayerAny machine
player:is_host()Is HostAny machine
player:position()Get Player LocationAny machine{x, y, z} in centimetres.
player:rotation()Get Player RotationAny machine{pitch, yaw, roll}; yaw only matters.
player:eye_height()Get Player Eye HeightAny machine
player:velocity()Get Player VelocityAny machine{x, y, z}, cm per second.
player:on_ground()Is Player GroundedAny machine
obj:on_enter(function(player) ... end)Which PlayerAny machineZones already tell you which player walked in.
obj:on_enter / obj:on_leaveIs Player BodyAny machineZones count each player once, by the body.
player:is_talking()Is Player TalkingAny machine
player:loudness()Get Player LoudnessAny machine0 to 1.
player:avatar_id()Get Player Avatar IdAny machineThe Workshop id, as text (it is bigger than Lua numbers like).
player:sit(obj [, part])Seat PlayerHostpart = a component name or component tag on obj; the object's root if left out.
player:stand_up([obj, part])Unseat PlayerHostWhere they step out.
player:move_to(x, y, z [, yaw])Move Player ToHost
player:send_to_spawn()Send Player To SpawnHost
player:say(text [, seconds])Show Message To PlayerHostSame as vrr.say(player, text).
player:is_here()Lua onlyAny machine, reaches the hostFalse once they left: check before using a player you kept.

Animation

LuaNodeRunsNote
player:play_animation("/Game/...", [rate, blend])Play Animation On PlayerHostPath of an animation in your world (right-click it, Copy Reference, keep the part in quotes).
player:stop_animation([blend])Stop Player AnimationHost
player:is_animating()Is Player AnimatingAny machine
player:play_upper_body("/Game/...", [rate, blend, loops])Play Upper Body Animation On PlayerAny machineArms only, they can keep walking.
player:stop_upper_body([blend])Stop Upper Body Animation On PlayerAny machine

Points and labels

LuaNodeRunsNote
player:add_points(n)Add Player PointsHostGives back the new total. The world's own scoreboard, not gold.
player:set_points(n)Set Player PointsHost
player:points()Get Player PointsAny machine
player:label(key, value)Set Player LabelHostAny text per player: a team, a role. An empty value removes it.
player:get_label(key)Get Player LabelAny machine
player:clear_labels()Clear Player LabelsHost

The realm

LuaNodeRunsNote
vrr.players()Get Players In RealmAny machineA list; vrr.player_count() for how many.
vrr.host()Get HostAny machine
vrr.announce(text [, seconds])Show Message To EveryoneHost
vrr.chat(text)Post Chat LineHost
vrr.fire_channel(name)Fire ChannelHostThe same channels VRSend / VRWhen tags use.
obj:tell_host(event [, text, number])Tell HostAny machine, reaches the hostRuns a custom event on a Blueprint of yours, on the host.
obj:tell_everyone(event [, text, number])Tell EveryoneAny machine, reaches the hostThe same, on every machine.
world.find_link(link)Find Item By LinkAny machineAn item placed with a Link name.
screen:play(url)Play On ScreenAny machine, reaches the hosthttp(s) links only.
screen:stop()Stop ScreenAny machine, reaches the host
screen:pause([true | false])Pause ScreenAny machine, reaches the host
screen:is_playing()Is Screen PlayingAny machine
vrr.fade_out()Fade Screen To BlackAny machineThis machine only.
vrr.fade_in()Fade Screen InAny machine
vrr.language()Get My LanguageAny machine"en", "de", ...

Input

LuaNodeRunsNote
player:is_held(action)Is Action HeldAny machineActions: Fire, FireLeft, Grab, GrabLeft, Jump, Crouch, Sprint, Interact, Menu, Aim, ButtonB, ButtonY, StickLeft, StickRight.
player:axis("Move" | "Look")Get Input AxisAny machine{x, y}, each -1 to 1.
player:amount(action)Get Action AmountAny machineHow far a trigger is pulled.
player:held_seconds(action)Get Action Held SecondsAny machine
player:action_label(action)Get Action LabelAny machineWhat the button is called on their device.
player:start_controlling([movement_only])Start ControllingAny machine, reaches the hostTheir input drives your thing; Menu gives it back.
player:stop_controlling()Stop ControllingAny machine, reaches the host
player:is_controlling()Is ControllingAny machine, reaches the host
player:vibrate([hand, strength, seconds])Vibrate ControllerAny machine, reaches the host

Dares and saved text

LuaNodeRunsNote
player:complete_dare(id)Complete DareAny machine
vrr.save(slot, text)Save TextAny machineKept on this player's PC, per world.
vrr.load(slot)Load Saved TextAny machine"" when nothing was saved.

Events

The Realm Events and Realm Input Events components, as functions you hand over. Add as many as you like; each one runs.

LuaBlueprint eventNote
vrr.on_player_join(function(player) end)On Player Arrived
vrr.on_player_leave(function(player) end)On Player Departedplayer.name still works.
vrr.on_points_changed(function(player, total) end)On Points Changed
vrr.on_chat(function(player, text) end)On Chat Message
vrr.on_channel(function(name) end)On Channel
vrr.on_match_won(function(winner) end)On Match WonThe built-in game modes.
vrr.on_match_reset(function() end)On Match Reset
vrr.on_action(function(player, action, pressed) end)On Player ActionThis machine's player only.
vrr.on_animation_finished(function(player, path) end)On Player Animation Finished
vrr.on_gesture(function(player, action, kind) end)On Player Action Tap / Hold / Double Tapkind = "tap", "hold" or "double".
vrr.on_controlling(function(player, on) end)On Player Controlling Changed
vrr.on_control_action(function(player, action, pressed) end)On Control ActionHost only.

Timers, objects, zones

LuaWhat it does
vrr.after(seconds, fn)Run fn once, later. Gives back an id.
vrr.every(seconds, fn)Run fn again and again. vrr.cancel(id) stops it. At most 64 timers.
vrr.time()Seconds since the world started.
vrr.log(...) / print(...)Writes to the log (the Output Log while you test).
vrr.is_host_copy()True in the host's copy of an Every player's machine script.
world.find(tag)The first object with that actor tag, or nil.
world.find_all(tag)Every object with that tag (up to 500).
obj:show() / obj:hide()Hidden also means no collision. Tick Replicates on the object so everyone sees it.
obj:move_to(x, y, z)Teleports it. Replicates + Replicate Movement for everyone to see.
obj:turn_to(pitch, yaw, roll)
obj:position(){x, y, z}
obj:set_text(text)The object's Text Render component, on the machine that runs the script only (a Text Render is not networked). For everyone, use an Every player's machine script, or a Blueprint event with tell_everyone.
obj:on_enter(fn) / obj:on_leave(fn)A zone: give the object a collision box with Generate Overlap Events on. fn gets the player. At most 64 zones.
obj:attach_to(player, "left" | "right" | "head")Snaps it onto a hand or the head (a desktop player's hands are where the game holds them; others do not see them). obj:detach() lets go.
obj:call(event [, text, number])Runs one of your Blueprint's custom events on THIS machine only: nothing goes over the network. For a widget, a sound or an effect one player should see. Inputs by name, like Tell Host: Sender (this machine's player), Text, Number.

Examples

Each of these runs as it is. Copy one into a Script actor (or click it in the script window's list) and tag your level's objects as it says.

Say hello to everyone who arrives

Run On: Host only. The smallest useful script. It greets each player by name and tells the first one they are alone for now.

vrr.on_player_join(function(player)
  player:say("Welcome, " .. player.name .. "!")
  if vrr.player_count() == 1 then
    player:say("You're the first one here. Invite a friend!", 6)
  end
end)

vrr.on_player_leave(function(player)
  vrr.announce(player.name .. " left the world")
end)

A gate only the red team can open

Run On: Host only. Tag a box with overlap events on as RedButton, and a gate mesh (Replicates ticked) as BigGate. A player label is how you mark teams.

local gate   = world.find("BigGate")
local button = world.find("RedButton")

-- put everyone who joins on a team, taking turns
local next_team = "red"
vrr.on_player_join(function(player)
  player:label("team", next_team)
  player:say("You are on the " .. next_team .. " team")
  if next_team == "red" then next_team = "blue" else next_team = "red" end
end)

button:on_enter(function(player)
  if player:get_label("team") == "red" then
    gate:hide()
    player:say("The gate is open for 10 seconds")
    vrr.after(10, function() gate:show() end)
  else
    player:say("Only the red team can open this gate")
  end
end)

A race with a timer and a best time

Run On: Host only. Two zones tagged StartLine and FinishLine. The best time is kept for as long as the world is open, and the winner gets a scoreboard point.

local start, finish = world.find("StartLine"), world.find("FinishLine")
local started = {}
local best, best_name = nil, nil

start:on_enter(function(player)
  started[player.id] = vrr.time()
  player:say("Go!", 2)
end)

finish:on_enter(function(player)
  local t0 = started[player.id]
  if not t0 then return end          -- they skipped the start line
  started[player.id] = nil

  local seconds = vrr.time() - t0
  local text = string.format("%.2f", seconds)
  if not best or seconds < best then
    best, best_name = seconds, player.name
    vrr.announce("New record: " .. player.name .. " in " .. text .. " s!")
    player:add_points(1)
  else
    player:say("Your time: " .. text .. " s (record " .. string.format("%.2f", best) .. " by " .. best_name .. ")")
  end
end)

King of the hill

Run On: Host only. A zone tagged Hill. Every second, each player standing on it gets a point. The first to 30 wins and the round starts over.

local hill = world.find("Hill")
local on_hill = {}

hill:on_enter(function(player) on_hill[player.id] = player end)
hill:on_leave(function(player) on_hill[player.id] = nil end)

vrr.every(1, function()
  for id, player in pairs(on_hill) do
    if player:is_here() then
      if player:add_points(1) >= 30 then
        vrr.announce(player.name .. " is the king of the hill!", 6)
        for _, p in ipairs(vrr.players()) do p:set_points(0) end
        vrr.fire_channel("HillWon")       -- let a Blueprint play fireworks
      end
    else
      on_hill[id] = nil
    end
  end
end)

Chat commands: !roll and !time

Run On: Host only. Reacts to public chat. Lua's math.random works as usual.

vrr.on_chat(function(player, text)
  if text == "!roll" then
    vrr.chat(player.name .. " rolled a " .. math.random(1, 6))
  elseif text == "!time" then
    vrr.chat("This world has been open for " .. math.floor(vrr.time() / 60) .. " minutes")
  elseif text:sub(1, 5) == "!say " then
    vrr.announce(player.name .. ": " .. text:sub(6))
  end
end)

A countdown round that talks to your Blueprints

Run On: Host only. A Blueprint tagged RoundBoard has a Text Render and custom events RoundStarted and RoundOver. The script keeps time, the Blueprint does the show.

local board = world.find("RoundBoard")
local seconds_left = 0
local ticker

local function start_round()
  seconds_left = 60
  board:tell_everyone("RoundStarted", "", 60)
  ticker = vrr.every(1, function()
    seconds_left = seconds_left - 1
    board:set_text(tostring(seconds_left))
    if seconds_left <= 0 then
      vrr.cancel(ticker)
      board:tell_everyone("RoundOver")
      vrr.announce("Round over! Next one in 15 seconds")
      vrr.after(15, start_round)
    end
  end)
end

vrr.after(5, start_round)

A lantern in your hand

Run On: Every player's machine. Runs on every machine and uses vrr.me(): each machine puts the lantern (tagged Lantern) in its own player's left hand, so everyone sees it in their own hand. Desktop players have no hands, so it goes to the head.

local me = vrr.me()
if me then
  local lanterns = world.find_all("Lantern")
  local mine = lanterns[1]
  if mine then
    if me:in_vr() then
      mine:attach_to(me, "left")
    else
      mine:attach_to(me, "head")
    end
    me:say("Your lantern is lit")
  end
end

A cinema that starts when you sit down

Run On: Host only. A screen item placed with the link Cinema, a chair Blueprint tagged Chair with a scene component named Seat, and a zone tagged ChairZone.

local screen = world.find_link("Cinema")
local chair  = world.find("Chair")
local zone   = world.find("ChairZone")

zone:on_enter(function(player)
  player:sit(chair, "Seat")
  if not screen:is_playing() then
    screen:play("https://www.youtube.com/watch?v=aqz-KE-bpKQ")
  end
end)

vrr.on_player_leave(function()
  if vrr.player_count() == 0 then screen:stop() end
end)

Hold to charge, let go to jump

Run On: Every player's machine. Input is known on the player's own machine. The longer you hold Interact, the stronger the buzz; a double tap of Jump plays a wave. Animations come from your world's own content by path.

vrr.on_gesture(function(player, action, kind)
  if not player:is_me() then return end
  if action == "Jump" and kind == "double" then
    player:play_upper_body("/Game/MyWorld/Anims/Wave.Wave")
  end
end)

vrr.every(0.25, function()
  local me = vrr.me()
  if me and me:is_held("Interact") then
    local power = math.min(1, me:held_seconds("Interact") / 3)
    me:vibrate("right", power, 0.25)
  end
end)

A complete game: collect the coins

Run On: Host only. Every coin is an actor tagged Coin, with a collision box (Generate Overlap Events on) and Replicates ticked. Walk into a coin to take it; the first to more than half of them wins, and a new round starts 10 seconds later. The whole build is in "Build a game: collect the coins" above.

local coins = world.find_all("Coin")
if #coins == 0 then
  vrr.log("No actors tagged Coin in this level")
  return
end
local to_win = math.floor(#coins / 2) + 1   -- more than half of them
local playing = false

local function new_round()
  for _, coin in ipairs(coins) do coin:show() end
  for _, p in ipairs(vrr.players()) do p:set_points(0) end
  playing = true
  vrr.announce("New round: collect " .. to_win .. " coins!", 4)
end

for _, coin in ipairs(coins) do
  coin:on_enter(function(player)
    if not playing then return end
    coin:hide()                        -- hidden also means no collision, so it counts once
    local total = player:add_points(1)
    player:say("Coins: " .. total .. " / " .. to_win, 2)
    if total >= to_win then
      playing = false
      vrr.announce(player.name .. " wins the coin hunt!", 6)
      vrr.after(10, new_round)
    end
  end)
end

vrr.on_player_join(function(player)
  player:say("Collect " .. to_win .. " coins to win!", 5)
end)

new_round()

Show each player their own visits on a widget

Run On: Every player's machine. A Blueprint tagged VisitsPanel has a Widget Component and a custom event ShowText with inputs Text (String) and Number (Float) that puts the text on the widget (see "Showing text on a widget" above). The script runs on every machine and obj:call stays on that machine, so each person sees their own count.

local visits = tonumber(vrr.load("visits")) or 0
visits = visits + 1
vrr.save("visits", tostring(visits))

local panel = world.find("VisitsPanel")
if panel then
  if visits == 1 then
    panel:call("ShowText", "First time here? Have a look around!", visits)
  else
    panel:call("ShowText", "Welcome back! Visit number " .. visits, visits)
  end
end

Remember a player between visits

Run On: Every player's machine. Saved text lives on the player's own PC, per world. Here it counts visits.

local visits = tonumber(vrr.load("visits")) or 0
visits = visits + 1
vrr.save("visits", tostring(visits))

local me = vrr.me()
if me then
  if visits == 1 then
    me:say("First time here? Have a look around!")
  else
    me:say("Welcome back! Visit number " .. visits)
  end
end

What a script cannot do

  • No files, no web, no other programs, no console commands, and no calling engine functions by name. A script only has plain Lua and the commands on this page.
  • A script that runs too long without coming back (about 2 million steps, or a quarter of a second, in one frame, all its events and timers together) or holds more than 16 MB of memory is stopped for good with an error, instead of freezing everyone's game. pcall cannot catch that stop.
  • Text patterns (string.find, match, gmatch, gsub) have a work limit too: a pattern that would take very long gives an error instead.
  • Not available: __gc in metatables, string.dump, and the collector's controls (collectgarbage("count") still works).
  • Messages and chat lines: at most 10 at once, one more each second. Commands that reach other players (points, labels, moving things, Blueprint events, animations and so on): 60 at once, 20 more each second. Screens: a new link every two seconds. Saved text: 10 at once, one more each second. Timers and zones: 64 each. One script: 65,536 characters.
  • Players cannot be moved, hidden or found as objects, only through their own commands.
  • Precompiled Lua is refused: scripts are always plain text, so anyone can read what a world does.

← Nodes · Scenarios →

Found a bug with the docs? Click here to report it →Report a docs bug →