Scripting Documentation
From OpenSimulator
(→String type in OpenSimulator) |
(→String type in OpenSimulator) |
||
| Line 34: | Line 34: | ||
Some OSSL functions may be added with workarounds<br> | Some OSSL functions may be added with workarounds<br> | ||
| + | |||
| + | Note also that encoding to utf8 to store on databases or send elsewhere may also have additional issues. MySQL currently may only use uft8 with at most 3 bytes. | ||
</div><br> | </div><br> | ||
Revision as of 11:24, 1 October 2021
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.
A script is not a like a full program, it is a set of blocks of code called when some event happens, like a touch on the door.
Many of those events happen at time critical moments, so those blocks 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.
OpenSimulator script language supports a subset of the Linden Labs Second Life script language (LSL) plus its own extensions (OSSL).
String type in OpenSimulator
Most OpenSimulator LSL/OSSL string methods only support 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
note that sl excludes
- U+FDD0..U+FDEF
OpenSimulator strings are internally encoded as C# 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 funrctions ignore this and just assume all characters are single utf16 chars.
For example llStringLength returns the number of .net chars on the string, not the number of its characters.
The functions that take a index arguments use them as a index to the chars array and so that may point to the middle of a complex character. In this case some of this functions may create invalid strings
This is more restrictive than SL that may support up to 2 char characters on most functions while OpenSimulator code is only safe with characters than can be represented by a single UTF-16 char as the rule above enforces.
Some OSSL functions may be added with workarounds
Note also that encoding to utf8 to store on databases or send elsewhere may also have additional issues. MySQL currently may only use uft8 with at most 3 bytes.
LSL (Linden Scripting Language)
OSSL (OpenSimulator Scripting Language)
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.
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.
Scripting System Status
Status Tables / Charts related to LSL and OSSL functions, constants and related material.
OSSL
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.
OpenSimulator Specific Materials:
- OSSL Functions with examples - A good place to start reading about OSSL scripting.
- OSSL Script Library A library of scripts which utilize OSSL functions.
Suggested Links for LSL wikis:
Note the Tutorials, Examples & Script Libraries
Off-World Local LSL Editing Tools & Syntax Highlighters
Note: most do not support osFunctions
All EDITORS (no osFunctions) 
- 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)
- LSLeditor SourceForge
- Original Author's website with his latest LSLeditor version
- 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.
LSL Plus (no osFunctions)
- 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)
- Notepad Plus Plus
- LSL and OS functions UDF
- 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.
KATE (no osFunctions)
- 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)
- 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).
FS2LSL Graphical editor (LSL OSSL)
- 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
Syntax Highlighting
- GeSHi project home page
- Most current version of GeSHI for download
- GeSHi LSL support file includes osFunctions & updated
- Extra Reference at MediaWiki: GeSHi Syntax Highlighter for WIKI and Forums
Miscellaneous:
- A simple web based Scratch like environment for creating LSL code and teaching kids to make LSL scripts
- AutoScript, Simple & Quick Code generator for simple things (ONLINE)
- lslsnippets
- Free offsite storage for LSL scripts up to 250k
- Free SL Scripts (library)
- Scratch for SecondLife (Script Code generator with Nice Interface - UPDATED JUL.09.2009)
- FS2LSL Flash Scratch to LSL (a feature-rich Scratch-like script code generator)
- Second Life Animated Texture Creator v0.4 - brought to you by Peregrine Salon
- Freescripts - More then 1000 open source/public domain scripts (library)
- Scriptastic - Block Based Script Building Tool (like Scratch) making LSL Scripting Simple Enough Even for Kids.
- GitHub FS2LSL - FS2LSL Online-Offline LSL/OSSL script editor for WEB or Windows (Programming for beginners).
- Con Wylie's Script Generator - Script Generator.
- Particles LSL Generator - LSL Particles System script generator.
- MiceOnABeam - Scripting tools & componants for your virtual wolrd.
- Autoscript - Script Generator.
- Grid URL Persister - Designed to make work with http-in easier.
- Easy Free Database - Designed to easier to save persistent variables in Second Life and OpenSim scripts..
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.
- OSSL Functions with examples - A good place to start reading about OSSL scripting.
- OSSL Script Library A library of scripts which utilize OSSL functions.
- OSSL Proposals - Suggestions for custom OSSL functions. Got a suggestion too? Add it!
- Drawing commands - How to use the texture draw functions supported in OSSL.
- OSSL TextureDrawing - Details of the OSSL texture drawing functions.
- Language Translation - A script which uses the JSON parsing function to call Google's Translation API
- OSGrid Forums - LSL/OSSL discussions, examples, tips, etc.
- OSSL example scripts for inventory - Allows adding the OSSL Functions examples scripts in the default inventory.
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.
- OSSL Standards - A whitepaper concerning naming-standards for the OpenSimulator scripting language
- OpenSim.Region.ScriptEngine.Common - How to create your own script engine
- DotNet-Engine - Describes some of the esoteric parts of the DotNet-Engine
Example LSL Scripts
- An Opensim version for llHTTPResponse
- Changed_Event_Example
- SetScope - Example of using SetScope()
- DONTSITONME
- llParticleSystemExample
- ModSendCommand
- Rotating Prim
- Particles
- Public_Trampoline_Script
- Sit and position
- Sound loop
- Smooth rotate texture
- Presentation Board - Simple Presentation Board that slides through inventory textures.
See Also
- Scripting Engine - Xengine Script Engine Transition (By Melanie_T), YEngine
- Scripting Languages - Supported Scripting Languages
- LSL/OSSL Status - Status and news about LSL and OSSL
- OSSL Enabling Functions - How to enable OSSL functions.
- Threat level - Information about OSSL threat levels.
