Revision as of 12:46, 16 July 2018

 

Home

 

Download

 

News

 

Support

 

Admin

 

Dev

 

Screen Shots

 

Grid List

 

Bugs

Languages:

English

Bitte beachten Sie

Diese Seite behandelt den Mechanismus des Bereichsmoduls, der seit OpenSimulator 0.6.9 vorhanden ist. Eine ältere Version die auf die älteren IRegionModule-Mechanismen verweist, finden Sie unter http://opensimulator.org/index.php?title=IRegionModule&oldid=13166

Siehe Related Software für Links zu vorhandenen Regionsmodulen.

Einführung

Region-Module sind Klassen, die die Schnittstellen INonSharedRegionModule oder ISharedRegionModule von OpenSimulator implementieren. .NET-DLLs, die diese Klassen enthalten, können dann in das Binärverzeichnis von OpenSimulator (bin /) gestellt werden. Beim Start durchsucht OpenSimulator dieses Verzeichnis und lädt dort alle darin enthaltenen Module.

Regionsmodule werden im Herzen des Simulators ausgeführt und haben Zugang zu allen Einrichtungen. Dies macht sie sehr leistungsfähig, bedeutet aber auch, dass bei der Erstellung besonders darauf geachtet werden muss, dass sie sich nicht negativ auf die Simulatorleistung auswirken.

Typischerweise registrieren Regionenmodule Methoden mit dem Ereignismanager des Simulators, die aufgerufen werden, wenn verschiedene Ereignisse auftreten (z. B. Avatar-Chat, Benutzer, der eine Region betritt usw.).

Es gibt zwei Arten von Regions-Modulen.

• Nicht freigegebene Module, für die ein separates Modul für jede Region/Szene erstellt wird
• Freigegebene Module, bei denen ein einzelnes Modul zwischen allen Regionen/Szenen geteilt wird, die auf demselben Simulator ausgeführt werden.

Erstellung eines Region Modules

Von Grund auf neu

Zu diesem Zeitpunkt werden Regionsmodule normalerweise in der OpenSimulator-Quellstruktur selbst mithilfe ihrer Build-Mechanismen erstellt.

Die Schritte sind wie folgt:

1. Navigieren Sie zu dem Verzeichnis addon-modules / in der Basis der OpenSimulator-Quellstruktur (nicht zu dem Verzeichnis bin / addon-modules / in der Bin-Baumstruktur, über das wir in Kürze sprechen werden).

2. Erstellen Sie ein Verzeichnis für das Regionsmodulprojekt, normalerweise mit demselben Namen wie das Regionsmodul. Zum Beispiel BareBonesNonSharedModule /

3. Erstellen Sie eine prebuild.xml für das Projekt. Dies ist die Datei, die von ./runprebuild.sh oder ./runprebuild.bat im Basis-OpenSimulator-Verzeichnis verwendet wird, um die entsprechenden Build-Dateien für Visual Studio, Monodevelop und nant zu erstellen. Für ein sehr einfaches Modul hätten Sie etwas wie

<Project frameworkVersion="v4_0" name="BareBonesNonSharedModule" path="addon-modules/BareBonesNonSharedModule/src/BareBonesNonSharedModule" type="Library">
  <Configuration name="Debug">
    <Options>
      <OutputPath>../../../../bin</OutputPath>
    </Options>
  </Configuration>
  <Configuration name="Release">
    <Options>
      <OutputPath>../../../../bin</OutputPath>
    </Options>
  </Configuration>
 
  <ReferencePath>../../../../bin</ReferencePath>
  <Reference name="System"/>
  <Reference name="log4net"/>
  <Reference name="Mono.Addins"/>
  <Reference name="Nini"/>
  <Reference name="OpenMetaverse"/>
  <Reference name="OpenMetaverseTypes"/>
  <Reference name="OpenSim.Framework"/>
  <Reference name="OpenSim.Region.Framework"/>
  <Reference name="OpenSim.Services.Interfaces"/>
 
  <Files>
    <Match pattern="*.cs" recurse="true"/>
    <Match path="Resources" pattern="*.*" buildAction="EmbeddedResource"/>
  </Files>
</Project>

Zu dieser Datei müssen einige Dinge beachtet werden

