AddonStructure/de
Innerhalb dieser und anderer Seiten im Wiki wird immer wieder Bezug genommen auf ein Verzeichnis, in denen die benutzerdefinierten Inhalte für Wesnoth gespeichert werden. Es wird hier mit userdata bezeichnet, obwohl ein Verzeichnis diesen Namens nicht (mehr) existiert. Die Bezeichnung hat sich aus praktischen Gründen eingebürgert.
Wie man den Pfad dieses Verzeichnis herausfindet und darauf zugreift, wird ausführlich unter EditingWesnoth erklärt.
Neue, benutzerdefinierte Inhalte, kurz UMC (User Made Content), werden auch als Add-ons und im Deutschen auch als Erweiterungen bezeichnet. Sie werden damit von den Inhalten unterschieden, die bereits vom Spiel mitgebracht werden. Man kann beim Erzeugen neuer Inhalte aber in hohem Maße auf bereits vorhandene Spieldaten zurückgreifen.
Um neue Inhalte zu erschaffen, ist es zunächst notwendig, im Verzeichnis userdata/data/add-ons/ ein neues Unterverzeichnis mit einem beliebigen Namen anzulegen. In diesem und allen weiteren Verzeichnisnamen sind KEINE Leerzeichen erlaubt. Statt dessen können Unter_Striche oder Binde-Striche verwendet werden.
In der Folge (und auch auf anderen Seiten im Wiki) wird ein derartiges Unterverzeichnis vorausgesetzt!
Contents
Die Datei _main.cfg
Im nachfolgende Beipiel gehen wir davon aus, eine neue Erweiterung namens A_Simple_Addon zu erzeugen.
- Dazu legen wir zunächst das Verzeichnis
userdata/data/add-ons/A_Simple_Addonan. - Danach erzeugen wir innerhalb des neuen Ordners eine Textdatei namens _main.cfg. Der Name der Datei bedeutet in etwa "Hauptkonfigurationsdatei". Die Datei _main.cfg stellt die Verbindung zwischen dem Spiel und dem Add-on her und weist das Spiel an, wie die Inhalte des Add-ons geladen werden sollen.
Hier ein sehr einfaches Beispiel für _main.cfg:
#textdomain wesnoth-A_Simple_Addon
[textdomain]
name="wesnoth-A_Simple_Addon"
path="data/add-ons/A_Simple_Addon/translations"
[/textdomain]
#ifdef MULTIPLAYER
[binary_path]
path=data/add-ons/A_Simple_Addon
[/binary_path]
{~add-ons/A_Simple_Addon/scenarios}
#endif
Als ein Nutzer ohne jede Programmiererfahrung ist es vermutlich hilfreich, an dieser Stelle zuerst auf das WML Tutorial zurückzugreifen, denn selbst dieses einfache Beispiel setzt bereits einige Kenntnisse voraus. Ein Nutzer mit entsprechender Vorerfahrung findet weiterführende Informationen in der WML-Referenz.
Zunächst wird mit #textdomain wesnoth-A_Simple_Addon bekannt gemacht, wie die aktuell gültige Textdomain heißt. Mit dem nachfolgenden WML-Tag [textdomain] wird die Textdomain definiert: ihr Name und der Pfad zum Ordner mit Übersetzungen. Der Name der Textdomain setzt sich aus dem Präfix wesnoth- und dem Namen des Add-ons zusammen. Diese Konvention hat sich durchgesetzt und erschwert deutlich das Entstehen von lästigen Namenskonflikten.
Anmerkung: Eine Textdomain ist nur erforderlich, wenn die Erweiterung Text enthält, der übersetzt werden kann und soll. Ein Musikerweiterung beispielsweise benötigt nicht notwendig eine Textdomain.
Alle Tags außer [campaign] und [textdomain] müssen durch eine bedingte Präprozessor-Anweisung der Form #ifdef [andere Tags] #endif umschlossen werden! Das betrifft auch solche Tags, die in anderen Schritten erst eingebunden werden. Diese Vorgehensweise bewirkt, dass bestimmte Inhalte der Erweiterung auch wirklich nur dann eingebunden werden, wenn sie benötigt werden, und verhindert Konflikte mit anderen Add-ons. Für weiterführende Informationen dazu siehe PreprocessorRef.
Im obigen Beispiel wird das Szenario nur im Multiplayer-Modus geladen. Innerhalb einer Kampagne kann man allerdings auch ein spezifisches Flag setzen, um einen bestimmten Inhalt nur innerhalb des Ablaufs dieser Kampagne zu laden.
Innerhalb der Tags [binary_path] wird der (relative) Pfad für binäre Daten definiert, den ein Add-on zusätzlich zu den vom Spiel vorgegebenen Standardpfaden nutzen soll. Diese Angabe ist also nur dann notwendig, wenn ein Add-on eigene binäre Daten nutzen möchte.
Im Anschluss daran wird durch {~add-ons/A_Simple_Addon/scenarios} noch der Pfad für die neuen Szenario-Daten definiert. Auch diese Angabe liegt noch innerhalb der bedingten Präprozessor-Anweisung, wird also nur im Falle eines Multiplayer-Spiels gültig.
Diese einfache Form der Pfadangabe gilt NICHT für die Angabe des Einheiten-Ordners units. Diese muss immer von [units]-Tags umschlossen werden:
[units]
{~add-ons/A_Simple_Addon/units}
[/units]
Anmerkung: Aus der Datei _main.cfg heraus darf nur Code eingebunden werden, keine binären Inhalte (wie etwa Musik, Sounds oder Bilder). Hier wird lediglich mit [binary path] ein Pfad definiert, auf den von anderen Dateien aus verwiesen werden kann.
Die Verzeichnis-Struktur
Welche Ordner als nächstes angelegt werden, hängt von den gewünschten neuen Inhalten der Erweiterung ab. So erfordern Kampagnen oder Karten-Pakete scenarios- und maps-Ordner, während ein Musik-Paket lediglich den Ordner music benötigt. In diesem Beispiel-Add-on nehmen wir an, dass eine Kampagne oder ein einzelnes Szenario erzeugt werden soll.
Wir legen die folgenden Ordner an:
- userdata/data/add-ons/A_Simple_Addon/scenarios
- userdata/data/add-ons/A_Simple_Addon/maps
Alle Datendateien für Karten werden im maps-Ordner gespeichert, während alle Konfigurationsdateien (mit der Endung .cfg) im scenarios-Ordner landen. Weiterführende Informationen zu diesen Themen finden sich unter BuildingMaps und BuildingScenarios.
Für weitere Inhalte, etwa Musik, Sound oder Grafiken, ist es notwendig, entsprechende Ordner anzulegen. Das wird eigentlich auch für alle andere Inhalte empfohlen, um die Übersicht zu wahren.
Die von der Spielengine definierte Verzeichnis-Struktur
Die Ordner, die Code enthalten - wie scenarios und macros - müssen nicht zwingend so benannt werden, sondern dürfen im Prinzip beliebige Namen erhalten. Allerdings ist es sinnvoll, diese selbsterklärenden Namen zu wählen.
Die folgenden Ordner müssen allerdings exakt wie angegeben benannt sein, damit die Spielengine sie findet:
- userdata/data/add-ons/A_Simple_Addon/images
- userdata/data/add-ons/A_Simple_Addon/music
- userdata/data/add-ons/A_Simple_Addon/sounds
Das gilt auch für einige Unterverzeichnisse von images:
- userdata/data/add-ons/A_Simple_Addon/images/attacks
Enthält die Icons für jeden Angriff, siehe auch UnitTypeWML#Attacks. - userdata/data/add-ons/A_Simple_Addon/images/terrain
Enthält Grafiken für Terrain, also die grundlegende Grafik für Karten. - userdata/data/add-ons/A_Simple_Addon/lua
Enthält Lua-Module, die in WML-Dateien durchwesnoth.require "Modul_Name"eingebunden werden können. - userdata/data/add-ons/A_Simple_Addon/translations
Enthält ggf. Übersetzungsdaten, kann aber auch leer sein. Ohne dieses Verzeichnis wird eine Warnung in der Standardfehlerausgabe (stderr) erzeugt. Der Pfad muss exakt dem innerhalb der[textdomain)-Tags in _main.cfg definierten Pfad entsprechen.
Wie die Spielengine genau auf die genannten Verzeichnisse zugreift, wird in BinaryPathWML erläutert.
Directory structure defined by convention
The names of these directories are not prescribed by the engine, but the current "best practice" is:
- userdata/data/add-ons/A_Simple_Addon/ai Lua files for the RCA_AI
- userdata/data/add-ons/A_Simple_Addon/masks files for TerrainMaskWML
- userdata/data/add-ons/A_Simple_Addon/units
- userdata/data/add-ons/A_Simple_Addon/utils containing WML macros
The "images" directory is prescribed by the engine, but can also use subdirectories:
- userdata/data/add-ons/A_Simple_Addon/images/halo for [halo_frame], etc
- userdata/data/add-ons/A_Simple_Addon/images/items
- userdata/data/add-ons/A_Simple_Addon/images/portraits for [unit_type]profile=
- userdata/data/add-ons/A_Simple_Addon/images/story backgrounds for [story] screens
- userdata/data/add-ons/A_Simple_Addon/images/units for [unit_type]image=, etc
Finally, the customary fallback for not putting stuff in the parent directory:
- userdata/data/add-ons/A_Simple_Addon/images/misc