From The Battle for Wesnoth Wiki

This page describes the configuration of the game by the files game.cfg, units.cfg and traits.cfg, all of which are located in the data/ directory.


The game.cfg file begins by referring to other files in the data/ directory. It then sets the value of some [advanced_preference]s.

The main tag in game.cfg is [game_config]. The first 9 keys in [game_config] refer to game constants.

  • base_income is the base income of all players whose base income is not specified in the scenario.
  • village_income refers to the non-upkeep income each village gives its controller.
  • heal_amount is the amount of HP that a unit next to a unit with 'heals' will regenerate.
  • healer_heals_heals_per_turn is the amount of HP that a single unit with 'heals' can heal per turn.
  • cure_amount and curer_heals_per_turn are similar but for units with 'cures' instead.
  • rest_heal_amount is the HP a unit regenerates each turn that unit does not move or fight.
  • recall_cost is the cost to recall any unit.
  • kill_experience is the amount of experience a unit gets for a kill per level of the unit it kills.

The rest of the keys only affect the graphics and music.

(not documented yet)

Then the various [textdomain]s for translations of various parts of Wesnoth follows.

The file ends with [hotkey] specifications.

Previously the [campaign] tags were also found in this file, but they have been moved into separate files for each campaign, which are found in the data/campaigns/ directory. See BuildingScenariosSimple for information on [campaign] tags.


In the units.cfg file, the various races and units used in Wesnoth are configured, within the [units] tag. It starts by including the units in data/units/, and by calling the trait macros that are in common for all races. Then it specifies the various races by the [race] tags.

Each [race] tag contains four keys: name, num_traits, male_names, and female_names. name is the ID of the race. num_traits is the number of traits members of this race receive. male_names, and female_names are defined by calling macros found in data/names.cfg, and are the base names for units of that race and gender. The attribute markov_chain_size=<number> is used by the name generator to specify how the base names are divided up and recombined to form new names.

The attribute not_living=yes may be added to make units of that race unpoisonable.

Next are the additional traits that are specific to the race in question, either by calling a predefined trait macro (preferred) or by use of the [trait] tag directly. The traits macros are found in the file traits.cfg, which is described further down on this page. To make the race ignore the global traits, add ignore_global_traits=yes. If this key is not added, the race specific traits are added to the list of common traits, but if it is present, the race specific traits replace the common trait set.

The last section of [units] contains the [movetype] tags. These create named common sets of movement costs, terrain defense values and weapon attack type resistances, which may be used when defining individual unit types, by setting the movetype key of the unit to the value of name as specified here. The subtags [movement_costs], [defense] and [resistance] may also be set directly in the description of a unit. See CreatingNewUnits for information on how to use them.


The [trait] tag consists of an id, a name, description and one or many [effect] subtags.

The id key is a unique identifier for the trait. The name key is the displayed (and translatable) name of the trait. The description key is a more informative description of the trait, primarily used as a tooltip in the game. The [effect] tag(s) determine what should be changed about a unit that receives this trait. It starts with the key apply_to, which determines what area of the unit's abilities that are affected. The value of apply_to decides which additional keys are used in the [effect] tag. The valid values for apply_to are: new_attack, attack, movement, hitpoints and max_experience. (What about status, does it still exist?)

  • new_attack: Gives the unit a new attack. The keys and subtags of the [effect] tag are in this case the same as the keys/tags for an [attack] tag (See CreatingNewUnits).
  • attack: Changes something about some of the unit's attacks.
    • range: Only attacks with this range are affected.
    • increase_damage: The damage the attack does is increased.
    • set_type: The type of the attack is changed.
  • movement: The unit's movement is changed.
    • increase: Amount to increase movement by in percentage (may be negative value, in which case movement is decreased.)
  • hitpoints: The unit gains or loses HP and/or max HP.
    • increase: Amount to increase HP by.
    • increase_total: Amount to increase max HP by.
    • heal_full: If value=yes, then (?).
  • loyal: Makes the unit's upkeep be 1.
  • max_experience: The amount of XP a unit needs to advance is changed.
    • increase: Amount to increase required XP by.
  • status: The unit's status is affected.
    • add: All values are added to the status. Values are 'poisoned' and 'slowed'.

See Also

This page was last edited on 24 February 2008, at 06:15.