C# scripting in OpenSim

A month ago, I wrote a short article about how to add an OSSL (OpenSimulator Scripting Language) function to OpenSim. This assumed that you were writing a script using the Linden Scripting Language (LSL).

However, in principle LSL is not the only language that you can write scripts in for OpenSim.  LSL scripts in OpenSim are actually translated into C# before being compiled and executed.  Therefore, it’s possible to bypass LSL and instead write in C# directly (or in Visual Basic, Javascript or any language which has a .net compiler that can be added to OpenSim).  Indeed, some OSSL functions (such as osParseJSON()) will not currently work in LSL at all – the data it returns cannot be easily stuffed into any LSL data type.  Unfortunately, there is a

major caveat with allowing OpenSim to directly execute C# and other non-LSL scripts.  We’ll cover this later on.

But first of all, how does one write and execute a C# script in OpenSim?  The first step is to make sure that OpenSim is allowed to compile C#.  In your OpenSim.ini file, you will need the entry

AllowedCompilers = lsl, cs

in either the [ScriptEngine.DotNetEngine] or [XEngine] sections depending on which script engine your using (or both, if you want to be sure).

Now that this is done, we can enter a C# script.  Here is a very short example.

//c#
// justincc's short test script

string message = "Hello avatar!";
string xml = "<tag>ribbit</tag>";

public void default_event_state_entry()
{
    llSay(0, message);
}

public void default_event_touch_start(
    LSL_Types.LSLInteger total_number)
{
    System.IO.StringReader sr
        = new System.IO.StringReader(xml);
    System.Xml.XmlTextReader reader
        = new System.Xml.XmlTextReader(sr);

    llSay(0, reader.ReadElementString("tag"));
}

You can copy and paste this into a normal Second Life script within OpenSim.

As you can see, the structure is quite different from that of an LSL script.  The first line

//c#

is always required to tell OpenSim that the script should be compiled as a C# script.  WIthout this, the LSL compiler would be used instead (unless you’ve changed the default compiler in OpenSim.ini).

In the subsequent lines you can see that we don’t have the ‘default’ state section that one would find in an LSL script.  Instead, the functions that receive events need to have names in the format <state>_event_<event function>.  For instance,


state_entry() in the default state an LSL script
becomes public void default_event_state_entry().

touch_start(integer total_number)
becomes default_event_touch_start(LSLType.LSLInteger total_number).


We need to use LSLType.LSLInteger instead of C#’s int since this is the method signature that the script engine expects).

There is a more complex example of a C# script that uses osParseJSON() here.

So what are the advantages of writing scripts directly in C#?  The major one is that one gets can use the .NET APIs directly.  We can’t use C#’s using directives in the script so they need to be accessed using their full names (e.g. System.IO.StringReader rather than StringReader).  Among other things, this allows one to use much richer data types in C# that aren’t available in LSL, such as System.Collections.Generic.Dictionary.  One could also do such things as parsing XML using .NET (or mono’s) bundled XML parsers, as shown in the example above.

However, this advantage also forms C# scripting’s current major weakness.  At the moment, as well being able to use such helpful classes as System.Collections.Generic.Dictionary, it’s also possible to call methods such as System.File.IO.Delete(“path/to/really/important/system/file”).  Mantis 2610 has some more details of why this is.  Hopefully, this can be fixed at some stage, but at the moment I would have to recommend that you don’t enable C# scripting on a server unless you really, really, really trust everybody who has access to it.

Alternatively, one may also be able to prevent non-administrators from creating or editing scripts at all.  I hope to write about this at a later date, though these OpenSim facilities are still very experimental.