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;

Internal actions are actions that WML uses internally that do not directly affect game play. For example, storing a variable is an internal action.

Condition Tags

These tags describe conditions which must be met before an action can take place. Some or all of them are used in the various Conditional Actions.

[have_unit]

A unit with greater than zero hit points matching this filter exists.

• StandardUnitFilter *: Selection criteria.
  * Note: Does not check for matching units in the recall list!
• count: (Optional) If used, a number of units equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".

[have_location]

A location matching this filter exists.

• StandardLocationFilter: Selection criteria.
• count: (Optional) If used, a number of locations equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".

[variable]

Test the value of a WML variable (see VariablesWML) against another value.

• name: The name of the variable to test.
• <comparison>: One of the following keys must be used to compare the value of the named variable, represented as $name below, against another value:
  • contains: $name contains this string value.
  • equals: $name is equal (string wise) to this value.
  • not_equals: $name is not equal (string wise) to this value.
  • numerical_equals: $name is equal (numerically) to this value.
  • numerical_not_equals: $name is not equal (numerically) to this value.
  • greater_than: $name is greater than this value.
  • greater_than_equal_to: $name is greater than or equal to this value.
  • less_than: $name is less than this value.
  • less_than_equal_to: $name is less than or equal to this value.
  • boolean_equals: $name has an equivalent boolean value. *
  • boolean_not_equals: $name does not have an equivalent boolean value. *
    * When values are evaluated as boolean values they are checked to see if they are false or true.
    These values are evaluated as false: no, false, off, 0, and 0.0
    These values are evaluated as true: yes, true, on, 1, and 0.1 (and any other non-zero number)

Meta Condition Tags

These tags aren't really conditions, themselves. Instead they are wrapped around condition tags to group them into multiple conditions that must all be met, lists of conditions that only one must be met, or conditions that must not be met. These are handled in order in any combination you can think of. One important thing to remember is if you are using [or] tags, the first conditional statement should not have an [or] tag wrapped around it.

[and]

A condition which must evaluate to true in addition to any others. Useful as a bracket for complex conditions, but not strictly necessary.

• Condition Tags: If these evaluate to true, the [and] tag evaluates to true.

[or]

A condition which, if it evaluates to true, is all that is necessary for the conditions to be met. In other words, if all other conditions are false, but one [or] condition is true, the conditions have been met for an action to take place. (See Example)

• Condition Tags: If these evaluate to true, the [or] tag evaluates to true.

[not]

A condition which reverses the evaluation of the contained condition(s).

• Condition Tags: If these evaluate to true, the [not] tag evaluates to false. If these evaluate to false, the [not] tag evaluates to true.

Conditional Actions

These internal actions describe actions that should be executed only if certain conditions (in almost all cases described using Condition Tags) are met.

[if]

Executes actions only if conditions described in the contained conditions are met.

• Condition Tags: Conditions which must be met for the actions in the [then] tag to be executed.

• [then]: Contains a set of action tags which should be executed if all conditions evaluate as true or if any single [or] tag evaluates as true.

• [else]: Contains a set of action tags which should be executed if any condition evaluates as false and all of the [or] tags evaluate as false.

[switch]

The [switch] tag is a special case because it does not use Condition Tags to control whether actions are performed. Instead, it executes different sets of actions based on the value of a variable.

• variable: The name of the variable to check.
• [case]: Case tag which forms a block containing:
  • value: The value to test the variable's value against.
  • <Action WML>: Action WML (Variable Actions, DirectActionsWML, InterfaceActionsWML, [event], etc.) to execute if the variable matches the value. (The rest of the [case] block after the value attribute.)
• [else]: Else tag which forms a block of action WML (Variable Actions, DirectActionsWML, InterfaceActionsWML, [event], etc.) to execute if no [case] block contains a value matching the value of the variable.

Example usage:

 [switch]
    variable=foo
    [case]
       value="A"
       ... WML if foo=A ...
    [/case]
    [case]
       value="B"
       ... WML if foo=B ...
    [/case]
    [else]
       ... WML if not foo=A nor foo=B ...
    [/else]
 [/switch]

[while]

