Second Life Wiki - User contributions [en]

Third Party Viewer Directory/Aperture Viewer

2025-08-29T15:46:50Z

Signal Linden: https://github.com/secondlife/third-party-viewers/issues/8

=={{TPVD-Icon|Aperture_Viewer}} Aperture Viewer==

{{TPVD-Detail
|home=https://apertureviewer.com
|privacy=https://github.com/ApertureViewer/Aperture-Viewer/wiki/Privacy-Policy
|download=https://github.com/ApertureViewer/Aperture-Viewer/releases
|source=https://github.com/ApertureViewer/Aperture-Viewer
|supportemail=contact@apertureviewer.com
|slcontact=ApertureViewerOfficial
|rlcontact=
|platforms={{TPVD-Platform|Windows|showtext=1}}
}}

Aperture Viewer is an advanced, open-source viewer delivering exceptional visual quality, powerful creative tools, and strong performance for Second Life and OpenSim. Created with artists in mind—but welcoming and accessible to everyone—Aperture Viewer offers an unmatched combination of visual control, thoughtful privacy features, and intuitive usability, enhancing the virtual experience for all users.

{{TPVD-Footer}}

LlSetGroundTexture

2025-08-11T15:49:35Z

Signal Linden:

{{LSL_Function
|inject-2
|func_id=|func_sleep=0.0|func_energy=10.0
|sort=SetGroundTexture
|func=llSetGroundTexture|sort=SetGroundTexture
|return_type=integer
|p1_type=list|p1_name=changes|p1_desc=List of changes to apply to ground textures on the region.
|func_desc=
Changes the textures used to paint the terrain of a region. The owner of the script must be able to manage the estate.
|return_text
|spec
|caveats=
* This function must be executed from a script in an object owned by the region owner or an estate manager.
* This function is throttled at 4 calls every 2 minutes.
* Always returns 0
* PBR terrain is all or nothing. Mixing normal terrain textures with PBR textures will cause the PBR textures to appear gray.
|constants=
{{LSL Constants/GroundTexture}}
|examples
|helpers
|also_functions=
{{LSL DefineRow||[[llModifyLand]]|Modifies terrain contours.}}
|also_tests
|also_events
|also_articles
|notes
|cat1=Ground
|cat2=Region
|cat3
|cat4
}}

Third Party Viewer Directory

2025-05-21T15:27:34Z

Signal Linden: Add Aperture Viewer

