the client surface — luau on libremetaverse

one client surface, hooked into the grid — the instrument every script plays

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 embeds the same vm and implements the same contract over its c++ managers — so a script targeting this document runs the same on either host. the binding code differs; the surface does not.

how it works

• a bot is libremetaverse + a luau vm behind a shim. vm execution uses c++ exception trampolines and error containment, so callback failures log cleanly without crashing the host.
• the viewer implements the same client contract over its c++ managers.
• bots and the viewer are both websocket clients of one hub, drivable at once over mcp.

conventions & await ergonomics

bindings come in six kinds: command (sends/acts), snapshot (copies host state into a fresh table), query (returns a simple value), event (client.on_*), deferred-async (result arrives via a later on_* event), and completion (callback or await).

for completion calls there are two spellings of one request: pass a trailing fn(ok, err), 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 correlates back. the worker stays free during the wait.

the namespaces

• client — network, chat, im
• client.self — movement & actions
• client.appearance, client.marketplace (direct delivery), client.web (web session)
• client.rlv & lockdown, client.friends, client.avatars, client.directory
• client.grid, client.objects, client.inventory, client.parcels, client.groups
• timers & stats, the raw packet escape hatch

the complete reference — every namespace, every signature, the worked example and the raw-packet template — lives at dev.inworld.help/ukulele. this is the map of the instrument.