Getting Started with Region Modules

Revision as of 08:35, 15 November 2008

Hello World

This brief tutorial is intended to get people started with developing applications with/for opensim using region modules and the opensim API. The module available here writes "HELLO" in prims on every region of your opensim instance, and makes them move every 2 seconds or so. Please note:

• The opensim API is rapidly changing. The code available here works for SVN 7176, which corresponds to opensim 0.6.0. Please use a fresh install of 7176 to run this example. The example assumes the default configuration of opensim out-of-the-box. If you try to run this example on custom configurations, you may get errors and/or warnings. Those errors/warnings can be easily fixed in the code of the example, once you understand how to work with the opensim API. But since I can't predict all combinations of configuration settings out there, the assumption here is a fresh install of opensim SVN 7176. Deviate at your own risk.

To get started:

1. Download and install opensim svn 7176, and build it as normal. Run it once, so you create a default region and a default user. Then shut it down.
2. Get this zip file: http://www.ics.uci.edu/~lopes/opensim/HelloWorld.zip. Unzip it somewhere.
3. Before you go changing the code of the application, see its effect inworld by doing this:
   • Grab HelloWorld/bin/Release/HelloWorld.dll and dump it in opensim/bin
   • Start opensim as normal, and login to it.

You should see the word HELLO spelled out in prims, and moving every so often.

Are you ready to explore the code now?

Hold on. Before we do that, let me give you the 30-second introduction to Visual C# for Java programmers. Visual C# is similar to Eclipse, if you ever used that. When it builds, it places the resulting dll or exe in whatever folder you tell it too (right-click on the project->properties). By default it places them in bin/Release. When you compile it with debugging, that goes into bin/Debug. In spirit, the dll is equivalent to a jar file. That's what you want to produce and pass around. The PDB file can be ignored, unless you want to debug. The HelloWorld example uses the defaults of VC#, so every time you build it without debugging, the dll is placed under HelloWorld/bin/Release. To build without debugging information, simply right-click on the solution in the Solution Explorer window and choose Build.

Another note: the solution file included in the zip is for VC# 2005. If you have VC# 2008 that's fine too. Just double-click on the solution file, and VC# 2008 will convert the whole thing.

OK, now we're ready. Go ahead and double-click on HelloWorld.sln.

The only class in this example is called HelloWorldModule, and it starts like this:

using System;
using System.Collections.Generic;
using System.Reflection;

using log4net;
using Nini.Config;
using OpenMetaverse;

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

namespace HelloWorld
{
   public class HelloWorldModule : IRegionModule
   {

       private static readonly ILog m_log = LogManager.GetLogger(MethodBase.GetCurrentMethod().DeclaringType);

       List<Scene> m_scenes = new List<Scene>();
       Dictionary<Scene, List<SceneObjectGroup>> scene_prims = new Dictionary<Scene, List<SceneObjectGroup>>();

       int counter = 0;
       bool positive = true;

       #region IRegionModule interface

       public void Initialise(Scene scene, IConfigSource config)
       {
           m_log.Info("[HELLOWORLD] Initializing...");

           m_scenes.Add(scene);
       }

       public void PostInitialise()
       {
           m_scenes[0].EventManager.OnFrame += new EventManager.OnFrameDelegate(OnTick);
           foreach (Scene s in m_scenes)
               DoHelloWorld(s);
       }

       public void Close()
       {
       }

       public string Name
       {
           get { return "Hello World Module"; }
       }

       public bool IsSharedModule
       {
           get { return false; }
       }

       #endregion

...
}