Scripting Documentation

From OpenSimulator

(Difference between revisions)
Jump to: navigation, search
(How to use scripts in OpenSimulator)
m (Breaking introduction in 2 parts)
 
(115 intermediate revisions by 7 users not shown)
Line 2: Line 2:
  
 
== About OpenSimulator scripting ==
 
== About OpenSimulator scripting ==
An important ingredient in worlds simulation is scripting.<br>
+
An important ingredient in virtual worlds simulation is scripting.<br>
 +
Scripts allow the addition of actions to 'entities' in world, like making a door react to a touch and open.<br>
 +
Since version 0.9.1.0, you can chose between old [[XEngine]] or new [[YEngine]] script engines.<br>
 +
Script engines do script compilation and control script execution.<br>
 
OpenSimulator script language supports a subset of the Linden Labs Second Life script language (LSL) plus its own extensions (OSSL).
 
OpenSimulator script language supports a subset of the Linden Labs Second Life script language (LSL) plus its own extensions (OSSL).
  
[http://wiki.secondlife.com/wiki/LSL_Portal LSL (Linden Scripting Language)]<br>
+
== LSL in a nutshell ==
[[OSSL Implemented|OSSL]]<br>
+
LSL is a event-driven language. A script is a collection of functions called event handlers.
  
<div style="background-color:#FFA0A0; padding:10px; padding-bottom:5px; border: 1px #FF544F solid">
+
Events are generated by the environment (mouse clicks, collisions and many more). <u>Many of those events happen at time critical moments, so those event handlers should be small and fast to reduce impact on the rest of simulation.</u> YEngine may allow long processing to happen with less impact on the simulation, but that will happen at lower priority.
'''A script is not a full program!
+
 
 +
(Hopefully), a script does nothing when there is no event to process. Is sits waiting for an event. Only events matching a event handler present in the script will be generated. If the script has no handler for mouse clicks, mouse clicks won't be reported.
 +
 
 +
LSL functions may also generate events. For example, llRezObject will trigger a object_rez event. llMessageLinked, a link_message event. This makes your script asynchronous (request action in a handler, get result in another handler). Understanding the flow of events in your script is essential.
 +
 
 +
An event cannot interrupt another event. Processing of the previous event must be finished before accepting a new one. Events are queued up to the number of 300 (OpenSim.ini, MaxScriptEventQueue). Finally, LSL has states that implements the concept of [https://en.wikipedia.org/wiki/Finite-state_machine state machine]. A script can respond differently to a same event in different states, or to another set of events.
 +
 
 +
== String type in OpenSimulator ==
 +
<div style="background-color:#FFA500; padding:10px; padding-bottom:5px; border: 1px #FF544F solid">
 +
<b>Most OpenSimulator LSL/OSSL string functions are only safe with characters that can be represented by a single .net (UTF-16) char. This means strings with characters of the Basic Multilingual Plane excluding combining characters</b><br>
 +
That is Unicode code points up to U+FFF0, except:<br>
 +
*U+0300..U+036F (combining characters)<br>
 +
*U+1AB0..U+1AFF (combining characters)<br>
 +
*U+1DC0..U+1DFF (combining characters)<br>
 +
*U+20D0..U+20FF (combining characters)<br>
 +
*U+D800..U+DFFF (reserved for higher planes encode using 2 chars)<br>
 +
*U+FE20..U+FE2F<br>
 +
<b>Only in this case some compatibility with SL is possible.</b><br>
 +
OpenSimulator strings are internally encoded as .net strings that are basically arrays of UTF-16 chars.<br>
 +
A unicode character may be represented by more than one of those chars, but most .net and mono string functions ignore this and just assume all characters are single utf16 chars.<br>
 +
For example llStringLength returns the number of .net chars on the string, not necessary the real number of its characters.<br>
 +
Functions that take a index or in string position arguments use them as a index to the array  of chars and so that may point to the middle of a complex character. In this case some of this functions may even create strings with invalid characters.<br>
 +
SL string functions do support most cases of 2 char characters, so full compatibility is not possible without breaking compatibility with older OpenSimulator versions. Only in this case some compatibility with SL is possible. Multiple char characters support also has a high performance cost.
 
</div><br>
 
</div><br>
A script should only perform fast, simple operations, otherwise it may have very negative impact on a simulator operation.
+
 
 +
 
 +
[http://wiki.secondlife.com/wiki/LSL_Portal LSL (Linden Scripting Language)]<br>
 +
[[OSSL Implemented|OSSL (OpenSimulator Scripting Language)]]<br>
  
 
== Configuring scripting ==
 
== Configuring scripting ==
Line 23: Line 51:
 
Known problems:
 
Known problems:
 
* Error messages about scripting errors are often cryptic, and tend to be long.
 
* Error messages about scripting errors are often cryptic, and tend to be long.
* Linux/Mac users will need to upgrade the default mono to "mono-complete" in order to have a fully functional scripting engine in OpenSimulator. See [http://opensimulator.org/mantis/view.php?id=5007 the bug tracker] for details.
+
* Script syntax and execution may depend on the engine used, old [[XEngine]] or [[YEngine]]
 +
* On teleports or crossings from a region using YEngine to a region using XEngine, script state (like changed values on global variables) is lost. Should be okay on the inverse direction.
  
 
== Scripting System Status ==
 
== Scripting System Status ==
Line 62: Line 91:
 
:* [http://sourceforge.net/projects/lsleditor/ LSLeditor SourceForge]
 
:* [http://sourceforge.net/projects/lsleditor/ LSLeditor SourceForge]
 
:* [http://www.lsleditor.org/ Original Author's website with his latest LSLeditor version]
 
:* [http://www.lsleditor.org/ Original Author's website with his latest LSLeditor version]
:* [https://github.com/wp2opensim/LSLEditor LSL Editor] for Windows10 (from version WhiteCoreDev 2.56 Oct 2017)
 
 
:Now an Open Source project. New release is February 2012 (Ver.2.44.2). A valuable tool and easy install.
 
:Now an Open Source project. New release is February 2012 (Ver.2.44.2). A valuable tool and easy install.
 
----
 
----
Line 71: Line 99:
 
'''Notepad++''' ''(osFunctions supported with add-on UDF)'' [[Image:Windows_logo.png|24px|frameless|Windows version available]]
 
'''Notepad++''' ''(osFunctions supported with add-on UDF)'' [[Image:Windows_logo.png|24px|frameless|Windows version available]]
 
:* [http://notepad-plus-plus.org/ Notepad Plus Plus]
 
:* [http://notepad-plus-plus.org/ Notepad Plus Plus]
:* [https://github.com/WhiteStar-Magic/NotePad---userdef/archives/master LSL and OS functions UDF]
+
:* [https://gist.github.com/Tampa/7e02383b5abf1813fb143594cd7bcbdd LSL and OS functions UDF]
:* [https://github.com/wp2opensim/Notepad-plus-plus-OSSL-LSL-syntax-highlighting Notepad++ OSSL-LSL Syntax] with autocomplete and Phoenix LSL Präprozessor Syntax and oslogfile syntax highlight.
+
 
:Windows only Editor with enhanced capabilities & supports most languages. Very powerful & feature rich.
 
:Windows only Editor with enhanced capabilities & supports most languages. Very powerful & feature rich.
 
----
 
----
Line 85: Line 112:
 
:To use OSSL feature, use ".ossl" for your script file extension.
 
:To use OSSL feature, use ".ossl" for your script file extension.
 
:It is currently compatible with LL v3.4.1 and OpenSimulator v0.7.4+ (master r/21068).
 
:It is currently compatible with LL v3.4.1 and OpenSimulator v0.7.4+ (master r/21068).
----
 
'''FS2LSL Graphical editor''' ''(LSL OSSL)'' [[Image:Windows_logo.png|24px|frameless|Windows version available]][[Image:Macosx_logo.png|24px|MacOSX version available]][[Image:Tux.png|24px|frameless|Linux version available]]
 
:* [https://github.com/wp2opensim/FS2SL GitHub FS2LSL Graphical editor]
 
:Free and open source text editor, Online-Offline LSL/OSSL Graphical script editor for WEB Browser or Windows (Programming for beginners)
 
 
----
 
----
  
 
More editors are listed at http://wiki.secondlife.com/wiki/LSL_Alternate_Editors
 
More editors are listed at http://wiki.secondlife.com/wiki/LSL_Alternate_Editors
 
 
=== Syntax Highlighting ===
 
 
* [http://qbnz.com/highlighter/ GeSHi project home page]
 
* [https://sourceforge.net/projects/geshi/files/geshi/GeSHi%201.0.8.10/ Most current version of GeSHI for download]
 
* [https://github.com/WhiteStar-Magic/Scripting-Syntax-Highlights GeSHi LSL support file] includes osFunctions & updated
 
* Extra Reference at MediaWiki: [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi GeSHi Syntax Highlighter for WIKI and Forums]
 
  
 
=== Miscellaneous: ===
 
=== Miscellaneous: ===
 
* [http://scriptastic.greenbush.us A simple web based Scratch like environment for creating LSL code and teaching kids to make LSL scripts ]
 
 
* [http://www.hilarymason.com/blog/secondlife/autoscript-creates-lsl-scripts-without-code/ AutoScript, Simple & Quick Code generator for simple things (ONLINE)]
 
  
 
* [http://code.google.com/p/lslsnippets/ lslsnippets ]
 
* [http://code.google.com/p/lslsnippets/ lslsnippets ]
 
* [http://www.vtoreality.com/2006/free-offsite-storage-for-lsl-scripts-up-to-250k/186/ Free offsite storage for LSL scripts up to 250k ]
 
 
* [http://www.freeslscripts.gendersquare.org/index.php Free SL Scripts (library)]
 
 
* [http://s4sl.blogspot.com/ Scratch for SecondLife (Script Code generator with Nice Interface - UPDATED JUL.09.2009)]
 
 
 
* [http://inworks.ucdenver.edu/jkb/fs2lsl/ FS2LSL Flash Scratch to LSL (a feature-rich Scratch-like script code generator)]
 
* [http://inworks.ucdenver.edu/jkb/fs2lsl/ FS2LSL Flash Scratch to LSL (a feature-rich Scratch-like script code generator)]
 
+
* [https://outworldz.com/cgi/freescripts.plx Freescripts] - More then 1000 open source/public domain scripts (library)
* [http://www.peregrinesalon.com/2009/01/05/major-upgrade-to-animated-gif-to-animated-sl-texture-conversion-tool-v04/ Second Life Animated Texture Creator v0.4 - brought to you by Peregrine Salon]
+
* [https://www.conwylie.co.uk/ScriptGenerator/ Con Wylie's Script Generator] - Script Generator.
 
+
* [http://particles-lsl-generator.bashora.com/ Particles LSL Generator] - LSL Particles System script generator.
* [[Presentation Board]] - Simple Presentation Board that slides through inventory textures...
+
* [http://www.miceonabeam.com/ MiceOnABeam] - Scripting tools & componants for your virtual wolrd.
 
+
* [http://www.3greeneggs.com/autoscript/ Autoscript] - Script Generator.
* [http://www.free-lsl-scripts.com/cgi/freescripts.plx More then 1000 open source/public domain scripts (library)]
+
* [https://gridurl.appspot.com/ Grid URL Persister] - Designed to make work with http-in easier.
 
+
* [http://outworldz.appspot.com/ Easy Free Database] - Designed to easier to save persistent variables in Second Life and OpenSim scripts..
* [http://greenbushlabs.com/scriptastic Block Based Script Building Tool (like Scratch) making LSL Scripting Simple Enough Even for Kids]
+
 
+
* [https://github.com/wp2opensim/FS2SL GitHub FS2LSL] - FS2LSL Online-Offline LSL/OSSL script editor for WEB or Windows (Programming for beginners)
+
  
 
== Additional Resources for Scripting (OSSL) ==
 
== Additional Resources for Scripting (OSSL) ==
Line 137: Line 138:
 
* [[OsParseJSON example1|Language Translation]] - A script which uses the JSON parsing function to call Google's Translation API
 
* [[OsParseJSON example1|Language Translation]] - A script which uses the JSON parsing function to call Google's Translation API
 
* [http://www.osgrid.org/forums/ OSGrid Forums] - LSL/OSSL discussions, examples, tips, etc.
 
* [http://www.osgrid.org/forums/ OSGrid Forums] - LSL/OSSL discussions, examples, tips, etc.
 +
* [https://github.com/BigManzai/opensim-ossl-example-scripts OSSL example scripts for inventory] - Allows adding the [[OSSL Implemented|OSSL Functions examples]] scripts in the default inventory.
  
 
== How to contribute ==
 
== How to contribute ==
Line 144: Line 146:
 
* [[OpenSim.Region.ScriptEngine.Common]] - How to create your own script engine
 
* [[OpenSim.Region.ScriptEngine.Common]] - How to create your own script engine
 
* [[OpenSim.Region.ScriptEngine.DotNetEngine|DotNet-Engine]] - Describes some of the esoteric parts of the DotNet-Engine  
 
* [[OpenSim.Region.ScriptEngine.DotNetEngine|DotNet-Engine]] - Describes some of the esoteric parts of the DotNet-Engine  
 
  
 
== Example LSL Scripts ==  
 
== Example LSL Scripts ==  
 
 
* [[An Opensim version for llHTTPResponse]]
 
* [[An Opensim version for llHTTPResponse]]
 
* [[Changed_Event_Example]]
 
* [[Changed_Event_Example]]
 +
* [[OpenSim:_LSL2CS|SetScope]] - Example of using SetScope()
 
* [[DONTSITONME]]
 
* [[DONTSITONME]]
 
* [[LlParticleSystemExample|llParticleSystemExample]]
 
* [[LlParticleSystemExample|llParticleSystemExample]]
Line 159: Line 160:
 
* [[Sound loop]]
 
* [[Sound loop]]
 
* [[Smooth rotate texture]]
 
* [[Smooth rotate texture]]
 +
* [[Presentation Board]] - Simple Presentation Board that slides through inventory textures.
  
 
== See Also ==
 
== See Also ==

Latest revision as of 05:05, 6 June 2023

Contents

[edit] About OpenSimulator scripting

An important ingredient in virtual worlds simulation is scripting.
Scripts allow the addition of actions to 'entities' in world, like making a door react to a touch and open.
Since version 0.9.1.0, you can chose between old XEngine or new YEngine script engines.
Script engines do script compilation and control script execution.
OpenSimulator script language supports a subset of the Linden Labs Second Life script language (LSL) plus its own extensions (OSSL).

[edit] LSL in a nutshell

LSL is a event-driven language. A script is a collection of functions called event handlers.

Events are generated by the environment (mouse clicks, collisions and many more). Many of those events happen at time critical moments, so those event handlers should be small and fast to reduce impact on the rest of simulation. YEngine may allow long processing to happen with less impact on the simulation, but that will happen at lower priority.

(Hopefully), a script does nothing when there is no event to process. Is sits waiting for an event. Only events matching a event handler present in the script will be generated. If the script has no handler for mouse clicks, mouse clicks won't be reported.

LSL functions may also generate events. For example, llRezObject will trigger a object_rez event. llMessageLinked, a link_message event. This makes your script asynchronous (request action in a handler, get result in another handler). Understanding the flow of events in your script is essential.

An event cannot interrupt another event. Processing of the previous event must be finished before accepting a new one. Events are queued up to the number of 300 (OpenSim.ini, MaxScriptEventQueue). Finally, LSL has states that implements the concept of state machine. A script can respond differently to a same event in different states, or to another set of events.

[edit] String type in OpenSimulator

Most OpenSimulator LSL/OSSL string functions are only safe with characters that can be represented by a single .net (UTF-16) char. This means strings with characters of the Basic Multilingual Plane excluding combining characters
That is Unicode code points up to U+FFF0, except:

  • U+0300..U+036F (combining characters)
  • U+1AB0..U+1AFF (combining characters)
  • U+1DC0..U+1DFF (combining characters)
  • U+20D0..U+20FF (combining characters)
  • U+D800..U+DFFF (reserved for higher planes encode using 2 chars)
  • U+FE20..U+FE2F

Only in this case some compatibility with SL is possible.
OpenSimulator strings are internally encoded as .net strings that are basically arrays of UTF-16 chars.
A unicode character may be represented by more than one of those chars, but most .net and mono string functions ignore this and just assume all characters are single utf16 chars.
For example llStringLength returns the number of .net chars on the string, not necessary the real number of its characters.
Functions that take a index or in string position arguments use them as a index to the array of chars and so that may point to the middle of a complex character. In this case some of this functions may even create strings with invalid characters.
SL string functions do support most cases of 2 char characters, so full compatibility is not possible without breaking compatibility with older OpenSimulator versions. Only in this case some compatibility with SL is possible. Multiple char characters support also has a high performance cost.



LSL (Linden Scripting Language)
OSSL (OpenSimulator Scripting Language)

[edit] Configuring scripting

There are a number of parameters that can be tweaked for scripting, such as those which enable OSSL commands or increase the limits on certain script facilities (e.g. listeners).

For standalone and small grid use, the default scripting settings should be fine. See Configuring Scripting for information on configuring these parameters.

[edit] How to use scripts in OpenSimulator

If you have never written a script in LSL before, then please have a look at the LSL wiki to learn the scripting basics. If you do have (some) experience with writing or editing LSL scripts, then the procedure is identical to the procedure on SL. Known problems:

  • Error messages about scripting errors are often cryptic, and tend to be long.
  • Script syntax and execution may depend on the engine used, old XEngine or YEngine
  • On teleports or crossings from a region using YEngine to a region using XEngine, script state (like changed values on global variables) is lost. Should be okay on the inverse direction.

[edit] Scripting System Status

Status Tables / Charts related to LSL and OSSL functions, constants and related material.

LSL/OSSL Status Overview
LSL

OSSL

[edit] Additional Resources for Scripting (LSL)

There have been many questions regarding scripts and tools for scripting lately. Presented here are a variety of Links to Resources which will help most people with Scripting LSL.

[edit] OpenSimulator Specific Materials:

[edit] Suggested Links for LSL wikis:

Note the Tutorials, Examples & Script Libraries

[edit] Off-World Local LSL Editing Tools & Syntax Highlighters

Note: most do not support osFunctions

All EDITORS (no osFunctions) Windows version availableMacOSX version availableLinux version available

In this repository you can find the syntax grammar, syntax highlighting and snippet files for the Linden Scripting Language (LSL) of Second Life for different kinds of software.

LSL EDITOR (no osFunctions) Windows version available

Now an Open Source project. New release is February 2012 (Ver.2.44.2). A valuable tool and easy install.

LSL Plus (no osFunctions) Windows version availableMacOSX version availableLinux version available

Open source Eclipse plugin. Regular updates. Not quite as quick to get installed as LSLEditor, but very good tool.

Notepad++ (osFunctions supported with add-on UDF) Windows version available

Windows only Editor with enhanced capabilities & supports most languages. Very powerful & feature rich.

KATE (no osFunctions) Windows version availableMacOSX version availableLinux version available

Free and open source text editor, supporting lots of scriptinmg and programming languages out of the box. This includes LSL.

Sublime Text 2 (os*/wl*/mod* functions supported with the bundle below) Windows version availableMacOSX version availableLinux version available

Completions & syntax coloring of LSL/OSSL functions/events/constants & in-world editor look-and-feel theme.
To use OSSL feature, use ".ossl" for your script file extension.
It is currently compatible with LL v3.4.1 and OpenSimulator v0.7.4+ (master r/21068).

More editors are listed at http://wiki.secondlife.com/wiki/LSL_Alternate_Editors

[edit] Miscellaneous:

[edit] Additional Resources for Scripting (OSSL)

There have been many questions regarding scripts and tools for scripting lately. Presented here are a a few links to Resources which will help most people with OSSL scripting.

[edit] How to contribute

The ScriptEngine is being developed by many developers. New developers are always welcome. If you want to contribute, even just a tiny little bit, have a look at the OpenSim.Region.ScriptEngine page. There is a lot of developer activity on IRC (Support), feel free to drop in.

[edit] Example LSL Scripts

[edit] See Also

Personal tools
General
About This Wiki