BuildingUnits
When creating custom content, you might want to create a cool new unit. This page will walk you through the creation of a new unit and discuss how you can use it in-game.
Before you begin, you should be remember that the [unit_type] tag will create a new type of unit, while the [unit] tag allows you to use the unit in your scenario. This article will focus on the use of the former.
Creating a new unit
The easiest way to make a new unit is to make a copy of an existing unit's configuration file and modify it. All units shipped with the game can be found in the game's data/core/units directory (see EditingWesnoth for how to find it).
When you are editing the file, pay attention to the property keys. If you forget to modify each key (for example, the unique id key), problems may arise, varying for minor issues such as lack of features on the unit, to game refusing to load the unit file, or, in the worst case, crashing the game.
For complete reference on unit properties see UnitTypeWML. Most of them are self-explanatory to anyone who has played Wesnoth for very long, and are brief but descriptive.
There are a few important basics:
- The first attribute of a unit type is the id= key, which is a unique identifier for that type. Whenever referring to a unit type via in a scenario, you use this id. It is not translatable. The name= key is the displayed name of the unit type in places such as help, the status table, and the sidebar, and is translatable. You can have a complex id, but a simple name. Remember that this is NOT the same as the name of a specific instance of a unit created in a scenario via [unit].
- When referencing the unit type, the id must be reproduced verbatim, without typos, and in a case-sensitive manner. If you don't do this, the game will throw Unknown Unit errors.
- Do not set movement= to 0. It creates weird infinite movement behavior. This might be fixed in the future. For now, to make an immobile unit, set movement to 1 and use [movement_costs] to make it unable to move onto any terrain.
Using your new unit
Custom unit configuration files should be put in your add-on's units directory, and their custom graphics in the images/units directory. Be sure to have the units directory included from your _main.cfg. The include for this directory, however, should be wrapped in a [units][/units] tag pair. See AddonStructure for an example.
All units in this directory will now be accessible in any content loaded under the same #ifdef conditional. You can now allow sides to recruit the unit by listing it in the recruit= key in [side] (see SideWML, place instances of it on the map with their own custom stats via [unit], or anything else you please.
Multiplayer factions and eras
Another common use of custom units it to group them into a multiplayer faction, and group one or several factions together into an era. A faction is several units that represent a common theme, such as the Loyalists. An era is several factions grouped together, usually under a common theme, but can also be done so for other reasons; an example would be the Default era, which contains all the eras used in multiplayer.
Note: Remember that eras and factions is a construct unique to multiplayer.
More detailed instructions on factions and eras can be found in the EraWML article. A faction, if there's only one, must be included in an era. You will not be able to add your units to any era that ships with the game.