EventWML

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

Many WML tags describe how things are; they list properties of individual campaigns, scenarios, unit types, terrains, etc. Events describe how things change while playing. Use events if you want something to happen in given circumstances; for example to display a message when unit gets to a specified location, captures the village, kills enemy unit, or dies.

Each event has three parts:

1. General type of situation when this event happens. For example an event happens after some unit kills another unit.
2. More specific circumstances. For example an event where one unit kills another can be narrowed to killers/victims of specific unit type, or belonging to a specific player.
3. An action which happens under such circumstances.

The [event] tag

Appears in tags: [scenario], [unit] [event].

Attributes:

• name -- type of the event; a basic description of when the event will trigger; see below

An [allow_undo] tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. It is up to the scenario designer to avoid abusing this command by allowing undo on events that shouldn't be undoable. The results of doing this may be strange. This actually does have functionality beyond aesthetics like signs: suppose you have an event that performs some action depending on the condition of an 'if' statement. This event might be executed on every single move, but the body of the 'if' statement entered only in a few cases. Previously this would completely disable undo for the entire scenario, while now it can be made to only disable undo in the cases where the event mutates the scenario.

Primary_unit can be referred to as unit and Secondary_unit can be referred to as second_unit in [message] tags. For example:

[event]
name=die
  [message]
  speaker=second_unit
  message="Hahaha, I finally killed you!"
  [/message]

  [message]
  speaker=unit
  message="It's not over yet! I'll come back to haunt you!"
  [/message]
[/event]

These keys and tags are more complex ways to filter when an event should trigger:

• first_time_only whether the event should be removed from the scenario after it is triggered. Default is 'yes'.
• [filter] the event will only trigger if primary_unit matches this filter.
  • standard unit filter - attributes for [filter] are described in FilterWML
• [filter_second] is like [filter], but for secondary_unit.
  • standard unit filter
• [special_filter] and [special_filter_second] Template:DevFeature can be used to set some additional filtering criteria for primary_unit and secondary_unit that are not generally available in a standard unit filter. Can be used in events attack, attacker_hits, attacker_misses, defender_hits, defender_misses and attack_end.
  • weapon the name of the weapon used.
  • terrain the letter of the terrain the unit is on.

Event lifespan

These are the rules to determine when the event exists; that is, during which interval of the game it can be triggered if the specific circumstances happen.

If event is defined in a [scenario] tag, it becomes active when the scenario is loaded. If event is defined in a [unit] tag, it becomes active when a unit of this type appears in scenario. If event is defined in another [event] tag, it becomes active when the parent event is triggered.

If the event has first_time_only attribute set to "yes", it stops being active after it was first time triggered.

All events stop being active after a scenario is unloaded.

Event types

The following types of events are specified using the name attribute. For example name=prestart.

Event prestart is triggered when a scenario is ready to start, but before anything is shown on the screen at all. You can use this event to:

• set scenario objectives
• initialize variables
• set village ownership
• place items on the map

[event]
  name=prestart

  [objectives]
    side=1
    [objective]
      description= _"Defeat enemies"
      condition=win
    [/objective]
    [objective]
      description= _"Death of your hero"
      condition=lose
    [/objective]
  [/objectives]

  {PLACE_IMAGE galleon.png 50 50}

[/event]

You can also use this event to make an epilogue; that is a scenario which displays a story, and then campaign ends.

[event]
  name=prestart
  [endlevel]
    result=continue_no_save
  [/endlevel]
[/event]

Event start is triggered when the map is shown before the beginning of scenario. You can use this event to:

• recall units
• display starting dialog

[event]
  name=start

  [recall]
    description=My Hero
  [/recall]

  [message]
    description=My Hero
    message= _"We are ready to fight another battle."
  [/message]

[/event]

Event new turn is triggered whenever the last player ends their turn. The value of the WML variable turn_number is set to the number of the turn that is beginning. You can use this event if you want something to happen when the conditions are met in the beginning of the turn. You probably want to set first_time_only=no.

[event]
  name=new turn
  first_time_only=no

  [command]
    [if]
      [have_unit]
        x=20-30
        y=20-30
        side=2
      [/have_unit]
      [then]
      [/then]
      [else]
        [message]
          description=My Hero
          message= _"The area has been cleared"
        [/message]
        [endlevel]
          result=victory
        [/endlevel]
      [/else]
    [/if]
  [/command]

[/event]

Event side turn is triggered when any player ends their turn. When a player ends their turn, before any events of this type trigger, the value of the WML variable side_number is set to the number of the side of the player about to take their turn.

Event turn X is triggered at the start of turn X. X cannot be 1.

