IRegionModule

From OpenSimulator

Revision as of 16:19, 12 February 2008 by KMeist Hax (Talk | contribs)

Jump to: navigation, search

Contents

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
    • db4o is partially implemented
    • 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.

Interface

All region modules must implement this interface:

public interface IRegionModule
{
    void Initialise(Scene scene);
    void PostInitialise();
    void Close();
    string Name { get; }
    bool IsSharedModule { get; }
}
Name Description
Initialize 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.
PostInitialize 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.

How to write a new region module

Walk through on Windows

On Windows, using Visual studio, this is what you need to do, to create a new region module:

  1. Create a new project
    1. File, New, Project
    2. Select "Visual C#", "Class Library"
    3. Give the region module some good name, like: "MyRegionModule"
  2. Reference the required OpenSim assemblies
    1. Right click on "References" and choose "Add Reference..."
    2. Choose the browse tab
    3. Navigate to the bin folder of OpenSim
    4. Select "OpenSim.Framework.dll"
    5. Click Ok
    6. Right click once more on "References" and choose "Add Reference..."
    7. Select "OpenSim.Region.Environment.dll"
    8. Click Ok
  3. Change default class, to a meaningfull name
    1. Right click on "Class1.cs" and rename the file to "MyRegionModuleMain.cs

Now the code should look something like this:

using System;
using System.Collections.Generic;
using System.Text;

namespace MyRegionModule
{
    public class MyRegionModuleMain
    {
    }
}

delete the unwanted using lines:

using System.Collections.Generic;
using System.Text;

now, the program should contain:

using System;

namespace MyRegionModule
{
    public class MyRegionModuleMain
    {
    }
}

add references to the main OpenSim modules:

using OpenSim.Region.Environment.Interfaces;
using OpenSim.Region.Environment.Scenes;

specify that MyRegionModuleMain should inherit from the IRegionModule interface:

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.

Personal tools
General
About This Wiki