wesnoth/data/core/macros/event-utils.cfg

#textdomain wesnoth
# 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_WML
    # Creates a generic event.  Strictly a syntactic shortcut
    [event]
        name={NAME}
        {ACTION_WML}
    [/event]
#enddef

#define ON_PRESTART ACTION_WML
    # 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_WML}
    [/event]
#enddef

#define ON_START ACTION_WML
    # 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_WML}
    [/event]
#enddef

#define ON_SIDETURN ACTION_WML
    # 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_WML}
    [/event]
#enddef

#define ON_TURN TURN ACTION_WML
    # 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_WML}
    [/event]
#enddef

#define ON_VICTORY ACTION_WML
    # 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_WML}
    [/event]
#enddef

#define ON_DEFEAT ACTION_WML
    # 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_WML}
    [/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_WML
    # 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_WML}
    [/event]
#enddef