IRegionModule

Revision as of 19:03, 3 December 2010

 

Home

 

Download

 

News

 

Support

 

Admin

 

Dev

 

Screen Shots

 

Grid List

 

Bugs

Languages:

English    Deutsch

Introduction

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

Region modules execute within the heart of the simulator and have access to all its facilties. 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.

There are two types of region module.

• Non-shared modules where a separate module is created for each region/scene
• Shared region modules, where a single module is shared between all regions/scenes running on the same simulator.

Region Modules require a few basic things:

• The Base Interface
• Some callbacks for OpenSim events

Example

Let's start off with the most basic region module possible. Below is a region module that does nothing more than log the events that it receives. Technically, it could be made a little simple by printing messages directly to the console rather than OpenSim's logging infrastructure but it's better to have it nicely integrated.

You can also find this example in OpenSim/Region/OptionalModules/Example/BareBonesNonShared/BareBonesNonSharedModule.cs in OpenSim's source distribution. There's also a bare bones shared module example there.

using System;
using System.Reflection;
using log4net;
using Mono.Addins;
using Nini.Config;
using OpenSim.Region.Framework.Interfaces;
using OpenSim.Region.Framework.Scenes;
 
namespace OpenSim.Region.OptionalModules.Example.BareBonesNonShared
{
    /// <summary>
    /// Simplest possible example of a non-shared region module.
    /// </summary>
    /// <remarks>
    /// This module is the simplest possible example of a non-shared region module (a module where each scene/region
    /// in the simulator has its own copy).
    ///
    /// When the module is enabled it will print messages when it receives certain events to the screen and the log
    /// file.
    /// </remarks>
    [Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule", Id = "BareBonesNonSharedModule")]
    public class BareBonesNonSharedModule : INonSharedRegionModule
    {
        private static readonly ILog m_log = LogManager.GetLogger(MethodBase.GetCurrentMethod().DeclaringType);
 
        public string Name { get { return "Bare Bones Non Shared Module"; } }        
 
        public Type ReplaceableInterface { get { return null; } }
 
        public void Initialise(IConfigSource source)
        {
            m_log.DebugFormat("[BARE BONES]: INITIALIZED MODULE");
        }
 
        public void Close()
        {
            m_log.DebugFormat("[BARE BONES]: CLOSED MODULE");
        }
 
        public void AddRegion(Scene scene)
        {
            m_log.DebugFormat("[BARE BONES]: REGION {0} ADDED", scene.RegionInfo.RegionName);
        }
 
        public void RemoveRegion(Scene scene)
        {
            m_log.DebugFormat("[BARE BONES]: REGION {0} REMOVED", scene.RegionInfo.RegionName);
        }        
 
        public void RegionLoaded(Scene scene)
        {
            m_log.DebugFormat("[BARE BONES]: REGION {0} LOADED", scene.RegionInfo.RegionName);
        }                
    }
}

The Base Interfaces

Region modules must implement INonSharedRegionModule or ISharedRegionModule as appropriate - the example above implements INonSharedRegionModule. However, both these interfaces extend IRegionBase, defined as follows.

public interface IRegionModuleBase
{
     string Name { get; }
     Type ReplaceableInterface { get; }
     void Initialise(IConfigSource source);
     void AddRegion(Scene scene);
     void RemoveRegion(Scene scene);
     void RegionLoaded(Scene scene);
     void Close();
}

INonSharedRegionModule itself contains no methods, being defined simply as

public interface INonSharedRegionModule : IRegionModuleBase
{
}

ISharedRegionModule has one additional method.

public interface ISharedRegionModule : IRegionModuleBase
{
    void PostInitialise();
}

Enabling the module

Creating the module code itself isn't quite enough to enable it. To do that, we need to make it visible to OpenSim's module mechanism (which is currently Mono.Addins).

This is done by adding an Extension attribute to the class, for example.

[Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule", Id = "BareBonesNonSharedModule")]

The important part here is the "Path" section - this is how OpenSim retrieves modules from Mono.Addins. The Id can be anything meaningful to the module.

Integrating with OpenSim

NOTE: This section is now very out of date - NEEDS WORK!

Accessible Objects

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

In the AddRegion 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

• Getting Started with Region Modules -- the Hello World of OpenSim application development. Rather old by now but still worth a look.
• Read the source for existing opensim core modules. These are in the OpenSim.Region.CoreModules and OpenSim.Region.OptionalModules projects.
• Read the source code for the EventManager class in the OpenSim.Region.Framework.Scenes project. These list the many events that exist. Some modules may also export their own events (e.g. OnInventoryArchiveSaved in the InventoryArchiverModule at OpenSim/Region/CoreModules/Avatar/Inventory/Archiver/).
• Help write some examples here. OpenSim grows with your contributions.