InternalActionsWML

[edit]WML Tags

A: abilities, about, achievement, achievement_group, add_ai_behavior, advanced_preference, advancefrom, advancement, advances, affect_adjacent, ai, allied_with, allow_end_turn, allow_extra_recruit, allow_recruit, allow_undo, and, animate, animate_unit, animation, aspect, attack (replay, weapon), attack_anim, attacks (special, stats), avoid;

B: base_unit, background_layer, berserk, binary_path, break, brush;

C: campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, checkbox, choice, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_palette, color_range, command (action, replay), continue, core, credits_group, criteria;

D: damage, damage_type, death, deaths, default, defend, defends, defense, delay, deprecated_message, destination, difficulty, disable, disallow_end_turn, disallow_extra_recruit, disallow_recruit, do, do_command, drains, draw_weapon_anim;

E: editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry (credits, options), era, event, experimental_filter_ability, experimental_filter_ability_active, experimental_filter_specials, extra_anim;

F: facet, facing, fake_unit, false, feedback, female, filter (concept, event), filter_adjacent, filter_adjacent_location, filter_attack, filter_attacker, filter_base_value, filter_condition, filter_defender, filter_enemy, filter_location, filter_opponent, filter_own, filter_owner, filter_radius, filter_recall, filter_second, filter_second_attack, filter_self, filter_side, filter_student, filter_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, fonts, for, foreach, found_item, frame;

G: game_config, get_global_variable, goal, gold, gold_carryover;

H: harm_unit, has_ally, has_attack, has_unit, has_achievement, have_location, have_unit, heal_on_hit, heal_unit, healed_anim, healing_anim, heals, hide_help, hide_unit, hides;

I: idle_anim, if (action, animation, intro), illuminates, image (intro, terrain), init_side, insert_tag, inspect, item, item_group;

J: jamming_costs, join;

K: kill, killed;

L: label, language, leader, leader_goal, leadership, leading_anim, levelin_anim, levelout_anim, lift_fog, limit, literal, load_resource, locale, lock_view, lua;

M: male, menu_item, message, micro_ai, missile_frame, modification, modifications, modify_ai, modify_side, modify_turns, modify_unit, modify_unit_type, move, move_unit, move_unit_fake, move_units_fake, movement_anim, movement costs, movetype, multiplayer, multiplayer_side, music;

N: not, note;

O: object, objective, objectives, on_undo, open_help, option, options, or;

P: part, petrifies, petrify, place_shroud, plague, poison, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, progress_achievement, put_to_recall_list;

R: race, random_placement, recall (action, replay), recalls, recruit, recruit_anim, recruiting_anim, recruits, redraw, regenerate, remove_event, remove_item, remove_object, remove_shroud, remove_sound_source, remove_time_area, remove_trait, remove_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resolution, resource, return, role, rule;

S: save, scenario, screen_fade, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_achievement, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, objective, set_menu_item), show_objectives, side, skirmisher, slider, slow, snapshot, sound, sound_source, source (replay, teleport), special_note, specials, split, stage, standing_anim, statistics, status, store_gold, store_items, store_locations, store_map_dimensions, store_reachable_locations, store_relative_direction, store_side, store_starting_location, store_time_of_day, store_turns, store_unit, store_unit_defense, store_unit_defense_on, store_unit_type, store_unit_type_ids, store_villages, story, swarm, sub_achievement, switch, sync_variable;

T: target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, test_do_attack_by_id, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel;

U: unhide_unit, unit (action, scenario), unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;

V: value, variable, variables, variant, variation, victory_anim, village, vision_costs, volume;

W: while, wml_message, wml_schema;

Z: zoom;

Part of ActionWML, Internal actions are actions that WML uses internally that do not directly affect game play (or, at least, are not readily apparent to the player). For example, storing a variable is an internal action.

Variable Actions