• In OpenSimulator 0.8, wenn Sie auf Windows aufbauen, müssen Sie eine FrameworkVersion von 4_0 anstelle von 3_5 im oberen <Project> -Tag verwenden. Vor OpenSimulator 0.8 muss dies jedoch net 3_5 sein, damit der Build fortgesetzt werden kann. Bei Mono kann dies entweder 3_5 oder 4_0 auf OpenSimulator 0.8 sein, muss aber 4_0 sein, wenn Sie C# 4.0-Funktionen verwenden möchten.
• Das Pfadattribut in <Projekt> muss auf den Speicherort im Verzeichnis addon-modules verweisen, in dem sich der Quellcode befindet. Dieses Verzeichnis ist relativ zum OpenSimulator-Stammpfad. Im obigen Beispiel befindet sich der Code in addon-modules / BareBonesNonSharedModule / src / BareBonesNonSharedModule.
• Die <OutputPath> -Tags geben an, wo Ihre kompilierte Modul-DLL kopiert wird, nachdem sie erstellt wurde. Dies ist relativ zum Speicherort Ihres Quellcodes, wie im Pfadattribut von <Project> angegeben. In den meisten Fällen möchten Sie, dass dies zusammen mit dem Rest der DLLs im OpenSimulator-Verzeichnis / bin abgelegt wird. Legen Sie diese Datei nicht in das Verzeichnis bin / addon-modules - dies ist verwirrend nur für Addon-Modul-Konfigurationsdateien (* .ini).
• Der <ReferencePath> -Wert gibt an, wo das Modulprojekt die DLLs finden kann, auf die es verweisen muss (OpenSimulator.Framework.dll, log4net.dll usw.).
• Jede Bibliothek, auf die Sie in Ihren Modulen verweisen, benötigt ein <Referenz> -Tag. Das obige Beispiel listet Bibliotheken wie OpenSim.Framework.dll und OpenMetaverse auf.
• Weitere Beispiele finden Sie in der Hauptdatei prebuild.xml im Stammverzeichnis der OpenSimulator-Quellstruktur. Bitte beachten Sie, dass das obige Beispiel im Vergleich zu vielen anderen Einträgen optimiert ist - die Hauptdatei muss zu einem gewissen Zeitpunkt vereinfacht werden, da es eine große Redundanz gibt (zB muss Pfad nicht in jedem <Reference> angegeben werden) bereits durch <ReferencePath> angegeben).

4. Navigieren Sie zurück zum OpenSimulator-Stammverzeichnis und führen Sie ./runprebuild.sh (Linux, Mac OSX) oder ./runprebuild.bat (Windows) aus. In der resultierenden Ausgabe, in der Nähe der Spitze, sollten Sie die Linie sehen

searchDirectory: addon-modules/BareBonesNonSharedModule

o.ä. Wenn Sie jetzt eine IDE wie Visual Studio oder MonoDevelop verwenden, sollten Sie jetzt in der Lage sein, die OpenSim.sln-Lösung neu zu laden und Ihr Projekt in der Quellstruktur zu sehen.

Wenn etwas schief geht, schauen Sie sich die Ausgabe für runprebuild.sh/.bat genau an. Möglicherweise sehen Sie Nachrichten wie

[!] Could not resolve Solution path: addon-modules/BareBonesNonSharedModule/src/BareBonesNonSharedModule

was darauf hinweist, dass Ihre prebuild.xml-Datei für dieses Modul den Quellordner nicht korrekt aufnimmt.

5. Fügen Sie nach Bedarf Moduldateien in Ihrem Projekt hinzu oder bearbeiten Sie sie.

6. Führen Sie runprebuild.sh erneut aus, wenn Sie Ihrem Modul neue Dateien hinzugefügt haben.

7. Erstellen Sie OpenSim.sln mit Ihrer üblichen Build-Methode, egal ob Sie innerhalb der IDE oder in der Befehlszeile mit xbuild (mono) oder nant arbeiten.

8. Wenn die Kompilierung erfolgreich ist, kopiert der Buildprozess die Binärdatei in das OpenSimulator-Verzeichnis bin /. Wenn Sie OpenSimulator das nächste Mal starten, sollte es in den Simulator geladen werden und in der Ausgabe für den Konsolenbefehl "show modules" erscheinen.

Aus bestehendem Modul-Code

Wenn Sie ein Regionsmodul erstellen möchten, das bereits existiert, sind die Schritte etwas einfacher.

1. Platzieren Sie den Modulcode im OpenSimulator-Addonmodul-Basisverzeichnis. Wenn Sie z. B. ein Modul namens EventRecorderModule kompilieren möchten, befindet es sich unter addon-modules / EventRecorderModule. Bitte beachten Sie, dass der Name des Moduls mit dem Patch in der Datei prebuild.xml übereinstimmen muss (in diesem Beispiel ist die Datei EventRecorderModule / prebuild.xml).

