#textdomain wesnoth-After_the_Storm
#
# Macros controlling the segmented scenario mechanism employed
# throughout AtS E3.
#
# The SEGMENTED_SCENARIO macro is one of the cornerstones of this mechanism.
# It is expected to be substituted early in the scenario file, before any
# custom events. Use ADD_SEGMENT to add configurations for each floor.
#
# Scenarios using this mechanisms should provide no initial map data, and
# they should also take care of placing any necessary leaders on the map
# by hand (see below for information about custom events).
#
# The ON_FLOOR macro provides a convenient way to switch floors including
# a minimal amount of code each time. You *must* use this macro in your own
# prestart event to update the gamestate according to your desired initial
# floor.
#
# Events that can only take place when on a given floor can be defined with
# the auxiliary ON_FLOOR macro, which sets or adds a [filter_condition]
# requirement so the event only triggers on that floor.
#
# It is possible to hook into the floors mechanism via specific custom
# event handlers, that will be invoked as appropriate when entering or
# leaving floors, according to any first_time_only limitations for those
# handlers.
#
# The custom events emitted are:
#
#   * "enter floor $n": Takes place right after entering the floor $n
#     (after the floor switch code is executed and "setup floor $n"
#     emitted). If $n is not provided, the handler will run for *any*
#     floor before any floor-specific handlers. At this point, the
#     $floor_config.current variable reflects the *new* floor number.
#
#   * "leave floor $n": Takes place right before leaving the floor $n
#     (before the floor switch code is executed and "setup floor $n"
#     emitted). If $n is not provided, the handler will run for *any*
#     floor before any floor-specific handlers. At this point, the
#     $floor_config.current variable reflects the *old* floor number.
#
#   * "setup floor $n": Takes place during the configuration of the
#     given floor $n, after most of the floor switch code is executed.
#     If $n is not provided, the handler will run for *any*  floor
#     before any floor-specific handlers. At this point, the
#     $floor_config.current variable reflects the *new* floor number.
#
# Generally, only the $floor_config.current variable should be accessed
# by your own scenario code, and it should be treated as a *constant*.
#
# During victory events, $floor_config (and thus $floor_config.current)
# ceases to exist unless you use the PRESERVE_FLOOR_CONFIGURATION_ON_VICTORY
# macro before.
#
# When switching floors, all items and units previously on-map (except
# side 1 units) are destroyed without emitting events for them. You might
# want to use the "leave floor" events to take care of tracking any
# units that might remain on-map when this happens. Shroud, fog, and terrain
# changes aren't tracked or handled by this implementation either.
#

##
# Accompanies the definition of an event that's only fired when the player
# is on a specific floor. This should go _after_ or instead of any other
# [filter_condition] nodes for the event definition.
#
# Arguments:
#
#   _NUM                   The required floor number.
#
##
#define ON_FLOOR _NUM
    [+filter_condition]
        {VARIABLE_NUMERICAL_EQUALS floor_number {_NUM} }
    [/filter_condition]
#enddef

##
# This is the main macro including the code blocks configuring the scenario
# floors and such. It should go near the top of the scenario. You should not
# specify your own initial map data.
##
#define SEGMENTED_SCENARIO
    {NO_MAP_DATA}

    {FLOOR_VARIABLES_CONFIGURATION}

    {FLOOR_CONTROLLER}
#enddef

##
# Defines a new floor. Floors are automatically numbered
# in a sequence as they are added, starting from 1. At least
# one floor is needed for the scenario to work properly, and
# there must be a prestart event using the SWITCH_FLOOR macro
# to select the initial floor as well.
#
# Arguments:
#
#   _MAP_DATA              The terrain map data.
#
#   _SCHEDULE_TIME_WML     The ToD schedule ([time] nodes) for
#                           this floor. If empty, the ToD detected
#                           on prestart for the first turn will be
#                           used instead.
#
#   _PLAYLIST_MUSIC_WML    The playlist WML ([music] nodes) for
#                           this floor. If empty, music is left
#                           unchanged each time the player enters
#                           the floor.
#
##
#define ADD_SEGMENT _MAP_DATA _SCHEDULE_TIME_WML _PLAYLIST_MUSIC_WML
    [event]
        name=prestart

        [set_variables]
            name=floor_config.floor
            mode=append
            [value]
                map_data={_MAP_DATA}
                [schedule]
                    {_SCHEDULE_TIME_WML}
                [/schedule]
                [music_playlist]
                    {_PLAYLIST_MUSIC_WML}
                [/music_playlist]
            [/value]
        [/set_variables]
    [/event]
#enddef

##
# Disables the automatic destruction of the $floor_config container
# on victory, making the regular victory event (or subsequent scenarios)
# responsible for its cleanup.
#
# This is provided merely as a convenience to retrieve $floor_config.current
# during victory. Its use is not recommended.
##
#define PRESERVE_FLOOR_CONFIGURATION_ON_VICTORY
    [event]
        remove=yes
        id=floor_controller_victory_cleanup
    [/event]
#enddef

##
# This is the trigger used for switching between floors.
#
# Arguments:
#
#   _NUM                   The new floor number.
#
##
#define SWITCH_FLOOR _NUM
    {VARIABLE new_floor_number {_NUM} }

    [fire_event]
        name="enter floor"
    [/fire_event]
#enddef

# kate: indent-mode normal; encoding utf-8; space-indent on;