IRegionModule

From OpenSimulator

(Difference between revisions)
Jump to: navigation, search
(Introduction)
m
Line 1: Line 1:
 
== 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.
+
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)
 
* Database engines can be replaced (currently OpenSim has full support for)
Line 12: Line 12:
 
** Asset storage
 
** Asset storage
 
** Script execution
 
** Script execution
* Scrip languages can be replaced
+
* Script languages can be replaced
 
* ''Region modules can be added''
 
* ''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 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.
+
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 ==
 
== Interface ==
All region modules must implement this interface<br/>
+
All region modules must implement this interface:
<code>
+
 
    public interface IRegionModule
+
public interface IRegionModule
    {
+
{
        void Initialise(Scene scene);
+
    void Initialise(Scene scene);
        void PostInitialise();
+
    void PostInitialise();
        void Close();
+
    void Close();
        string Name { get; }
+
    string Name { get; }
        bool IsSharedModule { get; }
+
    bool IsSharedModule { get; }
    }
+
}
</code>
+
 
<br/>
+
 
<table>
 
<table>
 
<tr>
 
<tr>
Line 38: Line 37:
 
<tr>
 
<tr>
 
<td>Initialize</td>
 
<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>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>
 
</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>PosrInitialize</td>
+
<td>PostInitialize</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>
+
<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>
 
<tr>
 
<tr>
 
<td>Close</td>
 
<td>Close</td>
<td>This method will be invoked, when the sim is closing down.</td>
+
<td>This method will be invoked when the sim is closing down.</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
Line 60: Line 59:
  
 
== How to write a new region module ==
 
== How to write a new region module ==
=== Walk through on windows ===
+
=== Walk through on Windows ===
On windows, using Visual studio, this is what you need to do, to create a new region module:<br/>
+
On Windows, using Visual studio, this is what you need to do, to create a new region module:
  
 
#Create a new project
 
#Create a new project
Line 80: Line 79:
  
 
Now the code should look something like this:
 
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:<br/>
 
  
<code>
+
using System;
using System.Collections.Generic;
+
using System.Collections.Generic;
using System.Text;
+
using System.Text;
</code>
+
 +
namespace MyRegionModule
 +
{
 +
    public class MyRegionModuleMain
 +
    {
 +
    }
 +
}
  
now, the program should contain:<br/>
+
delete the unwanted <tt>using</tt> lines:
  
<code>
+
using System.Collections.Generic;
using System;
+
using System.Text;
  
namespace MyRegionModule
+
now, the program should contain:
{
+
    public class MyRegionModuleMain
+
    {
+
    }
+
}
+
</code>
+
  
add references to the main OpenSim modules<br/>
+
using System;
<code>
+
using OpenSim.Region.Environment.Interfaces;
+
namespace MyRegionModule
using OpenSim.Region.Environment.Scenes;
+
{
</code>
+
    public class MyRegionModuleMain
 +
    {
 +
    }
 +
}
  
specify that <tt>MyRegionModuleMain</tt> should inherit from the <tt>IRegionModule</tt> interface
+
add references to the main OpenSim modules:
  
 +
using OpenSim.Region.Environment.Interfaces;
 +
using OpenSim.Region.Environment.Scenes;
  
<code>
+
specify that <tt>MyRegionModuleMain</tt> should inherit from the <tt>IRegionModule</tt> interface:
using System;
+
  
namespace MyRegionModule
+
using System;
{
+
    public class MyRegionModuleMain : IRegionModule
+
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.
+
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 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.
+
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.

Revision as of 21:58, 10 October 2007

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 (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
  • 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 is used to display a friendly name, in logs etc.
IsSharedModule (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

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;

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