Difference between revisions of "AddonStructure"

From The Battle for Wesnoth Wiki
(The Main File)
(The Main File: Slight clarification on the iportance of _main.cfg)
 
(15 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
{{Translations}}
 +
{{Create}}
 +
 
In order to create custom content for Wesnoth, you need to set up a folder in <i>userdata</i>/data/add-ons/. If you have not found your userdata directory yet, read [[EditingWesnoth]] and come back here. This page will explain the basic directory structure of an add-on and where stuff goes.
 
In order to create custom content for Wesnoth, you need to set up a folder in <i>userdata</i>/data/add-ons/. If you have not found your userdata directory yet, read [[EditingWesnoth]] and come back here. This page will explain the basic directory structure of an add-on and where stuff goes.
  
Line 5: Line 8:
 
== The Main File ==
 
== The Main File ==
  
For this example, we will assume your are creating an add-on called <b>Valen</b>.
+
For this example, we will assume you are creating an add-on called <b>A Simple Addon</b>.
  
*Create the empty directory <b><i>userdata</i>/data/add-ons/Valen</b>.
+
*Create the empty directory <b><i>userdata</i>/data/add-ons/A_Simple_Addon</b>.
*Create a file called <b>_main.cfg</b> inside the Valen folder.
 
  
The _main.cfg file will instruct the game on how to load your content. This example simply shows a very simple example of the file.
+
<b>Important:</b> Remember to use underscores or hyphens in all directory and file names instead of spaces. Failure to do so will result in your content not working properly.
  
#textdomain wesnoth-Valen
+
*Create a file called <b>_main.cfg</b> inside the A_Simple_Addon folder. Without this file, the game will not even recognize that your add-on exists.
[textdomain]
 
    name="wesnoth-Valen"
 
    path="data/add-ons/Valen/translations"
 
[/textdomain]
 
 
#ifdef MULTIPLAYER
 
[binary_path]
 
    path=data/add-ons/Valen
 
[/binary_path]
 
 
{~add-ons/Valen/scenarios}
 
#endif
 
  
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 "wesnoth-", to ensure that it does not conflict with other textdomains that might be specified on a given system and is compatible with [[WesCamp]].
+
The _main.cfg file will instruct the game on how to load your content. Here is shown a very simple example of the file.
 +
 
 +
<syntaxhighlight lang=wml>
 +
#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
 +
</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]].
  
 
<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.
 
<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.
  
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 correct time and does not conflict with other namespaces. In the example above, the scenario 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.  
+
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>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].
+
<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:
 +
 
 +
<syntaxhighlight lang=wml>
 +
[units]
 +
    {~add-ons/A_Simple_Addon/units}
 +
[/units]
 +
</syntaxhighlight>
  
 
== The Directory Structure ==
 
== The Directory Structure ==
Line 40: Line 54:
 
Create the following directories:
 
Create the following directories:
  
*<b><i>userdata</i>/data/add-ons/Valen/scenarios</b>
+
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/scenarios</b>
*<b><i>userdata</i>/data/add-ons/Valen/maps</b>
+
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/maps</b>
 +
 
 +
All map files used in scenarios go in <b>maps</b> (see [[BuildingMaps]]. All configuration (‘.cfg’) files for scenarios go in <b>scenarios</b> (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 <b>scenarios</b> and <b>macros</b>) anything you like, but the binary content directories listed below <b>must</b> 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.
  
All map files used in scenarios go in <b>maps</b> (see [[BuildingMaps]]. All configuration (‘.cfg’) files for scenarios go in <b>scenarios</b> (see [[BuildingScenarios]]).
+
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/images</b>
 +
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/music</b>
 +
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/sounds</b>
  
If you have additional custom content such as images or units, create the respective following:
+
Some subdirectories of <b>images</b> are also supported by the engine:
  
*<b><i>userdata</i>/data/add-ons/Valen/macros</b>
+
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/images/attacks</b> Icons for each attack, see [[UnitTypeWML#Attacks]]'s documentation for '''icon'''
*<b><i>userdata</i>/data/add-ons/Valen/units</b>
+
*'''''userdata''/data/add-ons/A_Simple_Addon/images/terrain</b> Terrain graphics
*<b><i>userdata</i>/data/add-ons/Valen/images</b>
+
 
*<b><i>userdata</i>/data/add-ons/Valen/sounds</b>
+
While Lua can be embedded in WML files, the following directory is supported for loading them via Lua's <b>wesnoth.require "<i>module_name</i>"</b>.
*<b><i>userdata</i>/data/add-ons/Valen/music</b>
+
 
 +
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/lua</b>
  
 
If you set up a textdomain, create a <b>translations</b> directory, even if it remains empty. Failure to do so generates a warning in stderr. This path <b>must</b> be the same as specified in the [textdomain] tag.
 
If you set up a textdomain, create a <b>translations</b> directory, even if it remains empty. Failure to do so generates a warning in stderr. This path <b>must</b> be the same as specified in the [textdomain] tag.
  
*<b><i>userdata</i>/data/add-ons/Valen/translations</b>
+
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/translations</b>
 +
 
 +
=== Directory structure defined by convention ===
 +
 
 +
The names of these directories are not prescribed by the engine, but the current "best practice" is:
 +
 
 +
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/ai</b> Lua files for the RCA_AI
 +
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/masks</b> files for TerrainMaskWML
 +
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/units</b>
 +
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/utils</b> containing WML macros
 +
 
 +
The "images" directory is prescribed by the engine, but can also use subdirectories:
 +
 
 +
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/images/halo</b> for '''[halo_frame]''', etc
 +
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/images/items</b>
 +
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/images/portraits</b> for '''[unit_type]profile='''
 +
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/images/story</b> backgrounds for '''[story]''' screens
 +
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/images/units</b> for '''[unit_type]image=''', etc
 +
 
 +
Finally, the customary fallback for not putting stuff in the parent directory:
  
<b>Note:</b> The above directory structure is a typical one, but it is not mandatory. As long as your translations folder is located at the path specified in your [textdomain] tag, and your binary content directories are relative to your [binary_path], you may call your directories anything and arrange them in any way you like.
+
*<b><i>userdata</i>/data/add-ons/A_Simple_Addon/images/misc</b>
  
 
==See also==
 
==See also==

Latest revision as of 22:51, 8 November 2020


In order to create custom content for Wesnoth, you need to set up a folder in userdata/data/add-ons/. If you have not found your userdata directory yet, read EditingWesnoth and come back here. This page will explain the basic directory structure of an add-on and where stuff goes.

Several pages on this wiki will assume you have done so and refer to relative paths in such.

The Main File

For this example, we will assume you are creating an add-on called A Simple Addon.

  • Create the empty directory userdata/data/add-ons/A_Simple_Addon.

Important: Remember to use underscores or hyphens in all directory and file names instead of spaces. Failure to do so will result in your content not working properly.

  • Create a file called _main.cfg inside the A_Simple_Addon folder. Without this file, the game will not even recognize that your add-on exists.

The _main.cfg file will instruct the game on how to load your content. Here is shown a very simple example of the file.

#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

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 "wesnoth-", to ensure that it does not conflict with other textdomains that might be specified on a given system and is compatible with WesCamp.

Note: 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.

All tags save for [campaign] and [textdomain] must be enclosed in an #ifdef 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.

Note: Only code must be included from this file. You do not 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 units directory cannot be done by a simple path inclusion; it also must be wrapped in a [units][/units] tag pair, as such:

[units]
    {~add-ons/A_Simple_Addon/units}
[/units]

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

See also

This page was last edited on 8 November 2020, at 22:51.