SLua Alpha

Warning!

This functionality is in alpha. Instability is to be expected, and there may be very sharp edges. At this point it is expected that Luau can crash regions and perform other types of undesirable behavior.

Second Life Lua (SLua) Alpha

Luau logo

We're thrilled to announce the launch of the SLua Alpha for Second Life! This significant update introduces the Lua scripting language, offering creators enhanced performance, improved memory efficiency, and a more versatile scripting environment.

What is SLua?

SLua is scripting for Second Life based on Luau, a fast, small, safe, and gradually typed embeddable scripting language derived from Lua. It is designed to be backwards compatible with Lua 5.1, incorporating features from future Lua releases and expanding the feature set with type annotations and a state-of-the-art type inference system. Luau is largely implemented from scratch, with the language runtime being a heavily modified version of the Lua 5.1 runtime, featuring a completely rewritten interpreter and other performance innovations.

Why Lua?

The decision to integrate Lua into Second Life was driven by its ability to meet all the requirements for a scripting engine within the platform. Lua offers a high-quality scripting experience to creators, addressing many of the limitations present in the current LSL (Linden Scripting Language) environment. Its lightweight nature and performance optimizations make it an ideal choice for enhancing the scripting capabilities in Second Life. For more information on why Lua was chosen, please see the Lua FAQ.

How to Get Started with SLua

In order to play with SLua, you'll need to download our Lua project viewer, and log onto our Aditi beta grid.

• Access the latest build of the SLua-enabled Second Life Viewer from here.

Once you've got the new viewer and have logged onto the beta grid, head over to these SLua-enabled regions:

• Luau Yardang
• Luau Tombolo
• Luau Mesa
• Luau Tideland

When editing a script in the new Lua project viewer, you'll notice a new Compiler drop-down near the save button. This drop-down will allow you to select which compiler will be used, as well as which script runtime will be used (LSO2, Mono, Luau).

Compiler drop-down options:

• LSL: Legacy (LSO2) - Scripts written in LSL, to be run on the old LSO2 VM
• LSL: Mono- Scripts written in LSL, to be run on the Mono VM
• Lua - Scripts written in Lua, to be run on the SLua VM
• LSL/Luau- Scripts written in LSL, to be run on the SLua VM

Transitioning from LSL to SLua

• Function Namespacing:
  • In SLua, Linden Lab functions have been moved under the ll namespace.
  • For example:
    • llSay becomes ll.Say
    • llGetPos becomes ll.GetPos
• Lists
  • Lua indexes begin from 1, unlike LSL where indexes begin from 0.
  • Lua uses {} for tables, unlike LSL where [] is used for lists.
  • When calling LL functions in SLua, lists often have type-strict requirements, unlike Luau in general.
    • For example, ll.SetPrimitiveParams({PRIM_GLOW, 0, 1}) will cause a type-error because 0 is a Luau number type, instead of the LSL integer type expected by llSetPrimitiveParams. For cases like this, there are special functions which provide the correct data types.
    • Correct: ll.SetPrimitiveParams({PRIM_GLOW, integer(0), 1})
    • Similar functions exist for: integer, uuid (key), vector, quaternion (rotation)

SLua Libraries

• Coroutines:
  • SLua supports coroutines, allowing for cooperative multitasking within scripts.
  • Key functions include:
    • coroutine.create
    • coroutine.status
    • coroutine.resume
  • Refer to the coroutine library documentation for more details.
• Bitwise Operations:
  • SLua includes a bit32 library for bitwise operations, enabling more efficient data manipulation.
  • Refer to the bit32 library documentation for more details.
• Standard Library:
  • SLua comes equipped with a standard library of functions designed to manipulate built-in data types.
  • Explore the Luau Standard Library for a comprehensive list of available functions.

Feedback and Support

We encourage all creators to explore the new scripting capabilities and provide feedback. Your insights are invaluable in refining and enhancing this feature. For more information and to share your experiences, please refer to our Lua FAQ.

Example Scripts

To help you get started, we've assembled some example scripts that demonstrate the capabilities of SLua. These scripts cover various functionalities and can serve as a foundation for your own creations. Please feel free to propose changes to these scripts, or modify them to your heart's desire!

default_script.lua

This script is roughly equivalent to the default "new script" that gets created for LSL.

function state_entry()
    ll.Say(0, "Hello, Avatar!")
end

-- Called when the object is touched.
function touch_start(total_number)
   ll.Say(0, "Touched.")
end

-- Invoke state_entry on startup, since simulator doesn't invoke 
-- it like it does in LSL
state_entry()

dialog.lua

This script demonstrates how one can interact with dialog menus.

-- Define the menu buttons and dialog message.
local buttons = {"-", "Red", "Green", "Yellow"}
local dialogInfo = "\nPlease make a choice."

local ToucherID = nil
local dialogChannel = nil
local listenHandle = nil

-- This function is called when the script first starts.
function state_entry()
    -- Get the object's key and compute a dialog channel number.
    local key = ll.GetKey()
    -- Extract the last 7 characters of the key and convert it from hex.
    dialogChannel = -1 - tonumber(string.sub(tostring(key), -7, -1), 16)
end

-- Called when the object is touched.
function touch_start(num_detected)
    ToucherID = ll.DetectedKey(0)
    -- If there is already a listen handle, then remove it
    if listenHandle then
        ll.ListenRemove(listenHandle)
    end
    listenHandle = ll.Listen(dialogChannel, "", ToucherID, "")
    ll.Dialog(ToucherID, dialogInfo, buttons, dialogChannel)
    -- Set a 60-second timer for response.
    ll.SetTimerEvent(60.0)
end

