Addonentwicklung

Aus Echo12 Wiki
Wechseln zu: Navigation, Suche

Addons oder sogenannte Mods lassen sich relativ einfach entwickeln wenn man die Grundlagen kennt.

Verzeichnisstruktur

Jeder Ordner laesst sich zu einem Addon als pbo packen. Hierbei sollten unten genannte Dateien in diesem Ordner existieren. Nachdem das Verzeichnis als pbo gepackt wurde muss es, um mitgeladen werden zu koennen, in einen Modfolder von Arma abgelegt werden. Hierbei wuerden wir beispielsweise @mymod mitladen und im Arma Verzeichnis wuerde sich die Pbo im Verzweichnis Arma2OA\@mymod\addons\myaddon.pbo befinden.

Notwendige Dateien

Grundsaetzlich ist nur die PBOPrefix Datei fuer ein Addon notwendig, es koennen jedoch auch andere Dateien noetig sein.

$PBOPREFIX$

Die Datei $PBOPREFIX$ befindet sich im Hauptordner des entpackten Addons und gibt den virtuellen Dateipfad an, in dem spaeter alle Dateien des Addons liegen und angesprochen werden koennen. Diese spezielle Datei wird nicht von allen Packern/Entpackern unterstuetzt, weswegen ich cPbo empfehle.

Die Datei hat beispielsweise folgenden Inhalt:

x\e12\addons\amf_main

Wenn sich nun eine script.sqf Datei im Hauptordner des Addons befinden wuerde und das Addon mit der darin befindlichen $PBOPREFIX$ gepackt und mitgeladen wird, kann man in der Mission mittels [] execVM "x\e12\addons\amf_main\script.sqf"; unsere script.sqf ausfuehren.

Hierbei ist der Pfad per Konvention folgendermassen aufgebaut:

  • x\: Dass es im Addonnamespace liegt
  • e12\: Autor oder Gruppenprefix
  • addons\: Immer gleich
  • amf_main: Name des Addons

Auf Leer- und Sonderzeichen ist zu verzichten. Wenn diese Konvention verletzt wird, gibt es keine einfache Moeglichkeit mit CBA innerhalb des Addons zu arbeiten, das uns viele nuetzliche Moeglichkeiten bietet.

config.cpp/.bin

Die Config.cpp ist der Einstieg in die Konfiguration von Arma und muss nach Konvention diesen Namen tragen. Es ist moeglich die config.cpp mittels Rapify zu der config.bin zu binaerisieren, dies ist in der Releasephase wichtig, da dadurch die Abarbeitung von Arma beschleunigt wird.

Ein Beispielsinhalt zur Definition des Addons:

class CfgPatches
{
    class e12_amf_main
    {
        units[] = {};
        weapons[] = {};
        requiredVersion = 1.62;
        requiredAddons[] = {"CBA_MAIN","CA_Modules"};
        author[] = {"Coati - Echo12 Development Team"};
        version = "1.0.1";
        authorUrl = "http://www.echo12.de";
    };
};
class CfgMods
{
    class e12_amf_main
    {
        dir = "@e12_amf";
        name = "E12 Advanced Mission Framework";
        hidePicture = "true";
        hideName = "true";
        actionName = "Website";
        action = "http://www.echo12.de";
        description = "Echo12";
    };
};

CBA Integration

CBA bietet fuer Addonentwickler nicht nur die XEH also die Erweiterten Event Handler, sondern bietet viele Makros die die Addonentwicklung erleichtern. Um CBA zu integrieren muss als CBA_MAIN als requiredAddon angeben werden: requiredAddons[] = {"CBA_MAIN"};. Nachdem unten stehende Dateien im Addonfolder angelegt worden sind, sollte jede Skriptdatei folgenden Header beinhalten um Makros verwenden zu koennen:

#include "script_component.hpp"
...mein Skriptcode...

Notwendige Dateien

script_component.hpp

#define COMPONENT amf_main
#define PREFIX e12

#include "script_macros.hpp"

Hier definieren wir das Prefix e12 und als Componentname amf_main, diese Angaben muessen mit den Pfadangaben in $PBOPREFIX$ (oben) uebereinstimmen. Ebenso inkludieren wir die Datei script_macros.hpp.

script_macros.hpp

In dieser Datei koennen wir eigene Makros unterbringen und koennen das CBA Debugging mit DEBUG_MODE_FULL aktivieren (im Beispiel auskommentiert). Am Ende laden wir die CBA Macros.

//#define DEBUG_MODE_FULL
#include "\x\cba\addons\main\script_macros_common.hpp"

Eventhandler

Eventhandler sind fuer Addons wichtig, die nicht nur von der Mission aus per execVM aufgerufen werden sollen, sondern auch selbststaendig zu Missionstart Scripte ausfuehren sollen. Der Code der config.cpp zur Definition von PreInit und PostInit Eventhandler sieht wie folgt aus. Es sei angemerkt, dass die eigentlich Init Phase fuer Addons zwar bereit steht, sie aber meistens wenig sinn macht, bzw besser in Form von im Editor setzbaren Modulen umgesetzt wird. Fuer Information zu Pre und Postinit siehe Missionsinitialisierung.

class Extended_PreInit_EventHandlers
{
    class e12_amf_main {
        clientInit = "call compile preprocessFileLineNumbers 'x\e12\addons\amf_main\XEH_PreInit.sqf'";
        serverInit = "call compile preprocessFileLineNumbers 'x\e12\addons\amf_main\XEH_PreInit.sqf'";
    };
};

class Extended_PostInit_EventHandlers
{
    class e12_amf_main {
        clientInit = "e12retnull = [] spawn compile preprocessFileLineNumbers 'x\e12\addons\amf_main\XEH_PostClientInit.sqf'";
        serverInit = "e12retnull = [] spawn compile preprocessFileLineNumbers 'x\e12\addons\amf_main\XEH_PostServerInit.sqf'";
    };
    
};

Wichtig zu erkennen ist, dass PreInit Eventhandler sequenziell (call) und PostInit Eventhandler parallel (spawn) eingebunden werden. Das ist wichtig, da wir in der PreInit Phase alle Skripte kompilieren und bereitstellen und wir sicher sein wollen, dass diese in der darauf folgenden Init- und PostInitPhase bereit sind. Sollte man PreInit EH parallel einbinden kann es passieren, dass der PreInit Code erst nach dem PostInitCode abgeschlossen wird. Aus der sequenziellen Einbindung folgt, dass in der PreInit Phase keine Berechnungen ausgefuehrt werden sollen.