Wesnoth Markup Language

Wesnoth Markup Language

File:Allied Factions small.png A screenshot of a user-made campaign in the text editor gVim
Filename extension	.cfg
Developed by	Battle for Wesnoth development team
Type of format	Event-driven programming language
Extended from	XML

Wesnoth Markup Language a language somewhat related to XML used for coding the content for the open source game The Battle for Wesnoth.

The format is similar to XML, but tags are enclosed in square brackets.

Despite the "Markup" in the name, WML has added features to the point that it can be considered a programming language, and is believed to be Turing complete. It is an event-driven language, with the [event] tag allowing actions to be taken on events such as kills, deaths, movement, or specific turns. Variables and arrays are also supported. There is a preprocessor, mainly used to include different WML for different difficulty levels.

Structure

WML has several top-level tags that define the purpose of a file, such as [campaign], which denotes a campaign, [scenario], which is a campaign scenario, [unit], which describes a unit, and others. Within those tags, there are other tags which are functions within a top-level tag. For example, [side] in the [scenario] tag describes a side in a campaign scenario. These tags may also have tags under them, for example, [story] is part of [scenario], but it also has the [part] tag under it. All tags end with the same name but with a forward slash (/) before them, e.g. [scenario] ends with [/scenario]. Tags that do not have tags under them have parameters or a string, e.g. [message] has the parameter message="Place message string here", where a message string goes in between the quotes. a space, underscore, space (e.g. message= _ "string") after the equals sign indicates a translatable string.

Preprocessor

Ref:
The preprocessor is used to simplify commonly used tasks; the campaign Under the Burning Suns uses these. Some of the more tedious coding is put into the preprocessor, so that everytime you need to write it, you just write the macro instead of the entire code, which the preprocessor reads. The macro takes place of the original block of code, thus making programming in WML much easier and less tedious.
First, you must write the actual coding in a file that Wesnoth will read. Usually, if you used this in a campaign, for example, you would tell Wesnoth to read it by putting the path in curly brackets, e.g. {somewhere/someplace/random_place/file.ext}. Then, in that file, you would use #define MACRO PARAMETER_1 PARAMETER_2 PARAMETER_N (MACRO is the name of your macro, and PARAMETER_N is a parameter/string) and then write the code. For variable parameters, you would would put the name of your parameter in curly brackets. After defining the macro, it is ended with #enddef (which tells Wesnoth that the macro ends there) Example code:

#define MACRO TYPE X Y

[unit]

    type={TYPE}

    x={X}

    y={Y}

    side=2

[/unit]

#enddef

(This macro defines creation of an enemy unit. Note that 'side' parameter has a set value, which means that it is fixed, whatever variables are stated elsewhere in the macro.) Note that everything in the macro is in capital letters, and there should be no spaces within a name (because spaces separate parameters) so underscores should be used. When using the macro in normal coding, you would put the macro in curly brackets, i.e. {MACRO TYPE X Y}, where in place of TYPE, X and Y there would be a value (type would be a unit name, x and y numerical values of positions on the map). Each of the values are in parentheses.

File Directory System

Ref:
Wesnoth uses a file system in order to know how to read each file. Each file has the .cfg file extension. The file system is pivotal to how Wesnoth reads the WML.
There are 15 main files in the C:\Program Files\Wesnoth\data directory (the directory shown is if the default directory was accepted at installation). These are:

• amla.cfg - global definition for After Max-Level Advancement (AMLA), which is an advancement after when a unit has achieved its highest level
• fonts.cfg - tells the game which fonts it can use
• game.cfg - loads all of the files listed here (except itself). The game only actually loads this file on its own, it contains links to all other files, which is how the game opens up all the CFG files. It also contains global variables, e.g. amount of health healed per turn when next to a healer.
• help.cfg - the entire help system document
• items.cfg - macros for common objects and items used in the game, also available for campaign writer use
• multiplayer.cfg - defines the multiplayer eras and factions
• names.cfg - lists of name fragments that are randomly put together to create random-sounding names. They are segregated by race and gender
• scenario-test.cfg - a simple test scenario. Run it with the command wesnoth -t in Command Prompt (MS Windows XP) or similar
• schedules.cfg - defines the global day-night cycle
• terrain.cfg - defines the terrain types
• terrain-graphics.cfg - defines terrain layering and usage of random terrain
• tips.cfg - what the Tome of Wesnoth will show (this is at the bottom left-hand corner of the main menu)
• traits.cfg - defines all traits used globally in the game
• utils.cfg - some common macros used in the game, also available for campaign writer use
• units.cfg - defines the races, which traits each race has, and the movement types (which set defenses, resistances, and movement costs)

As stated above, the game.cfg file links to all of the main CFG files. These load, and have their own links to a folder directory which stores the data related to it. For example, the units.cfg loads the C:\Program Files\Wesnoth\data\units directory, loading all the units that are in there. This is why the location of a file is important, because the respective main CFG will load all files in the directory that is related to it.

Links

• "Create" section of Wesnoth wiki with WML tutorials and references