These actions are focused, in one way or another, on variables. Creating them, modifying them, capturing game data to them, you name it, these actions are all about the variables.

[set_variable]

The [set_variable] tag is used to create and manipulate WML variables­­­. The VARIABLE macro is a quick syntactic shortcut for simple variable creation and the VARIABLE_OP macro is a quick syntactic shortcut for performing simple mathematical operations on variables.

• name: the name of the variable to manipulate

• value: set the variable to the given value (can be numeric or string). Use literal for no substitution. (see VariablesWML)

• literal: set the variable to the given value (can be numeric or string). This does not interpret any dollar signs.

• to_variable: set the variable to the value of the given variable, e.g. 'to_variable=temp' would be equivalent to 'value=$temp'.

• add: add the given amount to the variable.

• sub: subtract the given amount from the variable.

• multiply: multiply the variable by the given number. The result is a float.
  To negate a number, multiply by -1. If you negate 0, the result is a floating-point negative zero -0. To display -0 as 0, use a second tag with add=0; it will flip -0 to 0 but not affect other numbers.

• divide: divide the variable by the given number. The result is a float. Wesnoth 1.9 and later no longer uses integer division. Use a second tag with round=floor if you relied on this.

• modulo: returns the remainder of a division.

• abs: Returns the absolute value of the variable.

• root: Use root=square to calculate the square root. (Version 1.15.0 and later only) Also supports root=cube and arbitrary integer roots.

• power: Raise the variable to some power.

• rand: the variable will be randomly set.
  You may provide a comma separated list of possibilities, e.g. 'rand=Bob,Bill,Bella'.
  You may provide a range of numbers (integers), e.g. 'rand=3..5'.
  You may combine these, e.g. 'rand=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. If a number or item is repeated, it is sampled more frequently as appropriate. See MultiplayerContent for more info on the MP case.
  Using rand= will automatically result in the current action being non undoable. Ignoring possible [allow_undo].

• time=stamp: Retrieves a timestamp in milliseconds since wesnoth was started, can be used as timing aid. Don't try to use this as random value in MP since it will cause an OOS.

• string_length: Retrieves the length in characters of the string passed as this attribute's value; such string is parsed and variable substitution applied automatically (see VariablesWML for details).

• [join] joins an array of strings to create a textual list
  • variable: name of the array
  • key: the key of each array element(array[$i].foo) in which the strings are stored
  • separator: separator to connect the elements
  • remove_empty: whether to ignore empty elements

• ipart: Assigns the integer part (the part to the left of the decimal point) of the referenced variable.

• fpart: Assigns the decimal part (the part to the right of the decimal point) of the referenced variable.

• round: Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:
  • round=ceil: Rounds upward to the nearest integer.
  • round=floor: Rounds down to the nearest integer.
  • round=trunc: (Version 1.15.0 and later only) Rounds towards zero; this is the same operation as ipart, but operating on the value already contained in the variable rather than the value assigned to the key.

• min, max: (Version 1.15.9 and later only) Specify a comma-separated list of numbers; either the smallest or largest number in the list will be assigned to the variable.

• reverse=yes: (Version 1.15.9 and later only) Reverses the string value of the variable. For example, "delfador" becomes "rodafled".

• formula: Calculate the new value of the variable from a WFL formula operating on the old value. This is similar to using the $(...) syntax but avoids the possibility of WFL syntax errors if a referenced variable is empty.

[set_variables]

Manipulates a WML array or container

• name: the name of the array or container to manipulate