2. Führen Sie wie oben prebuild.sh/prebuild.bat erneut aus. Dies ist das Einfügen des Moduls in die OpenSimulator-Build-Lösung (OpenSim.sln).

3. Sie können das Modul jetzt mit Visual Studio, MonoDeveloper, xbuild oder nant kompilieren.

4. Beim nächsten Start von OpenSimulator sollte das Modul geladen werden (die Datei prebuild.xml platziert das eingebaute Modul in das Bin / des OpenSimulator).

Installieren von Regionsmodulen

Wenn Sie nur eine vorhandene Region-Modul-DLL installieren, anstatt sie aus der Quelle zu erstellen, müssen Sie dies tun

1. Kopieren Sie die DLL und alle anderen zugehörigen Dateien in $ OPENSIM_BASE / bin

2. In den meisten Fällen konfigurieren Sie das Modul, indem Sie entweder den gewünschten Abschnitt zu OpenSim.ini hinzufügen, ihn als bin / addon-modules / MyModule / config / config.ini hinzufügen oder indem Sie explizit die Konfigurationsdatei des Moduls hinzufügen.

Region Modul Schnittstellen

Alle Regionsmodule müssen INonSharedRegionModule oder ISharedRegionModule von OpenSim.Region.Framework.Interfaces implementieren. Wenn ein Regionsmodul INonSharedRegionModule implementiert, wird eine Instanz dieses Moduls für jede Region (aka Szene) im Simulator erstellt. Jedes Modul kennt nur seine eigene Region. Wenn ein Regionsmodul ISharedRegionModule implementiert, existiert nur eine einzige Instanz des Moduls und es wird über alle Regionen / Szenen in den Simulatoren informiert.

Sowohl INonSharedRegionModule als auch ISharedRegionModule erweitern IRegionModuleBase, das den Großteil der Schnittstellenmethoden implementiert. Diese sind wie folgt.

public interface IRegionModuleBase
{
     string Name { get; }
     Type ReplaceableInterface { get; }
     void Initialise(IConfigSource source);
     void AddRegion(Scene scene);
     void RemoveRegion(Scene scene);
     void RegionLoaded(Scene scene);
     void Close();
}

INonSharedRegionModule selbst enthält keine Methoden, einfach definiert als

public interface INonSharedRegionModule : IRegionModuleBase
{
}

ISharedRegionModule verfügt über eine zusätzliche Methode.

public interface ISharedRegionModule : IRegionModuleBase
{
    void PostInitialise();
}

Beispiel Region Modul

In diesem Beispiel wird davon ausgegangen, dass Sie die Datei verwenden, die sich bereits in der OpenSimulator-Quellstruktur (ab 0.7.1) unter OpenSim / Region / OptionalModules / Example / BareBonesNonShared / BareBonesNonSharedModule.cs befindet. Es gibt dort auch ein Beispiel für ein Shared-Modul. Um dies als separates Projekt zu erstellen, beachten Sie bitte die obigen Anweisungen.

BareBonesNonShreadModule ist sehr einfach. Es führt lediglich Aufrufe von IRegionModule-Methoden in den Prozess der Aktivierung des Moduls aus.

In der Quellstruktur ist die Attributzeile [Erweiterung ...] kommentiert. Sie können dies auskommentieren, OpenSimulator neu erstellen und starten, um das Modul in Aktion zu sehen.

using System;
using System.Reflection;
using log4net;
using Mono.Addins;
using Nini.Config;
using OpenSim.Region.Framework.Interfaces;
using OpenSim.Region.Framework.Scenes;
 
[assembly: Addin("BareBonesNonSharedModule", "0.1")]
[assembly: AddinDependency("OpenSim", "0.5")]
 
