OSSL

From OpenSim

Jump to: navigation, search


This is currently written up in one of justincc's blog posts. Some of that information should be transferred to here

Read whats implemented .


The following is JustinCC's blog post in question. Dated October 24th, 2008.

Note: A newer mechanism for adding OSSL script functions from region modules without any need to patch the OpenSimulator code itself is described at OSSL_Script_Library/ModInvoke.


Introduction

Despite our long term desire to see OpenSimulator 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

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. 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 OpenSimulator 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 OpenSimulator 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 :-)

Personal tools
About This Wiki