• mode: one of the following values:
  • replace: will clear the array name and replace it with given data. This is the default value.
  • append: will append given data to the current array
  • merge: will merge in the given data into name. Attributes in [value] will overwrite any existing already in name. Tags in [value] modify the corresponding tag of the original value of name, so for example the first [attack] tag in [value] would modify the first [attack] tag of name rather than appending a new [attack] tag. A few special syntaxes are supported:
    • __remove=yes: When used in a subtag, causes the corresponding subtag in name to be deleted rather than merged. Deletion happens after any other subtags have been merged.
    • add_to_xxx: Adds its integer value to the integer value of xxx in name, and sets xxx in name to the result. (Version 1.13.8 and later only) Now adds as real numbers rather than integers.
    • concat_to_xxx: (Version 1.13.8 and later only) Similar to add_to_xxx, but does string concatenation instead of numerical addition.
  • insert: will insert the given data at the index specified in the name attribute, such as name=my_array[1]. The default index is zero, which will insert to the front of the array. Note: if an invalid index is used, empty containers will be created before the insertion is performed. In other words, do not attempt to insert at an index greater than (or equal to) the array's current length. This limitation may be removed in future versions.

• to_variable: set the array or container to the value of the given variable

• [value]: the WML inside the [value] tags will be stored in data, variables will be interpolated directly, use $| in order to escape the $ sign, you can store arrays of WML by supplying multiple [value] tags. (See Example)

• [literal]: same as [value], but variables will not be substituted, [literal] and [value] can not be used in the same [set_variables] tag, i.e. you can not create arrays by piling a mix of [value] and [literal] tags

• [split]: splits a textual list into an array which will then be set to data
  • list: textual list to split
  • key: the key of each array element(array[$i].foo) in which the strings are stored; defaults to value if omitted.
  • separator: separator to separate the elements; if omitted, each character of the string will become an element in the result array.
  • remove_empty: whether to ignore empty elements; ignored if separator is omitted

(Version 1.13.4 and later only) You can now mix [value], [literal], and [split] in the same [set_variables] tag. They will be processed in order of appearance. Multiple instances of [split] are also supported now.

Capturing Game Data

These actions capture different bits of game data and store them to variables so they can be examined and/or manipulated.

[store_gold]

Stores a side's gold into a variable.

• StandardSideFilter: The first matching side's gold will be stored in the variable "variable".
• variable: (default='gold') the name of the variable to store the gold in

[store_locations]

Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side' (villages only). The array will include any unreachable border hexes, if applicable.

• StandardLocationFilter: a location or location range which specifies the locations to store. By default, all locations on the map are stored.

• variable: the name of the variable (array) into which to store the locations. Defaults to location.

• mode: (Version 1.13.0 and later only) defaults to always_clear, which clears the variable, whether or not a match is found. If mode is set to replace, the variable will not be cleared, and locations which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are locations matching the filter. If mode is set to append, the variable will not be cleared, and locations which match the filter will be added to the array after the existing elements.

[store_reachable_locations]

Stores locations reachable by the given units. Can store either the movement, attack or vision ranges.

• [filter]: a StandardUnitFilter. The locations reachable by any of the matching units will be stored.
• [filter_location]: (optional) a StandardLocationFilter. Only locations which also match this filter will be stored.
• range: possible values movement (default), attack, vision. If movement, stores the locations within the movement range of the unit, taking Zone of Control into account. If attack, stores the attack range (movement range + 1 hex). See note below for vision.
• moves: possible values current (default), max. For movement and attack, specifies whether to use the current or maximum movement points when calculating the range. Ignored for vision.
• viewing_side: If left unset then fog and shroud are ignored, hidden ambushers are not ignored, and the real reach of the units is stored. If set to a non-zero number, then the area stored for each unit matching the SUF is based on the information visible to that unit's side; it doesn't matter which non-zero number is given. Ignored completely for vision.
• variable: the name of the variable (array) into which to store the locations.

In 1.14 and before, the vision range is calculated as max movement range ignoring ZoC + 1 hex.

(Version 1.15.12 and later only) vision uses the same calculations as the fog and shroud, and handles:

• units with vision costs different to movement costs
• units whose vision points aren't the same as their max movement points
• jamming by enemy units

[store_map_dimensions]

Stores the map dimensions in a variable.

