Manni: Created page with "{{Quicklinks|Developing_OpenSim_Addins}} = Developing OpenSim Addins = Diese Seite erklärt, wie man OpenSimulator Region Module Addins entwickelt, paketiert und verteilt. Sie..."

2025-12-16T09:18:49Z

Created page with "{{Quicklinks|Developing_OpenSim_Addins}} = Developing OpenSim Addins = Diese Seite erklärt, wie man OpenSimulator Region Module Addins entwickelt, paketiert und verteilt. Sie..."

New page

{{Quicklinks|Developing_OpenSim_Addins}}
= Developing OpenSim Addins =
Diese Seite erklärt, wie man OpenSimulator Region Module Addins entwickelt, paketiert und verteilt. Sie richtet sich an Entwickler, die zusätzliche Funktionalität bereitstellen möchten, die über die Kernverteilung von OpenSim hinausgeht, und die diese in binärer Form an andere weitergeben möchten. Diese Anleitung bezieht sich auf [[New Region Modules|Region Module]], die auf den Simulatoren laufen. Es wird vorausgesetzt, dass Sie bereits mit den Grundlagen der Entwicklung von Region Modulen vertraut sind.

'''Hinweis:''' Diese Dokumentation wurde für OpenSimulator Version 0.9.3.x mit .NET 8.0 Runtime aktualisiert.

Wenn Sie nach der Installation von Drittanbieter-Addins suchen, lesen Sie bitte [[Installing 3rd party addins|diese andere Seite]].

== Voraussetzungen ==

