ConditionalActionsWML

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

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

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

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

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

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

See Also

• VariablesWML
• InternalActionsWML
• DirectActionsWML
• InterfaceActionsWML
• EventWML
• ReferenceWML