-- Called when a dialog response is received.
function listen(channel, name, sender_id, message)
    if message == "-" then
        -- Redisplay the dialog if the "-" option is selected.
        ll.Dialog(ToucherID, dialogInfo, buttons, dialogChannel)
        return
    end
    -- Stop the timer, and stop the listening handler.
    ll.ListenRemove(listenHandle)
    ll.SetTimerEvent(0)
    -- Let the user know what they selected
    ll.Say(0, `You selected {message}`)
end

-- Called when the timer expires.
function timer()
    -- Stop the timer and clean up the listener.
    if listenHandle then
        ll.SetTimerEvent(0)
        ll.ListenRemove(listenHandle)
        ll.Whisper(0, "Sorry. You snooze; you lose.")
    end
end

-- Invoke state_entry on startup, since simulator doesn't invoke 
-- it like it does in LSL
state_entry()

user_input_coroutine.lua

This script demonstrates coroutines and how they can simplify the overarching logic of a script, enabling us to write multi-event code within a single function instead of fragmenting it across separate event handlers.

-- Wait for user-input before doing something useful with it.
main = function()
    ll.Listen(0, "", "", "")
    ll.OwnerSay("Do you want pants or gloves?")
    local clothing = coroutine.yield() -- pause the routine's execution here
    ll.OwnerSay("For men or women?")
    local gender = coroutine.yield()
    ll.OwnerSay("Favorite color?")
    local color = coroutine.yield()
    ll.OwnerSay("Here's "..color.." "..clothing.." for "..gender)
    finished = true
end

function touch_start(total_num)
    if finished ~= false then -- unset or true
        finished = false
        routine = coroutine.create(main) -- new coroutine
        coroutine.resume(routine)        -- run coroutine
    end
end

-- When the coroutine is suspended,
-- we can resume its execution by calling the coroutine again
-- and pass any number of arguments to be returned by yield()
function listen(channel, name, id, message)
    if finished == false then
        coroutine.resume(routine, message)
    end
end

dialog_coroutine.lua

This script demonstrates how one could use coroutines to handle dialog responses, with multi-user support.

-------------------------
-- Minimal EventLoop
-------------------------
local EventLoop = {
    -- Coroutine -> eventName it’s waiting for
    _coros = {},
    running = false
}

function EventLoop:create_task(func)
    local coro = coroutine.create(func)
    self._coros[coro] = false
    self:_run_coro(coro)
    return coro
end

function EventLoop:kill_task(coro)
    self._coros[coro] = nil
    if coroutine.status(coro) ~= "dead" then
        coroutine.close(coro)
    end
end

-- Internal helper: resumes a coroutine
function EventLoop:_run_coro(coro, ...)
    if coroutine.status(coro) == "dead" then
        return
    end

    local old_running = self.running
    self.running = true

    self._coros[coro] = false
    local ok, eventAwaited = coroutine.resume(coro, ...)
    self.running = old_running

    if not ok then
        ll.OwnerSay(`Coroutine error: {eventAwaited}`)
        self._coros[coro] = nil
        return
    end

    -- If still alive, 'eventAwaited' is the next event it wants
    self._coros[coro] = eventAwaited
end

function EventLoop:handle_event(eventName, ...)
    ll.OwnerSay(`Handling event {eventName}`)
    local snapshot = table.clone(self._coros)
    for coro, waitingFor in pairs(snapshot) do
        if coroutine.status(coro) == "dead" then
            self._coros[coro] = nil
        elseif waitingFor == eventName then
            ll.OwnerSay(`Dispatching event {eventName} to {coro}`)
            self:_run_coro(coro, ...)
        end
    end
end

-- Coroutines use this to yield until an event
local function await_event(name)
    assert(EventLoop.running, "await_event called outside a coroutine!")
    return coroutine.yield(name)
end

-------------------------
-- Script Logic
-------------------------
local buttons = {"-", "Red", "Green", "Yellow"}
local dialogInfo = "\nPlease make a choice."

-- Use the chat listener to feed the event-loop
function listen(channel, name, sender_id, message)
    -- We handle all 'listen' events via the event-loop
    EventLoop:handle_event(`listen_{channel}`, channel, name, sender_id, message)
end

-- Called when the script starts
function state_entry()
    -- Seed math.random so each new script run doesn’t repeat the same channels
    math.randomseed(ll.GetUnixTime())
    ll.OwnerSay("Script started with random channels for each user.")
end

-- A coroutine function for a single user's dialog flow
local function handle_dialog_for_user(userId)
    -- Use a random channel
    local channel = math.random(0x1, 0xFFFF)
    -- Create a listener for that channel
    local listenHandle = ll.Listen(channel, "", "", "")

    while true do
        -- Show the user a dialog
        ll.Dialog(userId, dialogInfo, buttons, channel)

        -- Wait for the next 'listen' event (channel, name, sender_id, message)
        local c, n, sid, msg = await_event(`listen_{channel}`)

        -- If this "listen" event isn't for our channel/user, ignore it
        if c == channel and sid == userId then
            -- If user pressed "-", re-display the menu, else they picked a final color
            if msg ~= "-" then
                ll.Say(0, `{n} selected {msg}`)
                -- Now that they've chosen something else, remove the listener and finish
                ll.ListenRemove(listenHandle)
                return
            end
        end
    end
end

-- Called when the object is touched
function touch_start(num_detected)
    for i=0, num_detected-1 do
        local toucherId = ll.DetectedKey(i)
        -- Create a separate coroutine for each person who touches
        EventLoop:create_task(function()
            handle_dialog_for_user(toucherId)
        end)
    end
end

-- Run state_entry on load:
state_entry()

More Examples

• Find more example scripts at Luau Example Scripts

• Lua Gotchas, Footguns and Other Hazards