Bevor Sie OpenSim Addins entwickeln, stellen Sie sicher, dass Sie Folgendes haben:
* .NET 8.0 SDK installiert (https://dotnet.microsoft.com/en-us/download/dotnet/8.0)
* OpenSimulator 0.9.3.x Quellcode oder Entwicklungsumgebung
* Grundlegendes Verständnis von C# und OpenSim Region Module Entwicklung

== Das finale Paket ==

OpenSim enthält mehrere eingebaute Addins, die als Beispiele dienen. Zwei gute Referenzen sind:
* '''OpenSim.Addons.OfflineIM''' - Verarbeitet Offline-Sofortnachrichten
* '''OpenSim.Addons.Groups''' - Stellt Gruppenfunktionalität bereit

Ein typisches Addin-Paket enthält:
* Die Region Module DLL
* Alle externen Abhängigkeiten (zusätzliche DLLs)
* Konfigurationsdateien (.ini)
* Zusätzliche Ressourcen (HTML-Dateien, Bilder, etc.)

Dies sind alle Dateien, die OpenSim-Benutzer benötigen, um das Addin in ihren Installationen auszuführen.

== Addin-Direktiven ==

Wie üblich sollte das Region Module mit dem Extension-Attribut als OpenSim Region Module annotiert werden:

['''Extension'''(Path = "/OpenSim/RegionModules", NodeName = "RegionModule", Id = "IhrModulId")]
public class IhrModul : ISharedRegionModule
{
...
}

Für nicht-geteilte Region Module verwenden Sie stattdessen '''INonSharedRegionModule'''.

Zusätzlich sollte das Assembly, das das Region Module enthält, die folgenden Direktiven in Properties/AssemblyInfo.cs enthalten:

// Diese Zeilen sind für die Addin-Paketierung erforderlich
[assembly: '''Addin'''("IhrAddin.Name", OpenSim.VersionInfo.VersionNumber + ".1")]
[assembly: '''AddinDependency'''("OpenSim.Region.Framework", OpenSim.VersionInfo.VersionNumber)]
[assembly: '''AddinDescription'''("Beschreibung Ihres Addins")]
[assembly: '''AddinAuthor'''("Ihr Name")]

// Die nächsten Zeilen sind optional - externe Abhängigkeiten einbinden
[assembly: '''ImportAddinAssembly'''("ExterneBibliothek.dll")]
[assembly: '''ImportAddinFile'''("IhreKonfig.ini")]
[assembly: '''ImportAddinFile'''("ressource.html")]

=== Addin-Direktiven verstehen ===

Die erste Direktive [assembly: '''Addin'''("IhrAddin.Name", OpenSim.VersionInfo.VersionNumber + ".1")] legt den öffentlichen Namen Ihres Addins fest: Dies ist, was die Benutzer sehen werden. Achten Sie besonders auf die Versionsnummer. Während Sie jede beliebige Versionsnummer verwenden können, wird dringend empfohlen, die Versionsnummer Ihres Addins mit der OpenSim-Version zu verknüpfen, gegen die Sie Ihren Code kompilieren.

Mit .NET 8.0 ist die Binärkompatibilität weiterhin wichtig, daher sollten Sie Ihre Benutzer darüber informieren, mit welcher OpenSim-Version dieses Addin kompatibel ist. Der direkteste Weg, diese Information weiterzugeben, besteht darin, sie zur Versionsnummer Ihres Addins hinzuzufügen. In diesem Fall verwenden wir die ersten Ziffern, um die OpenSim-Versionsnummer (z.B. 0.9.3.1) anzugeben, und die letzte Ziffer, um die eigene Version dieses Addins anzugeben. Wenn wir dieses Addin zwischen OpenSim-Releases weiterentwickeln würden, würde diese letzte Ziffer auf 2 erhöht, während die ersten Ziffern gleich blieben.

Die zweite Direktive [assembly: '''AddinDependency'''("OpenSim.Region.Framework", OpenSim.VersionInfo.VersionNumber)] legt die Abhängigkeit mit der konkreten OpenSim-DLL fest, die dieses Addin erweitert. Alle Region Module Addins erweitern OpenSim.Region.Framework. Auch hier sollte die Versionsnummer die aktuelle OpenSim-Versionsnummer sein, da dies die DLL ist, gegen die Sie Ihren Code kompilieren. Für eine Erklärung, wie die Versionierung funktioniert, siehe [[Installing_3rd_party_addins#Versioning]]

Die dritte und vierte Direktive geben eine Beschreibung und Autorenschaft-Informationen für Ihr Addin.

Die letzten Direktiven (ImportAddinAssembly, ImportAddinFile) binden zusätzliche Dateien in das Paket ein, die notwendig sind, damit die Addins in den Umgebungen Ihrer Benutzer funktionieren. Die Direktive [assembly: '''ImportAddinAssembly'''("ExterneBibliothek.dll")] hat zwei Zwecke: (1) sie bindet diese DLL in das Paket ein und (2) sie informiert die Laufzeitumgebung des Benutzers, dass diese DLL ebenfalls geladen werden sollte, wenn unser Addin in den Speicher geladen wird.

== Beispiel: OfflineIM Addon ==

Das OfflineIM-Addon, das mit OpenSim ausgeliefert wird, demonstriert Best Practices:

'''Modul-Deklaration:'''
[Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule", Id = "OfflineIMConnectorModule")]
public class OfflineIMRegionModule : ISharedRegionModule, IOfflineIMService
{
public void Initialise(IConfigSource config)
{
IConfig cnf = config.Configs["Messaging"];
if (cnf == null)
return;
if (cnf != null && cnf.GetString("OfflineMessageModule", string.Empty) != Name)
return;

m_Enabled = true;
// ... Initialisierungscode
}

public void AddRegion(Scene scene)
{
if (!m_Enabled)
return;

scene.RegisterModuleInterface<IOfflineIMService>(this);
// ... Region-Setup
}
// ... andere Interface-Methoden
}

'''AssemblyInfo.cs:'''
[assembly: Addin("OpenSim.OfflineIM", OpenSim.VersionInfo.VersionNumber)]
[assembly: AddinDependency("OpenSim.Region.Framework", OpenSim.VersionInfo.VersionNumber)]

== Konfiguration ==

Ein sehr wichtiger Teil des Prozesses hat mit der Konfiguration Ihres Addins zu tun. Anstatt Benutzer zu zwingen, ihre OpenSim.ini-Dateien manuell zu bearbeiten und den zu Ihrem Addin gehörenden Konfigurationsabschnitt hinzuzufügen, empfehlen wir die Verwendung modularer Konfigurationen. In modularen Konfigurationen sind Ihre Komponenten dafür verantwortlich, ihre eigenen Konfigurationsdateien zu lesen.

Hier ist das empfohlene Muster zum Laden der Konfiguration:

public void Initialise(IConfigSource config)
{
// Wir laden die Konfigurationsdatei nur, wenn die Hauptkonfiguration noch nichts über dieses Modul weiß
IConfig cnf = config.Configs["IhrModulName"];
if (cnf == null)
{
LoadConfiguration(config);
cnf = config.Configs["IhrModulName"];
if (cnf == null)
{
m_log.WarnFormat("[IHR MODUL]: Konfigurationsabschnitt nicht gefunden. Kann nicht fortfahren.");
return;
}
}

// Konfigurationswerte lesen
m_Enabled = cnf.GetBoolean("Enabled", false);
// ... weitere Konfiguration
}

LoadConfiguration sollte wie folgt deklariert werden:

private void LoadConfiguration(IConfigSource config)
{
string configPath = string.Empty;
bool created;
if (!Util.MergeConfigurationFile(config, "IhrModul.ini",
Path.Combine(AssemblyDirectory, "IhrModul.ini"),
out configPath, out created))
{
m_log.WarnFormat("[IHR MODUL]: Konfigurationsdatei nicht zusammengeführt");
return;
}
if (created)
{
m_log.ErrorFormat("[IHR MODUL]: BITTE BEARBEITEN SIE {0} VOR DEM AUSFÜHREN DIESES ADDINS", configPath);
throw new Exception("Addin muss vor dem Ausführen konfiguriert werden");
}
}

private static string AssemblyDirectory
{
get
{
string location = Assembly.GetExecutingAssembly().Location;
return Path.GetDirectoryName(location);
}
}

Diese Methode verwendet '''OpenSim.Framework.Util.MergeConfigurationFile''', die die ConfigDirectory-Variable aus der OpenSim-Konfiguration liest und prüft, ob die Konfigurationsdatei dieses Moduls bereits vorhanden ist. Wenn ja, wird sie einfach mit den OpenSim-Konfigurationen zusammengeführt. Wenn nicht, kopiert sie die Konfigurationsdatei, die sie im Paket mitgebracht hat, in das ConfigDirectory und warnt den Operator, dass er sie nach seinen Bedürfnissen bearbeiten sollte.

== Projektstruktur ==

OpenSim 0.9.3.x verwendet entweder traditionelle prebuild.xml oder moderne .NET SDK-Style .csproj-Dateien.

=== Verwendung von Prebuild (Traditionell) ===

Wenn Sie prebuild.xml verwenden, stellen Sie sicher, dass alle notwendigen Dateien in das Ausgabeverzeichnis kopiert werden:

<Project name="OpenSim.Addon.IhrModul" path="addon-modules/IhrModul" type="Library">
<Configuration name="Debug">
<Options>
<OutputPath>../../bin/</OutputPath>
<AllowUnsafe>true</AllowUnsafe>
</Options>
</Configuration>
<Configuration name="Release">
<Options>
<OutputPath>../../bin/</OutputPath>
<AllowUnsafe>true</AllowUnsafe>
</Options>
</Configuration>

<ReferencePath>../../bin/</ReferencePath>
<Reference name="Nini" path="../../bin/"/>
<Reference name="log4net" path="../../bin/"/>
<Reference name="Mono.Addins" path="../../bin/"/>

<Reference name="OpenSim.Region.Framework"/>
<Reference name="OpenSim.Framework"/>

<Files>
<Match pattern="*.cs" recurse="true">
<Exclude name="obj" pattern="obj"/>
<Exclude name="Tests" pattern="Tests"/>
</Match>
<Match pattern="*.ini" buildAction="Copy" destination="../../bin/" />
<Match pattern="*.html" buildAction="Copy" destination="../../bin/" />
</Files>
</Project>

Nach dem Erstellen/Ändern von prebuild.xml ausführen:
$ runprebuild.bat (Windows)
$ ./runprebuild.sh (Linux/Mac)

=== Verwendung von .NET SDK-Style Projekten (Modern) ===

Moderne .NET 8.0-Projekte können SDK-Style .csproj-Dateien direkt verwenden:

<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
<OutputPath>../../bin/</OutputPath>
<GenerateAssemblyInfo>false</GenerateAssemblyInfo>
<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
</PropertyGroup>

<ItemGroup>
<Reference Include="Mono.Addins" HintPath="../../bin/Mono.Addins.dll" Private="False" />
<ProjectReference Include="../../OpenSim/Region/Framework/OpenSim.Region.Framework.csproj" />
<ProjectReference Include="../../OpenSim/Framework/OpenSim.Framework.csproj" />
</ItemGroup>

<ItemGroup>
<None Update="*.ini" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>
</Project>

== Ihr Addon bauen ==

=== Mit Prebuild ===
1. Führen Sie Prebuild aus, um Projektdateien zu generieren
2. Bauen Sie mit dotnet oder Visual Studio:
$ dotnet build IhrAddon.csproj -c Release

=== Mit direkter .csproj ===
$ dotnet build IhrAddon.csproj -c Release

Alle Ausgabedateien sollten im bin/-Verzeichnis neben anderen OpenSim-Assemblies landen.

== Das Addin paketieren ==

Um die Dateien für die Verteilung zu paketieren, verwenden Sie das '''mautil''' Kommandozeilen-Tool, das im OpenSim bin-Verzeichnis enthalten ist.

$ /pfad/zu/mautil.exe pack bin/IhrAddon.dll

Dies erstellt eine Datei namens '''IhrAddon_0.9.3.1.1.mpack''' (Version kann variieren). Dies ist das Addin-Paket, das an den Standorten der Benutzer verteilt und installiert wird.

Beachten Sie, dass .mpack-Dateien komprimierte (zip) Archive sind. Sie können sie öffnen und ihren Inhalt mit Tools zur Inspektion von Zip-Dateien überprüfen.

=== mautil-Befehle ===

Das mautil-Tool (Mono.Addins Manager) unterstützt mehrere Befehle:

* '''pack''' - Erstellt ein .mpack-Paket aus einer DLL
* '''rep-build''' - Baut ein Addin-Repository
* '''install''' - Installiert ein Addin aus einem Repository
* '''uninstall''' - Deinstalliert ein Addin
* '''list''' - Listet installierte Addins auf

Für weitere Informationen:
$ /pfad/zu/mautil.exe --help

== Ihre Addins verteilen ==

Um Ihre Addins anderen zur Verfügung zu stellen, müssen Sie Ihr eigenes Addin-Repository erstellen und es auf einem Webserver hosten.

Um das Repository zu erstellen, erstellen Sie irgendwo einen Ordner und platzieren Sie alle Ihre Addin-Pakete (.mpack) darin. Dann:

$ /pfad/zu/mautil.exe rep-build /pfad/zu/repo/ordner

Dies erstellt zusätzliche Indexdateien (main.mrep, root.mrep) mit den richtigen Einträgen. Alles, was Sie als Nächstes tun müssen, ist den gesamten Inhalt dieses Ordners auf einen Webserver hochzuladen.

Schließlich müssen Sie Ihre Benutzer über die URL Ihres Repositorys informieren, damit sie es zu ihren Registern hinzufügen und Addins aus Ihrem Repository installieren können. Sie können Ihr Repo [[List of 3rd Party Addin Repositories|hier]] hinzufügen.

== Best Practices ==

* '''Versionskompatibilität:''' Kompilieren Sie immer gegen die spezifische OpenSim-Version, die Ihr Addon anvisiert
* '''Konfiguration:''' Verwenden Sie modulare Konfigurationsdateien, anstatt manuelle OpenSim.ini-Bearbeitungen zu erfordern
* '''Abhängigkeiten:''' Dokumentieren Sie alle externen Abhängigkeiten klar
* '''Testen:''' Testen Sie Ihr Addon sowohl mit Standalone- als auch mit Grid-Konfigurationen
* '''Dokumentation:''' Stellen Sie klare Installations- und Konfigurationsanweisungen bereit
* '''Protokollierung:''' Verwenden Sie geeignete Log-Level (Debug, Info, Warn, Error)
* '''.NET 8.0:''' Stellen Sie Kompatibilität mit .NET 8.0 Runtime sicher
* '''Fehlerbehandlung:''' Implementieren Sie ordnungsgemäße Fehlerbehandlung und geben Sie aussagekräftige Fehlermeldungen

== Fehlerbehebung ==

=== Häufige Probleme ===

* '''Assembly nicht gefunden:''' Stellen Sie sicher, dass alle referenzierten Assemblies im bin-Verzeichnis sind
* '''Versions-Missmatch:''' Überprüfen Sie, dass OpenSim.VersionInfo.VersionNumber mit Ihrer OpenSim-Installation übereinstimmt
* '''Modul lädt nicht:''' Prüfen Sie, dass das Extension-Attribut korrekt ist und das Modul das richtige Interface implementiert
* '''Konfiguration nicht gefunden:''' Überprüfen Sie, dass die .ini-Datei ins bin-Verzeichnis kopiert wurde und MergeConfigurationFile aufgerufen wird
* '''.NET Runtime-Probleme:''' Stellen Sie sicher, dass .NET 8.0 Runtime installiert ist

== Siehe auch ==

* [[New Region Modules]] - Dokumentation zur Region Module Entwicklung
* [[Installing 3rd party addins]] - Anleitung für Benutzer zur Installation von Addins
* [[List of 3rd Party Addin Repositories]] - Community-Addon-Repositories

== Externe Links ==

* [https://github.com/opensim/opensim OpenSimulator GitHub Repository]
* [https://dotnet.microsoft.com/en-us/download/dotnet/8.0 .NET 8.0 Download]
* [http://opensimulator.org/ OpenSimulator Webseite]

Developing OpenSim Addins/de - Revision history

Manni: Created page with "{{Quicklinks|Developing_OpenSim_Addins}} = Developing OpenSim Addins = Diese Seite erklärt, wie man OpenSimulator Region Module Addins entwickelt, paketiert und verteilt. Sie..."