[event]
  name=turn 6

  # bring reinforcements
  [unit]
    type=Orcish Slayer
    description=Nafga
    side=2
    x=20
    y=20
  [/unit]

[/event]

Event time over is triggered on turn turns. (turns is specified in [scenario]) This event is typically used to display a dialog that player has lost because the time ran out.

[event]
  name=time over
  [message]
    description=My Hero
    message= _"It is too late! We are doomed!"
  [/message]
[/event]

However, time running out does not have to be fatal. If a scenario condition says something like "survive X turns", it can be a victory condition.

[event]
  name=time over
  [message]
    description=My Hero
    message= _"We have survived!"
  [/message]
  [endlevel]
    result=victory	
  [/endlevel]
[/event]

Event ai turn is triggered just before the AI is invoked for a player. This is called after side turn, so if you move a unit here, its movement will not be reset .

Event enemies defeated is triggered when all units with canrecruit=1 (i.e. all leaders) not allied with side 1 are killed.

Event victory is triggered by any tag of the form [endlevel] result=victory [/endlevel] in this scenario. The actions in the victory event wil happen before all actions in those tag. It helps debugging if the victory event allows you to safely advance to any of the possible next maps after using the ":n" command. Scenarios where key units are picked up before the victory, or where some action chosen earlier determines which map to advance to, make it hard to quickly test scenarios in a campaign. (See also [endlevel], DirectActionsWML)

Event defeat in this scenario, any tag of the form [endlevel] result=defeat [/endlevel] will be automatically preceded by all actions in this tag. (See also [endlevel], DirectActionsWML)

Event types related to units

Events with the following trigger types can be filtered on (see FilterWML). Whenever one of these events is triggered, the position of primary_unit is stored in the variables 'x1' and 'y1', and the position of secondary_unit is stored in 'x2' and 'y2'.

• moveto triggers after primary_unit moves. Usually the location of primary_unit is also filtered on; remember that this is the location that primary_unit lands on, not the location it started on or any location it travels on.
• sighted this event triggers when primary_unit moves to a location where secondary_unit is in primary_unit's sight range.
• attack this event triggers when primary_unit attacks secondary_unit.
• attacker_hits Template:DevFeature this event triggers when the attacker (primary_unit) hits the defender (secondary_unit).
• attacker_misses Template:DevFeature same as attacker_hits, but is triggered when the attacker misses.
• defender_hits Template:DevFeature this event triggers when the attacker (primary_unit) is hit in retaliation by the defender (secondary_unit).
• defender_misses Template:DevFeature same as defender_hits, but is triggered when the defender misses.
• attack_end Template:DevFeature is similar to attack, but is instead triggered after the fight, not before. Note that if either unit is killed during the fight, this event triggers before any die events.
• stone this event triggers when primary_unit is hit by an attack with the 'stones' ability (See stones, AbilitiesWML) by secondary_unit (secondary_unit is the unit with the 'stones' ability.)
• die this event triggers when primary_unit is killed by secondary_unit.
• capture this event triggers when primary_unit captures a village. The village may have been previously neutral, or previously owned by another side; merely moving into your own villages does not constitute a capture.
• recruit this event triggers when primary_unit is recruited or recalled. (That is, when a unit is recruited or recalled, it will trigger this event and this event's filter will filter that unit.)
• advance Template:DevFeature this event triggers just before primary_unit is going to advance to another unit.
• post_advance Template:DevFeature this event triggers just after primary_unit has advanced to another unit.
• select Template:DevFeature triggers when a unit is selected. Mainly useful for the tutorial.

Actions triggered by [event]

After the trigger conditions have been met, all action tags within the [event] tag are executed in the order they are written in.

There are 3 main types of actions:

• direct actions (DirectActionsWML) which have a direct effect on gameplay
• display actions (InterfaceActionsWML) which show something to the user
• internal actions (InternalActionsWML) which are used by WML internally

Several actions use standard filters to find out which units to execute the command on. These are denoted by the phrases "standard unit filter" and "standard location filter".

Nested events

There is 1 special type of action: event creation. By placing an [event] tag inside another [event] tag, the nested event is created when the outer event executes. For example, you could create a portal that opens on turn 10. The outer event executes on turn 10, creating the nested moveto event, which executes when a player steps on a certain spot. An equivalent way of doing this would be to a single moveto event with an if statement to check for turn number, but using nested [event] tags is a simple and elegant way to accomplish more complex tasks without resorting to excessive if statements.

See Also

• DirectActionsWML
• InternalActionsWML
• InterfaceActionsWML
• FilterWML
• ReferenceWML