jump to navigation

OpenSim Scripting Languages: LSL and OSSL October 24, 2008

Posted by justincc in opensim, opensim-dev, opensim-tech-basics, secondlife.
trackback

Introduction

Despite our long term desire to see OpenSim become a general virtual environment platform, implementing all the functions in the Linden Scripting Language (LSL) for the Second Life environment has become one of our de facto aims.  This is very understandable for two reasons

  1. There is a large stock of Second Life scripts already written in LSL.  The more accurately our implementation of LSL, the easier it is to reuse that existing code.
  2. The syntax and ll functions of LSL effectively constitute a language specification.  This allows lots of different open source contributors to work in ‘bazaar‘ fashion.  Many different people can contribute patches that implement ll functions piecemeal, with no need to co-ordinate their efforts with other open source contributors.

However, LSL is imperfect.  Leaving aside any questions about the inconsistency of Linden Lab’s ll function implementations or the deficiencies of the language itself, there is also a lot of missing functionality.  For instance, in LSL one cannot teleport an agent (instead various imperfect workarounds have to be used).  Neither can one write data to notecards, or find out information about avatar group roles.

OpenSimulator Scripting Language (OSSL)

How could the problem of missing functionality be addressed?  If we leave aside the prospect of using completely different languages with their own function implementations (C#, Python, etc.), one way to do it is to extend LSL by adding extra functions that OpenSim understands.  This is what the OpenSimulator Scripting Language (OSSL) is.  It is effectively all of LSL plus extra functions that start with an os prefix.  os functions can be used in a script in exactly the same way as ll functions are used.  Examples of os functions are

  • osTeleportAgent() allows you to teleport an agent to another position and region.
  • osSetDynamicTextureURL() allows you to display an external or dynamically generated image inworld  (as used in this inworld webpage display script or my own ‘graffiti board’ script that displays text on a single texture in-world.
  • osParseJSON() allows you to parse JSON within a script.  This isn’t such a good example as the HashTable return type probably makes it unusable currently in LSL scripts (the example here is a script in compiled C#).  However, I think it could be extended to return a data structure that could be used in LSL.

How to implement an OSSL function

Implementing an OSSL function is a little fiddly – you need to make changes in 3 places.  First, let’s do the actual implementation itself.  Just as there exists an LSL_Api class in the OpenSim.Region.ScriptEngine.Shared.Api package that implements all the LSL functions, so there is an OSSL_Api class that implements OSSL functions.  To implement a new function, one would add a method with the same name in OSSL_Api.cs.  For example

public string osMyFunction()
{
    // We'll talk about this in the next section
    CheckThreatLevel(ThreatLevel.None, "osMyFunction");  

    // Let stats know that a script line has been executed
    m_host.AddScriptLPS(1);  

    return "Hello World!";
}

The method signature for this implementation needs to be added to the interface IOOSL_Api in OpenSim.Region.ScriptEngine.Shared (Api/Interface directory)

string osMyFunction();

Finally, a method to call the function via this interface must be added to the ScriptBaseClass (which underlies all LSL and OSSL scripts) in the OSSL_Stub.cs file in package OpenSim.Region.ScriptEngine.Shared.Api.Runtime.

public string osMyFunction()
{
    return m_OSSL_Functions.osMyFunction();
}

Then it’s a case of recompiling OpenSim and restarting the region server.  Before you restart, make sure that

AllowOSFunctions = true

is set in your OpenSim.ini.  If this isn’t set then no os function will run no matter what threat level is set (as discussed below).

Once you’ve restarted OpenSim, you can invoke osMyFunction() in an in-world script

default
{
    state_entry()
    {
        llSay(0, osMyFunction());
    }
}

In the future I hope it will become possible to add new functions via plugins rather than by altering the OSSL_Api.cs file.

Don’t threaten me

You may have noticed the line

CheckThreatLevel(ThreatLevel.None, "osMyFunction");

above.  Just as some ll functions are dangerous in a virtual world environment and need to be limited (e.g. llRezObject()), so os functions may also need to be controlled.  Therefore, each os function has a ‘threat level’ that is checked before execution.  Threat levels range from None (no threat at all), through to Moderate (intentional abuse may cause denial of service) and up to Severe (even casual use may cause region instability and/or data loss).  Our example osMyFunction() is rated None because it simply returns “Hello world”.  Something like osTeleportAgent() is currently rated High because no security checks are currently carried out before teleport.

Region adminstrators can change the level of os functions they prefer to allow by changing the OSFunctionThreatLevel attribute in OpenSim.ini.  They can also turn individual os functions on and off.

In a public virtual world context you might never want to allow functions with high threat levels.  However, in a virtual world where the people allowed in are trusted, or in application virtual environments allowing such functions may make a lot more sense.

Contributions welcome

OSSL is by no means complete.  So patches to implement functions that you wish existed in LSL are welcome – we’re always happy to consider them 🙂

Advertisements

Comments»

1. C# scripting in OpenSim « justincc’s opensim blog - November 21, 2008

[…] by justincc in opensim, opensim-scripting, opensim-tech-basics. trackback A month ago, I wrote a short article about how to add an OSSL (OpenSimulator Scripting Language) function to OpenSim. This assumed that […]

2. Patrick - January 18, 2009

about drawing textures,

Great job, but, when you want to draw a text including “;” in it you miss all that come after “;”. Is there any issue to it ?

Thanks

justincc - January 20, 2009

This may be a bug or it may simply require clarification of how to do this – please raise an issue in the OpenSim bug database at http://opensimulator.org/mantis/main_page.php

3. Ai Austin - January 23, 2009

Justin, I cannot see a “OSSL_Api.cs” file in the Opensim bin area.. is it normally empty… with the osFunctions like osSetDynamicTextureURL, osSetDynamicTextureData, etc built in?

can we get a l;ist of the built in functions on the OS Wiki? And the threat level for each alongide? Meanwhile, what is the required threat level setting in opensim.ini for the 2 above?

4. justincc - January 23, 2009

OSSL_Api.cs is actually in the source code at OpenSim/Region/ScriptEngine/Shared/Api/Implementation/OSSL_Api.cs

As you pointed out to me by e-mail, this is a list of functions at http://opensimulator.org/wiki/OSSL_Implemented

5. Ai Austin - January 23, 2009

Ah, thanks Justin. You blog here also says you can individually enable/dispable osFunctions… is that mutually separate to setting the threat level, and where can you do it – is it in opensim.ini?

If I want to say allow 3 specific osFunctions and no others, wehatever their threat level, how is that done?

justincc - January 25, 2009

Yes, I see this isn’t documented very well – there isn’t even anything in OpenSim.ini.example for this. There might be something on the wiki but I don’t know where. A link would be appreciated if you can find one.

From reading the code, it looks like a setting in OpenSim.ini in the [XEngine] or [ScriptEngine.DotNetEngine] sections such as

Allow_osTeleportAgent = true

would allow it for everybody no matter what threat level threshold was set (and as long as the general AllowOSFunctions switch is true).

On the other hand, it looks like one can also supply a list of UUIDs for users so that only scripts owned by that user can execute that function. For instance,

Allow_osTeleportAgent = 36bff189-1a29-41dd-aeaa-81139148ec08

would allow only scripts owned by the user denoted by uuid 36bff189-1a29-41dd-aeaa-81139148ec08 to execute osTeleportAgent().

6. Ai Austin - January 25, 2009

Thanks, I will test with that.

Can yo tell if the default for AllowOSFunctions is false as I suspect? If so we should get the opensim.ini.example file amended… it current states the default is true. Can you check and make that change to get everything in sync as a developper Justin?

Also, it would be great to get the osSetDynamicTextureData full function set documented on the Wiki, and the 2 examples in the distrtibution lined explicity to the Wiki page so all the xanmplesa are available to a wilki broswer.

7. Ai Austin - January 26, 2009

I found that the list of osSetDynamic TextureData functions is available at

http://opensimulator.org/wiki/OSSL_TextureDrawing

Though te 3example is a C# one which I am not sure how to compile as I have DotNetEngione enabed.

I added the function list as a link in
http://opensimulator.org/wiki/OSSL_Implemented

The Opensim Wiki is difficult to fund one way round.

8. justincc - January 30, 2009

I correct the information in OpenSim.ini.example about AllowOSFunctions in r8184.

Filling out the functions I’m afraid I will have to leave to somebody else, since I have to prioritize my (always) limited time 🙂

You might be somewhat disturbed to know that while looking for the os functions page in the wiki, I came across another one at

http://opensimulator.org/wiki/LSL_osFunctions

This should really be amalgamated with

http://opensimulator.org/wiki/OSSL_Implemented

justincc - January 30, 2009

Oops my mistake. The stuff on http://opensimulator.org/wiki/LSL_osFunctions is largely suggestions for functions, not actually implemented ones.

9. Nolo - February 7, 2009

I felt compelled to second the notion of Ai @ #8.

“Also, it would be great to get the osSetDynamicTextureData full function set documented on the Wiki, and the 2 examples in the distrtibution lined explicity to the Wiki page so all the xanmplesa are available to a wilki broswer.”

I understand that it’s difficult to ask for such things and to do so leans toward optimism, but ANY help in the area of documentation would greatly serve /everybody’s/ cause to date. Calling all units – rapid fire reporting needed on site! 🙂 I tend to border on the insane though…

10. justincc - February 8, 2009

@Nolo. Oh, I do agree, proper documentation would be very nice. Unfortunately, it seems that my fellow developers don’t always agree with me – hopefully this is an area in which we will improve as OpenSim matures.

Actually, I believe that osSetDynamicTextureData is only a thin wrapper around a .NET library function for drawing lines, text, etc. dynamically on a surface. So if one were to hunt that down in the .NET SDK documentation that might provide all the information that you need.

11. Stefanie - June 3, 2010

thanks for providing this description, but how to implement events in OSSL?

12. justincc - June 14, 2010

Hi Stefanie. Unfortunately, I suspect that there’s no easy way to provide custom events in OSSL at this time without changing a lot of core OpenSim code.

13. David - August 10, 2010

Great!!! Worked just fine. Recompiled with VS# 2008 Express, I’m testing my own osFunctions on my Standalone region an all it´s ok!!
Thanks

14. AdelleF - October 22, 2010

Thanks for this Justin, it was a great help in my getting started with programming OpenSim 🙂


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: