Luau on LibreMetaverse

The client surface hooked into the grid, and how we drive bots & the viewer with Luau.

How it works

A bot is a LibreMetaverse grid client with an embedded Luau VM behind a C ABI shim. One worker thread owns the VM; grid events marshal onto it. Scripts touch the grid only through one global table, client.

The viewer (Alchemy) embeds the same VM and implements the same client contract over its C++ managers. A Luau script that targets this document runs verbatim on either host — the binding code differs, the surface does not.

Bots and the viewer are both WebSocket clients of one hub. Each registers under an id (a bot registers under its SL username; the viewer registers too), and the hub relays control requests to any of them — so many bots and viewers are drivable at once, including over MCP tooling.

Conventions

Completion — callback or await. Pass a trailing fn(ok, err) and it fires once when the reply (or failure) correlates back; or omit it and call from inside a coroutine: local ok, err = client.self.sit(uuid) yields the coroutine and returns (ok, err) when the reply arrives. bot.eval runs your source on the coroutine path, so a top-level await suspends the eval and resumes on the reply — the worker stays free during the wait. ok=false carries an error string ("timeout", or a server alert). Never blocking: the reply is delivered onto the same worker thread, so a busy-wait would deadlock.

UUIDs cross the boundary as lowercase strings. Vectors are {x,y,z}; quaternions {x,y,z,w}. Two universal channels backstop everything: client.on_message(type, fn) / client.send_message(type, table) (raw classic-UDP), and client.on_alert(fn) (the server's generic notice text).

Running Luau in a bot

The hub exposes MCP tools (and the same calls over its WebSocket) to reach any registered bot or viewer:

-- via bot_eval
return client.self.info().name        -- "inworldhelp Resident"
client.chat("hello from luau", 0)
for _, f in client.friends.list() do print(f.name) end

Services

A service is a .luau module in the bot's include directory that returns {name?, start, stop}. The hub holds, per bot, which services run at startup (persisted, survives restarts) and starts them once the bot signals it is ready (post-login). start() should be light — set up timers / event handlers, not act — and stop() must clear every interval and reset handlers.

local M = { name = "heartbeat" }
local timer
function M.start()
  timer = client.set_interval(30, function()
    print("[heartbeat] as " .. client.self.info().name)
  end)
end
function M.stop()
  if timer then client.clear_interval(timer); timer = nil end
end
return M

Enable it for a bot with bot_service {id, action="enable", name="heartbeat"}. It then starts on every (re)connect until disabled.

client — network, chat, IM

client.self — movement & actions

client — timers

client — raw escape hatch

The universal backstop: subscribe to and send any classic-UDP PacketType by name. A reflection marshaller decodes a packet into {_type, <BlockName> = {fields} | {block[]}} and builds one from the same shape. Anything without a typed binding is reachable here.

client.friends

friend = {uuid, name, online, rights{can_see_me_online, can_see_me_on_map, can_modify_my_objects, can_see_them_online, can_see_them_on_map, can_modify_their_objects}}

client.avatars

client.directory — search

client.grid — region lookup

client.objects

prim = {local_id, id, owner_id, group_id, parent_id, flags, text, name, description, position, scale, rotation}

client.inventory

node = {uuid, name, parent_uuid, owner_id, kind} where kind is "item" or "folder"; items also carry {asset_uuid, asset_type, inventory_type}.

client.parcels

parcel = {local_id, name, description, owner_id, group_id, area, max_prims, sale_price, flags, aabb_min, aabb_max}

client.groups

group = {id, name, insignia_id, charter, member_count, money, open_enrollment}

Worked example

Every binding here is live, and every line touches only the client contract — so the whole script runs unchanged on the viewer once it implements the same surface.

-- greeter: auto-accept friends, greet, sit with recovery, click menus
local me = client.self.info()

client.on_friendship_offered(function(o)
  client.friends.accept(o.from_agent_id, o.session_id)
  client.instant_message(o.from_agent_id, "Hi " .. o.from_name .. "!")
end)

client.on_alert(function(a) print("[alert] " .. a.message) end)

-- sit with a result; ok=false carries "timeout" or the server alert text
client.self.sit(TARGET, function(ok, err)
  if ok then print("seated") else client.self.walk_to(128, 128, 22) end
end)

-- answer a blue-menu dialog by clicking the first button
client.on_script_dialog(function(d)
  client.self.reply_dialog(d.channel, 0, d.buttons[1], d.object_id)
end)

-- nearby-avatar radar
client.on_nearby(function(r) print(#r.avatars .. " avatars nearby") end)

-- anything untyped is still reachable raw
client.on_message("MeanCollisionAlert", function(pkt) print("bumped") end)

Raw packets — the message template

Beyond the typed surface, client.on_message / client.send_message reach any of the ~483 classic-UDP packets by name. The reference for every one is data/message_template.msg in the bot repo (the Linden message template) — it generates the PacketType enum and the packet classes in Packets.g.cs. A packet's block layout in that file is the table shape the hatch gives and takes.

Reading a template entry

Each packet is a header line then blocks; each block is a name + arity then its fields:

ImprovedInstantMessage Low 254 NotTrusted Zerocoded   -- name, freq, id, trust, encoding
{
    AgentData Single          -- Single  → pkt.AgentData = { … }
    {   AgentID   LLUUID  }
    {   SessionID LLUUID  }
}
{
    MessageBlock Single
    {   ToAgentID LLUUID     }
    {   Dialog    U8         }   -- IM type
    {   Message   Variable 2 }
    …
}

• Single → a {fields} table at pkt.<Block>.
• Multiple / Variable → a 1-based array of {fields} (like MeanCollision), even when there's one entry.

Field types marshal both ways: LLUUID ↔ lowercase string · U8…U64 / S8…S32 / F32 / F64 ↔ number · BOOL ↔ boolean · Variable N ↔ string (bytes; a single trailing NUL is stripped on read) · Fixed N ↔ N raw bytes as a string · LLVector3 ↔ {x,y,z} · LLQuaternion ↔ {x,y,z,w}.

Setting up a receiver

client.on_message("AvatarAnimation", function(pkt)
  local who = pkt.Sender.ID                    -- Single block
  for _, a in pkt.AnimationList do             -- Variable block → array
    print(who .. " playing " .. a.AnimID)
  end
end)

Building one to send

-- a raw IM: the typed client.instant_message only sends Dialog 0;
-- the packet lets you set any Dialog (offers, lures, group invites, typing…)
local me = client.self.info()
client.send_message("ImprovedInstantMessage", {
  AgentData = { AgentID = me.agent_id, SessionID = me.session_id },
  MessageBlock = {
    FromGroup = false, ToAgentID = TARGET,
    ParentEstateID = 0, RegionID = "00000000-0000-0000-0000-000000000000",
    Position = me.position, Offline = 0,
    Dialog = 0,                                -- 0 = normal IM
    ID = "00000000-0000-0000-0000-000000000000", Timestamp = 0,
    FromAgentName = me.name, Message = "hi (raw)", BinaryBucket = "",
  },
})

Packets worth reaching for

The ones without a typed binding (or where raw gives you more). Full field lists are in the template block for each.

Everything else — all ~483 names, every field — is in data/message_template.msg. List the names with awk '$2 ~ /^(Low|Medium|High|Fixed)$/{print $1}' data/message_template.msg; the block layout under a name is exactly the pkt table for it.

Binding source: LibreMetaverse.LuauBot/ClientBindings*.cs; packets: data/message_template.msg. Change a binding here first, keep both hosts in step.