AddonStructure
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 your are creating an add-on called Valen.
- Create the empty directory userdata/data/add-ons/Valen.
- Create a file called _main.cfg 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.
#textdomain wesnoth-Valen
[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.
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.
[binary_path] and all other tags and inclusions should be enclosed in an #ifdef preprocessor statement (see PreprocessorRef for more information on how this works). This is to make sure your content only loads at correct time. 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.
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].
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/Valen/scenarios
- userdata/data/add-ons/Valen/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 or units, create the respective following:
- userdata/data/add-ons/Valen/macros
- userdata/data/add-ons/Valen/units
- userdata/data/add-ons/Valen/images
- userdata/data/add-ons/Valen/sounds
- userdata/data/add-ons/Valen/music
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 should be the same as specified in the [textdomain] tag.
- userdata/data/add-ons/Valen/translations
Note: 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.