IRegionModule

Revision as of 17:29, 4 July 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.

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

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.