Like the [if] tag, executes actions only if conditions described in the contained conditions are met. Additionally, the [while] tag continues to execute the actions until the contained conditions are no longer met. Executes a maximum of 1024 iterations per invocation.

• Condition Tags: Conditions which must be met for the actions in the [do] tag to be executed.

• [do]: contains actions that should be executed repeatedly until some condition is false.

The [while] tag is useful for iterating over an array. An array is a list of values. The numberth value in the array array is stored in the WML variable array[number]. Note that if number is the value of the variable variable, the expression $array[$variable] will return the numberth value in array.

'FOREACH' Macro

This macro simplifies the use of a [while] tag to create a for-each iteration format. This is useful, for example, when you want to iterate over each row in a table. To use it, use the FOREACH and NEXT macros documented here.

'REPEAT' Macro

This macro simplifies the use of a [while] tag to execute the same action(s) repeatedly for a specified number of times. To use it, use the REPEAT macro documented here.

[event]

This adds a new event to the scenario. The event is in the normal format for an [event] tag (See EventWML). This is useful if you want an event that can only be triggered when a prior event is fulfilled

Variable Actions

These tags describe actions that affect the values of WML variables (see VariablesWML for information on WML variables, and UtilWML for convenient macro shortcuts for some of these):

• [set_variable]: manipulates a WML variable. (Note: You can use the VARIABLE predefined macro to achieve the same result in a shorter format) Template:DevFeature Floating-point arithmetic is now fully supported.
  • 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 dollars signs.
  • format: This attribute will be deprecated from 1.7 on. Same behaviour as value.
  • to_variable: Fully processes its value as in format, and then gets the variable with that name.
  • add: add the given amount to the variable. To subtract, add a negative number.
  • multiply: multiply the variable by the given number. To divide, multiply by the inverse eg: 4/2 = 4 * 1/2 = 4 * 0.5. To negate, multiply by -1. The result is an integer. Template:DevFeature Floating point values are no longer rounded.
  • divide: divide the variable by the given number. The result is an integer. Template:DevFeature Floating point results are no longer rounded. If both variables are integers, Integer division is used.
  • modulo: returns the remainder of an integer division. Both variables need to be an integer, the result is also an integer. eg 5 % 2 = 1. Template:DevFeature Floating point variables also work.
  • random: the variable will be randomly set.
    You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'.
    You may provide a range of numbers (integers), e.g. 'random=3..5'.
    You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with format.
  • rand: does the same as random, but has better MP support. See BuildingMultiplayerExamples for more info on the MP case. It is highly recommended that you use this feature for randomization.
  • 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.
  • Template:DevFeature 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).
  • Template:DevFeature [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
  • Template:DevFeature ipart: Assigns the integer part (the part to the left of the comma) of the referenced variable.
  • Template:DevFeature fpart: Assigns the decimal part (the part to the right of the comma) of the referenced variable.
  • Template:DevFeature round: Rounds the variable to the specified number of digits of precision. Negative precision works as expected (rounding 19517 to -2 = 19500). Special values:
    • ceil: Rounds upward to the nearest integer.
    • floor: Rounds down to the nearest integer.

• Template:DevFeature [set_variables]: manipulates a WML array
  • name: the name of the container to manipulate
  • mode: one of the following values:
    • replace: will clean the array name and replace it with given data
    • append: will append given data to the current array
    • merge: will merge in the given data into name
    • 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 unless the variable already contains data at that index. This limitation may be removed in future versions.
  • to_variable: data will be set to the given array
  • [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, example:

[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}
=>bar; more

• • [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
    • separator: separator to separate the elements
    • remove_empty: wether to ignore empty elements

• Template:DevFeature [fire_event]: trigger a WML event
  • name: the name of event to trigger
  • [primary_unit]: primary unit for the event (usually the attacker) (optional)
  • [secondary_unit]: secondary unit for the event (usually the defender) (optional)
  • both tags have some keys which are optional :
    • x,y: location of this unit
    • In Wesnoth 1.5.9 and onwards, [primary_unit] and [secondary_unit] can take a Standard Unit Filter, but it will never match on a recall list unit. If it matches multiple units, the first unit that would be obtained with [store_unit] will be used in the relevant event parameter ($unit or $secondary_unit) and event filter.
  • [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.

• [store_unit]: stores details about units into game variables.
  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], DirectActionsWML, and FOREACH, UtilWML
  • [filter]: StandardUnitFilter all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.
  • 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 only be cleared if a match is found. If mode is set to append, the variable will not be cleared.
  • 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.

When a unit is stored, the following values may be manipulated with [set_variable]

• description
• experience
• facing
• gender
• canrecruit
• overlays
• goto_x
• goto_y
• hitpoints
• moves
• resting
• side
• type
• unrenamable
• upkeep
• user_description
• x
• y
• [variables]
• [status]
• [modifications]

Variables, status, and modifications are children of the stored unit variable. Example:

[set_variable]
name=unit_store.status.poisoned
value=yes
[/set_variable]

All keys and tags in the unit definition may be manipulated, including some others. Here is a sample list. 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.

• advances_to
• alignment
• alpha
• attacks_left
• canrecruit
• controller
• cost
• description
• experience
• facing
• flying
• fog
• gender
• get_hit_sound
• gold
• goto_x
• goto_y
• hitpoints
• id
• image
• image_defensive
• income
• language_name (same as the name key in the unit config)
• level
• max_attacks
• max_experience
• max_hitpoints
• max_moves
• movement
• movement_type
• moves
• race
• resting
• shroud
• side
• type
• unit_description
• unrenamable
• usage
• value
• x
• y
• zoc
• [advancement]
• [/advancement]
• [movement_costs]
• [/movement_costs]
• [defense]
• [/defense]
• [resistance]
• [/resistance]
• [variables]
• [/variables]
• [status]
• [/status]
• [attack]
• [/attack]
• [modifications_description]
• [/modifications_description]
• [modifications]
• [/modifications]

• [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' (the terrain type for a starting location is always 'K' unless it has been changed) and Template:DevFeature 'owner_side' (villages only)
  • side: the side whose starting location is to be stored
  • variable: (default='location'): the name of the variable to store the location 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 Template:DevFeature 'owner_side' (villages only).
  • StandardLocationFilter: a location or location range which specifies the locations to store. You must specify this or no locations will be stored.
  • variable: the name of the variable (array) into which to store the locations
  • terrain: a comma-sperated list of terrain codes. (See TerrainCodesWML for possible values.) If present, locations will only be chosen if the code for the terrain type of that location is listed.
  • radius: if present, any locations which are within radius hexes of the location filter will also be stored
  • [filter]: StandardUnitFilter only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.
• [store_villages]: Stores a series of locations of villages 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 Template:DevFeature 'owner_side'.
  • owner_side: a side number. If present, only villages owned by this side will be choosen. If owner_side=0, store the unowned villages.
  • variable: the name of the variable (array) into which to store the locations
  • terrain: a series of terrain characters. (See TerrainLettersWML for possible values.) If present, villages will only be chosen if the terrain code of the terrain type of that location is listed. You may give a comma separated list of terrains.
• [store_gold]: Stores a side's gold into a variable.
  • side: (default=1) the side for which the gold should be stored
  • variable: (default='gold') the name of the variable to store the gold in
• [store_side]: stores information about a certain side in a variable. The variable will contain the member variables 'name', 'team_name', 'gold' and 'income', 'fog', 'shroud', 'hidden' Template:DevFeature, 'user_team_name', 'colour', 'controller', 'village_gold' and 'recruit'.)
  • side: the side whose information should be stored
  • variable: the name of the variable to store the information in
• [clear_variable]: This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario.
  Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.
  • name: the name of the variable to clear, multiple comma-separated variable names can be given.
• [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 [if]) to see whether a role was assigned. This tag uses a StandardUnitFilter 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.
• Template:DevFeature [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.
• Template:DevFeature [insert_tag]: inserts a variable as WML
  • name: the ["name"] to be given to the tag
  • variable: name of the variable to be inserted
• Template:DevFeature [store_time_of_day]: stores time of day information from the current scenario into a WML variable container.
  • 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.

See Also

• VariablesWML
• DirectActionsWML
• InterfaceActionsWML
• EventWML
• ReferenceWML