Difference between revisions of "AddonStructure/de"

Revision as of 19:54, 13 February 2022

Creator's Guide

Add-on Structure • Maps • Scenarios • Campaigns • Multiplayer • Units • Distributing Content

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!

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_Addon an.
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.

The Directory Structure

What to create next depend on what type of content you are creating. For example, campaigns or map packs will have scenarios and maps directories, while a music pack would have only music. Here we will assume you are creating a campaign or single-scenario add-on.

Create the following directories:

userdata/data/add-ons/A_Simple_Addon/scenarios
userdata/data/add-ons/A_Simple_Addon/maps

All map files used in scenarios go in maps (see BuildingMaps. All configuration (‘.cfg’) files for scenarios go in scenarios (see BuildingScenarios).

If you have additional custom content such as images, sounds or music, it's necessary to create additional directories. Even for other custom content, creating directories to organise it is recommended.

Directory structure defined by the engine

You may name the directories containing code (such as scenarios and macros) anything you like, but the binary content directories listed below must be named as such and be relative to your [binary_path]. This is because when trying to resolve an image path, Wesnoth will look under images/, and likewise for sounds and music, in as explained in the BinaryPathWML page.

userdata/data/add-ons/A_Simple_Addon/images
userdata/data/add-ons/A_Simple_Addon/music
userdata/data/add-ons/A_Simple_Addon/sounds

Some subdirectories of images are also supported by the engine:

userdata/data/add-ons/A_Simple_Addon/images/attacks Icons for each attack, see UnitTypeWML#Attacks's documentation for icon
userdata/data/add-ons/A_Simple_Addon/images/terrain Terrain graphics

While Lua can be embedded in WML files, the following directory is supported for loading them via Lua's wesnoth.require "module_name".

userdata/data/add-ons/A_Simple_Addon/lua

If you set up a textdomain, create a translations directory, even if it remains empty. Failure to do so generates a warning in stderr. This path must be the same as specified in the [textdomain] tag.

userdata/data/add-ons/A_Simple_Addon/translations

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

@@ Line 16: / Line 16: @@
 #Dazu legen wir zunächst das Verzeichnis <code>''userdata''/data/add-ons/A_Simple_Addon</code> an.
-#Danach erzeugen wir innerhalb des neuen Ordners eine Textdatei namens '''_main.cfg'''. Ohne diese Datei wird das Spiel nicht einmal bemerken, dass dein Add-on existiert. Der Name der Datei bedeutet in etwa "Hauptkonfigurationsdatei".
+#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.
-Die Datei _main.cfg weist das Spiel an, wie die Inhalte des Add-ons geladen werden sollen. Hier ein sehr einfaches Beispiel:
+Hier ein sehr einfaches Beispiel für _main.cfg:
 <syntaxhighlight lang=wml>
@@ Line 36: / Line 36: @@
 </syntaxhighlight>
-The [textdomain] WML tag specifies where the game should look for translations to the strings in the add-on. The textdomain should be the add-on's directory name prefixed with <b>"wesnoth-"</b>, to ensure that it does not conflict with other textdomains that might be specified on a given system and is compatible with [[WesCamp]].
+<small>Als ein Nutzer ohne jede Programmiererfahrung ist es vermutlich hilfreich, an dieser Stelle zuerst auf das [[WML_for_Complete_Beginners:_Introduction|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 [[ReferenceWML|WML-Referenz]].</small>
-<b>Note:</b> A textdomain is only required if your add-on contains text meant to be translated. In the case of, for example, a music pack, no textdomain is needed.
+Zunächst wird mit <code>#textdomain wesnoth-A_Simple_Addon</code> bekannt gemacht, wie die aktuell gültige Textdomain heißt. Mit dem nachfolgenden WML-Tag <code>[textdomain]</code> 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.
-All tags save for [campaign] and [textdomain] <b>must</b> be enclosed in an <b>#ifdef</b> preprocessor conditional - including those substituted through inclusion (see [[PreprocessorRef]] for more information). This is to make sure your content only loads at the correct time and does not conflict with other add-ons. In the example above, the scenarios will be loaded when you enter multiplayer mode. In a campaign, you can set up a specific flag to allow your content to only load when that campaign is played.
+<b>Anmerkung:</b> 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.
-<b>Note:</b> Only <b>code</b> must be included from this file. You <b>do not</b> need to include binary content (such as sounds, images, or music). Those may be referred to simply by path relative to the one specified in [binary_path]. Also, including the <b>units</b> directory cannot be done by a simple path inclusion; it also must be wrapped in a <b>[units][/units]</b> tag pair, as such:
+Alle Tags außer [campaign] und [textdomain] '''müssen''' durch eine bedingte Präprozessor-Anweisung der Form <code>#ifdef [andere Tags] #endif</code> 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 <code>[binary_path]</code> 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.<br>
+Im Anschluss daran wird durch <code>{~add-ons/A_Simple_Addon/scenarios}</code> 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.<br>
+Diese einfache Form der Pfadangabe gilt NICHT für die Angabe des Einheiten-Ordners '''units'''. Diese muss immer von <code>[units]</code>-Tags umschlossen werden:
 <syntaxhighlight lang=wml>
@@ Line 49: / Line 55: @@
 [/units]
 </syntaxhighlight>
+'''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 <code>[binary path]</code> ein Pfad definiert, auf den von anderen Dateien aus verwiesen werden kann.
 == The Directory Structure ==