DirectActionsWML

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

Direct actions

Direct actions are actions that have a direct effect on gameplay.

The following tags are actions:

• [endlevel] ends the scenario.
  • result before the scenario is over, all events with name=result are triggered. The message result_message with the heading result_heading (see LanguageWML) are displayed. If result=victory, the player progresses to the next level; if result=defeat, the game returns to the main menu. These last two are rarely used: result=continue behaves identically to result=victory except the player's gold is not reduced to 80%, and it does not bring up a "Victory" message or the gold changing message (since it doesn't change); result=continue_no_save works similarly, except the player is not asked whether to save the game, and is taken directly to the next scenario without any messages. Unless result=defeat, the following keys can also be used:
  • bonus whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes.
  • next_scenario (default specified in [scenario] tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in next_scenario.
  • When the result is "victory" the following keys can be used:Template:DevFeature
    • carryover_percentage by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
    • carryover_add if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.
• [unit] places a unit on the map. For syntax see SingleUnitWML.
• [recall] recalls a unit. The unit is recalled free of charge, and is placed near the leader.
  • standard unit filter the first matching unit will be recalled. If no units match this tag is ignored.
  • x,y the unit is placed here instead of next to the leader.
  • show if not "no", display the unit being recalled.
• [teleport] teleports a unit on map.
  • [filter] (standard unit filter) all units matching the filter will be teleported.
  • x,y the position to teleport to.
• [terrain_mask] changes the terrain on the map. See TerrainMaskWML.
• [terrain] changes the terrain on the map.
  • letter the character of the terrain to use. See TerrainLettersWML to see what letter a type of terrain uses.
  • standard location filter- the area to change the terrain of.
• [gold] give one side gold.
  • amount the amount of gold to give.
  • side (default=1) the number of the side to give the gold to.
• [unstore_unit] creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also [store_unit], [while] and [clear_variable] in InternalActionsWML. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
  • variable the name of the variable.
  • find_vacant whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.
  • text (translatable) floating text to display above the unit, such as a damage amount
  • red, green, blue (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
  • advance if the XP has been modified then there will be tried to advance the unit, default true. Template:DevFeature
• [allow_recruit] allows a side to recruit units it couldn't previously recruit.
  • type the types of units that the side can now recruit.
  • side (default=1) the number of the side that is being allowed to recruit the units.
• [disallow_recruit] prevents a side from recruiting units it could previously recruit.
  • type the types of units that the side can no longer recruit.
  • side (default=1) the number of the side that may no longer recruit the units.
• [set_recruit] sets the units a side can recruit.
  • recruit the types of units that the side can now recruit.
  • side (default=1) the number of the side that is having its recruitment set.
• [modify_side] modifies some details of a given side in the middle of a scenario. The following listed properties are the only properties that [modify_side] can affect!'
  • side (default=1) the number of the side that is to be changed.
  • income the income given at the begining of each turn.
  • team_name the team in which the side plays the scenario.
  • user_team_name a translatable string representing the team's description. This has no effect on alliances. Defaults to team_name.
  • gold the amount of gold the side owns.
  • (Template:DevFeature) The following keys are only recognized in the latest development versions:
    • village_gold the income setting per village for the side.
    • controller the identifier string of the side's controller. Uses the same syntax of the controller key in the [side] tag.
    • fog a boolean string (yes/no) describing the status of Fog for the side.
    • shroud a boolean string describing the status of Shroud for the side.
• [modify_turns] modifies the turn limit in the middle of a scenario.
  • value the new turn limit.
  • add if used instead of value, specifies the number of turns to add to the current limit (can be negative).
• [capture_village] changes the ownership of a village.
  • side the side that takes control of the village. If not given, the village will become neutral.
  • x, y the location of the village.
• [kill] Removes all units (including units in a recall list) that match the filter from the game.
  • standard unit filter
  • animate if 'yes', displays the unit dying (fading away).
  • fire_event if 'yes', triggers any appropriate 'die' events (See EventWML). Note that any 'die' events triggered by this are executed immediately, interrupting the current event and thus causing the x1, y1, x2, and y2 variables to be reset for that 'die' event, which in turn causes those variables to be invalid for the remainder of this event.
• [unstone] Unstones all units that match the filter.
  • [filter] (standard unit filter) all units matching the filter will be unstoned. If no unit matches the filter, then nothing happens (probably). If absent, all units on the map are unstoned.
• [object] gives some unit an object and removes all items on the tile the unit is on.
  • id when the object is picked up, a flag is set for id. The object cannot be picked up if a flag for id has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per level. In a campaign objects with the same id can be assigned once per level.
  • [effect] one or more effect elements may be listed. See EffectWML for a description of [effect].
  • duration if 'level', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).
  • [filter] (standard unit filter) the first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
  • [then] a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a [removeitem] tag, but you could probably put any tags that otherwise work in a [then] tag.
  • silent whether or not messages should be suppressed. Default is "no".
  • image the displayed image of the object.
  • name (translatable) displayed as a caption of the image.
  • description (translatable) displayed as a message of the image.
  • cannot_use_message (translatable) displayed instead of description if no unit passes the filter test.
  • If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
  • The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.
• [remove_shroud] removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
  • side (default=1) the side for which to remove shroud.
  • standard location filter- the range of tiles for which shroud should be removed.
• [place_shroud] places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
  • side (default=1) the side for which to place shroud.
  • standard location filter- the range of tiles on which shroud should be placed.
• [allow_undo] allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move is undone. It is up to the scenario designer to avoid abusing this command. You do not use [allow_undo] before or after usage of other direct actions (DirectActionsWML). If you modify a variable (InternalActionsWML), then you set it back before using [allow_undo].
  • The [allow_undo] command has no effect within a [then] or [else] or [do] command. Thus, it is impossible to check a conditional using [if] or [while], then only [allow_undo] sometimes. You have a choice: the moveto event may either allow undo whenever the event fires, or it may never allow undo; you may use filters to control whether the event fires. (Template:DevFeatureThis bug should be fixed in 1.3.4)
  • Technically, if [allow_undo] is inside an [event] with first_time_only=yes (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the move the first time.
  • Do not use [allow_undo] in multiplayer scenarios, because it causes out-of-sync errors. Someone should report this to the bug-tracker with example code so that it can be fixed.

See Also

• InternalActionsWML
• InterfaceActionsWML
• EventWML
• ReferenceWML