{{KBwarning|width=90%| The viewers listed here are not developed nor distributed by Linden Lab. Being listed here means only that the developers of the viewer have represented that they comply with the [http://secondlife.com/corporate/tpv.php Policy on Third-Party Viewers] and the [http://secondlife.com/corporate/tos.php Second Life Terms of Service]. You are responsible for evaluating whether you want to use and share information with them.}}

<noinclude>{{OS License Nav}}</noinclude>
==Using third party viewers==

You may connect to Second Life using software released by a third-party developer. Linden Lab provides a [http://secondlife.com/corporate/tpv.php Policy on Third-Party Viewers] to promote a positive and predictable experience for all Second Life Residents. Beware of third-party viewers that are not in the Viewer Directory: they have either declined to self-certify their compliance with Linden Lab policies or been refused for noncompliance with the policies.

==Active Full Viewers==

These viewers are projects that are updated regularly to track new developments in the Linden Lab viewer, and implement a full graphical environment.

{|border="1" style="width: 100%; border-collapse: separate; border-spacing: 0; border-width: 1px; border-style: solid; border-color: #000; padding: 0;"
|- style="background-color: #dfd;"
!Viewer
!Description
!Platforms

|-
{{TPVD-Listing|Alchemy|An experimental Second Life™ viewer striving to be at the forefront of stability, performance, and technological advancement in the open-source metaverse viewer field.|{{TPVD-Platform|Windows}}{{TPVD-Platform|MacOS}}{{TPVD-Platform|Linux}}|iconversion=2}}

|-
{{TPVD-Listing|Aperture Viewer|A powerful, open-source viewer for Second Life and OpenSim, offering exceptional visuals, creative tools, and intuitive features designed for artists and accessible to all.|{{TPVD-Platform|Windows}}}}

|-
{{TPVD-Listing|Black Dragon|
The primary goal of Black Dragon is to enhance and refine the visuals of Second Life as well as having unique design approaches and features.|{{TPVD-Platform|Windows}}}}

|-
{{TPVD-Listing|Firestorm|The next generation viewer from The Phoenix Firestorm Project, Firestorm is based on the LL V3 LGPL code and offers extensive interface customizability including V1 skin options, feature and option rich with 24/7 support.|{{TPVD-Platform|Windows}}{{TPVD-Platform|MacOS}}{{TPVD-Platform|Linux}}}}

|-
{{TPVD-Listing|Kirstens|A hybrid viewer based on a mixture of official sources and custom code aimed specifically at experienced users, with emphasis on the visuals.|{{TPVD-Platform|Windows}}|iconversion=4}}

|-
{{TPVD-Listing|Kokua|Kokua provides releases for PC, Mac and Linux with and without Marine Kelley's RLV together with a broad selection of original features and the best from other viewers.

Kokua aims to be the viewer of choice for RLV users who want Marine Kelley's original implementation with more bells and whistles than Marine's own viewer.|{{TPVD-Platform|Windows}}{{TPVD-Platform|MacOS}}{{TPVD-Platform|Linux}}{{TPVD-Platform|Linux64}}}}

|-
{{TPVD-Listing|Catznip|Catznip aims to refine and reinvent your window into Second Life. Our focus is stability, usability, privacy and plenty of new original home grown features. It's about taking a fresh look at things and attempting to do them better.|{{TPVD-Platform|Windows}}{{TPVD-Platform|Linux}}|iconversion=2}}

|-
{{TPVD-Listing|Restrained Love|The RLV enhances your experience when you use it in conjunction with RLV-compatible objects, which are able to restrict the user from detaching items, receiving IMs, hearing chat, teleporting etc.|{{TPVD-Platform|Windows}}{{TPVD-Platform|MacOS}}}}

|-
{{TPVD-Listing|Singularity|Singularity strives to combine the beloved look and feel of Viewer 1.23 with the latest and greatest of available technology, and to stay compatible with future Second Life changes and features.|{{TPVD-Platform|Windows}}{{TPVD-Platform|Linux}}}}

|-
{{TPVD-Listing|Genesis|Genesis is a blazingly fast, high performance 1.23 style viewer for Second Life, offering the very latest features, never seen before in a Legacy viewer. |{{TPVD-Platform|Windows}}}}

|-
{{TPVD-Listing|CoolVLViewer|An improved and expanded v1-UI viewer kept in close sync with Linden Lab's official viewer features. Geared towards performances and stability. The oldest maintained TPV (first release date: 2007-11-16)|{{TPVD-Platform|Windows}}{{TPVD-Platform|MacOS}}{{TPVD-Platform|Linux}}}}

|-
{{TPVD-Listing|Megapahit|This fork is planned to be the shelter for the metaverse refugees, especially those from less supported operating systems|{{TPVD-Platform|MacOS}}{{TPVD-Platform|Linux}}}}

|-
{{TPVD-Listing|Lovense|Lovense Viewer is a free third-party viewer for Second Life that enables seamless integration with Lovense products.|{{TPVD-Platform|MacOS}}{{TPVD-Platform|Windows}}}}
|}

==Subset Viewers==

These viewers omit some aspects of the full viewer functionality.

{|border="1" style="width: 100%; border-collapse: separate; border-spacing: 0; border-width: 1px; border-style: solid; border-color: #000; padding: 0;"
|- style="background-color: #dfd;"
!Viewer
!Description
!Platforms

|-
{{TPVD-Listing|Radegast|Light-weight feature rich '''non-graphical''' client, ideal for situations where full 3D rendering client is less than ideal option, for instance, an office environment, running on low performance computers and similar.|{{TPVD-Platform|Windows}}{{TPVD-Platform|MacOS}}{{TPVD-Platform|Linux}}}}

|-
{{TPVD-Listing|SpeedLight|Pure web Second Life viewer. Supports desktop and all mobile browsers, allows switching between devices.|{{TPVD-Platform|Windows}}{{TPVD-Platform|MacOS}}{{TPVD-Platform|Linux}}{{TPVD-Platform|Android}}{{TPVD-Platform|iPhone}}|iconversion=1}}

|-
{{TPVD-Listing|MetaChat|iOS - TEXT ONLY - Second Life® client.|{{TPVD-Platform|iPhone}}|iconversion=1}}

|-
{{TPVD-Listing|Mobile Grid Client|Second Life and Open Simulator messaging client for all Android powered devices.|{{TPVD-Platform|Android}}}}




|}


<div style="background-color: #dfd; margin: 20px 10px 10px 10px; padding: 1px 10px 10px 10px;">

==For developers: how to apply to list a viewer in this directory==

# Your Second Life accounts must be in good standing, must not be suspended, and must not have been permanently banned or terminated.
# You must have valid payment information on file with us or have been age verified by us.
# Review our Policy on Third-Party Viewers and the Second Life Terms of Service.
# Make sure you and your third-party viewer are in compliance with our policies.
# Open an [https://github.com/secondlife/third-party-viewers/issues/new/choose Application Issue] on the [https://github.com/secondlife/third-party-viewers Third Party Viewer] Github repository and submit it.

</div>

<div style="background-color: #fdd; margin: 20px 10px 10px 10px; padding: 1px 10px 10px 10px;">

==Reporting policy violations==

If you believe that you have direct evidence that any third party viewer (whether listed in the Third Party Viewer Directory or not) may be in violation of the [http://secondlife.com/corporate/tpv.php Second Life Terms of Service] or the [http://secondlife.com/corporate/tpv.php Policy on Third Party Viewers], you can [https://github.com/secondlife/third-party-viewers/issues/new/choose file a violation report] to be investigated.
</div>
[[Category:Third Party Viewers]]

File:TPV-ApertureViewer-Icon.png

2025-05-21T15:24:16Z

Signal Linden: Signal Linden moved page File:TPV-ApertureViewer-Icon.png to File:TPV-Aperture Viewer-Icon.png

#REDIRECT [[File:TPV-Aperture Viewer-Icon.png]]

File:TPV-Aperture Viewer-Icon.png

2025-05-21T15:24:15Z

Signal Linden: Signal Linden moved page File:TPV-ApertureViewer-Icon.png to File:TPV-Aperture Viewer-Icon.png

Third Party Viewer Directory/Aperture Viewer

2025-05-21T15:21:52Z

Signal Linden: Fix icon URL

=={{TPVD-Icon|Aperture_Viewer}} Aperture Viewer==

{{TPVD-Detail
|home=https://github.com/ApertureViewer/Aperture-Viewer/wiki
|privacy=https://github.com/ApertureViewer/Aperture-Viewer/wiki/Privacy-Policy
|download=https://github.com/ApertureViewer/Aperture-Viewer/wiki/Download-&-Installation
|source=https://github.com/ApertureViewer/Aperture-Viewer
|supportemail=Aperture ''dot'' Viewer ''at'' gmail ''dot'' com
|slcontact=William Weaver (paperwork)
|rlcontact=
|platforms={{TPVD-Platform|Windows|showtext=1}}
}}

Aperture Viewer is an advanced, open-source viewer delivering exceptional visual quality, powerful creative tools, and strong performance for Second Life and OpenSim. Created with artists in mind—but welcoming and accessible to everyone—Aperture Viewer offers an unmatched combination of visual control, thoughtful privacy features, and intuitive usability, enhancing the virtual experience for all users.

{{TPVD-Footer}}

Third Party Viewer Directory/Aperture Viewer

2025-05-21T15:20:47Z

Signal Linden: Created page with "=={{TPVD-Icon|ApertureViewer}} Aperture Viewer== {{TPVD-Detail |home=https://github.com/ApertureViewer/Aperture-Viewer/wiki |privacy=https://github.com/ApertureViewer/Apertur..."

=={{TPVD-Icon|ApertureViewer}} Aperture Viewer==

{{TPVD-Detail
|home=https://github.com/ApertureViewer/Aperture-Viewer/wiki
|privacy=https://github.com/ApertureViewer/Aperture-Viewer/wiki/Privacy-Policy
|download=https://github.com/ApertureViewer/Aperture-Viewer/wiki/Download-&-Installation
|source=https://github.com/ApertureViewer/Aperture-Viewer
|supportemail=Aperture ''dot'' Viewer ''at'' gmail ''dot'' com
|slcontact=William Weaver (paperwork)
|rlcontact=
|platforms={{TPVD-Platform|Windows|showtext=1}}
}}

Aperture Viewer is an advanced, open-source viewer delivering exceptional visual quality, powerful creative tools, and strong performance for Second Life and OpenSim. Created with artists in mind—but welcoming and accessible to everyone—Aperture Viewer offers an unmatched combination of visual control, thoughtful privacy features, and intuitive usability, enhancing the virtual experience for all users.

{{TPVD-Footer}}

Template:TPVD-Icon

2025-05-21T15:18:37Z

Signal Linden:

<includeonly>{{#ifexist: File:TPV-{{{1}}}{{#if: {{{iconversion|}}}|-{{{iconversion}}}|}}-Icon.png|[[File:TPV-{{{1}}}{{#if: {{{iconversion|}}}|-{{{iconversion}}}|}}-Icon.png|48px|middle|link=Third Party Viewer Directory/{{{1}}}|{{{1}}}]]|}}</includeonly><noinclude>

Upload as '''File:TPV-'''''viewername''{'''-'''''iconversion''}'''-Icon.png''' and then use macros like:

<nowiki>
{{TPVD-Icon|Phoenix}} Phoenix

{{TPVD-Icon|Catznip|iconversion=2}} Catznip

{{TPVD-Icon|Bogus}} Bogus
</nowiki>

{{TPVD-Icon|Phoenix}}Phoenix

{{TPVD-Icon|Catznip|iconversion=2}}Catznip

{{TPVD-Icon|MetaChat|iconversion=1}} MetaChat

{{TPVD-Icon|Bogus}}Bogus
</noinclude>

File:TPV-Aperture Viewer-Icon.png

2025-05-21T15:15:09Z

Signal Linden:

Talk:Lua FAQ

2025-03-21T17:12:20Z

Signal Linden: Signal Linden moved page Talk:Lua FAQ to Talk:SLua FAQ

I really love the LSL Portal and so would appreciate if Lua can get the same treatment or coexist without causing confusion to existing or new scripters.

So I'm wondering about technical documentation and conflicts with LSL. Perhaps a) it might be wisest to create a "Lua Portal" that mirrors the LSL Portal but then is expanded over time. And/Or b) would all LSL functions pages (and the LSL Function template) be updated to show the Lua version? c) What if there is Lua-only function later or syntactical differences esp with functions that use or return lists as lists may not exist in Lua or work differently to Lua tables? And d) would a lot of the function documentation diverge too much due to differences in the languages in how they may need to treat types, operators and example code?

It seems a [[Lua Portal]] will be inevitable anyway, because there needs to be a central location where all the Lua-specific pages can be accessed from easily, such as developer resources (tutorials, guides and script examples and libraries), and Lua language reference just as easily as for LSL and also avoid confusing beginners dealing with two different languages on the platform.

Another thing to look at might be that there are a lot of LSL-specific pages that may need to be prefixed with LSL_ in their pages still, e.g. [[State]], [[While]], [[If]], etc since Lua will have differences to LSL. On the other hand there are also some other portals that also invade the global namespace e.g. [[Coding Standard]], [[Features]], [[Glossary]]. All of this affects search functionality. A disambiguation page or template akin to wikipedia may be necessary in place of some of the existing redirects. If someone searches for "string" or "if" they get fed with LSL currently.

-- [[User:Nexii Malthus|Nexii Malthus]] 14:19, 4 July 2024 (PDT)

: Hear, hear. I foresee a lot of work ahead of us SLWikians. If there is a direct 1:1 correspondence between LSL and Lua, well, in that case, we could do something similar to what Microsoft does on its documentation for .NET, where you get, for the same function, the C# and the VisualBasic variants — the idea being that the function is the ''same'', it's just the language construct that uses the function that will change.
: Other similar cases are those explaining, say, a RESTful API. The overall parameters are described, and then you get code snippets for implementing that call in several different programming languages, e.g. cURL/JavaScript/Python/PHP/Go, for instance.
: However, I can imagine that this simplistic approach will fail in our case, especially if we start getting some divergence between actual functions (i.e., new functions that only make sense in Lua, such as those dealing with JSON; and old functions that only make sense in LSL, such as those to retrieve values from a List). While (speculatively) Lua could have its own "List-like" type — it shouldn't be hard to implement — I can imagine that accessing its members will look quite different. Or perhaps not. In any case, there will be differences. It might make more sense to have a "Lua portal" instead, and just link together equivalent functionality (so that you can look up something and see both its LSL and Lua equivalents).
: Exciting times ahead :-) Lots of work to do as well. — [[User:Gwyneth Llewelyn|Gwyneth Llewelyn]] ([[User talk:Gwyneth Llewelyn|talk]]) 01:39, 29 August 2024 (PDT)

:: A friend suggested moving to github with markdown files for LSL. At first I was against it, I mean I really, really like the wiki you know? Its quirks and editing, the powerful template system. All the awesome content and contributed scripts.
:: But in hindsight, looking at MDN Web Docs and other community efforts out there, it looks like that's the way to go these days for documentation sites. There's also the huge issue around having to gain wiki editing access which added to moving away.
:: At least for Lua I think it will make sense going forward. I really don't think there is a nice way to layer another language on a mediawiki that has tons of legacy content centered around one scripting language.
:: The Lua Portal will be at most a convenient jumping off point to the technical documentation. -- [[User:Nexii Malthus|Nexii Malthus]] 05:50, 1 September 2024 (PDT)

== I 💙 Lua (well, not really, but ok)! Here are a few suggestions but also some questions: ==

All right, so I stumbled upon this page just today, after the general announcements posted on the forums. While I was aware of the effort of doing client-side Lua scripting, I had zero knowledge of the amazing work having been done "under the hood" to get LSL running on top of Luau — that idea never even crossed my simple mind, and aye, it ''does'' sound crazy indeed.

On the other hand, perhaps it's not so surprising. As I'm fond to quote all over the place, Lua was ''designed'' to be an embedded programming language for games and other applications. The keyword here is "designed for embedding". Obviously, you ''can'' embed JavaScript, or Python, or LIST (a popular choice in the recent past!), or naturally Java, and you can even embed C#, and there are several other languages that I'm sure that someone, somewhere, has written an "embeddable" version of whatever programming language has been invented out there. Since I saw that the OpenSimulator code included an embedded Prolog interpreter written in C# just to do ''one'' function, I can believe that anything is possible!

That does not mean that it's efficient, clean, easy, with a small footprint, etc. It just means that these embedded languages ''work''. That's the goal, after all.

Lua, by contrast, is not merely "the programming language". Syntax-wise, it has a wonderful long list of awesome features and concepts that make things insanely easy to do — aye, even compared to JavaScript. But it also has some terribly annoying quirks which make zero sense and are just a stupid way of "differentiating" the language from others in the same family. It's stupid to use <code>~=</code> instead of <code>!=</code>. Indeed, I find it even stranger due to Lua's Brazilian origin — the key for the tilde <code>~</code> is a dead key (used for the Portuguese vowels ã and õ), which means that, on a Portuguese keyboard, you need to press ''three'' keys to get the negation symbol!

Comments are also awful. I know that the "proper" way of doing comments is open to debate, but, at the end of the day, C's 50+-years-legacy of <code>/* ... */</code> and <code>//</code> (the latter "borrowed" from C++ and "backported" to C as well) is what everybody uses, at least on languages that are sensible enough not to consider whitespace as syntactically relevant (Python, I'm looking at ''you'').

And arrays starting at 1? Really? Why did you guys think that this is a good idea? Not to mention the mixed approach you've taken for delimiting blocks of code. I mean, there are a few schools of thought on this, and from the perspective of the programmer, you have two main choices: using a symbol (usually the curly braces; parenthesis in LISP or Prolog or perhaps a few other purely functional languages), which has the disadvantage of being hard to figure out (without tooling) to which code block a closing curly brace/parenthesis belongs to. Or there is the horrible — but useful! — idea of using reverse keywords to begin and start code blocks, e.g. <code>if ... fi</code>, which are aesthetically ugly but they do the job well. Alternatively, you always have <code>if ... endif</code> and similar constructs — giving the code some structure at the expense of having to type more. But <code>if... end</code> (and everything else ending with, well, <code>end</code>...) just means typing 3 characters instead of just one, but with the same lack of semantics. If you see an <code>end</code> in Lua, it can belong to anything, so it has no semantical meaning by itself (unlike a <code>fi</code> which can ''only'' terminate a conditional block started with <code>if</code>).

That said (and I wish I could have added the sentence "besides all the above, the rest is fine!", but I cannot — the list of oddities and quirks in Lua go on and on), the whole point of "Lua" is that it's not ''just'' the programming language. That's what the developer interacts with. Lua, however, is worthless by itself; the concept ''always'' includes the notion of an interpreter/JIT/full compiler that runs embedded into an application. And ''that's'' where Lua shines: it may have its oddities, but it was ''designed'' for having all these oddities (and so much more) getting efficiently and quickly run by any 'host'. That also means the ease of passing information between the host application and the Lua engine, in a safe (and sandboxed!) way. Again: you ''could'' do it on any other language via its own embedded mechanism. It's just that Lua happens to be especially good at such interfaces. I can imagine that getting Lua to access the vast library of LSL functionality is an almost trivial exercise; it's ''supposed'' to be simple to do that, after all. In other words: it's often less about the end users (those that will ultimately write code in Lua) and much more about the environment surrounding Lua, and how its highly portable embedded engine interfaces with such an environment.

Perhaps ironically, around 2020 or so, I struggled with the same issues, although at a much tinier (and less important!) scale. While developing some code that allowed full control over groups of independent agents (let's call them 'bots), I went through the usual phases of sloppy programming: first, figure out what functionality is common to all (say, logging in, moving around...) and implement those. Then essentially have a list (or a database table) with all the independent agents, and, for each, follow a sequence of operations, all of which hard-coded, That was fine, until the edge cases started to pop in — such as different agents requiring different settings. That quickly became unmanageable, so the next approach was to use more fields on the table, such as keeping track of the agent's location. To deal with different orders of execution, another table was created, listing, for each agent, what the sequence of operations for that agent was instructed to perform. This essentially describes a very crude state machine, where the entries are indexed by the function call to be made next.

And then, the inevitable happens. How to deal with conditionals? How to deal with loops? Oh, and wouldn't it be great to have some place to store some results separately for each function? (it could be "registers", or a classic stack with push/pop operations...)

In essence, I was asking the wrong questions: what I needed wasn't to "reinvent the wheel" and creating what ultimately would become an embedded language, designed from scratch. Instead, what I ''really'' needed was an embedded language!

At that time, I wanted just something ''very simple'' which could be ''quickly'' implemented (and its functions mapped to those on the host application). Since I usually work (on my own) with Go, I started looking for Go-specific solutions. And sure, there are a few, but they have the disadvantage that they're even less known (or used) than LSL. The obvious choice was naturally embedding a JavaScript engine, of which the best of the best is, allegedly, Google's own. It is also... massive, to say the least. Never mind that our contemporary Chromium-based browsers use this massive engine (even the SL Viewer does!); it might make sense if you have a need to access the vast library of JavaScript code all over the place; but that wasn't my case. I just wanted something ''familiar'' and having a community of a decent number of people that are able to provide libraries and have some availability to answer questions. That's when I came up with the idea of testing out Lua. There was a semi-decent effort to write a Lua engine completely in Go (as opposed to linking it to an externally-compiled C/C++ library, which would be the "usual" choice for most solutions), and I thought it would be a nice idea to experiment with.

As it happens, there are a few people writing some helper functions on top of what the "raw" library supports, which make exposing functions to Lua (and vice-versa) an almost banal exercise. It works admirably well. In fact, the ''only'' thing that really works ''well'' in my meagre coding attempts are the bits running on Lua — the rest of the much more complex effort of integrating the core application with the control of the independent agents is (for me!) much, much harder. In other words: by using Lua as the choice for the embedded language, I solved one problem — the user-facing aspect of dealing with the actual agent scripting, using a high-level language — and didn't need to ever worry with it again. It just works. Now I can switch the focus to "everything else" instead.

I was super-excited (and to be truthful, I had never programmed in Lua before, and know little more than the basics; think of my level of experience as being that of a 12-year-old who learned Lua to do interactive objects in Roblox — that's pretty much how much I know) and astonished at how well this worked. Not in terms of performance (frankly, I didn't really make benchmarks — all the bottlenecks occur ''outside'' the Lua environment, anyway; Lua scripts are spending most of their time waiting for the rest of the code to produce results and feed them back to Lua — but even the Go developers who did this Lua engine port admit that it's not ''that'' fast or optimised), but rather in terms of ''integration''. Now, nobody knows how the LL server code looks like, but we can at least assume that it shares some vague similarities with OpenSimulator code, for the simple reason that both technologies needs to handle functions called by LSL. While there are potentially many ways to implement that, and nobody can know if LL's code uses the "same" way as OpenSimulator (while, of course, the reverse is true!), it's worth speculating about the trouble in making '''every library function''' accessible from Lua as well. My belief is that this ''will'' be little more than a trivial exercise; compiling LSL to the Luau VM will be much more challenging, I think :)

That said, looking back, it's obvious that I shouldn't have been so "surprised" that everything worked so well. '''Lua is ''supposed'' to be embedded.''' It's one of its design features. In fact, although you ''can'' run Lua from the command line (or even compile things into executables), there is little incentive to do so: Lua will not be especially good, or fast, or "trendy", for independent, self-contained, command-line utilities. For that you already have C/C++, Python, and more recently Rust, Node.js and a bit of Go. That pretty much covers all the needs. On the other hand, the increasing number of applications using Lua as an ''embedded'' language is frankly astonishing. On my 'personal' bare metal server hosted on a remote data center, I have been running software that I never thought that they included an embedded Lua engine — such as one of the anti-spam services (!). Even the webserver itself (the lightweight nginx) can now have a module to allow its configuration files to be Lua programmes, as opposed to, well, configuration files.

I also have no idea, in the battle for the embedded programming languages, where Lua stands against the "competition". These days, even though LL tested out a very impressive array of choices, the truth is that JavaScript is highly likely the ''most'' used embedded language, since ''every'' browser uses it, and that means close to 5 billion users (who, of course, only ''benefit'' from JavaScript, they don't interact with it in any way). Python was once quite popular as an embedded language, but I guess that its maintenance chores are a nuisance to deal with. LISP was quite popular as an embedded language, and has probably been made famous because it used to be the embedded language used by Richard Stallman's Unix-based Emacs as well as Autodesk's AutoCAD, each running their specific dialects of LISP. Because of the widespread usage of LISP in the early days of embedded languages, I can imagine that it's still more popular than many other solutions out there. The only trouble with LISP is that it requires a very specific mindset to work with it (or else all things AI-related would be written in LISP and not in Python, which is hardly the "best" choice for that — but who am I to contradict millions of users?)

That said...

And that was the longest introduction ever...

I have a few questions that the original article didn't explain!

# Will SL-Lua also support external libraries ("external" meaning: any other Lua-asset to which we have permissions to access)? This is a crucial requirement, which LSL does not satisfy in the least; but it would make millions of lines of LSL code irrelevant, to the great relief of those needing to support the ever-increasing complexity put into LSL to allow it to do very complex tasks indeed. Imagine, for instance, a HUD library that can be easily distributed, with which 90% of the functionality would be packaged inside the library; you'd only need to add a bit of "glue code" on top of that. Or imagine the same thing for vendor machines — such as Casper's — which could therefore have a much cleaner way of integrating with "external" scripts, without needing to expose anything.
# In the same vein: except for the cases mentioned in the main article, does this mean that LL will essentially provide all (or most) standard libraries for Lua? This is relevant for those who really don't want to reinvent the wheel; the Lua standard libraries already do a ''lot'' of useful work, there is no need to redo everything — so long as these libraries can be used, of course. Even with limitations. It also means that a lot of LSL functionality which LL had to develop from scratch might not be necessary as well (when ''LSL'' needs access to those specific functions, it would just call them — via Lua!). I'm thinking about things such as the math library functions, for instance.
# Still on the issue of libraries: the article talks about a <code>ll</code> namespace, which in Lua can have different meanings and implementations ("everything is a table"). Does that imply that there will be ''one'' LL library with ''all'' the functions we have today for LSL — or that the LL library will be split according to different kinds of functionality, and just loaded on demand if needed? I'm thinking about how worthless it is for me to know that there are functions for dealing with Pathfinding, or all the vehicles and physics systems, when all I've got is an Animation Overrider to worry about. A much cleaner way to do things would be to encapsulate related functionality under different libraries or objects. Maybe that's exactly what is going to be done, and that's what will happen "under the hood" when we call a Lua function with <code>ll.someFunction()</code>. I'm not sufficiently familiar with Lua to know if there is a way to do that or not. My reason for asking that is just because I see the vastness of never-ending functions getting a bit out of hand, and it would be far better to aggregate them under different compartments — be they namespaces, libraries, tables/objects, whatever fits the concept best. The end-user (we, the scripters!) will probably never need to worry about that. Or maybe they would — by explicitly calling the libraries they need. This would also allow for more error-checking, i.e. you won't be able to call a similarly-named function by mistake if you have checked in a different library. A typical example are the two key/value pair stores, one implemented in one way for Experiences, the other implemented for any script running in a prim. Sometimes, it's easy to forget which is which, but if I haven't checked in the Experiences library explicitly, I will get an error for a "missing function" — a good hint that I'm probably trying to do something which isn't intended.
# Will Lua scripts be versioned, i.e. will there be a way to automatically let the programmer release a new version, and all existing copies of that asset would automatically "migrate" to the new version instead? This is becoming a more important requirement all the time, as the complexity of scripts continues to increase, and the need to get rid of obsolete versions and replace them automagically is a must; however, I'm quite aware that only a fraction of the users actually bother to do the upgrades. That happens for several reasons, but I can imagine that a lot has to do with the whole complex procedure of getting an "upgrade box", rezzing it on the ground (assuming you've got the correct permissions), then do the same with your HUD, clothing, device, etc., activate the upgrade box, and hope that it works...
# And how about a (better) integration with an ''external'' debugger? Having an internal one, of course, is great effort that you've done (or are in the process of doing). But let's just say that the internal code editor is not really up to modern standards... that said, I wish that the integration wt
# Will you include an official Lua <abbr title="Language Server Protocol">LSP</abbr> server? (There are plenty of those around! It's just that none will come with LL's library functions, of course...). This is mostly for those using external editors, since, internally, you already have something similar for LSL (similar... not quite the same, though...)
# While I understand that, for several reasons, mixing and matching code from LSL and Lua is, in general, a Bad Thing™, I wonder if you guys have thought about the possibility of LSL to call functions in Lua. This is mostly important if the Lua support allows external libraries (which could be Lua scripts) as described above; this could be a way to allow LSL to be "expanded" with libraries as well (namely, with Lua libraries, that is). That might matter most during a transition phase, of course.
# Some people that I talked to about Lua, who are themselves not programmers, asked me if, with Lua, there could be an (embedded) visual programming editor, such as you have in, say, Blender (or any other complex application, especially in the 3D rendering business; but even Filter Forge filters are visually programmed that way). While such options certainly exist and could be deployed over whatever Lua-based infrastructure, the question is if LL has considered that possibility at some point?
# And finally, just for the sake of curiosity, will the prevailing conceptual model for Lua also be a glorified state machine, like LSL? Or will a completely different model? The state machine model was actually a quite clever concept, even though most scripts I've come across rarely employ more than 1-2 states, which defeats the purpose. I'd think that the move to Lua would imply the end of the state machine model; but, on the other hand, this would also mean a much harder effort in adapting old LSL scripts and converting them to Lua (manually, that is!). Thus my curiosity!

That said, I'm looking forward to see what you guys have come up with :)

— [[User:Gwyneth Llewelyn|Gwyneth Llewelyn]] ([[User talk:Gwyneth Llewelyn|talk]]) 02:32, 1 September 2024 (PDT)

== I like Lua a lot! (compared to LSL). Here are some more thoughts and questions: ==
As a scripting instructor, my focus is on how to effectively teach Lua, particularly to those whose main language is LSL, and the challenges that they may encounter while learning and practicing Lua. I plan to start teaching Lua as soon as it becomes available on the beta grid.

: - Lua often has multiple ways to achieve the same result. Will you be providing guidelines or best practices to ensure a consistent approach? With thousands of scripters learning Lua, teaching them consistently would be highly beneficial.

: - One challenge for beginners is Lua's use of dynamic variables without assigned types, which can lead to issues like typos in variable names and unintended mixing of types. It would be helpful if the Lua editor or a pre-processor could include features such as:
# Warning if a variable name appears only once in the script, as this might indicate a typo.
# Warnings about undeclared variables. For instance, adding the "declaration" of global variables using a comment like: -- global variableName, anotherVariable, etc., to make it possible.
# Warnings about type mixing. For instance, adding prefixes like: nCounter, sMessage, bIsOn, or xMultiType (with "x" for variables expected to hold multiple types), to make it possible.

: At least, implementing the option 1 could be not too difficult and extremely helpful.

: - Will there be an option to translate from LSL user-code to Lua user-code? This would be incredibly valuable for reusing existing LSL scripts without manually rewriting them in Lua.

: - The only aspect of Lua that I dislike is the use of ~= (inequality operator instead of !=). On some keyboards requires multiple key presses (in mine, for instance, is AltGr+4+spacebar). It would be convenient if the editor could, when we type !=, replace it with ~=.

Expecting to see Lua in the beta grid in a few months :)

-- [[User:SuzannaLinn Resident|SuzannaLinn Resident]] ([[User talk:SuzannaLinn Resident|talk]]) 09:34, 10 September 2024 (PDT)

: I'd recommend a JSDoc style of comments for the Lua code rather than using a complex naming convention to variables. I've never seeng the single letter typing convention pass the test of time.
: It was mentioned in a recent user meeting that there will be no transpiler for LSL->Lua code. You will still be able to write LSL like normal, you don't have to use Lua. LSL is fine, no need to convert scripts. Link messages, listeners and all will also still work between different types of scripts. So you could send a link message from an LSL script to a Luau script.
: Linting would be good but there are linters already out there. See extensions in Visual Studio Code, there are some that provide lint and type warnings for Luau. I'm not sure the script editor in the SL client will ever do more than the minimum, if anything I'd like better integration with external editors, such as opening up the external editor directly on double-clicking a script instead of the script editor window. -- [[User:Nexii Malthus|Nexii Malthus]] 23:34, 13 September 2024 (PDT)

After further investigation and asking at the SUG meetings, I have some answers:
: - LuaSL will have the same type-checking and linting capabilities as Luau:
:: - Type checking automatically infers types from the values assigned to variables or manually by adding type annotations. These annotations can define types, combinations of types, or subtypes. There are directives that allow to control the level of type checking in each script, ranging from none to stricter than LSL.
:: - Linting identifies possible issues like uninitialized or unused variables, duplicated functions, mismatched parameter counts, return values, and many more. There are also directives to enable or disable specific linting checks.
:- There are no plans for a transpiler from LSL to Lua. Since LSL scripts can remain in LSL, the need for a transpiler is not significant enough (as previously commented). But not in my case, as a scripting teacher: I have around 60 classes with LSL scripts that I will need to change to Lua, so I will be working in my own transpiler.
-- [[User:SuzannaLinn Resident|SuzannaLinn Resident]] ([[User talk:SuzannaLinn Resident|talk]]) 07:38, 18 September 2024 (PDT)

I'm gathering information about Lua on my userpage for my students and anyone interested in it: '''[[User:SuzannaLinn_Resident/Lua | Introducing Lua index page]]'''

-- [[User:SuzannaLinn Resident|SuzannaLinn Resident]] ([[User talk:SuzannaLinn Resident|talk]]) 05:52, 3 October 2024 (PDT)

Lua FAQ

2025-03-21T17:12:18Z

Signal Linden: Signal Linden moved page Lua FAQ to SLua FAQ

__TOC__

=== Can I keep using LSL? ===

Yep! LSL should work exactly the same as before, and a lot of testing work has been done (and is being done) to ensure that is the case. Even if you’re an LSL pro and rely on things like <code>(some_list != [])</code> for getting the list length, or strange things like <code>((largestring="") + largestring)</code>, you’re fully covered. Those still work, and now have optimized implementations.

In fact, LSL will get better than ever before, running faster, and using less memory! The generated bytecode for an LSL script in Lua is generally half the size of a Mono script, and most strings take up half as much memory by virtue of using UTF-8 instead of UTF-16.

We’ve taken a lot of care in writing the new LSL compiler to make the scripting experience for people who prefer LSL better than it was before.

=== Are you going to stop adding functions / events to LSL? ===

In the general case, no. A big part of the work we’ve done is making it easy to share functions between LSL and Lua without much extra effort. For events and functions that can be reasonably exposed to LSL (i.e., they only use simple types that LSL has anyway) then LSL should still get those.

For more advanced features, the idea is that there should still be a path for exposing them to LSL. Obviously, with Lua it’s possible to have object-oriented APIs that would not be possible in LSL, but those objects will generally be written in a way that calling a method on a “special” object we introduce in Lua will really boil down to a function call that can be expressed in LSL.

Not a real example, but <code>some_object:giveInventoryList("folder_name", inventory_list)</code> might really boil down to a <code>llGiveInventoryList(some_object_id, "folder_name", "inventory_list");</code> call. In that way, most additional Lua functionality will be a fancy “easier” wrapper around functions shared with LSL!

The caveat is if functions are added that use new types that aren't in LSL (like functions that take in a <code>key -> value</code> map) likely won't be exposed to LSL, as there's no way to represent them in LSL anyway.

=== Wait, LSL can run on Lua now? How? Why would you do that? ===

A reasonable question! It sounds crazy at first, but as it turns out, LSL maps really well to Lua bytecode, and we already have a compiler that can output both Mono and legacy LSO2 bytecode. Writing a compiler that could output Lua bytecode wasn't terribly difficult, and it allows LSL scripts to run faster, and be more memory-efficient. Most importantly, it allows us to test behavior of the new scripting engine against the behavior of the existing Mono scripting engine. This helps us make sure we're doing an apples-to-apples comparison on our benchmarks, and that all the nice things that Mono currently gets us will also work correctly under the new scripting engine.

Additionally, for better or for worse, LSL is here to stay. People have been writing scripts in it for 20 years, and they're going to be running on the servers for years to come. Performance and memory usage issues with LSL scripts will continue to matter for the foreseeable future. The faster the server can run existing LSL scripts, the more time it can dedicate to running newer Lua scripts. Memory usage has been a particular problem with the existing Mono scripting engine, and this would help us address this.

=== What about running scripts on the viewer-side if I want viewer-side effects? Does this have any interaction with the work adding Lua addons into the viewer? ===

No, the work on adding Lua addons to the viewer is a separate effort. Lua scripts on SL will strictly run on the region, and not on the people's viewers. We're focused on providing a high-quality replacement to the existing server-side scripts before we look at anything else.

Note that we are all too aware of the current difficulty of scripting HUD UIs for Second Life (we make a lot of our own) and we're thinking of ways we can make things better, but there are no definite plans, and it wouldn't involve running scripts on the viewer in the near-term. The current UI tooling exposed to Lua viewer addons isn't tooled for being called from untrusted code either way, so lack of "client-side" scripts is unlikely to hinder any effort to create a better API for HUDs for in-world systems.

=== You said Lua runs LSL faster than Mono? It uses less memory? How? I'm suspicious. ===

A reasonable suspicion! We were also suspicious and suspected that Lua would be slightly slower, but in reality, yes, Lua can run LSL scripts quite a bit faster than the custom-patched Mono 2.6 we currently use. The best LSL on Mono has performed compared to Luau in our internal tests is 10% slower than Luau. Similarly, most LSL on Luau scripts end up being around half the size of Mono scripts. That means much more memory to play with in your LSL scripts.

The reason why isn't intuitive, after all, Mono is a lot more intricate and has a lot of fancy performance optimizations like a JIT optimizer, but it becomes clear when you look at the bytecode that's generated for LSL on each scripting engine.

Consider the following LSL function as an example:

<syntaxhighlight lang="lsl2">
float loudSubtract(float val, float sub) {
// subtract, telling the owner what we did
float new_val = val - sub;
llOwnerSay("New val is " + (string)new_val);
return new_val;
}
</syntaxhighlight>

This compiles to the following Luau bytecode (subject to further optimization):

{| role="presentation" class="wikitable mw-collapsible autocollapse mw-collapsed"
| Lua bytecode
|-
|<pre>
Function 0 (_floudSubtract):
SUB R2 R0 R1
GETIMPORT R3 2 [ll.OwnerSay]
GETIMPORT R6 5 [lsl.cast]
MOVE R7 R2
LOADN R8 3
CALL R6 2 1
LOADK R5 K6 ['New val is ']
CONCAT R4 R5 R6
CALL R3 1 0
RETURN R2 1
</pre>
|}

Okay, that's pretty decent. Some places where things could be more optimized, but no big deal. The equivalent Mono bytecode is (and bear with us, this is long:)

{| role="presentation" class="wikitable mw-collapsible autocollapse mw-collapsed"
| Mono bytecode
|-
|<pre>
.class public auto ansi serializable beforefieldinit
LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame
extends [UThread]LindenLab.SecondLife.UThread.UThreadStackFrame
{

.field public int32 ' pc'

.field public class LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575 ' instance'

.field public float32 val

.field public float32 'sub'

.field public float32 ' l0'

.field public int32 ' l1'

.method compilercontrolled specialname rtspecialname instance void
.ctor(
int32 _param1,
class LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575 _param2,
float32 _param3,
float32 _param4,
float32 _param5,
int32 _param6
) cil managed
{
.maxstack 4

IL_0000: ldarg.0 // this
IL_0001: call instance void [UThread]LindenLab.SecondLife.UThread.UThreadStackFrame::.ctor()

// [29 5 - 29 28]
IL_0006: ldarg.0 // this
IL_0007: ldarg.s _param1
IL_0009: nop
IL_000a: nop
IL_000b: nop
IL_000c: stfld int32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::' pc'

// [30 5 - 30 34]
IL_0011: ldarg.0 // this
IL_0012: ldarg.s _param2
IL_0014: nop
IL_0015: nop
IL_0016: nop
IL_0017: stfld class LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::' instance'

// [31 5 - 31 23]
IL_001c: ldarg.0 // this
IL_001d: ldarg.s _param3
IL_001f: nop
IL_0020: nop
IL_0021: nop
IL_0022: stfld float32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::val

// [32 5 - 32 23]
IL_0027: ldarg.0 // this
IL_0028: ldarg.s _param4
IL_002a: nop
IL_002b: nop
IL_002c: nop
IL_002d: stfld float32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::'sub'

// [33 5 - 33 28]
IL_0032: ldarg.0 // this
IL_0033: ldarg.s _param5
IL_0035: nop
IL_0036: nop
IL_0037: nop
IL_0038: stfld float32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::' l0'

// [34 5 - 34 28]
IL_003d: ldarg.0 // this
IL_003e: ldarg.s _param6
IL_0040: nop
IL_0041: nop
IL_0042: nop
IL_0043: stfld int32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::' l1'
IL_0048: ret

} // end of method LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::.ctor

.method public virtual instance object
Resume() cil managed
{
.maxstack 8

// [37 37 - 37 99]
IL_0000: ldarg.0 // this
IL_0001: ldfld class LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::' instance'
IL_0006: ldarg.0 // this
IL_0007: ldfld float32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::val
IL_000c: ldarg.0 // this
IL_000d: ldfld float32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::'sub'
IL_0012: call instance float32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575::gloudSubtract(float32, float32)
IL_0017: box [mscorlib]System.Single
IL_001c: ret

} // end of method LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::Resume
} // end of class LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame

// ... Within the actual script class

.method public hidebysig instance float32
gloudSubtract(
float32 val,
float32 'sub'
) cil managed
{
.maxstack 16
.locals init (
[0] float32 num1,
[1] int32 'l1[34-35], num2[69-151], num2[151-152]',
[2] class LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame c9eec9e37575gloudSubtractFrame,
[3] float32 num3
)

// [17 5 - 17 60]
IL_0000: call bool [UThread]LindenLab.SecondLife.UThread.UThread::IsRestoring()
IL_0005: brfalse IL_0036

// [19 7 - 19 202]
IL_000a: call class [UThread]LindenLab.SecondLife.UThread.UThreadStackFrame [UThread]LindenLab.SecondLife.UThread.UThread::Pop()
IL_000f: castclass LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame
IL_0014: stloc.2 // c9eec9e37575gloudSubtractFrame

// [20 7 - 20 53]
IL_0015: ldloc.2 // c9eec9e37575gloudSubtractFrame
IL_0016: ldfld float32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::' l0'
IL_001b: stloc.0 // num1

// [21 7 - 21 55]
IL_001c: ldloc.2 // c9eec9e37575gloudSubtractFrame
IL_001d: ldfld int32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::' l1'
IL_0022: stloc.1 // l1

// [22 7 - 22 55]
IL_0023: ldloc.2 // c9eec9e37575gloudSubtractFrame
IL_0024: ldfld int32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::' pc'
IL_0029: switch (IL_0085, IL_004b)

// [31 5 - 31 58]
IL_0036: call bool [UThread]LindenLab.SecondLife.UThread.UThread::IsSaveDue()
IL_003b: brfalse IL_004b

// [33 7 - 33 15]
IL_0040: ldc.i4 1 // 0x00000001
IL_0045: stloc.1 // num2

// [34 7 - 34 20]
IL_0046: br IL_0087

// [37 5 - 37 70]
IL_004b: ldarg.s 'sub'
IL_004d: nop
IL_004e: nop
IL_004f: nop
IL_0050: ldarg.s val
IL_0052: nop
IL_0053: nop
IL_0054: nop
IL_0055: call float64 [LslUserScript]LindenLab.SecondLife.LslUserScript::Subtract(float64, float64)
IL_005a: stloc.0 // num1

// [38 5 - 38 84]
IL_005b: ldloc.0 // num1
IL_005c: call string [LslLibrary]LindenLab.SecondLife.LslRunTime::ToString(float32)
IL_0061: ldstr "New val is "
IL_0066: call string [LslUserScript]LindenLab.SecondLife.LslUserScript::Add(string, string)
IL_006b: call void [LslLibrary]LindenLab.SecondLife.Library::llOwnerSay(string)

// [39 5 - 39 58]
IL_0070: call bool [UThread]LindenLab.SecondLife.UThread.UThread::IsSaveDue()
IL_0075: brfalse IL_0085

// [41 7 - 41 15]
IL_007a: ldc.i4 0 // 0x00000000
IL_007f: stloc.1 // num2

// [42 7 - 42 20]
IL_0080: br IL_0087

// [45 5 - 45 17]
IL_0085: ldloc.0 // num1
IL_0086: ret
IL_0087: nop

// [47 5 - 47 194]
IL_0088: ldloc.1 // num2
IL_0089: ldarg.0 // this
IL_008a: ldarg val
IL_008e: nop
IL_008f: nop
IL_0090: ldarg 'sub'
IL_0094: nop
IL_0095: nop
IL_0096: ldloc.0 // num1
IL_0097: ldloc.1 // num2
IL_0098: newobj instance void LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::.ctor(int32, class LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575, float32, float32, float32, int32)
IL_009d: pop

// [49 5 - 49 17]
IL_009e: ldloc.3 // num3
IL_009f: ret

} // end of method
}
</pre>
|}

While this might look unreasonably large, this is also pretty similar to how <code>async</code> C# functions that have <code>await</code>s get compiled. The code required to allow a function to pause in the middle to let other things run is necessarily very large, and our Mono bytecode instrumentation is essentially a special variant of that which optimizes for cases where the function won't have to pause. Try pasting the following code into sharplab.io (while decompiling to IL) and you'll see something very similar:

<pre>
using System.Threading.Tasks;
public class Example {
public async Task llOwnerSay(string val)
{
// stub
}

public async Task<float> loudSubtract(float val, float sub) {
float new_val = val - sub;
await llOwnerSay("New val is " + new_val.ToString());
return new_val;
}
}
</pre>

The Lua bytecode ends up being a lot smaller, because the Lua scripting engine itself knows how to handle this case, and doesn't need to add any special code to your scripts to allow them to be paused and resumed in the middle of a function.

Even though Mono has a JIT optimizer, which should in theory make the script run faster, this sort of code is very unusual, and the JIT optimizer isn't able to optimize it very well. That means that even though Luau itself is in theory slower, it's able to run LSL much faster than Mono can.

You might also notice things like call <code>float64 [LslUserScript]LindenLab.SecondLife.LslUserScript::Subtract(float64, float64)</code> in the Mono code. Those are necessary because of LSL's weird operand evaluation order, but are unnecessary in Luau because of the more efficient form of bytecode that Luau uses.

In general, C# doesn't aim at producing very small bytecode for async functions, which is important for something like Second Life where you might have thousands of different individual scripts running within a region. Luau does generate small bytecode, while still having decent performance, making it a good choice for Second Life. And hey, strings are UTF-8 in Lua instead of UTF-16 as in Mono, so they use much less memory for most data as well.

=== Are we going to get a higher memory limit in scripts? ===

Not at first, Luau uses less memory than Mono, so you shouldn't really miss it. You're not going to start hitting script memory limits just because you converted your script to Lua. Using Lua proper should allow you to more precisely control memory usage in your scripts, e.g. by being able to handle memory allocation errors in <code>pcall()</code> and access to the mutable <code>buffer</code> class for byte-packing.

There is some interest in giving specific scripts a little more memory if they're designated "high priority", like a main "game manager" object for an experience, but there are no specific plans for this at the moment.

=== Are my existing LSL scripts going to run on Lua Automatically? ===

While we can test running LSL in Lua now, and the idea is to eventually phase out Mono, there’s no immediate plans to transparently migrate existing scripts over to Lua. There are ideas about how this could be done safely without breaking existing content, but we want to make sure we have everything right before we start work on this.

=== How does interoperation with LSL work? ===

Everything that you expect from LSL should have some equivalent in Lua. There’s <code>key</code>s, <code>rotation</code>s and <code>vector</code>s and something like <code>some_vec * some_rot</code> in LSL is the exact same in Lua scripts.

All LSL functions will be available in Lua, and something like <code>llSay(0, “hi!”)</code> is just <code>ll.Say(0, “hi!”)</code> now. What about <code>llSetPos(llGetPos() + <0, 0, 1>);</code>? Just <code>ll.SetPos(ll.GetPos() + vector(0, 0, 1))</code>.

No special magic required here, and you can write whatever fancy wrappers you want around the existing LSL functions. We’ll be looking at how residents actually write these wrappers to inform the design of “official” higher-level Lua APIs, so we’re excited to see your ideas!

=== Can I mix LSL and Lua in the same script? ===

No, although most things should be a direct translation. At some point we may make a tool to help you do this, but there are no specific plans at the moment.

If your object has multiple scripts, you can mix LSL and Lua within the same object, though.

=== Can we use all of Lua? Is anything not there? ===

Most everything will be there, except for two notable exceptions:

* <code>getfenv()</code> / <code>setfenv()</code> / <code>_ENV</code> are not accessible because they necessarily make the script harder to optimize. Usually people only use this for mocking in test code, and this can be accomplished by passing in a parameter with a table of function references rather than pretending you have different global variable values for certain functions.
* <code>loadstring()</code> is not supported since it has a huge impact on performance. For those not familiar, this is equivalent to eval() in other languages. Every single time you call <code>loadstring()</code> the compiler has to go over what you passed in, compile it, and then load the generated bytecode. The Lua compiler isn’t particularly fast, and doing this can cause your script to halt in a way that we can’t interrupt to give other scripts time to run. This is a big part of why <code>eval()</code> and <code>loadstring()</code> are generally considered poor programming practice.

The one real use-case we could think of for <code>loadstring()</code> is a debugger, and we’re looking at implementing a “real” debugger that lets you step through your code. Note that this won’t happen with the initial release, but watch this space!

One thing that is planned, but will likely not be in the initial release is the coroutine library. This is one we’d really like to have in there, so you can do fancy things like have multiple “timers” in a script by just having coroutines that sleep every so often, but multiple running coroutines within the same script doesn’t fit well with the existing scripting architecture the Second Life server uses. Rest assured, this will be in there soon™ after Lua is released, but in the meantime you can still use something like the <code>Promise</code> chaining that JavaScript uses to write asynchronous event handlers.

We’ll have code demonstrating "proper" usage of Lua around the time that the public beta starts.

=== Why Lua? I wanted C#! ===

Great question!

The server Lua scripting initiative actually started off as an attempt to get C# working on Second Life, basically as a revival of the work started in the 2000s. The initial thought was “this should be pretty easy, most of the work was already done getting everything onto Mono!” A lot of effort was put in over several months to:

* Understand the Mono and .NET Core runtimes
* Observe how other Engines and Virtual Worlds have embedded C# and scripting in general
* Understand how recent advancements in scripting technologies (like WebAssembly) might make this integration easier
* Whether unique properties of how scripting / content creation works on Second Life would make this harder to implement

Unfortunately, the reasons we were ultimately unable to do this were very technical, so there’s no side-stepping a whole lot of tech-speak here, but there were several key properties that made integrating C# in Second Life rather difficult to implement:

==== Sandboxing with reflection is hard ====

Previous proof-of-concept code for C# in Second Life relied on CoreCLR sandboxing in Mono. This approach has fallen out of favor in recent years, because similar approaches led to many, many security holes in Java’s browser plugin. This sandboxing method is not possible in .NET Core, and has been totally removed.
Since this sandboxing is no longer in .NET, we need to rely on the ability to look at code to determine if it looks “dangerous” before running it. Some people have done this, but it can only be done properly by disabling reflection, which is a core part of C# and .NET! Without reflection, you’re unable to use the fancy third-party Newtonsoft.JSON libraries or whatnot that you would have otherwise been able to use.

Big portions of .NET’s standard library use reflection in a way that would be unsafe to expose to residents for scripting facilities, so you essentially have to maintain a list of functions and classes that are “safe” to use, and write alternatives to functions that are “unsafe” to call, but provide useful functionality. At this point, the scripting language that you’re exposing is a pretty bare-bones C# that needs to be scripted fundamentally differently from how you would write C# in Unity, for example.

Allowing the use of modern C# features would require migration off of Mono and onto .NET core, which would be more involved than integrating Lua. Mono is in maintenance mode at the moment, and only supports the legacy .NET framework
Ensuring that we’re able to correctly limit each script’s memory usage in a low-impact way is a bit of an unsolved problem in .NET Core. Generally, memory allocation tracking is something that you only do for debugging, but we need to do it for all scripts! What happens if you declare a static global in a C# script? Is the memory usage counted against all scripts of that type? Do all scripts share the data in that static variable?

What about if there’s a function in the standard library that keeps a static cache of data? How do we penalize (or not penalize) scripts for allocations that they didn’t even control? How do we make sure that data remains consistent across script unloads / reloads?

These are problems that most people embedding C# don’t need to solve, and the solutions that do exist are not generally workable into Second Life’s scripting model without multiple months of work. Most other virtual worlds do script sandboxing on a per-parcel or per-region level and put everything into the same logical scripting sandbox, which Second Life does not do. People would be rightly annoyed if someone’s HUD or attachments caused their parcel to go over the memory limit and things stopped working.

==== Making everything micro-threaded with extreme size constraints is hard ====

We need to be able to temporarily pause scripts in the middle of running an event handler so we can ensure we fairly schedule code execution. Previously, we wrote a script to do some quite clever binary instrumentation of .NET assemblies to inject yield points. This works quite well for for LSL scripts, but there are issues with C# in particular.

One is that it doesn’t handle the <code>try</code>/<code>finally</code> construct in C#. While not impossible to handle, this would be a difficult undertaking. Something that would be much more difficult is allowing pausing execution inside a constructor or other such special constructs in C#. While the stack induction and bytecode manipulation done by our current system is very cool, it is quite complex to update, relies on outdated tools that don’t work with new .NET versions, and necessarily requires making the bytecode quite a bit larger than it would otherwise be by injecting hooks.

But that’s not a huge deal, our .NET instrumentation library was written when <code>async</code>/<code>await</code> was not a thing in C#, so we should be able to inject <code>async</code>/<code>await</code> into user-provided source code instead to make it possible to transparently pause scripts right? Ehhhh, sort of. There are certain functions that cannot be made <code>async</code> in C# without breaking things. Object constructors are one of those, we have no way to pause and resume inside those. The situation is similar inside <code>ToString()</code> overloads. If we make a user-provided <code>ToString()</code> overload async, it’ll just never get called in cases where ToString() would normally get called! And what about implementing <code>IEnumerable.GetIterator()</code>? That might work… if you did a lot of work of replacing <code>IEnumerable</code> with <code>IAsyncEnumerable</code>., and <code>foreach</code> with <code>await foreach</code>... sometimes.

Suffice to say, that if you go this route, you end up with something that’s sort-of C# but is missing a lot of things people expect of C#, and may not behave the same as the regular C# that it pretends to be.

==== Saving script state ====

But let’s not forget one of the most important cases where SL is unique: Scripts can move into your inventory, across region boundaries, etc, without having to care too much that it even happened. Even if your script runs forever in a single function, that’s totally fine! For example, this is a valid LSL script:

default {
state_entry() {
integer i;
while(TRUE) {
llSetText("Run Number " + (string)(i++), <1,1,1>, 1);
}
}
}

All it does is run forever in the same function, incrementing a number in the floating text above an object. It still works if you take the object into your inventory, it still works if you move the object to another region, as a scripter you don't really have to care except in limited circumstances.

That's a pretty contrived example, but there are tons of scripts with a structure like this! Probably a more common example is a math-heavy function that just takes a while to run. Under the current model, you can interrupt what's going on by just picking up the object, then plop it back down later and let it continue on. There are a number of ways you can handle this without serializing the whole runtime state, like raising an exception in the middle of executing the function, but what are the chances that people will handle this correctly? How many command-line scripts have you used that do something really weird when you pressed <code>CTRL+C</code>?

To keep things simple for creators, we wanted to keep this nice property of LSL in whatever language we chose. This seemingly simple feature requires a lot of work because, think about it, how many programming languages let you seamlessly halt a program in the middle of it doing something, move it over to another computer, then resume whatever it was doing? Can you do that without doing a full-memory snapshot that would be gigabytes in size? That's not really a thing that people generally do, but it's required for us to not have sharp edges on our script creation experience!

We have a version of this in our Mono scripting engine, which was all written in-house. It works very well for LSL, but it has trouble with more complex structures. As it turns out, taking all the state of a running program, serializing it, then transparently deserializing it is a difficult problem, even with data that looks simple.

Suppose we have something like <code>Dictionary<SomeObject, int></code> that we use as a counter for how many times we've seen each <code>SomeObject</code>. What do you do if the <code>GetHashCode()</code> bucketing changes after the script deserializes and the memory increases? Can you prevent that from happening? Will live <code>IEnumerator</code>s still work correctly? How can you be sure of this? .NET makes no guarantees about any of this behavior, and good luck digging through the .NET source code to figure out if any of this is even the case.

What about types that aren't marked <code>[Serializable]</code>, including types in the standard library? Can people just not use those? Do we have to write special custom serializers for them? Could they just randomly break when the script is deserialized and we accept that as a consequence?

As you can see, there are a lot of hidden sharp edges involved in transparently moving scripts across servers, and the general answer provided when you ask about doing this is "That's very hard, make users write more intricate scripts that explicitly handle their own serialization and save their own state." This is fine if most of your users are professional programmers, not so if you have a mix of professional programmers and regular users who just want an object that counts how many people have clicked on their head.

==== Wrapping it up ====

This is a very small subset of the issues we ran into while trying to design a satisfactory C#-based scripting system that fits Second Life's needs. Seriously, there's about 20 pages of notes.

Meanwhile, Lua makes most of these things easy. Want to halt a script mid-execution? Okay, set an interrupt handler. Want to serialize your script while it's running and have it move to another server? Okay, there are libraries that have existed for decades that can do this. Fable's save file system was based on this. Quite a lot of scripting engine integration problems we have that would rise to the level of extremely difficult and relatively novel Computer Science research in .NET (and by extension, C#) are relatively simple to do with Lua.

=== Okay, but seriously, why Lua specifically? Because it's popular for games? Because <other platform> uses it? Why not <X>? ===

Actually, no. Neither other users of Lua, or a specific love of the language had anything to do with the decision. If you prefer a different programming language, there's a good chance we considered it. We actually looked at quite a lot of different languages and their associated engines, including JavaScript and WebAssembly, Lua was considered fairly late in the process. The ones below are just a small subset of the ones that we looked at:

[[File:Lsl_vm_comparison.png|1000px]]

As you can see, Luau was the only scripting runtime that fulfilled all of our requirements for a scripting engine within Second Life, and we arrived at it quite late in the decision process. We wanted something that we knew could deliver a high-quality scripting experience to creators, and we believe that Lua can best provide it.

=== I genuinely hate Lua and refuse to use it ===

A lot of people feel the same about LSL! Kidding aside, this is a totally defensible position, Lua can be a quirky language. Yes, it's strange that array indices start at 1. Yes, sometimes you can forget that you join strings with <code>..</code> and not <code>+</code>. It can take some getting used to.

A big part of the reason why we're using Luau is due to the quality of the scripting engine itself, not specifically the language. A lot of issues people had with older versions of Lua have been addressed in Luau, and ones that haven't been for one reason or another can be easily dealt with since we have such a high degree of control over the scripting engine now. Luau is very easy to modify. If we find that there are real quality-of-life issues with Lua that people run into while writing scripts, we can just change how it works, assuming the benefits outweigh the cost of breaking interoperability with Lua scripts from elsewhere.

But hey, maybe you really still hate the idea of using Lua. That's fine! The nice thing about having Lua instead of just LSL is there are a number of languages that can compile down to Lua code that could potentially work in Second Life! People have done work to get TypeScript and C# compiling to Lua, and it works pretty well for them, and there's also more exotic languages like MoonScript that target Lua specifically. See this GitHub repo for a listing: https://github.com/hengestone/lua-languages

If you're so inclined, you can go as far as to take the Luau transpiler and hack it up to support <code>!=</code> and <code>//</code> comments and really whatever you want. So long as it can take that source and output it to standard Lua, you're good.

=== Are you going to be using Lua 5.1? Why not 5.4? ===

We're using Luau as the base, which is ''compatible'' with Lua 5.1 but not necessarily Lua 5.1. It includes various features of PUC-Rio's Lua implementation up to and including 5.4. The Luau Compatibility reference is a good guide for which features are taken from which versions of PUC-Rio Lua: https://luau-lang.org/compatibility

=== Are there going to be integer types in SL's Lua implementation? ===

We have added 32-bit integers but they are strictly for compatibility with existing LSL APIs where integer type identity is important within a list (<code>llSetPrimitiveParams()</code> and friends.) They don't have a literal form in Luau scripts and in general you should just use regular Lua numbers if you care about performance, since the Luau VM optimizes for their use, but technically you can use them. The Luau project discussions have some explanation as to why integers aren't a first-class user-facing type in Luau https://github.com/luau-lang/luau/discussions/242#discussioncomment-1707387.

==== Are integer operations supported at all, then? (i.e. bitwise operators) ====

Yes, through the <code>bit32</code> library. In fact, ''more'' integer operations than are currently supported in LSL, like logical shift right and rotate operations. See https://luau-lang.org/library#bit32-library .

Lua Alpha

2025-03-13T22:55:58Z

Signal Linden:

{{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.

'''🚨 PLEASE NOTE Memory and performance characteristics, and API specifics may change! Scripts are currently being run in unoptimized form for development purposes.'''}}

= Second Life Lua (SLua) Alpha =

[[File:Luau.png|720px|thumb|right|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 [https://wiki.secondlife.com/wiki/Lua_FAQ 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 [https://lindenlab.freshdesk.com/support/solutions/articles/31000156725-accessing-aditi Aditi beta grid].

* Access the latest build of the SLua-enabled Second Life Viewer from [https://releasenotes.secondlife.com/viewer/7.1.12.13526902562.html here].

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

* [secondlife://Aditi/secondlife/SLua%20Yardang/241/235/27 SLua Yardang]
* [secondlife://Aditi/secondlife/SLua%20Tombolo/241/235/27 SLua Tombolo]
* [secondlife://Aditi/secondlife/SLua%20Mesa/241/235/27 SLua Mesa]
* [secondlife://Aditi/secondlife/SLua%20Tideland/241/235/27 SLua 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).

[[File:Compiler_dropdown.png|Compiler selection dropdown]]

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 <code>{}</code> for ''tables'', unlike LSL where <code>[]</code> is used for ''lists''.
** When calling LL functions in SLua, lists often have type-strict requirements, unlike Luau in general.
*** For example, <code>ll.SetPrimitiveParams({PRIM_GLOW, 0, 1})</code> will cause a type-error because <code>0</code> is a Luau <code>number</code> type, instead of the LSL <code>integer</code> type expected by [[llSetPrimitiveParams]]. For cases like this, there are special functions which provide the correct data types.
*** Correct: <code>ll.SetPrimitiveParams({PRIM_GLOW, integer(0), 1})</code>
*** 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 [https://luau.org/library#coroutine-library coroutine library documentation] for more details.
* '''Bitwise Operations:'''
** SLua includes a ''bit32'' library for bitwise operations, enabling more efficient data manipulation.
** Refer to the [https://luau.org/library#bit32-library 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 [https://luau.org/library 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 [https://wiki.secondlife.com/wiki/Lua_FAQ 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.
<source lang="lua">
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()
</source>

=== dialog.lua ===
This script demonstrates how one can interact with dialog menus.
<source lang="lua">
-- 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()
</source>

=== user_input_coroutine.lua ===
This script demonstrates [https://www.lua.org/pil/9.html coroutines] and how they can simplify the overarching logic of a script, enabling us to write the bulk of our multi-event code within a centralized function instead of fragmenting across separate event handlers.
<source lang="lua">
-- Wait for user input mid-function before doing something useful with it.
main = function(toucher)
local handle = ll.Listen(0, "", toucher, "")
local event = touch_start -- save function for later
touch_start = nil -- disable touch_start

ll.RegionSayTo(toucher, 0, "Do you want pants or gloves?")
local clothing = coroutine.yield() -- pause the routine's execution here
ll.RegionSayTo(toucher, 0, "For men or women?")
local gender = coroutine.yield()
ll.RegionSayTo(toucher, 0, "Favorite color?")
local color = coroutine.yield()
ll.RegionSayTo(toucher, 0, "Here's "..color.." "..clothing.." for "..gender)

ll.ListenRemove(handle)
touch_start = event -- restore touch_start
end

function touch_start(total_num)
local toucher = ll.DetectedKey(0)
routine = coroutine.create(main) -- new coroutine
coroutine.resume(routine, toucher) -- run coroutine (with one argument)
end

-- When the coroutine is suspended, incoming events can be handled
-- and we can resume() execution of the routine
-- and pass any number of arguments to be returned by yield()
function listen(channel, name, id, message)
coroutine.resume(routine, message)
end
</source>

=== multi_user_input_coroutine.lua ===
Following from the above example, how can we handle multiple users? This is where coroutines shine.

Instead of disabling touches to prevent others from interacting with the object, we can create new copies of the coroutine each time an avatar touches the object. We can then resume whichever coroutine is needed, based on the avatar, while all of them track their own progress separately and automagically.
<source lang="lua">
-- Key: avatar uuid; Value: coroutine thread
routines = {}

main = function(toucher)
local handle = ll.Listen(0, "", toucher, "")

ll.RegionSayTo(toucher, 0, "Do you want pants or gloves?")
local clothing = coroutine.yield()
ll.RegionSayTo(toucher, 0, "For men or women?")
local gender = coroutine.yield()
ll.RegionSayTo(toucher, 0, "Favorite color?")
local color = coroutine.yield()
ll.RegionSayTo(toucher, 0, "Here's "..color.." "..clothing.." for "..gender)

ll.ListenRemove(handle)
routines[toucher] = nil -- Remove from collection
end

function touch_start(total_num)
local toucher = ll.DetectedKey(0)
local routine = routines[toucher]
if not routine then -- New user needs new routine
routine = coroutine.create(main)
routines[toucher] = routine -- Add to collection
coroutine.resume(routine, toucher)
end
end

function listen(channel, name, id, message)
coroutine.resume(routines[id], message) -- Resume a specific coroutine
end
</source>

=== More Examples ===

* Find more example scripts at [[Luau Example Scripts]]

* [https://roblox.github.io/lua-style-guide/gotchas/ Lua Gotchas, Footguns and Other Hazards]

Try Lua

2025-03-13T20:23:02Z

Signal Linden: Created page with "'''Try Out SLua (Lua in Second Life) on the Beta Grid!''' Experience the next evolution of scripting in Second Life with SLua. Follow these steps to dive in: == 1. Create an..."

'''Try Out SLua (Lua in Second Life) on the Beta Grid!'''

Experience the next evolution of scripting in Second Life with SLua. Follow these steps to dive in:

== 1. Create an Account ==
# Go to [https://join.secondlife.com join.secondlife.com].
# Sign up for your free Second Life account.

== 2. Install the Alpha Client ==
# Visit [https://second.life/alternate-viewers second.life/alternate-viewers].
# Download and install '''Second Life Project Lua Editor'''.

== 3. Connect to the Beta Grid ==
# Launch '''Project Lua Editor'''.
# Go to '''Me > Preferences > Advanced''' and enable '''Show Grid Selection at login'''.
# At the login screen, select '''Beta Test Grid (Aditi)''' from the drop-down menu.
# Click '''Log In'''.

== 4. Teleport to an SLua Region ==
# Click the '''Map''' button.
# Search for '''"SLua"'''.
# Select a region and click '''Teleport''' to enter a sandbox area.

== 5. Start Scripting in SLua ==
# Enter Build mode ('''Build > Build''').
# Rez a box, then open its '''Content''' tab.
# Click '''New Script''' and start coding in '''SLua'''!

For more information about scripting with SLua, visit [[SLua Alpha]].

=== Additional Resources ===
* [https://second.life/accessing-aditi Beta grid (Aditi) instructions]

Lua Alpha

2025-03-12T01:35:44Z

Signal Linden:

Luau Alpha

2025-03-12T01:32:11Z

Signal Linden: Signal Linden moved page Luau Alpha to SLua Alpha

#REDIRECT [[SLua Alpha]]

Lua Alpha

2025-03-12T01:32:09Z

Signal Linden: Signal Linden moved page Luau Alpha to SLua Alpha

Lua Alpha

2025-03-05T01:09:09Z

Signal Linden:

Lua Alpha

2025-03-05T01:07:41Z

Signal Linden:

Luau Examples

2025-03-04T23:05:47Z

Signal Linden:

__TOC__

Example [[Luau Alpha|Luau]] scripts

== vehicle.lua ==
This script demonstrates how one may create their own vehicle scripts, which don’t rely on the underlying LL vehicle system.
<source lang="lua">
-- Control and permission constants
local PERMISSION_TAKE_CONTROLS = 0x4
local CONTROL_FWD = 0x1
local CONTROL_BACK = 0x2
local CONTROL_UP = 0x10
local CONTROL_DOWN = 0x20
local CONTROL_LEFT = 0x4
local CONTROL_RIGHT = 0x8
local PRIM_ROT_LOCAL = integer(29)

-- These two will hold the link numbers for left and right front wheels
local LINK_WHEEL_LEFT = 0
local LINK_WHEEL_RIGHT = 0

-- Integra Type R Engine properties
local Engine = {
rpm = 800, -- current engine RPM (starts at idle)
gear = 0, -- 0 = neutral; -1 = reverse; 1-5 for forward gears
idleRPM = 800, -- idle RPM
maxRPM = 8300, -- redline
throttle = 0.0, -- throttle value (0.0 to 1.0)
gearRatios = { -- Integra Type R gear ratios
[-1] = 3.727, -- reverse gear ratio
[0] = 0, -- neutral
[1] = 3.727,
[2] = 2.256,
[3] = 1.729,
[4] = 1.416,
[5] = 1.194
}
}

local FINAL_DRIVE = 4.1 -- Final drive ratio
local WHEEL_RADIUS = 0.3 -- in meters

-- Vehicle properties (using realistic Integra Type R mass)
local Vehicle = {
speed = 0, -- speed in m/s; negative indicates reverse motion
mass = 1200, -- mass in kg
angle = 0, -- heading angle in radians
steering = 0, -- steering input: -1 (left), 0 (none), 1 (right)
brake = false -- flag indicating if brakes are applied
}

-- Engine constants (using realistic Integra Type R values)
local MAX_TORQUE = 200 -- in Nm

-- Brake force constant (for active braking)
local BRAKE_FORCE = 4000 -- in Newtons

-- Define a torque curve function:
local function torqueCurve(rpm)
local peakRPM = 6000
if rpm < peakRPM then
return 0.8 + 0.2 * ((rpm - Engine.idleRPM) / (peakRPM - Engine.idleRPM))
else
local factor = 1 - 0.5 * ((rpm - peakRPM) / (Engine.maxRPM - peakRPM))
return math.max(0.5, factor)
end
end

-- Engine braking force when throttle is zero in gear.
local ENGINE_BRAKE_FORCE = 2000 -- in Newtons

-- Friction and drag constants
local G = 9.81 -- gravity (m/s^2)
local C_rr_inGear = 0.015 -- rolling resistance coefficient in gear
local C_rr_neutral = 0.05 -- rolling resistance coefficient in neutral

local airDensity = 1.225 -- kg/m^3
local dragCoefficient = 0.3 -- aerodynamic drag coefficient
local frontalArea = 2.2 -- in m^2

local function getAerodynamicDrag(speed)
return 0.5 * airDensity * dragCoefficient * frontalArea * speed * speed
end

-- Compute engine RPM from vehicle speed when in gear.
local function computeEngineRPMFromSpeed()
if Engine.gear == 0 then
return Engine.rpm -- In neutral, RPM is managed independently.
else
local conversionFactor = Engine.gearRatios[Engine.gear] * FINAL_DRIVE * (60 / (2 * math.pi * WHEEL_RADIUS))
local rpm = math.abs(Vehicle.speed) * conversionFactor
if rpm < Engine.idleRPM then rpm = Engine.idleRPM end
return rpm
end
end

-- For neutral, update RPM toward a target based on throttle.
local function updateEngineRPMNeutral()
local targetRPM = Engine.idleRPM + (Engine.maxRPM - Engine.idleRPM) * Engine.throttle
local changeRate = 200 -- RPM per tick
if Engine.rpm < targetRPM then
Engine.rpm = math.min(Engine.rpm + changeRate, targetRPM)
elseif Engine.rpm > targetRPM then
Engine.rpm = math.max(Engine.rpm - changeRate, targetRPM)
end
end

-- Calculate the engine force delivered to the wheels.
local function getEngineForce()
if Engine.gear == 0 then
return 0 -- In neutral, no drive force is transmitted.
else
if Engine.throttle == 0 then
-- Apply engine braking when throttle is released.
return -ENGINE_BRAKE_FORCE
else
local torque = Engine.throttle * MAX_TORQUE * torqueCurve(Engine.rpm)
local force = (torque * Engine.gearRatios[Engine.gear] * FINAL_DRIVE) / WHEEL_RADIUS
return force
end
end
end

-- Starts the engine by setting it to idle RPM.
local function startEngine()
Engine.rpm = Engine.idleRPM
ll.Say(0, "Engine started. RPM: " .. Engine.rpm)
end

-- Shifts the gear if valid.
local function shiftGear(newGear)
if Engine.gearRatios[newGear] then
Engine.gear = newGear
ll.Say(0, "Shifted to gear " .. newGear)
else
ll.Say(0, "Invalid gear: " .. newGear)
end
end

local function findWheels()
local total = ll.GetNumberOfPrims()
for i = 1, total do
local name = ll.GetLinkName(i)
if name == "WHEEL_LF" then
LINK_WHEEL_LEFT = i
elseif name == "WHEEL_RF" then
LINK_WHEEL_RIGHT = i
end
end
end

local castRayCounter = 0
local lastGrounded = false

local function isVehicleOnGround()
castRayCounter = castRayCounter + 1
if castRayCounter >= 5 then
castRayCounter = 0
local pos = ll.GetPos()
local rayDistance = 4.5 -- threshold distance (in meters) to consider as "grounded"
local rayStart = pos
local rayEnd = pos + vector(0, 0, -rayDistance)
local hitResult = ll.CastRay(rayStart, rayEnd, {})
if table.getn(hitResult) == 3 then
lastGrounded = true
else
lastGrounded = false
end
end
return lastGrounded
end

-- Timer event: updates engine, vehicle physics, steering, and rotates the wheels based on steering.
function timer()
local dt = 0.1 -- time step in seconds

-- For neutral, update RPM based on throttle.
if Engine.gear == 0 then
updateEngineRPMNeutral()
end

-- Calculate forces.
local C_rr = (Engine.gear == 0) and C_rr_neutral or C_rr_inGear
local F_roll = Vehicle.mass * G * C_rr
local engineForce = getEngineForce()
local dragForce = getAerodynamicDrag(math.abs(Vehicle.speed))
local netForce = engineForce - (F_roll + dragForce)

-- Apply braking force if brakes are engaged.
if Vehicle.brake then
netForce = netForce - BRAKE_FORCE
end

local acceleration = netForce / Vehicle.mass
local vel = ll.GetVel()
local horizontal_vec = vector(vel.x, vel.y, 0)
Vehicle.speed = (ll.VecMag(horizontal_vec) + acceleration * dt)

-- Limit vehicle speed based on gear.
if Engine.gear ~= 0 then
if Vehicle.speed < 0 then
Vehicle.speed = 0
end
local conversionFactor = Engine.gearRatios[Engine.gear] * FINAL_DRIVE * (60 / (2 * math.pi * WHEEL_RADIUS))
local maxSpeed = Engine.maxRPM / conversionFactor
if Vehicle.speed > maxSpeed then
Vehicle.speed = maxSpeed
end
end

-- When in gear, update RPM based on the new speed.
if Engine.gear ~= 0 then
Engine.rpm = computeEngineRPMFromSpeed()
end

-- Steering update using angular velocity and quaternions:
local STEERING_RATE = math.rad(6) -- desired steering rate per tick (radians)
local yawDelta = Vehicle.steering * STEERING_RATE -- small rotation for this tick

if yawDelta ~= 0 then
local deltaQuat = ll.Euler2Rot(vector(0, 0, yawDelta))
local angularSpeed = yawDelta / dt
local angularVelocity = vector(0, 0, angularSpeed)
ll.SetAngularVelocity(angularVelocity, 1)
Vehicle.angle = Vehicle.angle + yawDelta
else
ll.SetAngularVelocity(vector(0, 0, 0), 1)
end

-- Display engine RPM and speed (converted to mph).
local speed_mph = math.abs(Vehicle.speed) * 2.23694
ll.SetText("RPM: " .. math.floor(Engine.rpm) ..
" | Speed: " .. string.format("%.1f", speed_mph) ..
" mph", vector(0,0,0), 1)

-- Only update velocity if the vehicle is near the ground, and we're in gear.
if isVehicleOnGround() and Engine.gear ~= 0 then
local velocityVector
if Engine.gear > 0 then
velocityVector = vector(Vehicle.speed, 0, 0)
else
-- Reverse gear
velocityVector = vector(-Vehicle.speed, 0, 0)
end
ll.SetVelocity(velocityVector, 1)
end

-- Update the wheel rotations to visually match the steering.
local maxWheelTurn = math.rad(30) -- maximum wheel turn angle in radians
local wheelAngle = -Vehicle.steering * maxWheelTurn

if LINK_WHEEL_LEFT > 0 then
ll.SetLinkPrimitiveParamsFast(
LINK_WHEEL_LEFT,
{
PRIM_ROT_LOCAL,
ll.Euler2Rot(vector(-4.71239, -wheelAngle, 0))
}
)
end

if LINK_WHEEL_RIGHT > 0 then
ll.SetLinkPrimitiveParamsFast(
LINK_WHEEL_RIGHT,
{
PRIM_ROT_LOCAL,
ll.Euler2Rot(vector(4.71239, wheelAngle, 0))
}
)
end
end

-- Called when the object is touched: starts engine and simulation.
function touch_start(num)
ll.Say(0, "Touch detected, requesting controls and starting engine.")
ll.RequestPermissions(ll.GetOwner(), PERMISSION_TAKE_CONTROLS)
startEngine()
findWheels()
ll.SetTimerEvent(0.1)
end

-- Called when runtime permissions are granted.
function run_time_permissions(perm)
if bit32.band(perm, PERMISSION_TAKE_CONTROLS) then
ll.Say(0, "Permissions granted.")
local controlMask = bit32.bor(CONTROL_FWD, CONTROL_BACK, CONTROL_UP, CONTROL_DOWN, CONTROL_LEFT, CONTROL_RIGHT)
ll.TakeControls(controlMask, 1, 1)
end
end

-- Handle control events:
-- • CONTROL_FWD applies throttle.
-- • CONTROL_BACK applies the brakes.
-- • CONTROL_UP and CONTROL_DOWN shift gears.
-- • CONTROL_LEFT and CONTROL_RIGHT steer the vehicle.
function control(avatar_id, level, edge)
local start = bit32.band(level, edge)
local finish = bit32.band(bit32.bnot(level), edge)
local held = bit32.band(level, bit32.bnot(edge))
local untouched = bit32.bnot(bit32.bor(level, edge))

if bit32.band(held, CONTROL_BACK) ~= 0 then
Vehicle.brake = true
Engine.throttle = 0.0
elseif bit32.band(held, CONTROL_FWD) ~= 0 then
Vehicle.brake = false
Engine.throttle = 1.0
if Engine.gear == 0 then
updateEngineRPMNeutral()
end
else
Vehicle.brake = false
Engine.throttle = 0.0
end

if bit32.band(start, CONTROL_UP) ~= 0 then
shiftGear(Engine.gear + 1)
end

if bit32.band(start, CONTROL_DOWN) ~= 0 then
shiftGear(Engine.gear - 1)
end

local steeringInput = 0
if bit32.band(held, CONTROL_LEFT) ~= 0 then
steeringInput = steeringInput + 1
end
if bit32.band(held, CONTROL_RIGHT) ~= 0 then
steeringInput = steeringInput - 1
end
Vehicle.steering = steeringInput
end

</source>

== weather_box.lua ==
This script demonstrates coroutines, as well as working with a JSON-based web API:
<source lang="lua">
local TEXTBOX_CHANNEL = 323242
-- kludge because we don't have LSL constants in here yet
local HTTP_BODY_MAXLENGTH = integer(2)
local PRIM_TEXT = integer(26)
local PRIM_SIZE = integer(7)

gCityName = ""
gLatLong = nil -- A table of 2 elems when it's populated
gCityRequestTask = nil
gWeatherRequestTask = nil

-----
-- JSON stuff
-----

-- From https://github.com/rxi/json.lua/blob/master/json.lua

local json = {}

local escape_char_map = {
[ "\\" ] = "\\",
[ "\"" ] = "\"",
[ "\b" ] = "b",
[ "\f" ] = "f",
[ "\n" ] = "n",
[ "\r" ] = "r",
[ "\t" ] = "t",
}

local escape_char_map_inv = { [ "/" ] = "/" }
for k, v in pairs(escape_char_map) do
escape_char_map_inv[v] = k
end

local parse

local function create_set(...)
local res = {}
for i = 1, select("#", ...) do
res[ select(i, ...) ] = true
end
return res
end

local space_chars = create_set(" ", "\t", "\r", "\n")
local delim_chars = create_set(" ", "\t", "\r", "\n", "]", "}", ",")
local escape_chars = create_set("\\", "/", '"', "b", "f", "n", "r", "t", "u")
local literals = create_set("true", "false", "null")

local literal_map = {
[ "true" ] = true,
[ "false" ] = false,
[ "null" ] = nil,
}

local function next_char(str, idx, set, negate)
for i = idx, #str do
if set[str:sub(i, i)] ~= negate then
return i
end
end
return #str + 1
end

local function decode_error(str, idx, msg)
local line_count = 1
local col_count = 1
for i = 1, idx - 1 do
col_count = col_count + 1
if str:sub(i, i) == "\n" then
line_count = line_count + 1
col_count = 1
end
end
error( string.format("%s at line %d col %d", msg, line_count, col_count) )
end

local function codepoint_to_utf8(n)
-- http://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=iws-appendixa
local f = math.floor
if n <= 0x7f then
return string.char(n)
elseif n <= 0x7ff then
return string.char(f(n / 64) + 192, n % 64 + 128)
elseif n <= 0xffff then
return string.char(f(n / 4096) + 224, f(n % 4096 / 64) + 128, n % 64 + 128)
elseif n <= 0x10ffff then
return string.char(f(n / 262144) + 240, f(n % 262144 / 4096) + 128,
f(n % 4096 / 64) + 128, n % 64 + 128)
end
error( string.format("invalid unicode codepoint '%x'", n) )
end

local function parse_unicode_escape(s)
local n1 = tonumber( s:sub(1, 4), 16 )
local n2 = tonumber( s:sub(7, 10), 16 )
-- Surrogate pair?
if n2 then
return codepoint_to_utf8((n1 - 0xd800) * 0x400 + (n2 - 0xdc00) + 0x10000)
else
return codepoint_to_utf8(n1)
end
end

local function parse_string(str, i)
local res = ""
local j = i + 1
local k = j

while j <= #str do
local x = str:byte(j)

if x < 32 then
decode_error(str, j, "control character in string")

elseif x == 92 then -- `\`: Escape
res = res .. str:sub(k, j - 1)
j = j + 1
local c = str:sub(j, j)
if c == "u" then
local hex = str:match("^[dD][89aAbB]%x%x\\u%x%x%x%x", j + 1)
or str:match("^%x%x%x%x", j + 1)
or decode_error(str, j - 1, "invalid unicode escape in string")
res = res .. parse_unicode_escape(hex)
j = j + #hex
else
if not escape_chars[c] then
decode_error(str, j - 1, "invalid escape char '" .. c .. "' in string")
end
res = res .. escape_char_map_inv[c]
end
k = j + 1

elseif x == 34 then -- `"`: End of string
res = res .. str:sub(k, j - 1)
return res, j + 1
end

j = j + 1
end

decode_error(str, i, "expected closing quote for string")
end

local function parse_number(str, i)
local x = next_char(str, i, delim_chars)
local s = str:sub(i, x - 1)
local n = tonumber(s)
if not n then
decode_error(str, i, "invalid number '" .. s .. "'")
end
return n, x
end

local function parse_literal(str, i)
local x = next_char(str, i, delim_chars)
local word = str:sub(i, x - 1)
if not literals[word] then
decode_error(str, i, "invalid literal '" .. word .. "'")
end
return literal_map[word], x
end

local function parse_array(str, i)
local res = {}
local n = 1
i = i + 1
while 1 do
local x
i = next_char(str, i, space_chars, true)
-- Empty / end of array?
if str:sub(i, i) == "]" then
i = i + 1
break
end
-- Read token
x, i = parse(str, i)
res[n] = x
n = n + 1
-- Next token
i = next_char(str, i, space_chars, true)
local chr = str:sub(i, i)
i = i + 1
if chr == "]" then break end
if chr ~= "," then decode_error(str, i, "expected ']' or ','") end
end
return res, i
end

local function parse_object(str, i)
local res = {}
i = i + 1
while 1 do
local key, val
i = next_char(str, i, space_chars, true)
-- Empty / end of object?
if str:sub(i, i) == "}" then
i = i + 1
break
end
-- Read key
if str:sub(i, i) ~= '"' then
decode_error(str, i, "expected string for key")
end
key, i = parse(str, i)
-- Read ':' delimiter
i = next_char(str, i, space_chars, true)
if str:sub(i, i) ~= ":" then
decode_error(str, i, "expected ':' after key")
end
i = next_char(str, i + 1, space_chars, true)
-- Read value
val, i = parse(str, i)
-- Set
res[key] = val
-- Next token
i = next_char(str, i, space_chars, true)
local chr = str:sub(i, i)
i = i + 1
if chr == "}" then break end
if chr ~= "," then decode_error(str, i, "expected '}' or ','") end
end
return res, i
end

local char_func_map = {
[ '"' ] = parse_string,
[ "0" ] = parse_number,
[ "1" ] = parse_number,
[ "2" ] = parse_number,
[ "3" ] = parse_number,
[ "4" ] = parse_number,
[ "5" ] = parse_number,
[ "6" ] = parse_number,
[ "7" ] = parse_number,
[ "8" ] = parse_number,
[ "9" ] = parse_number,
[ "-" ] = parse_number,
[ "t" ] = parse_literal,
[ "f" ] = parse_literal,
[ "n" ] = parse_literal,
[ "[" ] = parse_array,
[ "{" ] = parse_object,
}

parse = function(str, idx)
local chr = str:sub(idx, idx)
local f = char_func_map[chr]
if f then
return f(str, idx)
end
decode_error(str, idx, "unexpected character '" .. chr .. "'")
end

function json.decode(str)
if type(str) ~= "string" then
error("expected argument of type string, got " .. type(str))
end
local res, idx = parse(str, next_char(str, 1, space_chars, true))
idx = next_char(str, idx, space_chars, true)
if idx <= #str then
decode_error(str, idx, "trailing garbage")
end
return res
end

-----
-- Event Loop
-----

-- A naive little event loop that lets you track running coroutines and dispatches
-- the events they're waiting for to them.

local EventLoop = {
-- Coroutine -> awaited event
_coros = {},
running = false
}

function EventLoop:create_task(func)
local coro = coroutine.create(func)
-- false has no semantic meaning here, we just want to reserve the space for
-- the coroutine in the table without saying we're awaiting anything yet.
self._coros[coro] = false
self:_run_coro(coro)
return coro
end

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

-- (internal) run the event
function EventLoop:_run_coro(coro, ...)
assert(coroutine.status(coro) ~= "dead")
-- assert(not self.running)
local old_running = self.running
self.running = true

-- Since we're running, this isn't currently awaiting anything
self._coros[coro] = false
local success, ret = coroutine.resume(coro, ...)
self.running = old_running

-- If we're not done then ret should be the kind of event we're awaiting.
-- Otherwise it's an error message or something. Who cares.
if not success then
-- Get rid of the coro
if ret then
ll.OwnerSay(`Might have an error: {ret}`)
end
ret = nil
end
self._coros[coro] = ret
end

-- Wake up any tasks that are waiting for this kind of event
function EventLoop:handle_event(name, ...)
-- We may mutate self._coros, so do a clone
local coros = table.clone(self._coros)
ll.OwnerSay(`Handling {name}`)

for coro, awaited_event in coros do
if coroutine.status(coro) == "dead" then
-- Hmm, this coroutine is dead, prune it.
self._coros[coro] = nil
end

if awaited_event == name then
ll.OwnerSay(`Dispatching {name} to {coro}`)
self:_run_coro(coro, ...)
end
end
end

function EventLoop:create_event_catcher(name)
local function catcher(...)
ll.OwnerSay("yay")
EventLoop:handle_event(name, ...)
end
return catcher
end

-- Helper function for waiting and telling the EventLoop what event you want
local function await_event(kind)
-- You had better do this inside a running event loop
assert(EventLoop.running)
-- This will yield, the EventLoop will resume us once it has
-- an event we might be interested in.
return coroutine.yield(kind)
end

-----
-- Script-specific functions
-----

local function hide_children()
for i=2,ll.GetNumberOfPrims() do
-- Hide all the child prims
ll.SetLinkAlpha(i, 0, -1)
ll.SetLinkPrimitiveParamsFast(i, {
PRIM_SIZE, vector(0.5, 0.5, 0.5),
PRIM_TEXT, "", vector(1,1,1), 1
})
end
end

local function send_textbox(avatar_id, message, channel)
ll.TextBox(avatar_id, message, channel)

while true do
local resp_channel, name, id, resp = await_event("listen")
if id ~= avatar_id or channel ~= resp_channel then
-- If this isn't a message we're interested in then wait for the next event
ll.OwnerSay(`{id}, {avatar_id}, {resp_channel}, {channel}`)
continue
end
return resp
end
end

local function make_json_request(url)
local req_id = ll.HTTPRequest(url, {HTTP_BODY_MAXLENGTH, integer(16000)}, "")
while true do
local ev_id, status, metadata, body = await_event("http_response")
if ev_id ~= req_id then
-- Not a response for the HTTP request we were waiting on, wait for the next event.
continue
end
return status, metadata, body
end
end

local function request_weather()
-- And you can use a wrapper like this to make an async function callable within both normal and coroutine contexts.
-- Normally this sort of thing would not be necessary, but here it is since the EventLoop lives in our own code,
-- and isn't a property of the actual script engine.
if gWeatherRequestTask then
EventLoop:kill_task(gWeatherRequestTask)
end

gWeatherRequestTask = EventLoop:create_task(function()
ll.OwnerSay("Requesting weather")
local status, metadata, body = make_json_request(`https://api.open-meteo.com/v1/forecast?latitude={gLatLong[1]}&longitude={gLatLong[2]}&current=temperature_2m&daily=temperature_2m_max`)
if status ~= 200 then
ll.OwnerSay("Error requesting weather")
return
end
local parsed = json.decode(body)

local current = parsed["current"]
ll.OwnerSay(`Temperature is {current["temperature_2m"]}C`)
ll.SetText(`Temperature in {gCityName} is currently {current["temperature_2m"]}C`, vector(1,1,1), 1)

-- Show the highs for each day
local days = parsed["daily"]["temperature_2m_max"]
for i=1,#days do
local link_num = i + 1
-- Higher temps = bigger on Z, negatives are unrepresentable :)
local z_size = (days[i] / 30) * 2
ll.SetLinkAlpha(link_num, 1, -1)
ll.SetLinkPrimitiveParamsFast(link_num, {
PRIM_SIZE, vector(0.5, 0.5, z_size),
PRIM_TEXT, `{days[i]}C`, vector(1,1,1), 1
})
end
end)
end

local function ask_for_city()
local resp = send_textbox(ll.GetOwner(), "What city do you want the weather for?", TEXTBOX_CHANNEL)
if not resp then
ll.OwnerSay("Got no response for city request.")
return
end

ll.OwnerSay(`You want the weather for {resp}.`)
gLatLong = nil
gCityName = resp

hide_children()

-- request the lat and long for this city
local status, metadata, body = make_json_request(`https://nominatim.openstreetmap.org/search.php?city={ll.EscapeURL(resp)}&format=jsonv2`)
local parsed = json.decode(body)
if not #parsed then
ll.OwnerSay(`Got no results for {resp}!`)
return
end

local first_result = parsed[1]
gLatLong = {first_result["lat"], first_result["lon"]}
ll.OwnerSay(`City Lat: {gLatLong[1]}, Long: {gLatLong[2]}`)

request_weather()

-- request weather again in 3 mins
ll.SetTimerEvent(180)
end

-----
-- Event Handlers
-----

-- If we don't care about conventionally dispatched events, we can just set the event handler to directly send
-- event data to the event loop.
http_response = EventLoop:create_event_catcher("http_response")
listen = EventLoop:create_event_catcher("listen")

-- More conventional event handlers work too.
function touch_start(num)
for i=0,num-1 do
if ll.GetOwner() ~= ll.DetectedKey(i) then
-- Go to next loop if it wasn't the owner touching us.
continue
end

if gCityRequestTask then
EventLoop:kill_task(gCityRequestTask)
end

-- Spin up a task to ask the user for their city
gCityRequestTask = EventLoop:create_task(ask_for_city)
break
end
end

function timer()
request_weather()
end

-- Not strictly necessary, but I like having the main function have its own scope.
-- Rather than just have top-level logic.
local function main()
ll.Listen(TEXTBOX_CHANNEL, "", "", "")
ll.SetText("", vector(1,1,1), 1)
hide_children()
ll.OwnerSay("Weatherbox operational!")
end

main()
</source>

Lua Alpha

2025-03-04T23:05:08Z

Signal Linden:

Luau Example Scripts

2025-03-04T23:04:06Z

Signal Linden: Signal Linden moved page Luau Example Scripts to Luau Examples

#REDIRECT [[Luau Examples]]

Luau Examples

2025-03-04T23:04:05Z

Signal Linden: Signal Linden moved page Luau Example Scripts to Luau Examples

= Luau Examples =

Example [[Luau Alpha|Luau]] scripts

== vehicle.lua ==
This script demonstrates how one may create their own vehicle scripts, which don’t rely on the underlying LL vehicle system.
<source lang="lua">
-- Control and permission constants
local PERMISSION_TAKE_CONTROLS = 0x4
local CONTROL_FWD = 0x1
local CONTROL_BACK = 0x2
local CONTROL_UP = 0x10
local CONTROL_DOWN = 0x20
local CONTROL_LEFT = 0x4
local CONTROL_RIGHT = 0x8
local PRIM_ROT_LOCAL = integer(29)

-- These two will hold the link numbers for left and right front wheels
local LINK_WHEEL_LEFT = 0
local LINK_WHEEL_RIGHT = 0

-- Integra Type R Engine properties
local Engine = {
rpm = 800, -- current engine RPM (starts at idle)
gear = 0, -- 0 = neutral; -1 = reverse; 1-5 for forward gears
idleRPM = 800, -- idle RPM
maxRPM = 8300, -- redline
throttle = 0.0, -- throttle value (0.0 to 1.0)
gearRatios = { -- Integra Type R gear ratios
[-1] = 3.727, -- reverse gear ratio
[0] = 0, -- neutral
[1] = 3.727,
[2] = 2.256,
[3] = 1.729,
[4] = 1.416,
[5] = 1.194
}
}

local FINAL_DRIVE = 4.1 -- Final drive ratio
local WHEEL_RADIUS = 0.3 -- in meters

-- Vehicle properties (using realistic Integra Type R mass)
local Vehicle = {
speed = 0, -- speed in m/s; negative indicates reverse motion
mass = 1200, -- mass in kg
angle = 0, -- heading angle in radians
steering = 0, -- steering input: -1 (left), 0 (none), 1 (right)
brake = false -- flag indicating if brakes are applied
}

-- Engine constants (using realistic Integra Type R values)
local MAX_TORQUE = 200 -- in Nm

-- Brake force constant (for active braking)
local BRAKE_FORCE = 4000 -- in Newtons

-- Define a torque curve function:
local function torqueCurve(rpm)
local peakRPM = 6000
if rpm < peakRPM then
return 0.8 + 0.2 * ((rpm - Engine.idleRPM) / (peakRPM - Engine.idleRPM))
else
local factor = 1 - 0.5 * ((rpm - peakRPM) / (Engine.maxRPM - peakRPM))
return math.max(0.5, factor)
end
end

-- Engine braking force when throttle is zero in gear.
local ENGINE_BRAKE_FORCE = 2000 -- in Newtons

-- Friction and drag constants
local G = 9.81 -- gravity (m/s^2)
local C_rr_inGear = 0.015 -- rolling resistance coefficient in gear
local C_rr_neutral = 0.05 -- rolling resistance coefficient in neutral

local airDensity = 1.225 -- kg/m^3
local dragCoefficient = 0.3 -- aerodynamic drag coefficient
local frontalArea = 2.2 -- in m^2

local function getAerodynamicDrag(speed)
return 0.5 * airDensity * dragCoefficient * frontalArea * speed * speed
end

-- Compute engine RPM from vehicle speed when in gear.
local function computeEngineRPMFromSpeed()
if Engine.gear == 0 then
return Engine.rpm -- In neutral, RPM is managed independently.
else
local conversionFactor = Engine.gearRatios[Engine.gear] * FINAL_DRIVE * (60 / (2 * math.pi * WHEEL_RADIUS))
local rpm = math.abs(Vehicle.speed) * conversionFactor
if rpm < Engine.idleRPM then rpm = Engine.idleRPM end
return rpm
end
end

-- For neutral, update RPM toward a target based on throttle.
local function updateEngineRPMNeutral()
local targetRPM = Engine.idleRPM + (Engine.maxRPM - Engine.idleRPM) * Engine.throttle
local changeRate = 200 -- RPM per tick
if Engine.rpm < targetRPM then
Engine.rpm = math.min(Engine.rpm + changeRate, targetRPM)
elseif Engine.rpm > targetRPM then
Engine.rpm = math.max(Engine.rpm - changeRate, targetRPM)
end
end

-- Calculate the engine force delivered to the wheels.
local function getEngineForce()
if Engine.gear == 0 then
return 0 -- In neutral, no drive force is transmitted.
else
if Engine.throttle == 0 then
-- Apply engine braking when throttle is released.
return -ENGINE_BRAKE_FORCE
else
local torque = Engine.throttle * MAX_TORQUE * torqueCurve(Engine.rpm)
local force = (torque * Engine.gearRatios[Engine.gear] * FINAL_DRIVE) / WHEEL_RADIUS
return force
end
end
end

-- Starts the engine by setting it to idle RPM.
local function startEngine()
Engine.rpm = Engine.idleRPM
ll.Say(0, "Engine started. RPM: " .. Engine.rpm)
end

-- Shifts the gear if valid.
local function shiftGear(newGear)
if Engine.gearRatios[newGear] then
Engine.gear = newGear
ll.Say(0, "Shifted to gear " .. newGear)
else
ll.Say(0, "Invalid gear: " .. newGear)
end
end

local function findWheels()
local total = ll.GetNumberOfPrims()
for i = 1, total do
local name = ll.GetLinkName(i)
if name == "WHEEL_LF" then
LINK_WHEEL_LEFT = i
elseif name == "WHEEL_RF" then
LINK_WHEEL_RIGHT = i
end
end
end

local castRayCounter = 0
local lastGrounded = false

local function isVehicleOnGround()
castRayCounter = castRayCounter + 1
if castRayCounter >= 5 then
castRayCounter = 0
local pos = ll.GetPos()
local rayDistance = 4.5 -- threshold distance (in meters) to consider as "grounded"
local rayStart = pos
local rayEnd = pos + vector(0, 0, -rayDistance)
local hitResult = ll.CastRay(rayStart, rayEnd, {})
if table.getn(hitResult) == 3 then
lastGrounded = true
else
lastGrounded = false
end
end
return lastGrounded
end

-- Timer event: updates engine, vehicle physics, steering, and rotates the wheels based on steering.
function timer()
local dt = 0.1 -- time step in seconds

-- For neutral, update RPM based on throttle.
if Engine.gear == 0 then
updateEngineRPMNeutral()
end

-- Calculate forces.
local C_rr = (Engine.gear == 0) and C_rr_neutral or C_rr_inGear
local F_roll = Vehicle.mass * G * C_rr
local engineForce = getEngineForce()
local dragForce = getAerodynamicDrag(math.abs(Vehicle.speed))
local netForce = engineForce - (F_roll + dragForce)

-- Apply braking force if brakes are engaged.
if Vehicle.brake then
netForce = netForce - BRAKE_FORCE
end

local acceleration = netForce / Vehicle.mass
local vel = ll.GetVel()
local horizontal_vec = vector(vel.x, vel.y, 0)
Vehicle.speed = (ll.VecMag(horizontal_vec) + acceleration * dt)

-- Limit vehicle speed based on gear.
if Engine.gear ~= 0 then
if Vehicle.speed < 0 then
Vehicle.speed = 0
end
local conversionFactor = Engine.gearRatios[Engine.gear] * FINAL_DRIVE * (60 / (2 * math.pi * WHEEL_RADIUS))
local maxSpeed = Engine.maxRPM / conversionFactor
if Vehicle.speed > maxSpeed then
Vehicle.speed = maxSpeed
end
end

-- When in gear, update RPM based on the new speed.
if Engine.gear ~= 0 then
Engine.rpm = computeEngineRPMFromSpeed()
end

-- Steering update using angular velocity and quaternions:
local STEERING_RATE = math.rad(6) -- desired steering rate per tick (radians)
local yawDelta = Vehicle.steering * STEERING_RATE -- small rotation for this tick

if yawDelta ~= 0 then
local deltaQuat = ll.Euler2Rot(vector(0, 0, yawDelta))
local angularSpeed = yawDelta / dt
local angularVelocity = vector(0, 0, angularSpeed)
ll.SetAngularVelocity(angularVelocity, 1)
Vehicle.angle = Vehicle.angle + yawDelta
else
ll.SetAngularVelocity(vector(0, 0, 0), 1)
end

-- Display engine RPM and speed (converted to mph).
local speed_mph = math.abs(Vehicle.speed) * 2.23694
ll.SetText("RPM: " .. math.floor(Engine.rpm) ..
" | Speed: " .. string.format("%.1f", speed_mph) ..
" mph", vector(0,0,0), 1)

-- Only update velocity if the vehicle is near the ground, and we're in gear.
if isVehicleOnGround() and Engine.gear ~= 0 then
local velocityVector
if Engine.gear > 0 then
velocityVector = vector(Vehicle.speed, 0, 0)
else
-- Reverse gear
velocityVector = vector(-Vehicle.speed, 0, 0)
end
ll.SetVelocity(velocityVector, 1)
end

-- Update the wheel rotations to visually match the steering.
local maxWheelTurn = math.rad(30) -- maximum wheel turn angle in radians
local wheelAngle = -Vehicle.steering * maxWheelTurn

if LINK_WHEEL_LEFT > 0 then
ll.SetLinkPrimitiveParamsFast(
LINK_WHEEL_LEFT,
{
PRIM_ROT_LOCAL,
ll.Euler2Rot(vector(-4.71239, -wheelAngle, 0))
}
)
end

if LINK_WHEEL_RIGHT > 0 then
ll.SetLinkPrimitiveParamsFast(
LINK_WHEEL_RIGHT,
{
PRIM_ROT_LOCAL,
ll.Euler2Rot(vector(4.71239, wheelAngle, 0))
}
)
end
end

-- Called when the object is touched: starts engine and simulation.
function touch_start(num)
ll.Say(0, "Touch detected, requesting controls and starting engine.")
ll.RequestPermissions(ll.GetOwner(), PERMISSION_TAKE_CONTROLS)
startEngine()
findWheels()
ll.SetTimerEvent(0.1)
end

-- Called when runtime permissions are granted.
function run_time_permissions(perm)
if bit32.band(perm, PERMISSION_TAKE_CONTROLS) then
ll.Say(0, "Permissions granted.")
local controlMask = bit32.bor(CONTROL_FWD, CONTROL_BACK, CONTROL_UP, CONTROL_DOWN, CONTROL_LEFT, CONTROL_RIGHT)
ll.TakeControls(controlMask, 1, 1)
end
end

-- Handle control events:
-- • CONTROL_FWD applies throttle.
-- • CONTROL_BACK applies the brakes.
-- • CONTROL_UP and CONTROL_DOWN shift gears.
-- • CONTROL_LEFT and CONTROL_RIGHT steer the vehicle.
function control(avatar_id, level, edge)
local start = bit32.band(level, edge)
local finish = bit32.band(bit32.bnot(level), edge)
local held = bit32.band(level, bit32.bnot(edge))
local untouched = bit32.bnot(bit32.bor(level, edge))

if bit32.band(held, CONTROL_BACK) ~= 0 then
Vehicle.brake = true
Engine.throttle = 0.0
elseif bit32.band(held, CONTROL_FWD) ~= 0 then
Vehicle.brake = false
Engine.throttle = 1.0
if Engine.gear == 0 then
updateEngineRPMNeutral()
end
else
Vehicle.brake = false
Engine.throttle = 0.0
end

if bit32.band(start, CONTROL_UP) ~= 0 then
shiftGear(Engine.gear + 1)
end

if bit32.band(start, CONTROL_DOWN) ~= 0 then
shiftGear(Engine.gear - 1)
end

local steeringInput = 0
if bit32.band(held, CONTROL_LEFT) ~= 0 then
steeringInput = steeringInput + 1
end
if bit32.band(held, CONTROL_RIGHT) ~= 0 then
steeringInput = steeringInput - 1
end
Vehicle.steering = steeringInput
end

</source>

== weather_box.lua ==
This script demonstrates coroutines, as well as working with a JSON-based web API:
<source lang="lua">
local TEXTBOX_CHANNEL = 323242
-- kludge because we don't have LSL constants in here yet
local HTTP_BODY_MAXLENGTH = integer(2)
local PRIM_TEXT = integer(26)
local PRIM_SIZE = integer(7)

gCityName = ""
gLatLong = nil -- A table of 2 elems when it's populated
gCityRequestTask = nil
gWeatherRequestTask = nil

-----
-- JSON stuff
-----

-- From https://github.com/rxi/json.lua/blob/master/json.lua

local json = {}

local escape_char_map = {
[ "\\" ] = "\\",
[ "\"" ] = "\"",
[ "\b" ] = "b",
[ "\f" ] = "f",
[ "\n" ] = "n",
[ "\r" ] = "r",
[ "\t" ] = "t",
}

local escape_char_map_inv = { [ "/" ] = "/" }
for k, v in pairs(escape_char_map) do
escape_char_map_inv[v] = k
end

local parse

local function create_set(...)
local res = {}
for i = 1, select("#", ...) do
res[ select(i, ...) ] = true
end
return res
end

local space_chars = create_set(" ", "\t", "\r", "\n")
local delim_chars = create_set(" ", "\t", "\r", "\n", "]", "}", ",")
local escape_chars = create_set("\\", "/", '"', "b", "f", "n", "r", "t", "u")
local literals = create_set("true", "false", "null")

local literal_map = {
[ "true" ] = true,
[ "false" ] = false,
[ "null" ] = nil,
}

local function next_char(str, idx, set, negate)
for i = idx, #str do
if set[str:sub(i, i)] ~= negate then
return i
end
end
return #str + 1
end

local function decode_error(str, idx, msg)
local line_count = 1
local col_count = 1
for i = 1, idx - 1 do
col_count = col_count + 1
if str:sub(i, i) == "\n" then
line_count = line_count + 1
col_count = 1
end
end
error( string.format("%s at line %d col %d", msg, line_count, col_count) )
end

local function codepoint_to_utf8(n)
-- http://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=iws-appendixa
local f = math.floor
if n <= 0x7f then
return string.char(n)
elseif n <= 0x7ff then
return string.char(f(n / 64) + 192, n % 64 + 128)
elseif n <= 0xffff then
return string.char(f(n / 4096) + 224, f(n % 4096 / 64) + 128, n % 64 + 128)
elseif n <= 0x10ffff then
return string.char(f(n / 262144) + 240, f(n % 262144 / 4096) + 128,
f(n % 4096 / 64) + 128, n % 64 + 128)
end
error( string.format("invalid unicode codepoint '%x'", n) )
end

local function parse_unicode_escape(s)
local n1 = tonumber( s:sub(1, 4), 16 )
local n2 = tonumber( s:sub(7, 10), 16 )
-- Surrogate pair?
if n2 then
return codepoint_to_utf8((n1 - 0xd800) * 0x400 + (n2 - 0xdc00) + 0x10000)
else
return codepoint_to_utf8(n1)
end
end

local function parse_string(str, i)
local res = ""
local j = i + 1
local k = j

while j <= #str do
local x = str:byte(j)

if x < 32 then
decode_error(str, j, "control character in string")

elseif x == 92 then -- `\`: Escape
res = res .. str:sub(k, j - 1)
j = j + 1
local c = str:sub(j, j)
if c == "u" then
local hex = str:match("^[dD][89aAbB]%x%x\\u%x%x%x%x", j + 1)
or str:match("^%x%x%x%x", j + 1)
or decode_error(str, j - 1, "invalid unicode escape in string")
res = res .. parse_unicode_escape(hex)
j = j + #hex
else
if not escape_chars[c] then
decode_error(str, j - 1, "invalid escape char '" .. c .. "' in string")
end
res = res .. escape_char_map_inv[c]
end
k = j + 1

elseif x == 34 then -- `"`: End of string
res = res .. str:sub(k, j - 1)
return res, j + 1
end

j = j + 1
end

decode_error(str, i, "expected closing quote for string")
end

local function parse_number(str, i)
local x = next_char(str, i, delim_chars)
local s = str:sub(i, x - 1)
local n = tonumber(s)
if not n then
decode_error(str, i, "invalid number '" .. s .. "'")
end
return n, x
end

local function parse_literal(str, i)
local x = next_char(str, i, delim_chars)
local word = str:sub(i, x - 1)
if not literals[word] then
decode_error(str, i, "invalid literal '" .. word .. "'")
end
return literal_map[word], x
end

local function parse_array(str, i)
local res = {}
local n = 1
i = i + 1
while 1 do
local x
i = next_char(str, i, space_chars, true)
-- Empty / end of array?
if str:sub(i, i) == "]" then
i = i + 1
break
end
-- Read token
x, i = parse(str, i)
res[n] = x
n = n + 1
-- Next token
i = next_char(str, i, space_chars, true)
local chr = str:sub(i, i)
i = i + 1
if chr == "]" then break end
if chr ~= "," then decode_error(str, i, "expected ']' or ','") end
end
return res, i
end

local function parse_object(str, i)
local res = {}
i = i + 1
while 1 do
local key, val
i = next_char(str, i, space_chars, true)
-- Empty / end of object?
if str:sub(i, i) == "}" then
i = i + 1
break
end
-- Read key
if str:sub(i, i) ~= '"' then
decode_error(str, i, "expected string for key")
end
key, i = parse(str, i)
-- Read ':' delimiter
i = next_char(str, i, space_chars, true)
if str:sub(i, i) ~= ":" then
decode_error(str, i, "expected ':' after key")
end
i = next_char(str, i + 1, space_chars, true)
-- Read value
val, i = parse(str, i)
-- Set
res[key] = val
-- Next token
i = next_char(str, i, space_chars, true)
local chr = str:sub(i, i)
i = i + 1
if chr == "}" then break end
if chr ~= "," then decode_error(str, i, "expected '}' or ','") end
end
return res, i
end

local char_func_map = {
[ '"' ] = parse_string,
[ "0" ] = parse_number,
[ "1" ] = parse_number,
[ "2" ] = parse_number,
[ "3" ] = parse_number,
[ "4" ] = parse_number,
[ "5" ] = parse_number,
[ "6" ] = parse_number,
[ "7" ] = parse_number,
[ "8" ] = parse_number,
[ "9" ] = parse_number,
[ "-" ] = parse_number,
[ "t" ] = parse_literal,
[ "f" ] = parse_literal,
[ "n" ] = parse_literal,
[ "[" ] = parse_array,
[ "{" ] = parse_object,
}

parse = function(str, idx)
local chr = str:sub(idx, idx)
local f = char_func_map[chr]
if f then
return f(str, idx)
end
decode_error(str, idx, "unexpected character '" .. chr .. "'")
end

function json.decode(str)
if type(str) ~= "string" then
error("expected argument of type string, got " .. type(str))
end
local res, idx = parse(str, next_char(str, 1, space_chars, true))
idx = next_char(str, idx, space_chars, true)
if idx <= #str then
decode_error(str, idx, "trailing garbage")
end
return res
end

-----
-- Event Loop
-----

-- A naive little event loop that lets you track running coroutines and dispatches
-- the events they're waiting for to them.

local EventLoop = {
-- Coroutine -> awaited event
_coros = {},
running = false
}

function EventLoop:create_task(func)
local coro = coroutine.create(func)
-- false has no semantic meaning here, we just want to reserve the space for
-- the coroutine in the table without saying we're awaiting anything yet.
self._coros[coro] = false
self:_run_coro(coro)
return coro
end

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

-- (internal) run the event
function EventLoop:_run_coro(coro, ...)
assert(coroutine.status(coro) ~= "dead")
-- assert(not self.running)
local old_running = self.running
self.running = true

-- Since we're running, this isn't currently awaiting anything
self._coros[coro] = false
local success, ret = coroutine.resume(coro, ...)
self.running = old_running

-- If we're not done then ret should be the kind of event we're awaiting.
-- Otherwise it's an error message or something. Who cares.
if not success then
-- Get rid of the coro
if ret then
ll.OwnerSay(`Might have an error: {ret}`)
end
ret = nil
end
self._coros[coro] = ret
end

-- Wake up any tasks that are waiting for this kind of event
function EventLoop:handle_event(name, ...)
-- We may mutate self._coros, so do a clone
local coros = table.clone(self._coros)
ll.OwnerSay(`Handling {name}`)

for coro, awaited_event in coros do
if coroutine.status(coro) == "dead" then
-- Hmm, this coroutine is dead, prune it.
self._coros[coro] = nil
end

if awaited_event == name then
ll.OwnerSay(`Dispatching {name} to {coro}`)
self:_run_coro(coro, ...)
end
end
end

function EventLoop:create_event_catcher(name)
local function catcher(...)
ll.OwnerSay("yay")
EventLoop:handle_event(name, ...)
end
return catcher
end

-- Helper function for waiting and telling the EventLoop what event you want
local function await_event(kind)
-- You had better do this inside a running event loop
assert(EventLoop.running)
-- This will yield, the EventLoop will resume us once it has
-- an event we might be interested in.
return coroutine.yield(kind)
end

-----
-- Script-specific functions
-----

local function hide_children()
for i=2,ll.GetNumberOfPrims() do
-- Hide all the child prims
ll.SetLinkAlpha(i, 0, -1)
ll.SetLinkPrimitiveParamsFast(i, {
PRIM_SIZE, vector(0.5, 0.5, 0.5),
PRIM_TEXT, "", vector(1,1,1), 1
})
end
end

local function send_textbox(avatar_id, message, channel)
ll.TextBox(avatar_id, message, channel)

while true do
local resp_channel, name, id, resp = await_event("listen")
if id ~= avatar_id or channel ~= resp_channel then
-- If this isn't a message we're interested in then wait for the next event
ll.OwnerSay(`{id}, {avatar_id}, {resp_channel}, {channel}`)
continue
end
return resp
end
end

local function make_json_request(url)
local req_id = ll.HTTPRequest(url, {HTTP_BODY_MAXLENGTH, integer(16000)}, "")
while true do
local ev_id, status, metadata, body = await_event("http_response")
if ev_id ~= req_id then
-- Not a response for the HTTP request we were waiting on, wait for the next event.
continue
end
return status, metadata, body
end
end

local function request_weather()
-- And you can use a wrapper like this to make an async function callable within both normal and coroutine contexts.
-- Normally this sort of thing would not be necessary, but here it is since the EventLoop lives in our own code,
-- and isn't a property of the actual script engine.
if gWeatherRequestTask then
EventLoop:kill_task(gWeatherRequestTask)
end

gWeatherRequestTask = EventLoop:create_task(function()
ll.OwnerSay("Requesting weather")
local status, metadata, body = make_json_request(`https://api.open-meteo.com/v1/forecast?latitude={gLatLong[1]}&longitude={gLatLong[2]}&current=temperature_2m&daily=temperature_2m_max`)
if status ~= 200 then
ll.OwnerSay("Error requesting weather")
return
end
local parsed = json.decode(body)

local current = parsed["current"]
ll.OwnerSay(`Temperature is {current["temperature_2m"]}C`)
ll.SetText(`Temperature in {gCityName} is currently {current["temperature_2m"]}C`, vector(1,1,1), 1)

-- Show the highs for each day
local days = parsed["daily"]["temperature_2m_max"]
for i=1,#days do
local link_num = i + 1
-- Higher temps = bigger on Z, negatives are unrepresentable :)
local z_size = (days[i] / 30) * 2
ll.SetLinkAlpha(link_num, 1, -1)
ll.SetLinkPrimitiveParamsFast(link_num, {
PRIM_SIZE, vector(0.5, 0.5, z_size),
PRIM_TEXT, `{days[i]}C`, vector(1,1,1), 1
})
end
end)
end

local function ask_for_city()
local resp = send_textbox(ll.GetOwner(), "What city do you want the weather for?", TEXTBOX_CHANNEL)
if not resp then
ll.OwnerSay("Got no response for city request.")
return
end

ll.OwnerSay(`You want the weather for {resp}.`)
gLatLong = nil
gCityName = resp

hide_children()

-- request the lat and long for this city
local status, metadata, body = make_json_request(`https://nominatim.openstreetmap.org/search.php?city={ll.EscapeURL(resp)}&format=jsonv2`)
local parsed = json.decode(body)
if not #parsed then
ll.OwnerSay(`Got no results for {resp}!`)
return
end

local first_result = parsed[1]
gLatLong = {first_result["lat"], first_result["lon"]}
ll.OwnerSay(`City Lat: {gLatLong[1]}, Long: {gLatLong[2]}`)

request_weather()

-- request weather again in 3 mins
ll.SetTimerEvent(180)
end

-----
-- Event Handlers
-----

-- If we don't care about conventionally dispatched events, we can just set the event handler to directly send
-- event data to the event loop.
http_response = EventLoop:create_event_catcher("http_response")
listen = EventLoop:create_event_catcher("listen")

-- More conventional event handlers work too.
function touch_start(num)
for i=0,num-1 do
if ll.GetOwner() ~= ll.DetectedKey(i) then
-- Go to next loop if it wasn't the owner touching us.
continue
end

if gCityRequestTask then
EventLoop:kill_task(gCityRequestTask)
end

-- Spin up a task to ask the user for their city
gCityRequestTask = EventLoop:create_task(ask_for_city)
break
end
end

function timer()
request_weather()
end

-- Not strictly necessary, but I like having the main function have its own scope.
-- Rather than just have top-level logic.
local function main()
ll.Listen(TEXTBOX_CHANNEL, "", "", "")
ll.SetText("", vector(1,1,1), 1)
hide_children()
ll.OwnerSay("Weatherbox operational!")
end

main()
</source>

2024-08-10T18:49:49Z

Signal Linden:

Third Party Libraries

2024-08-10T18:25:52Z

Signal Linden: Major update and clean up --updated all links, purged unused libraries.

__NOTOC__
The following table lists libraries and other third party dependencies used in constructing the Second Life Viewer.

Most of these (all the open source ones) should be available as prebuilds packaged by and for use with [[Autobuild]].

Anywhere that the following disagrees with the autobuild.xml file in the viewer source, that file is correct.

'''Creating a new third party package''

'''List of third party libraries'''

{| border="1" cellpadding="3"
|- style="background:#ffdead;"
!Library
!Repository
!License
!Upstream Home
!Description

|-
|apr_suite
|[https://github.com/secondlife/3p-apr_suite/ 3p-apr]
|[https://github.com/secondlife/3p-apr_suite/blob/main/apr/LICENSE Apache License]
|http://apr.apache.org/
|"A set of C functions which provide a portable and consistent interface into operating system - or simply widely useful - functionality. We primarily use it for threading and socket i/o. This is actually three packages, apr, apr-util and apr-iconv."
|-
|boost
|[https://github.com/secondlife/3p-boost 3p-boost]
|[https://github.com/boostorg/boost/blob/master/LICENSE_1_0.txt Boost License]
|http://www.boost.org/
|A set of portable C++ libraries which provide a wide set of functionality. Used primarily for tokenization.
|-
|curl
|[https://github.com/secondlife/3p-curl 3p-curl]
|''[https://github.com/secondlife/3p-curl/blob/master/curl/COPYING BSD-style]''[[#BSDstyle|B]]
| http://curl.haxx.se/libcurl/
|Handles moving data across the net in many different protocols. Used to GET/POST/PUT/DELETE web resources.
|-
|expat
|[https://github.com/secondlife/3p-expat 3p-expat]
|[https://github.com/libexpat/libexpat/blob/master/COPYING MIT License]
|https://github.com/libexpat/libexpat
|XML parser.
|-
|freetype
|[https://github.com/secondlife/3p-freetype 3p-freetype]
|[https://github.com/freetype/freetype/blob/master/LICENSE.TXT Freetype License and Others]
|http://www.freetype.org/
|Font engine.
|-
|glh_linear
|[https://github.com/secondlife/3p-glh_linear 3p-glh_linear]
|
|
|nVidia NVParse SDK: platform-independent C++ Apple OpenGL helper library
|-
|gstreamer
|[https://bitbucket.org/lindenlab/3p-gstreamer 3p-gstreamer]
|Open
|http://gstreamer.freedesktop.org
|
|-
|havok
|
|Commercial
|
|
|-
|jpeglib
|[https://bitbucket.org/lindenlab/3p-jpeglib 3p-jpeglib]
|Open
|http://www.ijg.org/
|JPEG decoder library.
|-
|kdu
|[https://hg.lindenlab.com/lindenlab/3p-kdu-private 3p-kdu-private][[#PrivateRepo|LL]]
|Commercial
|http://www.kakadusoftware.com
|Kakadu (KDU) JPEG-2000 decoder library.
|-
|libpng
|[https://bitbucket.org/lindenlab/3p-libpng 3p-libpng]
|Open
| http://www.libpng.org/pub/png/libpng.html
|PNG image library.
|-
|libxml2
|[https://github.com/secondlife/3p-libxml2 3p-libxml2]
|[https://gitlab.gnome.org/GNOME/libxml2/-/blob/master/Copyright?ref_type=heads MIT License]
|
|
|-
|ndofdev
|[https://github.com/secondlife/3p-libndofdev 3p-libndofdev]
|''[https://github.com/secondlife/3p-libndofdev/blob/master/libndofdev/COPYING BSD-style]''[[#BSDstyle|B]]
|
|Provides joystick driver support (mac and win) for the 3DConnexion SpaceNavigator.
|-
|ogg_vorbis
|[https://github.com/secondlife/3p-ogg_vorbis 3p-ogvorbis]
|''[https://github.com/xiph/ogg/blob/master/COPYING BSD-style]''[[#BSDstyle|B]]
|http://xiph.org/ogg/
|Audio codec and playback.
|-
|openal
|[https://github.com/secondlife/3p-openal-soft 3p-openal-soft]
|[https://github.com/secondlife/3p-openal-soft/blob/main/openal-soft/COPYING GPL]
|http://connect.creativelabs.com/openal/default.aspx
|3D Spatial audio
|-
|openjpeg
|[https://github.com/secondlife/3p-openjpeg 3p-openjpeg]
|''[https://github.com/uclouvain/openjpeg/blob/master/LICENSE BSD-style]''[[#BSDstyle|B]]
|http://www.openjpeg.org/
|An open-source JPEG-2000 library; a slower alternative to Kadaku. Used in the open source release
|-
|openssl
|[https://github.com/secondlife/3p-openssl 3p-openssl]
|[https://github.com/openssl/openssl/blob/master/LICENSE.txt Apache License]
|http://www.openssl.org/
|Provides encryption for sensitive actions such as user login
|-
|sdl
|[https://github.com/secondlife/3p-sdl2 3p-sdl2]
|[https://github.com/libsdl-org/SDL/blob/main/LICENSE.txt zlib License]
|http://www.libsdl.org/index.php
|The Simple DirectMedia Layer libraries are used for handling input and basic window/GL setup on the Linux client.
|-
|slvoice
|
|Commercial
|
|This is the Vivox provided executable (renamed SLVoice)
|-
|tut
|[https://github.com/secondlife/3p-tut 3p-tut]
|''[https://github.com/secondlife/3p-tut/blob/master/LICENSE.txt BSD-style]''[[#BSDstyle|B]]
|http://tut-framework.sourceforge.net/
|Unit test framework based on the use of c++ meta template programming. Used to test LL libraries.
|-
|xmlrpc_epi
|[https://github.com/secondlife/3p-xmlrpc-epi 3p-xmlrpc-epi]
|[https://github.com/secondlife/3p-xmlrpc-epi/blob/master/xmlrpc-epi/COPYING Epinions, Inc License]
|http://xmlrpc-epi.sourceforge.net/
|XML-RPC protocol utility
|-
|zlib-ng
|[https://github.com/secondlife/3p-zlib-ng 3p-zlib-ng]
|[https://github.com/zlib-ng/zlib-ng/blob/develop/LICENSE.md zlib License]
|http://www.zlib.net/
|zlib is a lossless data-compression library which is used for a variety of network i/o and file compression.
|}

= Redistribution =
Some files in the SL installation can't be freely redistributed. This means it's not possible to simply package and offer for download a modified viewer: some files '''must not''' be redistributed.

This page documents the licenses and redistribution requirements of various files used by the viewer.

== Windows ==
These are the files that need to be shipped with the Windows version

=== Runtime ===
Microsoft components. It's not yet known whether they're redistributable.

* dbghelp.dll: [http://msdn2.microsoft.com/EN-US/library/ms679294.aspx Redistributable]
* msvcp71.dll: C++ Runtime Library, redistributable -viewer now using msvcp80.dll when compiled with VC2005
* msvcr71.dll: C Runtime Library, [http://msdn2.microsoft.com/en-us/library/abx4dbyh(vs.71).aspx Redistributable] -viewer now using msvcr80.dll when compiled with VC2005

== FONTS ==
Meta font software files

From the Readme.txt
The Meta font software files contained in this folder are the
copyrighted property of FSI FontShop International ("FSI") and are
licensed by FSI solely for use by Linden Research, Inc. and by
residents or users of Second Life in the Second Life environment,
subject to the Second Life Terms of Service. These Meta font software
files may not be copied by residents or developers of Second Life or
used by them for any other purpose whatsoever.

* MtBkLfRg.ttf
* MtBdLfRg.ttf

NOTE: These files must be replaced for an true opensource build

=== Mozilla ===
The Gecko engine is MPL/GPL/LGPL licensed, which makes it redistributable.

* app_settings/mozilla
* freebl3.dll
* gksvggdiplus.dll
* js3250.dll
* nspr4.dll
* nss3.dll
* nssckbi.dll
* plc4.dll,
* plds4.dll
* smime3.dll
* softokn3.dll
* ssl3.dll
* xpcom.dll
* xul.dll

=== Kakadu ===
JPEG2000 library. '''Not redistributable'''.
OpenJPEG is an alternative library that is redistributable

* llkdu.dll

Starting with Viewer 2.5, llkdu.dll has been phased out. The libkdu.a and kdu.lib are still not redistributable but can be built from the toolkit provided by Kakadu under a license. How to build a viewer with such a library is documented in [[KDU Implementation]].

=== OpenSSL ===
SSL library. Redistributable.

* libeay32.dll
* ssleay32.dll

=== Vivox ===
Vivox is the component that provides the voice functionality.

* SLVoice.exe: Voice daemon. '''Not redistributable'''
* SLVoiceAgent: Exact purpose unknown. '''Not redistributable'''
* alut.dll: OpenAL, by Creative Labs. Redistributable.
* ortp.dll: oRTP project, LGPL. Redistributable.
* srtp.dll: Secure RTP?
* vivoxsdk.dll: Vivox Communications API. '''Not redistributable'''
* wrap_oal.dll: OpenAL32 by Creative Labs. Redistributable.

=== Unknown Libraries ===
The purpose and licensing of these files is not known:

* tntk.dll: Probably Vivox related -see [https://wiki.secondlife.com/wiki/Voice/Technical Voice/Technical] for other info on ViVox files

[[Category:Compiling viewer]]

Lua FAQ

2024-08-07T05:50:01Z

Signal Linden:

__TOC__

=== Can I keep using LSL? ===

Yep! LSL should work exactly the same as before, and a lot of testing work has been done (and is being done) to ensure that is the case. Even if you’re an LSL pro and rely on things like <code>(some_list != [])</code> for getting the list length, or strange things like <code>((largestring="") + largestring)</code>, you’re fully covered. Those still work, and now have optimized implementations.

In fact, LSL will get better than ever before, running faster, and using less memory! The generated bytecode for an LSL script in Lua is generally half the size of a Mono script, and most strings take up half as much memory by virtue of using UTF-8 instead of UTF-16.

We’ve taken a lot of care in writing the new LSL compiler to make the scripting experience for people who prefer LSL better than it was before.

=== Are you going to stop adding functions / events to LSL? ===

In the general case, no. A big part of the work we’ve done is making it easy to share functions between LSL and Lua without much extra effort. For events and functions that can be reasonably exposed to LSL (i.e., they only use simple types that LSL has anyway) then LSL should still get those.

For more advanced features, the idea is that there should still be a path for exposing them to LSL. Obviously, with Lua it’s possible to have object-oriented APIs that would not be possible in LSL, but those objects will generally be written in a way that calling a method on a “special” object we introduce in Lua will really boil down to a function call that can be expressed in LSL.

Not a real example, but <code>some_object:giveInventoryList("folder_name", inventory_list)</code> might really boil down to a <code>llGiveInventoryList(some_object_id, "folder_name", "inventory_list");</code> call. In that way, most additional Lua functionality will be a fancy “easier” wrapper around functions shared with LSL!

The caveat is if functions are added that use new types that aren't in LSL (like functions that take in a <code>key -> value</code> map) likely won't be exposed to LSL, as there's no way to represent them in LSL anyway.

=== Wait, LSL can run on Lua now? How? Why would you do that? ===

A reasonable question! It sounds crazy at first, but as it turns out, LSL maps really well to Lua bytecode, and we already have a compiler that can output both Mono and legacy LSO2 bytecode. Writing a compiler that could output Lua bytecode wasn't terribly difficult, and it allows LSL scripts to run faster, and be more memory-efficient. Most importantly, it allows us to test behavior of the new scripting engine against the behavior of the existing Mono scripting engine. This helps us make sure we're doing an apples-to-apples comparison on our benchmarks, and that all the nice things that Mono currently gets us will also work correctly under the new scripting engine.

Additionally, for better or for worse, LSL is here to stay. People have been writing scripts in it for 20 years, and they're going to be running on the servers for years to come. Performance and memory usage issues with LSL scripts will continue to matter for the foreseeable future. The faster the server can run existing LSL scripts, the more time it can dedicate to running newer Lua scripts. Memory usage has been a particular problem with the existing Mono scripting engine, and this would help us address this.

=== What about running scripts on the viewer-side if I want viewer-side effects? Does this have any interaction with the work adding Lua addons into the viewer? ===

No, the work on adding Lua addons to the viewer is a separate effort. Lua scripts on SL will strictly run on the region, and not on the people's viewers. We're focused on providing a high-quality replacement to the existing server-side scripts before we look at anything else.

Note that we are all too aware of the current difficulty of scripting HUD UIs for Second Life (we make a lot of our own) and we're thinking of ways we can make things better, but there are no definite plans, and it wouldn't involve running scripts on the viewer in the near-term. The current UI tooling exposed to Lua viewer addons isn't tooled for being called from untrusted code either way, so lack of "client-side" scripts is unlikely to hinder any effort to create a better API for HUDs for in-world systems.

=== You said Lua runs LSL faster than Mono? It uses less memory? How? I'm suspicious. ===

A reasonable suspicion! We were also suspicious and suspected that Lua would be slightly slower, but in reality, yes, Lua can run LSL scripts quite a bit faster than the custom-patched Mono 2.6 we currently use. The best LSL on Mono has performed compared to Luau in our internal tests is 10% slower than Luau. Similarly, most LSL on Luau scripts end up being around half the size of Mono scripts. That means much more memory to play with in your LSL scripts.

The reason why isn't intuitive, after all, Mono is a lot more intricate and has a lot of fancy performance optimizations like a JIT optimizer, but it becomes clear when you look at the bytecode that's generated for LSL on each scripting engine.

Consider the following LSL function as an example:

<syntaxhighlight lang="lsl2">
float loudSubtract(float val, float sub) {
// subtract, telling the owner what we did
float new_val = val - sub;
llOwnerSay("New val is " + (string)new_val);
return new_val;
}
</syntaxhighlight>

This compiles to the following Luau bytecode (subject to further optimization):

{| role="presentation" class="wikitable mw-collapsible autocollapse mw-collapsed"
| Lua bytecode
|-
|<pre>
Function 0 (_floudSubtract):
SUB R2 R0 R1
GETIMPORT R3 2 [ll.OwnerSay]
GETIMPORT R6 5 [lsl.cast]
MOVE R7 R2
LOADN R8 3
CALL R6 2 1
LOADK R5 K6 ['New val is ']
CONCAT R4 R5 R6
CALL R3 1 0
RETURN R2 1
</pre>
|}

Okay, that's pretty decent. Some places where things could be more optimized, but no big deal. The equivalent Mono bytecode is (and bear with us, this is long:)

{| role="presentation" class="wikitable mw-collapsible autocollapse mw-collapsed"
| Mono bytecode
|-
|<pre>
.class public auto ansi serializable beforefieldinit
LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame
extends [UThread]LindenLab.SecondLife.UThread.UThreadStackFrame
{

.field public int32 ' pc'

.field public class LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575 ' instance'

.field public float32 val

.field public float32 'sub'

.field public float32 ' l0'

.field public int32 ' l1'

.method compilercontrolled specialname rtspecialname instance void
.ctor(
int32 _param1,
class LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575 _param2,
float32 _param3,
float32 _param4,
float32 _param5,
int32 _param6
) cil managed
{
.maxstack 4

IL_0000: ldarg.0 // this
IL_0001: call instance void [UThread]LindenLab.SecondLife.UThread.UThreadStackFrame::.ctor()

// [29 5 - 29 28]
IL_0006: ldarg.0 // this
IL_0007: ldarg.s _param1
IL_0009: nop
IL_000a: nop
IL_000b: nop
IL_000c: stfld int32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::' pc'

// [30 5 - 30 34]
IL_0011: ldarg.0 // this
IL_0012: ldarg.s _param2
IL_0014: nop
IL_0015: nop
IL_0016: nop
IL_0017: stfld class LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::' instance'

// [31 5 - 31 23]
IL_001c: ldarg.0 // this
IL_001d: ldarg.s _param3
IL_001f: nop
IL_0020: nop
IL_0021: nop
IL_0022: stfld float32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::val

// [32 5 - 32 23]
IL_0027: ldarg.0 // this
IL_0028: ldarg.s _param4
IL_002a: nop
IL_002b: nop
IL_002c: nop
IL_002d: stfld float32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::'sub'

// [33 5 - 33 28]
IL_0032: ldarg.0 // this
IL_0033: ldarg.s _param5
IL_0035: nop
IL_0036: nop
IL_0037: nop
IL_0038: stfld float32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::' l0'

// [34 5 - 34 28]
IL_003d: ldarg.0 // this
IL_003e: ldarg.s _param6
IL_0040: nop
IL_0041: nop
IL_0042: nop
IL_0043: stfld int32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::' l1'
IL_0048: ret

} // end of method LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::.ctor

.method public virtual instance object
Resume() cil managed
{
.maxstack 8

// [37 37 - 37 99]
IL_0000: ldarg.0 // this
IL_0001: ldfld class LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::' instance'
IL_0006: ldarg.0 // this
IL_0007: ldfld float32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::val
IL_000c: ldarg.0 // this
IL_000d: ldfld float32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::'sub'
IL_0012: call instance float32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575::gloudSubtract(float32, float32)
IL_0017: box [mscorlib]System.Single
IL_001c: ret

} // end of method LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::Resume
} // end of class LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame

// ... Within the actual script class

.method public hidebysig instance float32
gloudSubtract(
float32 val,
float32 'sub'
) cil managed
{
.maxstack 16
.locals init (
[0] float32 num1,
[1] int32 'l1[34-35], num2[69-151], num2[151-152]',
[2] class LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame c9eec9e37575gloudSubtractFrame,
[3] float32 num3
)

// [17 5 - 17 60]
IL_0000: call bool [UThread]LindenLab.SecondLife.UThread.UThread::IsRestoring()
IL_0005: brfalse IL_0036

// [19 7 - 19 202]
IL_000a: call class [UThread]LindenLab.SecondLife.UThread.UThreadStackFrame [UThread]LindenLab.SecondLife.UThread.UThread::Pop()
IL_000f: castclass LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame
IL_0014: stloc.2 // c9eec9e37575gloudSubtractFrame

// [20 7 - 20 53]
IL_0015: ldloc.2 // c9eec9e37575gloudSubtractFrame
IL_0016: ldfld float32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::' l0'
IL_001b: stloc.0 // num1

// [21 7 - 21 55]
IL_001c: ldloc.2 // c9eec9e37575gloudSubtractFrame
IL_001d: ldfld int32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::' l1'
IL_0022: stloc.1 // l1

// [22 7 - 22 55]
IL_0023: ldloc.2 // c9eec9e37575gloudSubtractFrame
IL_0024: ldfld int32 LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::' pc'
IL_0029: switch (IL_0085, IL_004b)

// [31 5 - 31 58]
IL_0036: call bool [UThread]LindenLab.SecondLife.UThread.UThread::IsSaveDue()
IL_003b: brfalse IL_004b

// [33 7 - 33 15]
IL_0040: ldc.i4 1 // 0x00000001
IL_0045: stloc.1 // num2

// [34 7 - 34 20]
IL_0046: br IL_0087

// [37 5 - 37 70]
IL_004b: ldarg.s 'sub'
IL_004d: nop
IL_004e: nop
IL_004f: nop
IL_0050: ldarg.s val
IL_0052: nop
IL_0053: nop
IL_0054: nop
IL_0055: call float64 [LslUserScript]LindenLab.SecondLife.LslUserScript::Subtract(float64, float64)
IL_005a: stloc.0 // num1

// [38 5 - 38 84]
IL_005b: ldloc.0 // num1
IL_005c: call string [LslLibrary]LindenLab.SecondLife.LslRunTime::ToString(float32)
IL_0061: ldstr "New val is "
IL_0066: call string [LslUserScript]LindenLab.SecondLife.LslUserScript::Add(string, string)
IL_006b: call void [LslLibrary]LindenLab.SecondLife.Library::llOwnerSay(string)

// [39 5 - 39 58]
IL_0070: call bool [UThread]LindenLab.SecondLife.UThread.UThread::IsSaveDue()
IL_0075: brfalse IL_0085

// [41 7 - 41 15]
IL_007a: ldc.i4 0 // 0x00000000
IL_007f: stloc.1 // num2

// [42 7 - 42 20]
IL_0080: br IL_0087

// [45 5 - 45 17]
IL_0085: ldloc.0 // num1
IL_0086: ret
IL_0087: nop

// [47 5 - 47 194]
IL_0088: ldloc.1 // num2
IL_0089: ldarg.0 // this
IL_008a: ldarg val
IL_008e: nop
IL_008f: nop
IL_0090: ldarg 'sub'
IL_0094: nop
IL_0095: nop
IL_0096: ldloc.0 // num1
IL_0097: ldloc.1 // num2
IL_0098: newobj instance void LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575gloudSubtractFrame::.ctor(int32, class LSL_a26e2aa2_c02b_c23e_06be_c9eec9e37575, float32, float32, float32, int32)
IL_009d: pop

// [49 5 - 49 17]
IL_009e: ldloc.3 // num3
IL_009f: ret

} // end of method
}
</pre>
|}

While this might look unreasonably large, this is also pretty similar to how <code>async</code> C# functions that have <code>await</code>s get compiled. The code required to allow a function to pause in the middle to let other things run is necessarily very large, and our Mono bytecode instrumentation is essentially a special variant of that which optimizes for cases where the function won't have to pause. Try pasting the following code into sharplab.io (while decompiling to IL) and you'll see something very similar:

<pre>
using System.Threading.Tasks;
public class Example {
public async Task llOwnerSay(string val)
{
// stub
}

public async Task<float> loudSubtract(float val, float sub) {
float new_val = val - sub;
await llOwnerSay("New val is " + new_val.ToString());
return new_val;
}
}
</pre>

The Lua bytecode ends up being a lot smaller, because the Lua scripting engine itself knows how to handle this case, and doesn't need to add any special code to your scripts to allow them to be paused and resumed in the middle of a function.

Even though Mono has a JIT optimizer, which should in theory make the script run faster, this sort of code is very unusual, and the JIT optimizer isn't able to optimize it very well. That means that even though Luau itself is in theory slower, it's able to run LSL much faster than Mono can.

You might also notice things like call <code>float64 [LslUserScript]LindenLab.SecondLife.LslUserScript::Subtract(float64, float64)</code> in the Mono code. Those are necessary because of LSL's weird operand evaluation order, but are unnecessary in Luau because of the more efficient form of bytecode that Luau uses.

In general, C# doesn't aim at producing very small bytecode for async functions, which is important for something like Second Life where you might have thousands of different individual scripts running within a region. Luau does generate small bytecode, while still having decent performance, making it a good choice for Second Life. And hey, strings are UTF-8 in Lua instead of UTF-16 as in Mono, so they use much less memory for most data as well.

=== Are we going to get a higher memory limit in scripts? ===

Not at first, Luau uses less memory than Mono, so you shouldn't really miss it. You're not going to start hitting script memory limits just because you converted your script to Lua. Using Lua proper should allow you to more precisely control memory usage in your scripts, e.g. by being able to handle memory allocation errors in <code>pcall()</code> and access to the mutable <code>buffer</code> class for byte-packing.

There is some interest in giving specific scripts a little more memory if they're designated "high priority", like a main "game manager" object for an experience, but there are no specific plans for this at the moment.

=== Are my existing LSL scripts going to run on Lua Automatically? ===

While we can run LSL in Lua now, and the idea is to eventually phase out Mono, there’s no immediate plans to transparently migrate existing scripts over to Lua. There are ideas about how this could be done safely without breaking existing content, but we want to make sure we have everything right before we start work on this.

=== How does interoperation with LSL work? ===

Everything that you expect from LSL should have some equivalent in Lua. There’s <code>key</code>s, <code>rotation</code>s and <code>vector</code>s and something like <code>some_vec * some_rot</code> in LSL is the exact same in Lua scripts.

All LSL functions will be available in Lua, and something like <code>llSay(0, “hi!”)</code> is just <code>ll.Say(0, “hi!”)</code> now. What about <code>llSetPos(llGetPos() + <0, 0, 1>);</code>? Just <code>ll.SetPos(ll.GetPos() + vector(0, 0, 1))</code>.

No special magic required here, and you can write whatever fancy wrappers you want around the existing LSL functions. We’ll be looking at how residents actually write these wrappers to inform the design of “official” higher-level Lua APIs, so we’re excited to see your ideas!

=== Can I mix LSL and Lua in the same script? ===

No, although most things should be a direct translation. At some point we may make a tool to help you do this, but there are no specific plans at the moment.

If your object has multiple scripts, you can mix LSL and Lua within the same object, though.

=== Can we use all of Lua? Is anything not there? ===

Most everything will be there, except for two notable exceptions:

* <code>getfenv()</code> / <code>setfenv()</code> / <code>_ENV</code> are not accessible because they necessarily make the script harder to optimize. Usually people only use this for mocking in test code, and this can be accomplished by passing in a parameter with a table of function references rather than pretending you have different global variable values for certain functions.
* <code>loadstring()</code> is not supported since it has a huge impact on performance. For those not familiar, this is equivalent to eval() in other languages. Every single time you call <code>loadstring()</code> the compiler has to go over what you passed in, compile it, and then load the generated bytecode. The Lua compiler isn’t particularly fast, and doing this can cause your script to halt in a way that we can’t interrupt to give other scripts time to run. This is a big part of why <code>eval()</code> and <code>loadstring()</code> are generally considered poor programming practice.

The one real use-case we could think of for <code>loadstring()</code> is a debugger, and we’re looking at implementing a “real” debugger that lets you step through your code. Note that this won’t happen with the initial release, but watch this space!

One thing that is planned, but will likely not be in the initial release is the coroutine library. This is one we’d really like to have in there, so you can do fancy things like have multiple “timers” in a script by just having coroutines that sleep every so often, but multiple running coroutines within the same script doesn’t fit well with the existing scripting architecture the Second Life server uses. Rest assured, this will be in there soon™ after Lua is released, but in the meantime you can still use something like the <code>Promise</code> chaining that JavaScript uses to write asynchronous event handlers.

We’ll have code demonstrating "proper" usage of Lua around the time that the public beta starts.

=== Why Lua? I wanted C#! ===

Great question!

The server Lua scripting initiative actually started off as an attempt to get C# working on Second Life, basically as a revival of the work started in the 2000s. The initial thought was “this should be pretty easy, most of the work was already done getting everything onto Mono!” A lot of effort was put in over several months to:

* Understand the Mono and .NET Core runtimes
* Observe how other Engines and Virtual Worlds have embedded C# and scripting in general
* Understand how recent advancements in scripting technologies (like WebAssembly) might make this integration easier
* Whether unique properties of how scripting / content creation works on Second Life would make this harder to implement

Unfortunately, the reasons we were ultimately unable to do this were very technical, so there’s no side-stepping a whole lot of tech-speak here, but there were several key properties that made integrating C# in Second Life rather difficult to implement:

==== Sandboxing with reflection is hard ====

Previous proof-of-concept code for C# in Second Life relied on CoreCLR sandboxing in Mono. This approach has fallen out of favor in recent years, because similar approaches led to many, many security holes in Java’s browser plugin. This sandboxing method is not possible in .NET Core, and has been totally removed.
Since this sandboxing is no longer in .NET, we need to rely on the ability to look at code to determine if it looks “dangerous” before running it. Some people have done this, but it can only be done properly by disabling reflection, which is a core part of C# and .NET! Without reflection, you’re unable to use the fancy third-party Newtonsoft.JSON libraries or whatnot that you would have otherwise been able to use.

Big portions of .NET’s standard library use reflection in a way that would be unsafe to expose to residents for scripting facilities, so you essentially have to maintain a list of functions and classes that are “safe” to use, and write alternatives to functions that are “unsafe” to call, but provide useful functionality. At this point, the scripting language that you’re exposing is a pretty bare-bones C# that needs to be scripted fundamentally differently from how you would write C# in Unity, for example.

Allowing the use of modern C# features would require migration off of Mono and onto .NET core, which would be more involved than integrating Lua. Mono is in maintenance mode at the moment, and only supports the legacy .NET framework
Ensuring that we’re able to correctly limit each script’s memory usage in a low-impact way is a bit of an unsolved problem in .NET Core. Generally, memory allocation tracking is something that you only do for debugging, but we need to do it for all scripts! What happens if you declare a static global in a C# script? Is the memory usage counted against all scripts of that type? Do all scripts share the data in that static variable?

What about if there’s a function in the standard library that keeps a static cache of data? How do we penalize (or not penalize) scripts for allocations that they didn’t even control? How do we make sure that data remains consistent across script unloads / reloads?

These are problems that most people embedding C# don’t need to solve, and the solutions that do exist are not generally workable into Second Life’s scripting model without multiple months of work. Most other virtual worlds do script sandboxing on a per-parcel or per-region level and put everything into the same logical scripting sandbox, which Second Life does not do. People would be rightly annoyed if someone’s HUD or attachments caused their parcel to go over the memory limit and things stopped working.

==== Making everything micro-threaded with extreme size constraints is hard ====

We need to be able to temporarily pause scripts in the middle of running an event handler so we can ensure we fairly schedule code execution. Previously, we wrote a script to do some quite clever binary instrumentation of .NET assemblies to inject yield points. This works quite well for for LSL scripts, but there are issues with C# in particular.

One is that it doesn’t handle the <code>try</code>/<code>finally</code> construct in C#. While not impossible to handle, this would be a difficult undertaking. Something that would be much more difficult is allowing pausing execution inside a constructor or other such special constructs in C#. While the stack induction and bytecode manipulation done by our current system is very cool, it is quite complex to update, relies on outdated tools that don’t work with new .NET versions, and necessarily requires making the bytecode quite a bit larger than it would otherwise be by injecting hooks.

But that’s not a huge deal, our .NET instrumentation library was written when <code>async</code>/<code>await</code> was not a thing in C#, so we should be able to inject <code>async</code>/<code>await</code> into user-provided source code instead to make it possible to transparently pause scripts right? Ehhhh, sort of. There are certain functions that cannot be made <code>async</code> in C# without breaking things. Object constructors are one of those, we have no way to pause and resume inside those. The situation is similar inside <code>ToString()</code> overloads. If we make a user-provided <code>ToString()</code> overload async, it’ll just never get called in cases where ToString() would normally get called! And what about implementing <code>IEnumerable.GetIterator()</code>? That might work… if you did a lot of work of replacing <code>IEnumerable</code> with <code>IAsyncEnumerable</code>., and <code>foreach</code> with <code>await foreach</code>... sometimes.

Suffice to say, that if you go this route, you end up with something that’s sort-of C# but is missing a lot of things people expect of C#, and may not behave the same as the regular C# that it pretends to be.

==== Saving script state ====

But let’s not forget one of the most important cases where SL is unique: Scripts can move into your inventory, across region boundaries, etc, without having to care too much that it even happened. Even if your script runs forever in a single function, that’s totally fine! For example, this is a valid LSL script:

default {
state_entry() {
integer i;
while(TRUE) {
llSetText("Run Number " + (string)(i++), <1,1,1>, 1);
}
}
}

All it does is run forever in the same function, incrementing a number in the floating text above an object. It still works if you take the object into your inventory, it still works if you move the object to another region, as a scripter you don't really have to care except in limited circumstances.

That's a pretty contrived example, but there are tons of scripts with a structure like this! Probably a more common example is a math-heavy function that just takes a while to run. Under the current model, you can interrupt what's going on by just picking up the object, then plop it back down later and let it continue on. There are a number of ways you can handle this without serializing the whole runtime state, like raising an exception in the middle of executing the function, but what are the chances that people will handle this correctly? How many command-line scripts have you used that do something really weird when you pressed <code>CTRL+C</code>?

To keep things simple for creators, we wanted to keep this nice property of LSL in whatever language we chose. This seemingly simple feature requires a lot of work because, think about it, how many programming languages let you seamlessly halt a program in the middle of it doing something, move it over to another computer, then resume whatever it was doing? Can you do that without doing a full-memory snapshot that would be gigabytes in size? That's not really a thing that people generally do, but it's required for us to not have sharp edges on our script creation experience!

We have a version of this in our Mono scripting engine, which was all written in-house. It works very well for LSL, but it has trouble with more complex structures. As it turns out, taking all the state of a running program, serializing it, then transparently deserializing it is a difficult problem, even with data that looks simple.

Suppose we have something like <code>Dictionary<SomeObject, int></code> that we use as a counter for how many times we've seen each <code>SomeObject</code>. What do you do if the <code>GetHashCode()</code> bucketing changes after the script deserializes and the memory increases? Can you prevent that from happening? Will live <code>IEnumerator</code>s still work correctly? How can you be sure of this? .NET makes no guarantees about any of this behavior, and good luck digging through the .NET source code to figure out if any of this is even the case.

What about types that aren't marked <code>[Serializable]</code>, including types in the standard library? Can people just not use those? Do we have to write special custom serializers for them? Could they just randomly break when the script is deserialized and we accept that as a consequence?

As you can see, there are a lot of hidden sharp edges involved in transparently moving scripts across servers, and the general answer provided when you ask about doing this is "That's very hard, make users write more intricate scripts that explicitly handle their own serialization and save their own state." This is fine if most of your users are professional programmers, not so if you have a mix of professional programmers and regular users who just want an object that counts how many people have clicked on their head.

==== Wrapping it up ====

This is a very small subset of the issues we ran into while trying to design a satisfactory C#-based scripting system that fits Second Life's needs. Seriously, there's about 20 pages of notes.

Meanwhile, Lua makes most of these things easy. Want to halt a script mid-execution? Okay, set an interrupt handler. Want to serialize your script while it's running and have it move to another server? Okay, there are libraries that have existed for decades that can do this. Fable's save file system was based on this. Quite a lot of scripting engine integration problems we have that would rise to the level of extremely difficult and relatively novel Computer Science research in .NET (and by extension, C#) are relatively simple to do with Lua.

=== Okay, but seriously, why Lua specifically? Because it's popular for games? Because <other platform> uses it? Why not <X>? ===

Actually, no. Neither other users of Lua, or a specific love of the language had anything to do with the decision. If you prefer a different programming language, there's a good chance we considered it. We actually looked at quite a lot of different languages and their associated engines, including JavaScript and WebAssembly, Lua was considered fairly late in the process. The ones below are just a small subset of the ones that we looked at:

[[File:Lsl_vm_comparison.png|1000px]]

As you can see, Luau was the only scripting runtime that fulfilled all of our requirements for a scripting engine within Second Life, and we arrived at it quite late in the decision process. We wanted something that we knew could deliver a high-quality scripting experience to creators, and we believe that Lua can best provide it.

=== I genuinely hate Lua and refuse to use it ===

A lot of people feel the same about LSL! Kidding aside, this is a totally defensible position, Lua can be a quirky language. Yes, it's strange that array indices start at 1. Yes, sometimes you can forget that you join strings with <code>..</code> and not <code>+</code>. It can take some getting used to.

A big part of the reason why we're using Luau is due to the quality of the scripting engine itself, not specifically the language. A lot of issues people had with older versions of Lua have been addressed in Luau, and ones that haven't been for one reason or another can be easily dealt with since we have such a high degree of control over the scripting engine now. Luau is very easy to modify. If we find that there are real quality-of-life issues with Lua that people run into while writing scripts, we can just change how it works, assuming the benefits outweigh the cost of breaking interoperability with Lua scripts from elsewhere.

But hey, maybe you really still hate the idea of using Lua. That's fine! The nice thing about having Lua instead of just LSL is there are a number of languages that can compile down to Lua code that could potentially work in Second Life! People have done work to get TypeScript and C# compiling to Lua, and it works pretty well for them, and there's also more exotic languages like MoonScript that target Lua specifically. See this GitHub repo for a listing: https://github.com/hengestone/lua-languages

If you're so inclined, you can go as far as to take the Luau transpiler and hack it up to support <code>!=</code> and <code>//</code> comments and really whatever you want. So long as it can take that source and output it to standard Lua, you're good.

=== Are you going to be using Lua 5.1? Why not 5.4? ===

We're using Luau as the base, which is ''compatible'' with Lua 5.1 but not necessarily Lua 5.1. It includes various features of PUC-Rio's Lua implementation up to and including 5.4. The Luau Compatibility reference is a good guide for which features are taken from which versions of PUC-Rio Lua: https://luau-lang.org/compatibility

=== Are there going to be integer types in SL's Lua implementation? ===

We have added 32-bit integers but they are strictly for compatibility with existing LSL APIs where integer type identity is important within a list (<code>llSetPrimitiveParams()</code> and friends.) They don't have a literal form in Luau scripts and in general you should just use regular Lua numbers if you care about performance, since the Luau VM optimizes for their use, but technically you can use them. The Luau project discussions have some explanation as to why integers aren't a first-class user-facing type in Luau https://github.com/luau-lang/luau/discussions/242#discussioncomment-1707387.

==== Are integer operations supported at all, then? (i.e. bitwise operators) ====

Yes, through the <code>bit32</code> library. In fact, ''more'' integer operations than are currently supported in LSL, like logical shift right and rotate operations. See https://luau-lang.org/library#bit32-library .

Lua FAQ

2024-07-09T22:56:16Z

2024-07-02T19:56:12Z

Signal Linden: Created page with "__TOC__ === Can I keep using LSL? === Yep! LSL should work exactly the same as before, and a lot of testing work has been done (and is being done) to ensure that is the case..."