namespace OpenSim.Region.OptionalModules.Example.BareBonesNonShared
{
    /// <summary>
    /// Simplest possible example of a non-shared region module.
    /// </summary>
    /// <remarks>
    /// This module is the simplest possible example of a non-shared region module (a module where each scene/region
    /// in the simulator has its own copy).
    ///
    /// When the module is enabled it will print messages when it receives certain events to the screen and the log
    /// file.
    /// </remarks>
    [Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule", Id = "BareBonesNonSharedModule")]
    public class BareBonesNonSharedModule : INonSharedRegionModule
    {
        private static readonly ILog m_log = LogManager.GetLogger(MethodBase.GetCurrentMethod().DeclaringType);
 
        public string Name { get { return "Bare Bones Non Shared Module"; } }        
 
        public Type ReplaceableInterface { get { return null; } }
 
        public void Initialise(IConfigSource source)
        {
            m_log.DebugFormat("[BARE BONES]: INITIALIZED MODULE");
        }
 
        public void Close()
        {
            m_log.DebugFormat("[BARE BONES]: CLOSED MODULE");
        }
 
        public void AddRegion(Scene scene)
        {
            m_log.DebugFormat("[BARE BONES]: REGION {0} ADDED", scene.RegionInfo.RegionName);
        }
 
        public void RemoveRegion(Scene scene)
        {
            m_log.DebugFormat("[BARE BONES]: REGION {0} REMOVED", scene.RegionInfo.RegionName);
        }        
 
        public void RegionLoaded(Scene scene)
        {
            m_log.DebugFormat("[BARE BONES]: REGION {0} LOADED", scene.RegionInfo.RegionName);
        }                
    }
}

Aktivieren des Moduls

Das Erstellen des Modulcodes selbst reicht nicht aus, um es zu aktivieren. Um dies zu tun, müssen wir es für den Mono.Addins).

Dies geschieht beispielsweise, indem der Klasse ein Extension-Attribut hinzugefügt wird.

[Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule", Id = "BareBonesNonSharedModule")]

Der wichtige Teil hier ist der "Pfad" Abschnitt "/ OpenSim / RegionModules" - so ruft OpenSimulator Module von Mono.Addins ab. Die ID kann für das Modul sinnvoll sein.

Neuere Mono-Versionen benötigen diese Art von Abschnitt auch vor der Namespace-Deklaration:

[assembly: Addin("BareBonesNonSharedModule", "0.1")]
[assembly: AddinDependency("OpenSim", "0.5")]

Zu Beginn der Modulquellcodedatei müssen Sie diese Zeile hinzufügen:

using Mono.Addins;

Und prebuild.xml muss eine solche Zeile für neuere Mono-Versionen enthalten:

<Reference name="Mono.Addins.dll"/>

Integration mit OpenSimulator

HINWEIS: Dieser Abschnitt ist sehr unvollständig und Teile sind veraltet. Wenn Sie etwas wissen müssen, fragen Sie bitte in den Mailinglisten von OpenSimulator, wo wir beide die Frage beantworten und die notwendige Dokumentation hier hinzufügen können.

Beachten Sie jedoch, dass OpenSimulator ein sehr junges Projekt ist und die internen Schnittstellen sich kurzfristig ändern können. In diesem Fall liegt es an Ihnen, Ihr Modul mit späteren Versionen von OpenSimulator auf dem neuesten Stand zu halten.

Zugängliche Objekte

In der AddRegion- Routine erhalten Sie Zugriff auf das Szenenobjekt für die Region, von hier aus können Sie in die Szene spinnen und Zugang zu vielen anderen interessanten Objekten erhalten.

• scene.GetEntities() - gibt eine Liste aller Entitäten in der Umgebung zurück. Dies wird eine kombinierte Liste von SceneObjectGroups (Prim Sets) und ScenePresences (Avatars) sein.
• scene.GetAvatars() - ruft nur die Avatare in der Szene ab (sehr praktisch zum Senden von Nachrichten an Clients)
• scene.EventManager - Dies ist das Objekt, von dem aus Sie Callbacks für Szenenereignisse registrieren können. Einige Beispiele finden Sie unten.
• scene.RegionInfo - Eigenschaften der Region

Veranstaltungen

Verschiedene Ereignisse im OpenSimulator (z. B. Avatare, die eine Region betreten, Chat) haben Ereignis-Hooks, die ein Modul abonnieren kann. Die wichtigsten Ereignisse sind in Scene.EventManager verfügbar.

In vielen Fällen möchten Sie in dem Thread, der das Ereignis auslöst, so wenig Arbeit wie möglich leisten, da viele aus zeitkritischen Bereichen im OpenSimulator-Code kommen (z. B. innerhalb der Hauptszenerahmenverarbeitung) oder Bereiche, in denen ein Überfall andere Störungen verursacht ( zB Ereignisse, die melden, dass ein Root-Agent angekommen ist).

Diese Ereignisse sind etwas grob und bereit, da sie ursprünglich für die interne Verwendung von OpenSimulator erstellt wurden und standardmäßig Module gestartet wurden, um sie zu verwenden. Daher gibt es eine Inkonsistenz mit Namen, Argumenten und den offengelegten Ereignissen. Seien Sie bitte darauf vorbereitet, dass sich all dies im Laufe der Zeit ändert oder durch angemessenere Ereignisse ersetzt wird.

Registrierung für Veranstaltungen

Am Beispiel des SunModule können wir den folgenden Code sehen:

In Initialise():

...
m_scene.EventManager.OnFrame += SunUpdate;
...

Ganz einfach, wir haben gerade den EventManager bekommen und die SunUpdate Methode als Callback für das OnFrame Event registriert. OnFrame wird jedes Mal ausgelöst, wenn es in Opensim einen Renderrahmen gibt, der ungefähr 20 Mal pro Sekunde ist. In diesem Fall solltest du also sehr vorsichtig mit den Aktionen sein, die du in diesem Event machst, da sie sich direkt auf die Performance des Szenen-Loops auswirken (lange Wartezeiten führen zu Lag-Symptomen für bewegte Avatare usw.) .

Hier ist die Funktion selbst

public void SunUpdate()
{
    // this code just means only do this on every 1000th frame, and don't do it if the sun is in a fixed possition
    if (((m_frame++%m_frame_mod) != 0) || !ready || sunFixed)
    {
        return;
    }
 
    GenSunPos();        // Generate shared values once
 
    List<ScenePresence> avatars = m_scene.GetAvatars();
    foreach (ScenePresence avatar in avatars)
    {
        if (!avatar.IsChildAgent)
            avatar.ControllingClient.SendSunPos(Position, Velocity, CurrentTime, SecondsPerSunCycle, SecondsPerYear, OrbitalPosition);
    }
 
    // set estate settings for region access to sun position
    m_scene.RegionInfo.RegionSettings.SunVector = Position;
}

SunUpdate () nimmt keinen Parameter (einige Ereignisse erfordern sie möglicherweise). Es wird standardmäßig nur jedes 1000. Frame ausgelöst (m_frame_mod = 1000 in diesem Modul), so dass es nicht zu viele Zyklen dauert.

Damit sich die Sonnenposition für die Kunden ändert, muss ihnen gesagt werden, dass sie sich ändert. Dies geschieht, indem Sie eine Liste aller Avatare aus der Szene holen und dann die Sonnenposition nacheinander an sie senden. Darüber hinaus möchten Sie dies nur für Root-Agenten tun (Agenten, die tatsächlich einen angehängten Avatar haben, der sich bewegen kann, usw.). Updates, die an untergeordnete Agenten gesendet werden (die es Zuschauern ermöglichen, in benachbarte Regionen zu sehen), werden einfach ignoriert.

Verfügbare Ereignisse

Hier ist eine extrem unvollständige Liste der verfügbaren Ereignisse (die hoffentlich im Laufe der Zeit ausgefüllt werden sollte). Weitere Details finden Sie im OpenSimulator-Code selbst. Bitte beachten Sie auch, dass OpenSimulator noch in Entwicklung ist. Event-Parameter und Namen können sich im Laufe der Zeit ändern.

In der nachstehenden Tabelle signalisieren die Verzögerungsspalten, ob eine Verzögerung bei der Verarbeitung des Ereignisses wahrscheinlich den Simulator als Ganzes und / oder die betreffende Entität (z. B. einen Benutzer) stören wird. Beachten Sie jedoch, dass selbst wenn es keine sofortige Unterbrechung durch das Verzögern eines Ereignis-Threads gibt, das Verzögern von vielen zu Simulator-weiten Problemen führen wird, da der Threadpool erschöpft ist.

In OpenSim.Region.Framework.Scenes.EventManager

Where to go from here

• Getting Started with Region Modules -- the Hello World of OpenSimulator application development. Rather old by now but still worth a look.
• http://bluewallvirtual.com/example_region_module - More shared region module example code by Bluewall.
• Development discussion of the current region module mechanism
• Read the source for existing opensim core modules. These are in the OpenSim.Region.CoreModules and OpenSim.Region.OptionalModules projects. Looking through this code is an extremely good way to find out what region modules can do and how they can do it.
• Read the source code for the EventManager class in the OpenSim.Region.Framework.Scenes project. These list the many events that exist. Some modules may also export their own events (e.g. OnInventoryArchiveSaved in the InventoryArchiverModule at OpenSim/Region/CoreModules/Avatar/Inventory/Archiver/).
• Help write some examples here. OpenSimulator grows with your contributions.