# This file contains shortcuts for common WML events (such as prestart, side
# turn, and such), which can be used to write events faster and in less space.
#
# It is recommended that you only use these if you're confident you could write
# the expanded form as well; these are mostly intended as shortcuts for
# experienced WML authors.

# These don't depend on any other macros.  Please don't change this.
# ! in comments is used in generating HTML documentation, ignore it otherwise.


#define ON_EVENT NAME ACTION
# Creates a generic event.  Strictly a syntactic shortcut
    [event]
        name={NAME}
        {ACTION}
    [/event]
#enddef

#define ON_PRESTART ACTION
# Creates an event that triggers when the scenario starts but before the user
# gets any visible output.  Strictly a syntactic shortcut.
#
# For example, you can make side 2 start the scenario with ownership of the
# village at 13,15:
#
#! {ON_PRESTART (
#!   [capture_village]
#!       side=2
#!       x,y=13,15
#!   [/capture_village]
#! )}
    [event]
        name=prestart
        {ACTION}
    [/event]
#enddef



#define ON_START ACTION
# Creates an event that triggers when the scenario starts, after the map is
# displayed but before the player can act.  Strictly a syntactic shortcut.
#
# For example you could display some dialogue when the scenario starts:
#
#! {ON_START (
#!   [message]
#!       speaker=Konrad
#!       message= _ "Hey, I can see some enemies up ahead!"
#!   [/message]
#!
#!   [message]
#!       speaker=Delfador
#!       message= _ "Yes, so it would seem. Charge!"
#!   [/message]
#! )}
    [event]
        name=start
        {ACTION}
    [/event]
#enddef

# {ON_NEXT_TURN (
# Creates an event that triggers at the end of every turn.
#
# For example, you could give a player some gold at the end every turn:
#!   [gold]
#!       amount=35
#!       side=1
#!   [/gold]
#! )}

#define ON_NEXT_TURN ACTION
    [event]
        name=new turn
        first_time_only=no
        {ACTION}
    [/event]
#enddef

#define ON_NEXT_TURN_ONCE ACTION
# Creates an event that triggers at the end of the current turn.
# For example you could give a player some gold before his/hers next turn.:
#! {ON_NEXT_TURN (
#!   [gold]
#!       amount=100
#!       side=1
#!   [/gold]
#! )}
    [event]
        name=new turn
        first_time_only=yes
        {ACTION}
    [/event]
#enddef

#define ON_SIDETURN ACTION
# Creates an event that triggers at the start of every players turn
# For example, you could set each players gold to a fixed amount every turn.
#! {ON_SIDETURN (
#!   [modify_side]
#!       side=3
#!       gold=0
#!   [/modify_side]
#! )}
    [event]
        name=side turn
        first_time_only=no
        {ACTION}
    [/event]
#enddef


#define ON_TURN TURN ACTION
# Creates an event that triggers at the start of turn TURN
# For example you can create a Wose belonging to player 1 at turn 3:
# Strictly a syntactic shortcut.
#! {ON_TURN 3 (
#!   [unit]
#!       side=1
#!       type=wose
#!       x,y=12,4
#!   [/unit]
#! )}
    [event]
        name=turn {TURN}
        {ACTION}
    [/event]
#enddef

#define ON_LAST_TURN ACTION
# Creates an event that triggers when the last turn ends.
# Strictly a syntactic shortcut.
#
# For example you could display a message saying they suck:
#! {ON_LAST_TURN (
#!   [message]
#!       speaker=narrator
#!       message="They suck!"
#!   [/message]
#! )}
    [event]
        name=time over
        {ACTION}
    [/event]
#enddef

#define ON_VICTORY ACTION
# Creates an event that triggers when a player wins the game, before
# the game ends.  Strictly a syntactic shortcut.
#
# For example you could congratulate the player:
#! {ON_VICTORY (
#!   [message]
#!       speaker=narrator
#!       message="Congratulations!"
#!   [/message]
#! )}
    [event]
        name=victory
        {ACTION}
    [/event]
#enddef