• variable: the name of the variable where the values will be saved into. If it is skipped, a variable 'map_size' is used, and its contents overridden, if they existed already. The result is a container variable, with members width and height.

[store_side]

Stores information about a certain side in a variable.

Keys:

• StandardSideFilter: All matching sides are stored. (An array is created if several sides match - access it with side[2].team_name and so on.)
• variable: the name of the variable to store the information in (default: "side")
• mode:(Version 1.13.0 and later only) defaults to always_clear, which clears the variable, whether or not a match is found. If mode is set to replace, the variable will not be cleared, and sides which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are sides matching the filter. If mode is set to append, the variable will not be cleared, and sides which match the filter will be added to the array after the existing elements.

Result

Variable will contain following members:

• color: Team color used for ellipses, sprites, and flags. Will be one of the id's found in data/core/team-colors.cfg or a custom color defined by [color_range].
• controller: Indicates type of player that control this side. Note: In networked multiplayer, the controller attribute may not be the same on all clients. Be very careful or you have OOS errors.
  • human: Human player
  • ai: If players assigns "Computer Player" to "Player/Type" in game lobby
  • null: If players assigns "Empty" to "Player/Type" in game lobby
• fog: Indicates whether this side is affected by fog of war.
• gold: The amount of gold the side has.
• hidden: (boolean) If 'yes', side is not shown in status table.
• income: Income for this side (base income + all village income. AKA gross income. Note that this is different from the [side] income key).
• name: Name of player.
• recruit: A comma-separated list of unit types that can be recruited by this side.
• shroud: Whether this side is affected by shroud.
• side: The $side_number of the side belonging to this container
• side_name: Translated string representing the side's description.
• team_name: String representing the team's description. Sides with the same team_name are allied.
• user_team_name: Translated string representing the team's description.
• village_gold: The amount of gold given to this side per village it controls per turn.
• scroll_to_leader: (boolean) Whether the game view scrolls to the side leader at the start of their turn.
• flag: Flag animation for villages owned by this side (see [side]). Unless previously specified in [side] or changed with WML (see [modify_side]), this value may be empty for the default flag animation.
• flag_icon: Flag icon for the status bar for this side (see [side]). Unless previously specified in [side] or changed with WML (see [modify_side]), this value may be empty for the default flag icon.
• village_support: The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.
• defeat_condition: (Version 1.13.7 and later only) When the side will be considered defeated. See description at SideWML, ScenarioWML#Scenario_End_Conditions
• faction: (Version 1.13.7 and later only) id of the selected faction, string (multiplayer-only)
• faction_name: (Version 1.13.7 and later only) Name of the selected faction, string (multiplayer-only)
• num_units (Version 1.13.7 and later only): The number of units the side currently has on the map.
• num_villages (Version 1.13.7 and later only): The number of villages the side currently controls.
• total_upkeep (Version 1.13.7 and later only): The number of unit levels the side is currently supporting.
• expenses (Version 1.13.7 and later only): The amount of gold the side is currently spending to support units.
• net_income (Version 1.13.7 and later only): The income the side gains per turn after expenses.
• base_income (Version 1.13.8 and later only): The income the side gains per turn (same as [side] income key)

• (Version 1.13.7 and later only) All other keys and tags of the side that are contained in wesnoth.sides .__cfg

[store_starting_location]

Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x', 'y', 'terrain' and 'owner_side' (villages only)

• StandardSideFilter: The starting locations of all matching sides will be stored. If multiple sides are matched, a WML array will be created.
• variable: (default='location'): the name of the variable to store the location in
• mode:(Version 1.13.0 and later only) defaults to always_clear, which clears the variable, whether or not a match is found. If mode is set to replace, the variable will not be cleared, and the starting locations of the sides which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are locations matching the filter. If mode is set to append, the variable will not be cleared, and the starting locations of the matching sides will be added to the array after the existing elements.

[store_time_of_day]

Stores time of day information from the current scenario into a WML variable container.

