== 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 (almost complete)
** db4o is partially implemented
** MS-SQL Server is in a template stage.
* 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; }
}

<table>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
<tr>
<td>Initialize</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>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>
<tr>
<td>Close</td>
<td>This method will be invoked when the sim is closing down.</td>
</tr>
<tr>
<td>Name</td>
<td>This is used to display a friendly name, in logs etc.</td>
</tr>
<tr>
<td>IsSharedModule</td>
<td>'''''(needs to be doublechecked)'''''A sim server can house more than one region, this method should return true if the region module will operate on all regions</td>
</tr>
</table>

== 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:

#Create a new project
##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:

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

namespace MyRegionModule
{
public class MyRegionModuleMain
{
}
}

delete the unwanted <tt>using</tt> 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 <tt>MyRegionModuleMain</tt> should inherit from the <tt>IRegionModule</tt> 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.

IRegionModule

2007-10-10T21:54:11Z

Tleiades: /* Introduction */

== 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 a runtime.

* Database engines can be replaced (currently OpenSim has full support for)
** SQLite
** MySQL (almost complete)
** db4o is partially implemented
** MS-SQL Server is in a template stage.
* Backed servers can be replaced by changing a url, currently there are servers for:
** User authentication
** Grid registration
** Asset storage
** Script execution
* Scrip 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 registers for a number of events, e.g. chat messages, user logins, texture transfers, and takes what ever steps are appropriate for the purposes of the module.
== Interface ==
All region modules must implement this interface 
<code>
public interface IRegionModule
{
void Initialise(Scene scene);
void PostInitialise();
void Close();
string Name { get; }
bool IsSharedModule { get; }
}
</code>
 
<table>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
<tr>
<td>Initialize</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 at running at this time.
</td>
</tr>
<tr>
<td>PosrInitialize</td>
<td>Once the sim is fully initialized and all region modules has 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 all methods on the scene.</td>
</tr>
<tr>
<td>Close</td>
<td>This method will be invoked, when the sim is closing down.</td>
</tr>
<tr>
<td>Name</td>
<td>This is used to display a friendly name, in logs etc.</td>
</tr>
<tr>
<td>IsSharedModule</td>
<td>'''''(needs to be doublechecked)'''''A sim server can house more than one region, this method should return true if the region module will operate on all regions</td>
</tr>
</table>

== 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: 

#Create a new project
##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:
<code>
using System;
using System.Collections.Generic;
using System.Text;

namespace MyRegionModule
{
public class MyRegionModuleMain
{
}
}
</code>

delete the unwanted using lines: 

<code>
using System.Collections.Generic;
using System.Text;
</code>

now, the program should contain: 

<code>
using System;

namespace MyRegionModule
{
public class MyRegionModuleMain
{
}
}
</code>

add references to the main OpenSim modules 
<code>
using OpenSim.Region.Environment.Interfaces;
using OpenSim.Region.Environment.Scenes;
</code>

specify that <tt>MyRegionModuleMain</tt> should inherit from the <tt>IRegionModule</tt> interface

<code>
using System;

namespace MyRegionModule
{
public class MyRegionModuleMain : IRegionModule
{
}
}
</code>

Right click on the "IRegionModule" name, and selelect "Implement interface", "Implement Interface"; this will add an empty implementation of the interface required for a region module. If you compile 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 the region module will not do anything, worth while, in fact it will cause OpenSim to log a warning about exceptions in a loaded. module.

2007-10-09T21:12:42Z