IRegionModule

Revision as of 06:22, 18 September 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
- 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; }
}

Name	Description
Initialise	This method is called immediately after the region module has been loaded by the sim. At this time the module is passed a reference to the scene contained within the sim. The region module should store this reference for later use. Care should be taken, not to depend on the scene and/or sim being fully loaded and running at this time.
PostInitialise	Once the sim is fully initialized and all region modules have been loaded, the sim will invoke PostInitialize on all loaded region modules. At this point the sim will be fully operational, and it should be safe to invoke any method on the scene.
Close	This method will be invoked when the sim is closing down.
Name	This name is shown when the console command "show modules" is ran. It's should be a nice name like "Sim Chat Module" or "The Best Region Module Ever".
IsSharedModule	The simulator process (OpenSim.exe) supports running multiple regions (internally, a Scene object) on a single simulator process. If this returns True, the module will only be loaded once and Initialize will be called for each Scene being simulated. If false, a separate copy of your RegionModule will be created for each Scene.

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;
...
    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;
        }

@@ Line 18: / Line 18: @@
 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.
-== Interface ==
+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);
+      void Initialise(Scene scene, IConfig config);
       void PostInitialise();
       void Close();
@@ Line 36: / Line 40: @@
 </tr>
 <tr>
-<td>Initialize</td>
+<td>Initialise</td>
 <td>This method is called immediately after the region module has been loaded by the sim. At this time the module is passed a reference to the scene contained within the sim. The region module should store this reference for later use. Care should be taken, not to depend on the scene and/or sim being fully loaded and running at this time.
 </td>
 </tr>
 <tr>
-<td>PostInitialize</td>
+<td>PostInitialise</td>
 <td>Once the sim is fully initialized and all region modules have been loaded, the sim will invoke PostInitialize on all loaded region modules. At this point the sim will be fully operational, and it should be safe to invoke any method on the scene.</td>
 </tr>
@@ Line 58: / Line 62: @@
 </table>
-== How to write a new region module ==
+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.
-=== Walk through on Windows ===
-On Windows, using Visual studio, this is what you need to do, to create a new region module:
-#Create a new project
+== Accessible Objects ==
-##File, New, Project
-##Select "Visual C#", "Class Library"
-##Give the region module some good name, like: "MyRegionModule"
-#Reference the required OpenSim assemblies
-##Right click on "References" and choose "Add Reference..."
-##Choose the browse tab
-##Navigate to the bin folder of OpenSim
-##Select "OpenSim.Framework.dll"
-##Click Ok
-##Right click once more on "References" and choose "Add Reference..."
-##Select "OpenSim.Region.Environment.dll"
-##Click Ok
-#Change default class, to a meaningfull name
-##Right click on "Class1.cs" and rename the file to "MyRegionModuleMain.cs
-Now the code should look something like this:
+'''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.
- using System;
+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.
- using System.Collections.Generic;
- using System.Text;
- namespace MyRegionModule
- {
-     public class MyRegionModuleMain
-     {
-     }
- }
-delete the unwanted <tt>using</tt> lines:
+* 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
- using System.Collections.Generic;
+== Registering for Events ==
- using System.Text;
-now, the program should contain:
+Taking the SunModule as an example we can see the following code:
- using System;
+In Initialise"
+<pre code="c#">
- namespace MyRegionModule
+    m_scene.EventManager.OnFrame += SunUpdate;
- {
+...
-     public class MyRegionModuleMain
+    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;
+            }
-add references to the main OpenSim modules:
+            GenSunPos();        // Generate shared values once
- using OpenSim.Region.Environment.Interfaces;
+            List<ScenePresence> avatars = m_scene.GetAvatars();
- using OpenSim.Region.Environment.Scenes;
+            foreach (ScenePresence avatar in avatars)
+            {
+                if (!avatar.IsChildAgent)
+                    avatar.ControllingClient.SendSunPos(Position, Velocity, CurrentTime, SecondsPerSunCycle, SecondsPerYear, OrbitalPosition);
+            }
-specify that <tt>MyRegionModuleMain</tt> should inherit from the <tt>IRegionModule</tt> interface:
+            // set estate settings for region access to sun position
+            m_scene.RegionInfo.RegionSettings.SunVector = Position;
+        }
+</pre>
- using System;
- using OpenSim.Region.Environment.Interfaces;
- using OpenSim.Region.Environment.Scenes;
- namespace MyRegionModule
- {
-     public class MyRegionModuleMain : IRegionModule
-     {
-     }
- }
-Right click on the "IRegionModule" name, and select "Implement interface", "Implement Interface"; this will add an empty implementation of the interface required for a region module. If you compile the module, and ensure that the resulting .dll file is stored in the /bin directory of OpenSim, the region module will be loaded and exected the next time you start the sim.
-The close observer will have noticed that this region module will not do anything worthwhile; in fact it will cause OpenSim to log a warning about exceptions in a loaded module.
 [[Category:Development]]

Views

IRegionModule

From OpenSimulator

Revision as of 06:22, 18 September 2008

Contents

Introduction

The Base Interface

Accessible Objects

Registering for Events

Personal tools

General

For Administrators

For Developers

For Creators

For Grid Users

Related Links

About This Wiki

Search

Tools