#define ON_DEFEAT ACTION
# Creates an event that triggers when a player wins the game, before
# the game ends.  Strictly a syntactic shortcut.
#
# For example you could suggest an easier difficulty
# the player:
#! {ON_DEFEAT (
#!   [message]
#!   speaker=narrator
#!   message="Aww.. you lost. Try again with 800g and +40g income?"
#!   [/message]
#! )}
    [event]
        name=defeat
        {ACTION}
    [/event]
#enddef

#define ON_TILE X Y FILTER ACTION
# Creates an event that triggers anytime a unit steps on a given tile.
# The filter can be used to only affect special units, or units of a
# given player.  
#
# For example, we could make a tree where the first player's leader can 
# read a note, but nobody else:
#! {ON_TILE 5 7 (
#!   side=1
#!   canrecruit=1
#! ) (
#!   [message]
#!   speaker=narrator
#!   message="This is a note."
#!   [/message]
#! )}
    [event]
        name=moveto
        first_time_only=no
        [filter]
        x={X}
        y={Y}
        {FILTER}
        [/filter]
        {ACTION}
    [/event]
#enddef

#define ALLOW_UNDO
# Allows the player to undo the effects of a moveto event.
# Strictly a syntactic shortcut.
#
# For example, let's allow undoing reading a note:
#! {ON_TILE 5 7 () (
#! 	[message]
#! 		speaker=narrator
#! 		message="This is a note."
#! 	[/message]
#! 	{ALLOW_UNDO}
#! )}
	[allow_undo]
	[/allow_undo]
#enddef

#define ON_TILE_ONCE X Y FILTER ACTION
# Creates an event that triggers the first time a unit steps on a
# given tile.  The filter can be used to only affect special units, or
# units of a given player.  

For example we could make a text-message
# that is only readable once:
#! {ON_TILE_ONCE 5 7 () (
#!   [message]
#!       speaker=narrator
#!       message="This is a note."
#!   [/message]
#! )}
    [event]
        name=moveto
        first_time_only=yes
        [filter]
        x={X}
        y={Y}
        {FILTER}
        [/filter]
        {ACTION}
    [/event]
#enddef

#define ON_DEATH FILTER ACTION
# Creates an event that triggers anytime a unit matching FILTER dies.
# Strictly a syntactic shortcut.
#
# For example we can make all units scream in pain upon death:
#! {ON_DEATH () (
#!   [message]
#!       speaker=unit
#!       message="AAaaaaAAaaAAaarrrghh!!!"
#!   [/message]
#! )}
    [event]
        name=die
        first_time_only=no
        [filter]
        {FILTER}
        [/filter]
        {ACTION}
    [/event]
#enddef

#define ON_DEATH_ONCE FILTER ACTION
# Creates an event that triggers the first time a unit matching FILTER
# dies. Strictly a syntactic shortcut.
#
# For example we can make only player 3s leader units scream in
# pain upon death:
#! {ON_DEATH_ONCE (
#!   side=3
#!   canrecruit=1
#! ) (
#!   [message]
#!       speaker=unit
#!       message="AAaaaaAAaaAAaarrrghh!!!"
#!   [/message]
#! )}
    [event]
        name=die
        first_time_only=yes
        [filter]
        {FILTER}
        [/filter]
        {ACTION}
    [/event]
#enddef

#define ON_ADVANCEMENT FILTER ACTION
# Creates an event that triggers before any unit matching FILTER
# advances to a new class.  Strictly a syntactic shortcut.
#
# For example we could make it smile:
#! {ON_ADVANCEMENT () (
#!   [message]
#!       speaker=unit
#!       message=":D"
#!   [/message]
#! )}
    [event]
        name=advance
        first_time_only=no
        [filter]
        {FILTER}
        [/filter]
        {ACTION}
    [/event]
#enddef

#define ON_POSTADVANCEMENT FILTER ACTION
# Creates an event that triggers after any unit matching FILTER
# advanced to a new class.  Strictly a syntactic shortcut.
#
# For example we could make it claim to be
# the strongest one alive:
#! {ON_POSTADVANCEMENT () (
#!   [message]
#!       speaker=unit
#!       message="I'm the strongest one alive!"
#!   [/message]
#! )}
    [event]
        name=post_advance
        first_time_only=no
        [filter]
        {FILTER}
        [/filter]
        {ACTION}
    [/event]
#enddef
