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

Internal actions are actions that WML uses internally that do not directly affect gameplay, for example storing a variable.

The internal actions [if], [while], and [event] describe when/whether sets of actions should be executed.

[if]

Executes different sets of actions based on whether the conditions described in the condition tags are true or not.

Condition tags:

• [have_unit] a unit passing this filter with >0 HP exists
  • standard unit filter

• [have_location] Template:DevFeature a location passing this filter exists
  • standard location filter

• [and] If an [and] is present, all must evaluate to true in order for the [if] to evaluate true. Useful as a bracket for complex conditions, but not strictly necessary.
  • condition tags as in [if] - if these evaluate to true, [and] evaluates to true.

• [or] If an [or] is present, one must evaluate to true in order for the [if] to evaluate true. (Example)
  • condition tags as in [if] - if these evaluate to true, [or] evaluates to true.

• [not] If a [not] is present, none must evaluate to true in order for the [if] to evaluate true.
  • condition tags as in [if] - if these evaluate to true, [not] evaluates to false.

• Template:DevFeature [and],[or],[not] - the behavior is changing in the development version, where all top-level filters will support in-order conditional handling of and, or, and not. One important thing to remember with the new syntax is, if you have multiple [or]s, you no longer should wrap your first conditional statement into an [or] block.

• [variable] tests something about the value of a WML variable (see VariablesWML)
  • name the name of the variable to test the value of
    Only one of the following keys should be used for comparing the value of the variable to another value:
  • equals $name is equal (string wise) to this
  • not_equals $name is not equal to this
  • greater_than $name is numerically greater than this
  • less_than $name is less than this
  • greater_than_equal_to $name is not less than this
  • less_than_equal_to $name is not greater than this
  • numerical_not_equals $name is greater than or less than this
  • numerical_equals $name is not greater than or less than this
  • boolean_equals Template:DevFeature $name has the same boolean value (e.g. off, false, 0, no)
  • contains Template:DevFeature $name contains this string

After condition tags:

• [then] contains a set of action tags which should be executed if all conditions are true, or all conditions in any single [or] are true
• [else] contains a set of action tags which should be executed if any condition is false, and all [or] tags are false

[while]

executes commands if all conditions are true. Continues to execute them until a condition is not true.

Executes a maximum of 1024 iterations per invocation. Condition tags are the same as for [if]

After condition tags:

• [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. The macros 'FOREACH' and 'NEXT' (UtilWML) can be used to iterate over an array; i.e. run a set of actions once per element of the array.

{Foreach}

If you wish to use a "for-each" iteration format (useful for example when you want to do an iteration for each row in a table) you can use the FOREACH prededined macro.

[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

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)
  • name the name of the variable to manipulate
  • value set the variable to the given value (can be numeric or string). This only interprets dollars signs if it is the very first character, and then the entire value must be a simple variable name. (in 1.3.2, has the same effect as format. Use literal for no substitution)
  • literal set the variable to the given value (can be numeric or string). This does not interpret any dollars signs. Template:DevFeature
  • format set the variable to the given value. Interprets the dollar sign to a higher degree than most actions. (see VariablesWML)
  • 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.
  • divide Template:DevFeature divide the variable by the given number. The result is an integer.
  • modulo Template:DevFeature returns the remainder of an integer division. Both variables need to be an integer, the result is also an integer. eg 5 % 2 = 1.
  • 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 Template:DevFeature 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 Template:DevFeature 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.

• [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] (standard unit filter) 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.

• advanceto
• 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
• team_name
• 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', and 'terrain' (the terrain type for a starting location is always 'K' unless it has been changed)
  • 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).
  • standard location filter- 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 series of terrain characters. (See TerrainLettersWML for possible values.) If present, locations will only be chosen if the letter of the terrain type of that location is listed. (SVN terrain only) Here the list will be a comma separated list of terrains.
  • radius if present, any locations which are within radius hexes of the location filter will also be stored
  • [filter] (standard unit filter) 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] Template:DevFeature 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).
  • 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 letter of the terrain type of that location is listed. (SVN terrain only) Here the list will be a comma separated list of terrains.
• [store_gold] stores the gold for a certain side in a variable. (Template:DevFeature : this tag is no longer available)
  • 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'. (Template:DevFeature : in SVN trunk, after 1.3.9 release, this tag's resultant variable was extended to contain the members 'fog', 'shroud', '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.
• [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 Standard Unit 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 Standard Unit Filter 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.

See Also

• VariablesWML
• DirectActionsWML
• InterfaceActionsWML
• EventWML
• ReferenceWML