IRegionModule

Revision as of 02:29, 17 November 2008

Introduction

A key design principle of OpenSim is the heavy use of plug-ins. All the key components of OpenSim are designed to be replaceable or extensible at runtime.

• Database engines can be replaced (currently OpenSim has full support for)
  • SQLite
  • MySQL
  • MS-SQL Server is fairly complete but largely untested.

• Backend servers can be replaced by changing a url, currently there are servers for:
  • User authentication
  • Grid registration
  • Asset storage
  • Inventory storage
  • Messaging storage
  • Script execution

• Script languages can be replaced
• Region modules can be added

Region modules are .net/mono dlls. During initialization of the simulator, the current directory (/bin) and the scriptengines (/ScriptEngines) directory are scanned for dlls, in an attempt to load region modules stored there.

Region modules execute within the heart of the simulator. Typically region modules register for a number of events, e.g. chat messages, user logins, texture transfers, and take what ever steps are appropriate for the purposes of the module.

Region Modules require a few basic things:

• The Base Interface
• Some callbacks for OpenSim events

The Base Interface

All region modules must implement this interface:

public interface IRegionModule
{
    void Initialise(Scene scene, IConfig config);
    void PostInitialise();
    void Close();
    string Name { get; }
    bool IsSharedModule { get; }
}

The base interface doesn't give you much beyond a piece of loaded code. In order to do anything useful you'll need to use a combination of events and object crawling through scene.

Accessible Objects

Note: these are internal interfaces, and will change in the future, probably for the better. We expect these to stabalize over time, but for now this point in time snapshot is probably helpful.

In the Initialise routine you get access to the scene object for the region, from here you can spider down into the scene and get access to many other objects of interest.

• scene.GetEntities() - returns a list of all the Entities in the environment. This will be a combined list of SceneObjectGroups (prim sets) and ScenePresences (avatars).
• scene.GetAvatars() - get only the avatars in the scene (very handy for sending messages to clients)
• scene.EventManager - this is the object from which you can register callbacks for scene events. Some examples provided in a little bit
• scene.RegionInfo - properties about the region

Registering for Events

Taking the SunModule as an example we can see the following code:

In Initialise():

...
m_scene.EventManager.OnFrame += SunUpdate;
...

Pretty simple, we just got the EventManager and registered the SunUpdate method as a callback for the OnFrame event. OnFrame is triggered every time there is a render frame in opensim, which is about 20 times per second. If you are firing on the OnFrame event you need to do something small, or punt most of the time, as you'll negatively impact the performance of the system otherwise.

Now, for that function...

public void SunUpdate()
{
    // this code just means only do this on every 1000th frame, and don't do it if the sun is in a fixed possition
    if (((m_frame++%m_frame_mod) != 0) || !ready || sunFixed)
    {
        return;
    }
 
    GenSunPos();        // Generate shared values once
 
    List<ScenePresence> avatars = m_scene.GetAvatars();
    foreach (ScenePresence avatar in avatars)
    {
        if (!avatar.IsChildAgent)
            avatar.ControllingClient.SendSunPos(Position, Velocity, CurrentTime, SecondsPerSunCycle, SecondsPerYear, OrbitalPosition);
    }
 
    // set estate settings for region access to sun position
    m_scene.RegionInfo.RegionSettings.SunVector = Position;
}

SunUpdate() takes no parameter (some events may require them). It only fires every 1000th frame by default (m_frame_mod = 1000 in this module), so it doesn't take too many cycles.

In order for the sun position to change for the clients, they need to be told that it changes. This is done by getting a list of all the Avatars from the scene, then sending the Sun Position to each of them in turn. It is important to check to see if the avatar is a ChildAgent, otherwise you will generate zombies in opensim world.

Where to go from here

• Read the source for existing modules. You can do it here via view svn.
• Read the source for EventManager. It will tell you what events exist.
• Help write more examples here. OpenSim grows with your contributions.