XEngine

=Summary=

This is a fully functional, full featured script engine which supports persistent script states and script state serialization.

This engine is enabled by default.

For each unique script asset, XEngine will create up to 4 files. These are:


 * CommonCompiler_compiled_.dll, the actual executable DLL for that script asset.
 * On mono, CommonCompiler_compiled_.mdb, the debug data file (necessary for resolving line numbers).
 * On Windows, CommonCompiler_compiled_.pdb, the debug data file (necessary for resolving line numbers).
 * CommonCompiler_source_CommonCompiler_compiled_.cs, if WriteScriptSourceToDebugFile = true in [XEngine] in OpenSim.ini. This is the C# source file as translated from the source language (e.g. from LSL) before compilation.

If scripts contain identical source code then there can be more than one script using the same code. However, they will maintain separate state files to record the script's individual state. These are labelled


 * .state

For more information on state files, see below.

= Configuration =

XEngine is enabled by default in OpenSimulator. If you do need to enable it manually, make sure that the following line is present in your OpenSim.ini [Startup] section:

DefaultScriptEngine = "XEngine"

XEngine has a number of configuration options in OpenSim.ini, which are listed below, with an explanation and the default values:

''' WARNING! Do NOT copy the section below to your OpenSim.ini! ' Use the template provided in OpenSim.ini.example. The section below contains syntactically incorrect documentation text, which is not meant to be placed in the OpenSim.ini file!

ScriptStopStrategy
This setting was introduced in OpenSimulator 0.7.6 (http://opensimulator.org/pipermail/opensim-dev/2013-January/023985.html).

There are two possible values, "abort" (the default as of OpenSimulator 0.8) and "co-op".

In abort mode, a script thread that takes too long to stop when requested (e.g. because the object is de-rezzed), has its thread aborted via the Thread.Abort SDK method.

Although this is fine in the vast majority of cases, in heavily loaded simulators where many scripts are often being stopped, such an abort can destabilize the virtual machine and either crash the VM entirely or lead to odd problems such as 100% CPU usage with no apparent cause. Aborting threads in this way is highly discouraged.

The "co-op" setting instead inserts checks into the compiled script so that it can be co-operatively shut down rather than aborted. These checks are placed in such a way that the script cannot ignore them. Despite the name of the setting, co-op doesn't require any changes to the script source code itself - the checks are inserted entirely by XEngine under the hood.

As of OpenSimulator 0.7.6, this setting is technically experimental but should be considered operational, as it has been used in many settings and in places such as the OSGrid plazas without incident.

From OpenSimulator 0.7.6 to 0.8, if this setting was changed from "abort" to "co-op", then the compiled script cache would either need to be manually cleared or OpenSimulator started with DeleteScriptsOnStartup = true for one session.

As of git master d7b92604 OpenSimulator development code (11th July 2014), this setting can now be switched without any other user action being required. The recompiled DLLs will be used on the next simulator restart.

OS Functions enable/disable
For each function, you can add one line, as shown ; true is the default for all functions, and allows them if below threat level Allow_osSetRegionWaterHeight = true ''This allows any user to use it, if the threat level permits or ; false disables the function completely Allow_osSetRegionWaterHeight = false ''Prevents anyone from using it or ; Comma separated list of UUIDS allows the function for that list of UUIDS Allow_osSetRegionWaterHeight = 888760cb-a3cf-43ac-8ea4-8732fd3ee2bb ''Allows only the listed user(s) to use these functions (unconditionally)

Both engines share the same parser and LSL implementation, so any script that runs on one can be expected to run on the other, with a few notable exceptions:


 * Resetting other scripts (XEngine only)
 * Stopping/starting other scripts (XEngine only)

= Event Execution = XEngine maintains its own SmartThreadPool to execute script events. The maximum number of threads for this pool (and hence the maximum simultaneous events) is set by [XEngine] MaxThreads. You can also see this information in the "xengine status" command.

When a script event needs to be run (e.g. state_entry, touch_start, etc.), it is placed on the ScriptInstance.EventQueue. If there is no work item event already scheduled, then it is placed as a work item on the threadpool and m_CurrentWorkItem is set.

When a threadpool thread becomes available, it runs the event through the ScriptInstance.EventProcessor method. At the end of this method, if events are still waiting (i.e. if EventQueue.Count > 0) then another work item is scheduled.

= State persistence =

XEngine persists state and variable values for individual script instances across region restarts. This is stored in a .state file. When a script is deleted, the .state file is also deleted.