ConditionalActionsWML

From The Battle for Wesnoth Wiki
Revision as of 20:27, 10 December 2016 by Celtic Minstrel (talk | contribs) ([foreach]: Update for attribute renames done at some point)

[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, credits_group, criteria;

D:

damage, 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, found_item, for, foreach, 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, 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, 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, Conditional Actions WML is used to describe container actions that create branching and flow control for WML. The conditional actions act as gatekeepers, encapsulating other actions with conditions which must be met before an action can take place. These conditional actions also contain the actions which will take place if those conditions are met and, in some cases, what actions will take place if they are not met.

Conditional Actions

These actions describe actions that should be executed only if certain conditions are met.

[if]

Executes actions only if the contained conditions are met.

  • Condition Tags: Conditions which must be met for the actions in the [then] tag to be executed.
  • [then]: Contains actions which should be executed if all conditions evaluate as true or if any single [or] tag evaluates as true.
  • [elseif]: (Version 1.13.0 and later only) in case that the conditions inside [if] aren't met, these tags will be evalutated one by one. If the specified conditions are met, the contained [then] tags will be executed, and the cycle will end.
    • [then]: it behaves exactly like the [then] tag inside [if].
  • [else]: Contains actions which should be executed if any condition evaluates as false and all of the [or] tags evaluate as false.


Attention: There are tags named [if] and [else] inside [animation] (see AnimationWML), which have a different syntax.

Example usage:

 [if]
    [variable]
       name=we.gold
       greater_than=$they.gold
    [/variable]
    [then]
       [message]
          message=This should be easy!
       [/message]
    [/then]
    [else]
       [message]
          message=This will not be easy!
       [/message]
    [/else]
 [/if]

[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. Boolean variable values are not accepted and cause lua errors currently.

  • 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. This can be a comma separated list of values.
    • Action WML: Action WML 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 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 65536 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.

'REPEAT' Macro

This macro simplifies the use of a [while] tag to execute the same actions repeatedly for a specified number of times. To use it, use the REPEAT macro.

[for]

(Version 1.13.2 and later only)

Loops over an integer range. As of 1.13.2, this is used instead of [while] to implement the {FOREACH} macro. Note that, if iterating over an array to delete several elements, it is best to use reverse=yes to avoid accidentally skipping some elements.

  • start, end, step: Specify the range to iterate over. This range is inclusive, meaning that both start and end are included in the range (though if step is not 1 or -1, then end might be excluded if it's not reachable from start by incrementing by step). If step is omitted, it defaults to 1 or -1, depending which of start and end is greater. If start is omitted, it defaults to 0. If end is omitted, it defaults to start.
  • array, reverse: Specify an array to iterate over. This is a shortcut for specifying start=0 and end=$($array_name.length-1), or, if reverse=yes, for specifying start=$($array_name.length-1) and end=0. If used, the attributes start, end, and step are ignored.
  • variable: A name for the loop variable. Defaults to i.
  • [do]: The actions to execute on each iteration.

[foreach]

(Version 1.13.2 and later only)

Loops over an array variable. This is not used to implement the {FOREACH} macro because adding or removing elements while looping is not possible (and will usually raise an error).

  • array: The array variable to loop over.
  • variable: The name of a variable which refers to the current item. Defaults to this_item. Any changes made to this variable will persist in the array after the loop has completed.
  • index_var: The name of a variable which refers to the index of the current item. Defaults to i. Note that this is just for information purposes and should not be used to access the array from within the loop (any such changes made will not persist).
  • readonly: If set to yes, this prevents the array from being modified in any way during the loop. (It defaults to no.) That means that changes made through the item_var will not persist. Changes made through the index_var will also not persist (as normal). In effect, the array is reverted to its original state once the loop exits.
  • [do]: The actions to execute on each iteration.

[repeat]

(Version 1.13.2 and later only)

Repeats some actions a fixed number of times. This is a completely stateless loop - there's no way to know which iteration of the loop you're on. (If you need this, use [for] instead.)

  • times: The number of times to repeat the actions.
  • [do]: The actions to repeat.

[command]

This tag is more of an Unconditional Action: when it is encountered, the actions in its content are simply executed once. In practice, this tag serves little purpose. However, it may be used to arrange actions together in logical groups, for example, with actions that are stored in an array and later inserted. (It is also used inside of [set_menu_item] and [option] of InterfaceActionsWML.)

Condition Tags

True 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.

[true]
Represents a condition that always yields true. Takes no arguments.
[false]
Represents a condition that always yields false. Takes no arguments.
[have_unit]
A unit with greater than zero hit points matching this filter exists.
  • StandardUnitFilter *: Selection criteria. Do not use a [filter] tag.
  • 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".
  • search_recall_list: (Optional) If 'yes', search through recall list too. (Default is 'no')
[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 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. *
      * Using equals is faster. The point of numerical_equals and boolean_equals is not performance, it's representation. For instance, "1" and "1.0" are not equal as strings but they are equal as numbers; and "yes" and "true" are not equal as strings but they are equal as booleans. (This also explains why equals is faster: it is a straightforward comparison that doesn't try to understand what you have written.)
    • 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. *
[found_item]
(Version 1.13.2 and later only) Test if an item (ie, a modification given by [object]) has been found yet. Note: This will only detect objects added via ActionWML in an event. It will not detect objects added in [modifications] when a unit is created, nor objects added via [modify_unit] or the Lua wesnoth.add_modification function.
* id: The ID of the item to test. It must exactly match an [object] that has been taken for the test to pass.

Boolean Values

When values are evaluated as boolean values they are checked to see if they are false or true.

  • These values are evaluated as true: "yes" and "true"
  • These values are evaluated as false: "no", "false" and ""(uninitialized)
    • However, in contexts where true is defined as the default value, an uninitialized value would be considered true.

Warning: Do not use "off", "on", integers, floating-point numbers or anything else than the above as booleans.

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 top-to-bottom 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 other conditions that precede it. This is 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, when false, has no effect, but when true, allows previously failed conditions to be ignored.
  • Condition Tags: If these evaluate to true, the [or] tag evaluates to true.
[not]
Similar to [and], but its contents must be false. Thus it reverses the evaluation of its contents. Since a normal condition tag without contents is always considered true, an empty [not] is always considered false.
  • Condition Tags: If these evaluate to true, the [not] tag evaluates to false. If these evaluate to false, the [not] tag evaluates to true.


When multiple meta-conditions are encountered one after another in a containing tag, the evaluation order is as follows:

  1. the immediate contents of the containing tag are evaluated first to determine if there is a successful match known as a "true" condition
  2. this true or false result is combined with the top meta-condition to produce another true or false result
  3. this result is combined with the next meta-condition, and so on. However, if the engine recognizes that no remaining meta-conditions might reverse the result, it will cleverly skip them.
  4. if the final result is a successful match, then the action will take place.

For more details on use of meta-conditions, see these examples.

See Also