ConditionalActionsWML

From The Battle for Wesnoth Wiki
Revision as of 09:47, 5 April 2014 by Elvish Hunter (talk | contribs) (→‎[if]: Added back support for missing [then] tags)

[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, 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.

  • variable: The name of the variable to check. (Version 1.13.0 and later only) This key is required.
  • [case]: (Version 1.13.0 and later only) At least one [case] is required. On 1.11.x / 1.12.x [case] tags are not required.
    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. (Version 1.13.0 and later only) This key is required.
    • 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.

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.

[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]
Template:DevFeature1.11 Represents a condition that always yields true. Takes no arguments.
[false]
Template:DevFeature1.11 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. *

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

Retrieved from "https://wiki.wesnoth.org/index.php?title=ConditionalActionsWML&oldid=54388"