• x, y: Location to store the time for. Time areas matter; illumination does not. If this is omitted, the global (location-independent) time is stored.

• variable: (default='time_of_day') name of the container on which to store the information. The container will be filled with the same attributes found on TimeWML.

• turn: (defaults to the current turn number) changes the turn number for which time of day information should be retrieved.

[store_turns]

Stores the turn limit (the maximum number of turns). If there is no limit, this stores -1.

• variable: (default='turns') the name of the variable in which to store the turn limit.

[store_unit]

Stores details about units into a container variable. When a unit is stored, all keys and tags in the unit definition may be manipulated, including some others, with [set_variable]. A sample list of these tags and keys can be found at InternalActionsWMLUnitTags.

If you have a doubt about what keys are valid or what the valid value range is for each key, code a [store_unit] event, save the game, and examine what keys are in the file (or just examine the [unit] tag(s) in any save file). One can also use the :inspect command or the [inspect] tag to open a game-state inspector dialog, which can be used to view unit properties.

Common usage is to manipulate a unit by using [store_unit] to store it into a variable, followed by manipulation of the variable, and then [unstore_unit] to re-create the unit with the modified variables.

Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [unstore_unit] and [foreach].

• [filter] with a StandardUnitFilter as argument. All units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables. The units will be stored in order of their internal underlying_id attribute, which is usually in creation order (but you normally should not depend on the order).

• variable: the name of the variable into which to store the unit(s)

• mode: defaults to always_clear, which clears the variable, whether or not a match is found. If mode is set to replace, the variable will not be cleared, and units which match the filter will overwrite existing elements at the start of the array, leaving any additional elements intact if the original array contained more elements than there are units matching the filter. If mode is set to append, the variable will not be cleared, and units which match the filter will be added to the array after the existing elements.

• kill: if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.

[store_unit_defense]

(Version 1.13.9 and later only)

(Version 1.15.7 and later only) Fixed, was broken in 1.15.3

