PreprocessorRef
Contents
Overview
Wesnoth loads just one configuration file directly: data/_main.cfg. However the WML preprocessor allows to include more files. Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.
The preprocessor can interpret a simple language of string expansions known as macros. A macro should always be defined before the place where it needs to be used.
The preprocessor is applied recursively, so included files will be parsed for macros, and after macro expansion will be parsed for macros again, and so on. As a result, you should not write a recursive macro that references itself, because it will cause errors (but, alas, not necessarily error messages).
Preprocessor directives
The following directives are used to create and use macros, i.e. shortcuts which reduce repetition of information. See the macro reference for the list of predefined core macros.
The preprocessor has changed several times, so don't expect old Wesnoth versions to behave exactly the same as the current stable and development series.
Note: In multiplayer scenarios, these directives will appear to work only for the host and not for other clients. This is because the preprocessor is run only on the host, and the clients receive the resultant WML from the server. It's particularly important to keep this in mind before using preprocessor conditionals.
#define
Syntax: #define symbol [parameters] <newline> substitution #enddef
All subsequent occurences of {symbol [arguments]} (see below) will be replaced by the contents of the substitution block, with all occurrences of any parameter {parameter} within substitution replaced by the corresponding value in arguments. For example, the ENEMY_UNIT macro for the macro inclusion example below could be defined as follows:
#define ENEMY_UNIT TYPE X Y
## the ordering above is important, since the preprocessor does not distinguish
## data into different types; only the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE} ## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2 ## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef
(See SingleUnitWML for further information on creating units using WML.)
Important note: Although macros may look like they're simplifying the code, they do not help with wml bloating. Macros are very good at disguising WML bloat, but they do nothing to alleviate it. So instead of using macros to generate redundant and repetitive instructions, you should be considering how to eliminate redundancy through programming techniques of abstraction. The most popular way to improve your code is using custom events and fire_event tags. See also: Wml_optimisation.
#arg and #endarg
(Version 1.13.7 and later only)
Defines an optional argument for a macro along with its default value. Optional arguments can be used to make a macro more flexible and to allow its user to specify certain parameters only when necessary.
For example, one could define a shortcut macro for [message] with only one required argument (the text displayed), but several optional ones:
#define MESSAGE TEXT
#arg SPEAKER_ID
narrator
#endarg
#arg CAPTION
#endarg
#arg SOUND
#endarg
#arg IMG
#endarg
[message]
speaker={SPEAKER_ID}
message={TEXT}
caption={CAPTION}
sound={SOUND}
image={IMG}
[/message]
#enddef
The caller of the macro can then decide which, if any, of the default values to override:
{MESSAGE _"Halt!" SPEAKER_ID="Guard Captain"}
{MESSAGE _"Two days pass..." IMG=wesnoth-icon.png SOUND=ambient/morning.ogg}
{MESSAGE _"..."}
{MESSAGE _"Welcome!" CAPTION=_"Elóndra's shop of wonders" IMG=portraits/elves/shyde.png}
{MESSAGE _"*smash*" SPEAKER_ID="Bridge Troll" SOUND=mace.ogg}
Note: as with #enddef, the final linebreak before #endarg is included in the default value. This means that if the symbol is used in the middle of a line, you should place the #endarg immediately after the value has ended, without a linebreak in between.
#undef
Syntax: #undef symbol
Removes the previous definition of the macro named symbol.
Inclusion directive {}
This directive can be used to include macros, single files or sets of files from a target directory.
File/directory inclusions
Syntax: {path}
Includes the file with the specified path, which will in turn run the preprocessor on it and perform any required substitutions or inclusions within it. The path may not contain .. or the inclusion will be skipped.
The exact location in which the path will be resolved will depend on its prefix:
- {path}: If path isn't a known macro (see below), the game will assume it's a relative path to a file in the main game data/ directory and include it.
- {~path}: As above, but instead of the game data directory, the path is resolved relative to the user data/ directory, where user made add-ons can normally be found.
- {./path}: The path is resolved relative to the location of the current file containing this inclusion.
Information for locating the user data and game data directories can be found in EditingWesnoth.
Forward slashes (/) should always be used as the path delimiter, even if your platform uses a different symbol such as colons (:) or backslashes (\)! It is also very important to respect the actual letter case used to name files and directories for compatibility with case-sensitive filesystems on Unix-based operating systems.
When path points to a directory instead of a file, the preprocessor will include all files found within with the .cfg extension, in alphabetical order; files without this extension (such as .map or .png files) are ignored.
Some directories are handled in a special fashion according to their contents:
- If there's a file named _main.cfg in the target directory, only that file will be included and preprocessed. It may include other files from its own directory or subdirectories within it, of course. This is used for managing WML directories as self-contained packages, like user made add-ons.
- If there are files named _main.cfg in subdirectories of the target and there isn't one in the target itself, they will be all preprocessed. Given the following layout:
dir/ dir/a/_main.cfg dir/a/other.cfg dir/b/_main.cfg dir/b/other.cfg dir/other.cfg
Using {dir} will cause dir/a/_main.cfg, dir/b/_main.cfg and dir/other.cfg to be included.
- If there's a file named _final.cfg but no _main.cfg, the file is guaranteed to be included and processed after all the other files in the directory.
- If there's a file named _initial.cfg but no _main.cfg, the file is guaranteed to be included and processed before all the other files in the directory.
Macro inclusions
Syntax: {symbol [arguments] [optional arguments]}
If the macro named symbol is defined, the preprocessor will replace this instruction by the expression symbol was previously defined as, using arguments as parameters. The number of normal arguments must be exactly the same as in the original definition or an error will occur. Optional arguments can only be placed after all normal arguments, however they can be specified in any order desired.
You can create multiple word arguments by using parentheses to delimit the contents. For example, in {ENEMY_UNIT Wolf Rider 18 24} the four words will be interpreted as separate arguments and cause the preprocessor to fail since the macro was defined above with only three; instead, you should use {ENEMY_UNIT (Wolf Rider) 18 24}.
Optional arguments can also be delimited by placing parentheses, however they must be placed around both the argument name and content:
{MESSAGE _"I'll smash you!" (SPEAKER_ID=Bridge Troll) } # Correct
{MESSAGE _"I'll smash you!" SPEAKER_ID=(Bridge Troll) } # Wrong
This way even complex arguments can be passed:
{MODIFY_UNIT (
[filter_adjacent]
canrecruit=yes
[/filter_adjacent]
) side 2}
Using the name of an existing macro as the name of a macro argument is possible, but the argument will always take precedence over the original macro:
#define VARIABLE
#enddef
#define MACRO VARIABLE
{VARIABLE} # is calling for the argument, not for the macro above
#enddef
#ifdef and #ifndef
Unlike the other preprocessor directives, #ifdef and #ifndef are not mere conveniences. They are often necessary to distinguish between different gameplay modes or difficulties (see Built-in macros below).
Syntax: #ifdef symbol substitution-if-defined [#else substitution-if-not-defined ] #endif
If symbol has been defined with #define or as a built-in macro, the whole block will be replaced by substitution-if-stored. If not, it will be replaced by substitution-if-not-stored if it is available.
#ifndef is the exact opposite of #ifdef, reversing the logic:
Syntax: #ifndef symbol substitution-if-not-stored [#else substitution-if-stored] #endif
#ifhave and #ifnhave
Syntax: #ifhave path substitution-if-path-exists [#else substitution-if-path-does-not-exist] #endif
Checks for the existence of a file. Uses the same relative paths as include directives (see below).
Example:
#ifhave ~add-ons/My_Addon/_main.cfg
{MY_ADDON_MACROS}
#endif
#ifnhave does the opposite of #ifhave:
Syntax: #ifnhave path substitution-if-path-does-not-exist [#else substitution-if-path-exists] #endif
#ifver and #ifnver
Syntax: #ifver symbol operator version-number <newline> substitution-if-condition-met [#else substitution-if-condition-not-met] #endif
Compares a version number defined in a macro against an argument for conditional block inclusions, like #ifdef and #ifhave. operator is one of == (equal), != (not equal), < (less), <= (less or equal), > (greater), >= (greater or equal). The specified symbol should have been previously defined as plain text without more macro inclusions within it, and it must not require any arguments.
Versions with text suffixes are sorted in binary order and come after all versions with the same number. The most common suffixes begin with "+", but as this represents multiple possible versions, comparing versions against it is not recommended.
Example:
#ifver WESNOTH_VERSION >= 1.9.7+
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7+, 1.9.8 or later!"
[/message]
#else
#ifver WESNOTH_VERSION == 1.9.7
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7, and I’ll include some workaround code for bug #9001!"
[/message]
#endif
#endif
#ifnver does the opposite of #ifver:
Syntax: #ifnver symbol operator version-number <newline> substitution-if-condition-not-met [#else substitution-if-condition-met] #endif
#error
Syntax: #error [message]
Causes the WML preprocessor to fail unconditionally upon encountering the line. For add-ons, this will cause the game to display an error and return to the titlescreen if the add-on is required for the user's action (such as playing a campaign or loading a saved game). For core WML, this will cause the game to quit entirely.
Please note that in spite of the example below, it is not advisable to use this mechanism in published add-ons for version or feature-checking, since the message is not displayed in a form that permits translation and the additional trace information may confuse players. This directive is only intended as a debugging aid for content creators.
Example:
#ifver WESNOTH_VERSION < 1.11.10
#error This add-on does not support Wesnoth 1.11.10!
#endif
#warning
Syntax: #warning [message]
Causes the WML preprocessor to emit a warning upon encountering the line. The message will only be relayed to stderr, not to the player in the game UI. This directive is only intended as a debugging aid for content creators.
Example:
#ifver WESNOTH_VERSION < 1.11.10
#warning On Wesnoth 1.11.9 or earlier, bug workarounds enabled!
#endif
#deprecated
(Version 1.13.11 and later only)
Syntax: #deprecated level [version] message
The effect of this directive depends on whether it appears within a macro definition.
- If it appears at file level, outside any macro definition, then it immediately outputs a warning saying that the file is deprecated, with the provided message. Multiple #deprecated directives at toplevel in a single file will result in separate messages.
- If it appears inside a macro definition (#define ... #enddef), then it doesn't output anything. Instead, it marks the macro as deprecated. When that macro is later used, only then will the preprocessor output a warning saying that the macro is deprecated, with the provided message. Multiple #deprecated directives within a single macro will be merged into one message.
Note that deprecation messages will only appear if they have been set to. (Version 1.13.12 and later only) This can be done by enabling debug mode, or by going to Advanced Preferences and setting the log-level for the deprecation logdomain. (This can also be done on the command-line.)
The version argument is technically not optional. If you provide a deprecation level of 2 or 3, it is required to indicate the earliest version in which the feature could be removed. However, if you provide a deprecation level of 1 or 4, any provided version will instead be parsed as part of the message, so you will probably not want to provide one at all. Other deprecation levels are not valid. See the documentation for [deprecated_message] for the meaning of the various level values.
Built-in macros
The following macros are automatically defined with empty contents (unless specified otherwise) by the game engine depending on the configuration or gameplay mode.
- A campaign define symbol (see define in CampaignWML): defined when playing a single-player campaign.
- A campaign difficulty level, usually EASY, NORMAL or HARD (see difficulties in CampaignWML): defined according to the chosen difficulty when starting a single-player campaign, also stored in saved games.
- MULTIPLAYER: defined when in multiplayer mode.
- TUTORIAL: defined when playing the tutorial campaign.
- EDITOR: defined when running the built-in map editor.
- DEBUG_MODE: defined when the game has been launched in debug mode (i.e. with -d or --debug in the command line).
- APPLE: defined while processing the main game data when running on Mac OS X.
- WESNOTH_VERSION: defined containing just the game version number when running the WML preprocessor.
- CURRENT_FILE: Expands to the name of the current WML file.
- CURRENT_DIRECTORY: Expands to the name of the directory of {CURRENT_FILE}, I assume?
- LEFT_BRACE: (Version 1.15.2 and later only) Expands to
{. - RIGHT_BRACE: (Version 1.15.2 and later only) Expands to
}.
Note that the macros above are only those generated by wesnoth engine itself. For a list of macros defined outside engine, see here: https://www.wesnoth.org/macro-reference.html
Command-line preprocessor
Syntax: --preprocess <source file/directory> <target directory>
Or the short form:
Syntax: -p <source file/directory> <target directory>
You can specify a list of predefined defines with:
Syntax: --preprocess-defines=DEFINE1,DEFINE2,etc
comma separated list of defines to be used by '--preprocess' command. If 'SKIP_CORE' is in the define list the data/core won't be preprocessed.
The command will preprocess first the common config files in the main game data/ directory, and afterwards the specified ones. You can specify a single file to be preprocessed (if you want to preprocess multiple separate files, you'll need to run a different command line for each one), or an entire directory, which will be preprocessed according to the rules used by the inclusion directive above.
The resulted preprocessed files will be written in the target directory. There will be two types of files: .cfg files --- the normal ones, and .plain files containing line markers and textdomain changes.
If by chance, the simple macro define doesn't suffice, you can use:
Syntax: --preprocess-input-macros <file>
To import an existing file that contains macros, and they will be available in the defines database before processing the specified files.
There is also the possibility to export the preprocessed defines/macro list with:
Syntax: --preprocess-output-macros [<target file>]
This file could be fed to the 'input-macros' argument next time you run it. For example, a scenario would be: parsing just the core first time, and for the intended target files, you would add SKIP_CORE but import the generated macros file - that will be faster than preprocessing the core again. If the target file is not specified, the output file will be _MACROS_.cfg in the target directory of the preprocess's command.
If file/directory and target directory are not absolute paths, they will be considered relative to the game's executable path.
Some examples:
- Preprocess the entire tutorial dir, and write the results in the ~/result folder:
-p ~/wesnoth/data/campaigns/tutorial ~/result
- Add the MULTIPLAYER define to the list and preprocess a scenario's config file:
-p ~/.wesnoth/data/add-ons/My_Campaign/scenarios/01_First_Scenario.cfg ~/result --preprocess-defines=MULTIPLAYER
- Add the MY_CAMPAIGN and HARD defines before preprocessing a campaign's files:
-p ~/.wesnoth/data/add-ons/My_Campaign ~/result --preprocess-defines=MY_CAMPAIGN,HARD
If you want a more detailed (and potentially overwhelming) log, you can simply add the switches --log-debug=all or --log-info=all to the command line, so you can see how things are preprocessed in detail.