Stores in a variable the defense of a unit on a particular terrain. If terrain or location is not specified, the terrain on which the unit currently stands is used. (Note: it is a WML defense, so the higher it is, the weaker unit's defense is. A footpad on castle has 70% defense, so this function stores the value 30.)

• StandardUnitFilter
• loc_x, loc_y: x and y of a valid map location. The terrain on this location will be used for the defense calculation.
• terrain: The terrain code for which unit defense should be calculated. If terrain is specified, loc_x and loc_y are ignored.
• variable: the name of the variable into which to store the defense. default: "terrain_defense"

[store_unit_defense_on]

(Version 1.15.7 and later only) Similar to [store_unit_defense], but stores the same number that would be shown in the UI. For example, a footpad on castle has 70% defense, so this stores the value 70.

Takes the same attributes as [store_unit_defense], and defaults to storing the value in "terrain_defense".

[store_unit_type]

Stores a unit type definition into a variable.

• type: (required) the defined ID of the unit type, for example "Goblin Knight". Do not use a translation mark or it will not work correctly for different languages. A comma-separated list of IDs may also be used to store an array of unit types.

• variable: the name of the variable into which to store the unit type information (default "unit_type")

• mode:(Version 1.13.0 and later only) defaults to always_clear, which clears the variable. If mode is set to replace, the variable will not be cleared, and the unit type will overwrite the existing element at the start of the array, leaving any additional elements intact if the original array contained more elements. If mode is set to append, the variable will not be cleared, and the unit type will be added to the array after the existing elements.

[store_unit_type_ids]

• variable: the name of the variable into which to store a comma-separated list of all unit type IDs including all from all loaded addons

[store_villages]

Stores a series of locations of villages that pass certain criteria into an array. Each member of the result array will have members 'x' and 'y' (the position) and 'terrain' (the terrain type) and 'owner_side'.

Note: This differs from using [store_locations] only in that the hexes considered for match are restricted to those with villages (those whose terrain type has its 'gives_income' flag set to true), in the same way that use of either the 'owner_side' key or the '[filter_owner]' will. In fact, if either of these are present, [store_villages] and [store_locations] will behave identically.

• variable: the name of the variable (array) into which to store the locations (default: "location")
• StandardLocationFilter tags and keys as arguments

[store_items]

Stores current items in the scenario into an array. Each entry has at least members x and y and can have all of the other keys listed in the documentation of [item] (depending on what was set during creating the item).

• variable: name of the wml variable array to use (default "items")
• StandardLocationFilter keys as arguments: only items on locations matching this StandardLocationFilter will be stored
• item_name: (Version 1.15.0 and later only) if given, only items created with a matching [item]name= will be stored. As of 1.15.0, this does not support comma-separated lists.

[store_relative_direction]

(Version 1.13.0 and later only)

Gets the relative direction from one hex to another. This is an interface to the function wesnoth uses to decide how a unit will face while it is moving / attacking / defending.

• [source] x and y must describe a map location
• [destination] similar
• variable name of the variable to store string result in (one of 'n', 'nw', 'ne', 's', 'sw', 'se')
• mode optional. 0 is the default setting corresponding to default wesnoth implementation used in animations. 1 is an alternate "radially symmetric" mode. The default mode breaks ties in the direction of south, since this makes more units face the player directly on screen. The radially symmetric mode breaks ties in the direction of counter-clockwise, and might be more appropriate in some cases.

[find_path]

A WML interface to the pathfinder. Calculates the path between a unit and a location and returns the result in a WML variable, that contains also an array for every step of the path (including the starting hex).

• [traveler]: StandardUnitFilter, only the first matching unit will be used for calculation
• [destination]: StandardLocationFilter
• variable: the variable name where the result will be stored, if no value is supplied 'path' will be used as default name. Each step will be stored in a [step] array inside that variable.
• allow_multiple_turns: default no, if yes also moves that require more than one turn will be calculated.
• check_visibility: default no, if yes the path will not be computed if some hexes are not visible due to shroud.
• check_teleport: default yes; if no, teleport won't be taken in account while computing path.
• check_zoc: default yes; if no, unit ZOCs won't be considered while calculating the path.
• nearest_by: (Version 1.15.2 and later only) possible values "movement_cost" (default), "steps", "hexes"; if the [destination] SLF matches multiple hexes, the one that would need the least movement points to reach may not be the one that's closest as measured by hexes, or closest as measured by steps, from the starting point. This option chooses which measurement to prefer.

More detail about multiple destinations and the return structure is on FindPathExplanation (moved out of this page because it has an image in it).

This is the structure of the variable returned by [find_path]:

[path]
	hexes = non-zero if a path was successfully found.
		if the path is calculated to an impassable hex, or the move requires multiple turns
		and allow_multiple_turns is no, its value will be 0.
	from_x, from_y = location of the unit
	to_x, to_y = destination
	movement_cost = total movement cost required by unit to reach that hex
	required_turns = total turns required by unit to reach that hex
	[step]
		x, y = location of the step
		terrain = terrain of the step
		movement_cost = movement cost required by unit to reach that hex
		required_turns = turns required by unit to reach that hex
	[/step]
[/path]

[unit_worth]

Takes only an inline StandardUnitFilter (only the first matching unit will be used for the calculation) and outputs the following variables:

• cost: the current unit cost
• next_cost: the cost of the most expensive advancement
• health: the health of the unit in percentage
• experience: current experience in percentage
• unit_worth: how much the unit is worth

Mainly used for internal AI checks, but one could in theory just do anything with it.

[event]
    name=moveto
    [unit_worth]
       x,y=$x1,$y1
    [/unit_worth]
    [message]
        id=$unit.id
        message=_"I cost $cost gold, with $health|% of my hitpoints and $experience|% on the way to cost $next_cost|.
I am estimated to be worth $unit_worth"
    [/message]
    [clear_variable]
        name=cost,next_cost,health,experience,unit_worth
    [/clear_variable]
[/event]

[clear_variable]

This will delete the given variable. This tag can delete a scalar or an entire array; it can also delete one container at an array index. The macro CLEAR_VARIABLE is a shortcut for this tag.

This action is good to use to clean up the set of variables; for example, a well-behaved scenario will delete any variables that should not be kept for the next scenario before the end of the scenario. One can also clear tags and variables of stored units; for example, one can remove [trait]s and [object]s.

• name: the name of the variable to clear. This can also be a comma-separated list of multiple variable names.
  • If a name ends with an array index, then it deletes that one container, and shifts the indexes of all subsequent containers. For example, {CLEAR_VARIABLE my_awesome_array[2]} deletes my_awesome_array[2], but then moves my_awesome_array[3] to my_awesome_array[2], moves my_awesome_array[4] to my_awesome_array[3], and so on until the end of the array.
  • Note that {CLEAR_VARIABLE my_awesome_array} deletes the entire array, but {CLEAR_VARIABLE my_awesome_array[0]} deletes only the first container.

[sync_variable]

(Version 1.13.0 and later only)

Sets one or multiple variables to the same value as on all clients and also on replays, it uses the value from the currently active side.

• name the name of the variable to synchonize this can be a comma seperated list.

Other Internal Actions

Believe it or not, there are some internal actions that are not focused primarily on variables. They are all grouped here.

[fire_event]

Trigger a WML event (used often for custom events)

• name: the name of event to trigger
  • (Optional) (Version 1.13.6 and later only)

• id: (Optional) the id of a single event to trigger (Version 1.13.6 and later only)

• [primary_unit]: (Optional) Primary unit for the event. Will never match on a recall list unit. The first unit matching the filter will be chosen.
  • StandardUnitFilter as argument. Do not use a [filter] tag.

• [secondary_unit]: (Optional) Same as [primary_unit] except for the secondary unit.
  • StandardUnitFilter as argument. Do not use a [filter] tag.

• [primary_attack]: Information passed to the primary attack filter and $weapon variable on the new event.

• [secondary_attack]: Information passed to the second attack filter and $second_weapon variable on the new event.

• (Version 1.17.6 and later only) [data]: Additional arbitrary data to pass to the event. In addition to passing custom data, this can be used to set the damage_inflicted in an attack event or the owner_side in a village capture event. Values can only be used by Lua.

[remove_event]

(Version 1.13.0 and later only) Removes the event with the specified id.

• id: the id of the event to remove. May be a comma separated list.

[role]

Tries to find a unit to assign a role to.
This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use role= in a unit filter to identify the unit with that role (See FilterWML).
However, there is no guarantee that roles will ever be assigned. You can use [have_unit] (see Condition Tags) to see whether a role was assigned. This tag uses a StandardUnitFilter (without [filter]) with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a side attribute to force the unit to be on a particular side.

• role: the value to store as the unit's role. This role is not used in the StandardUnitFilter when doing the search for the unit to assign this role to.

• type: a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.

• reassign: (Version 1.13.6 and later only) Can be either yes or no, defaults to yes. If set to no then first search for a unit that already has this role, and if found use that unit.

• search_recall_list: (Version 1.13.5 and later only) whether to consider units on the recall list when assigning the role. Can be either yes or no, defaults to yes. (Version 1.13.6 and later only) If set to 'only', then units on the map are not considered when assigning the role - only units on the recall list can receive it. If reassign is no, this setting also affects the search for a unit that already has the role.

• [else] (Version 1.13.5 and later only) ActionWML to execute if the game is unable to find a unit to assign the role to. For example, this could be used to create a new unit satisfying the role.

• [auto_recall]: (Version 1.13.6 and later only) If present, and the role is assigned to a unit on the recall list, then that unit is recalled. Supports all unique keys of [recall], but no StandardUnitFilter.

• StandardUnitFilter, do not use a [filter] sub-tag. SUF's role= and type= keys are not used: if you want to use them, use a nested SUF wrapped inside a [and] tag.

[random_placement]

(Version 1.13.2 and later only)

Selects randomly a given number of locations from a given set of locations and exectutes the given code for each of those locations.

• [filter_location]: a StandardLocationFilter.
• [command]: contains ActionWml that is executed for each of the locations.
• num_items: the number of locations that should be selected. There are several ways of specifying this:
  • An integer, giving the exact number of locations to use. (Variable substitution is supported too.)
  • (Version 1.15.0 and later only) A percentage, meaning that fraction of the total available spaces.
  • (Version 1.15.0 and later only) A WFL formula. It has access to one variable, size, which is the total number of available spaces. In order to identify it as a WFL formula, the entire expression must be enclosed in parentheses. (Do not use a $, as that will cause it to see size as zero.)
  • A Lua expression. As with a WFL expression, it can access the size variable. (Version 1.15.0 and later only) This is now deprecated.
• variable: The name of the variable that contains the current location during the execution of [command]. This is a container with the attributes x, y, n and terrain.
• min_distance: The minimum distance of 2 chosen locations, a value less than 0 means that the same locations can be chosen more than one time.
• allow_less: If yes, the tag will not show an error in case there were less than num_items locations available.

Flow control actions

(Version 1.13.2 and later only)

There are three actions that alter the flow of execution. They are [break], [continue], and [return]. All of them take no arguments.

• [break]: The nearest enclosing loop immediately stops executing, and control continues with the next action after the end of that loop. If there is no enclosing loop, this is equivalent to [return].
• [continue]: The nearest enclosing loop immediately stops executing, and control continues at the beginning of that loop, with any iteration variables updated for the next iteration. If there is no enclosing loop, this is an error.
• [return]: Control immediately returns to the Wesnoth engine. This completely exits the current event, including any nested events, such that the [message] will not be displayed in the below example. No further WML actions are executed in this context. Any separate, subsequent events will be run as usual.

[event]
   name=moveto
   [fire_event]
      name=return_please
   [/fire_event]
   [message]
     message="Made it back"
   [/message]
[/event]
[event]
   name=return_please
   [return][/return]
[/event]

[unsynced]

(Version 1.13.2 and later only)

Runs the contained actionwml in a unsynced context, that means actions performed inside [unsynced] are not synced over the network. for example

[event]
   name=moveto
   {VARIABLE_OP message rand "Hi,Hello,How are you?"}
   [message]
      message = $message
   [/message]
   {CLEAR_VARIABLE message}
   [allow_undo]
   [/allow_undo]
[/event]

will print the same message to all clients, but also disallow undoing (regardless of [allow_undo]) for that moveto becasue it requests a synced random seed form the server. However this code

[event]
   name=moveto
   [unsynced]
      {VARIABLE_OP message rand "Hi,Hello,How are you?"}
      [message]
         message = $message
      [/message]
      {CLEAR_VARIABLE message}
   [/unsynced]
   [allow_undo]
   [/allow_undo]
[/event]

will not prevent undoing, but might print a different message for each client in a multiplayer game (or during a sp replay), so `[unsynced]` should not be used for actions that actually change the gamestate otherwise you'll get OOS

Examples

Using [set_variables] to Create Arrays of WML

[set_variables]
    name=arr
    mode=replace
    [value]
        foo=bar
    [/value]
    [value]
       foo=more
    [/value]
[/set_variables]
{DEBUG_MSG $arr[0].foo}
{DEBUG_MSG $arr[1].foo}

This will produce two output messages, first one saying bar and next one saying more.

See Also

• VariablesWML
• ActionWML
  • ConditionalWML
  • DirectActionsWML
  • InterfaceActionsWML
• EventWML
• ReferenceWML