The Battle for Wesnoth Wiki - User contributions [en]

NotSoEasyCoding

2007-07-06T00:03:55Z

Rusty: /* Config Writer */

== Foreword ==
This page shows projects which are considered a good idea by the developers but which have nobody working on them so far. If you think you've got the required skill for a task go on, implement it and you've got a high chance that it'll be accepted. The remaining barrier will only be that it's done well. :-)

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature I'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

== Campaign Server related features ==

=== Reimplement the campaign server in Perl ===
The current campaign server is written in C++ and networking with SDL_net isn't really optimal, neither is multithreading easy to do here. Therefore it was proposed to reimplement it in Perl as this should allow for easier inclusion of new features. There are already Perl Modules to read WML.

I'll soon start to work on this project, but the language of choice will be python instead of perl --[[User:SkeletonCrew|SkeletonCrew]] 21:50, 4 July 2007 (CEST)

=== Integrate WesCamp-i18n into the Campaign Server ===
So far translations of unofficial campaigns, eras or MP scenarios aren't too easy to handle. Authors must put their stuff into the WesCamp SVN repository, fetch translations from there and put those onto the campaign server. The vision for the future would be that the campaign server will automatically commit every change into the SVN repository and pull translations regulary. This would allow for new translations to appear in the download without further interaction of the authors.
Allefant already wrote some Python scripts to handle the SVN commit / fetch part which could be used as external helpers.

I started to work on this project --[[User:SkeletonCrew|SkeletonCrew]] 21:49, 4 July 2007 (CEST)
== Game Engine ==
=== Showing "Advantage" In-Game/End-Game ===

As described here: [http://www.wesnoth.org/forum/viewtopic.php?p=169416]

=== Multiplayer and RNG Cheating ===

As described here: [http://www.wesnoth.org/forum/viewtopic.php?t=9500]

== Data Structures ==
=== Config Writer ===

The speed of saving Wesnoth games is dominated by the time to marshall all the config structures. This involves deep copying them many times as each subsystem returns its config bundle; far better would be to have a "config_writer" class which is handed to each subsystem which iterates through its structures and does the writing (to file or network) directly to the config_writer instance.

Stop by #wesnoth-dev on freenode irc if you want to help with this, or post in the Coder's Corner.

=== Improvements to Unit Map ===

As described here: [http://www.wesnoth.org/forum/viewtopic.php?p=236063#236063]

ThemeWML

2006-05-28T02:35:05Z

Rusty: Document AUTOSAVES menu magic

{{WML Tags}}
== the toplevel [theme] tag ==

Themes are used both for the wesnoth game and the wesnoth editor.
Themes allow flexible configuration of how everything is laid out on-screen.

The only key in [theme] is ''name''. This is the name of the theme.

The only tag in [theme] is '''[resolution]''', but each theme can have multiple [resolution] tags.
The [resolution] tags are scanned until the first one which is of the same or lower resolution than is currently being used is found, and this is used as our theme.
This allows us to define themes to work differently on different resolutions,
and will allow us to support both high and low resolutions elegantly.

The following keys and tags are recognized for [resolution]:

* ''width//,//height'' dimensions in pixels

All subtags of [resolution] use the following keys:
* ''rect'' defines the rectangle to display on. Parts of a ''rect=a,b,c,d'' clause may be:
** number : absolute positions
** ''='' : same value as the same field in reference rect (alignment with reference)
** +number or -number : for a and b, add this value to reference's c and d respectively (spacing from reference)
; for c and d, add this value to self's a and b (specify by width and height)
** =+number or =-number : add this value to same field in reference rect (eg. consider reference as a container box)
* ''xanchor//,//yanchor'' control the behavior of how this rectangle changes as the resolution changes.
** 'left' its distance from the left side of the screen always remain the same, while changes in the resolution will change its size by the same amount (top for the y axis).
** 'right' its size always remain the same, as well as its distance to the right side of the screen (bottom for the y axis).
** 'fixed' its co-ordinates in that axis remain constant
** 'proportional' its co-ordinates multiplied by the ratio of the resolution being used to the canonical resolution.

== [main_map] ==

defines where the main game display (i.e. all the hexagons and units) is displayed.

== [mini_map] ==

determines where the mini map is displayed

== [panel] ==

displays an image as a panel on-screen.
* ''image'' the image used for the panel

== [label] ==

displays a text label on screen.
* ''prefix'' a string that will be printed before the text in all language
* ''text'' a text string id to be displayed
* ''postfix'' a string that will be printed after the text in all language
* ''icon'' an image that will be displayed instead of the text if it is available
* ''font_size'' the size of font to use for the label

== [menu] ==

* ''title'' the id of the string to write on the button
* ''title_literal'' a string that will be displayed "as is" in all language after the title
* ''image'' the image to use if available
* ''is_context_menu'' if set to true this menu will not be placed, but displayed on a right click
* ''items'' comma separated list of actions to put in the menu. if there is only one action, it will be executed
immediately and no menu will be displayed
** 'cycle' move to next movable unit
** 'endunitturn' consume this unit's move and cycle to the next one
** 'leader' senter on the leader
** 'undo' undo last action
** 'redo' redo undone action
** 'zoomin' zoom the map in
** 'zoomout' zoom the map out
** 'zoomdefault' return to default zoom
** 'fullscreen' switch fulscreen mode
** 'accelerated' switch turbo mode
** 'resistance' show resistance table of current unit
** 'terraintable' show terrain table of current unit
** 'describeunit' show unit description
** 'renameunit' change unit name
** 'save' save the game
** 'recruit' recruit a unit
** 'repeatrecruit' repeat last recruitement
** 'recall' recall a unit from previous scenarion
** 'endturn' end current turn
** 'togglegrid' toggle grid display
** 'statustable' show status table
** 'mute' mute all sounds
** 'speak' send message to other players
** 'createunit' debug create a unit on the map
** 'preferences' open preference dialog
** 'objectives' show objective window
** 'unitlist' list units
** 'statistics' show game statistics
** 'quit' quit the game
** 'labelterrain' label current location
** 'clearlabels' clear all labels on map
** 'showenemymoves' show grids reachable by the enemy
** 'bestenemymoves' show grids reachable by the enemy with no zone of control
** 'editnewmap' editor only start a new map
** 'editloadmap' editor only loads an existing map
** 'editsavemap' editor only saves the current map
** 'editsaveas' editor only saves the current map, let you choose a filename
** 'editsetstartpos' editor only set a starting position for a team
** 'editfloodfill' editor only flood the map with a terrain
** 'toggleshroud' toggle the "moving removes shroud" behaviour
** 'updateshroud' removes all possible shroud
** 'AUTOSAVES' expands to a list of all Auto-Save games prior to this one (1.1.3+)

== [status] ==

This tag describes the Status Table.
This tag contains many other tags, which determine where other game statistics, such as the current turn, and a description of selected units go.
For instance, the [time_of_day] tag will determine where the time of day image goes.
Each subtag of [status] can contain the following attributes

** ''font_size'' the size of font to use for the status
** ''rect'' the rectangle as for the main_map attribute
** ''xanchor'' the x-wise anchoring as for the main_map attribute
** ''yanchor'' the y-wise anchoring as for the main_map attribute
** ''prefix'' the string to display before the actual status, this is the string id for internationalisation
** ''prefix_literal'' a string to put after the prefix, but before the label for all languages.
** ''postfix_literal'' a string to put after the status
** ''postfix'' the string to display after the postfix_literal, this is the string id for internationalisation

the following tags are recognized for [status]:
* '''[unit_description]''' the user description of the current unit
* '''[unit_type]''' the type of the current unit
* '''[unit_level]''' the level of the current unit
* '''[unit_traits]''' the traits of the current unit
* '''[unit_status]''' the status of the current unit
* '''[unit_alignment]''' the alignment of the current unit
* '''[unit_abilities]''' the abilities of the current unit
* '''[unit_hp]''' the HP of the current unit
* '''[unit_xp]''' the XP of the current unit
* '''[unit_moves]''' the moves remaining for the current unit
* '''[unit_weapons]''' the attacks of the current unit
* '''[unit_image]''' the icon for the current unit
* '''[unit_profile]'''
* '''[time_of_day]''' the time of day on the current location
* '''[turn]''' the turn number and turn remaining
* '''[gold]''' the gold remaining
* '''[villages]''' the number of villages owned
* '''[num_units]''' the number of units owned
* '''[upkeep]''' the money needed to keep your units every turn
* '''[expenses]''' the money lost each turn when you don't have enough income
* '''[income]''' the income per turn (can be positive)
* '''[terrain]''' the text description of the current terrain
* '''[position]''' the current terrain's position
* '''[side_playing]''' the current playing side
* '''[observers]''' the current observers

== See Also ==

* [[ThemeSystem]]
* [[Using custom themes in campaigns]]
* [[ReferenceWML]]

[[Category: WML Reference]]

AnimationWML

2006-03-25T12:01:34Z

Rusty: r10777: comma-separated sound list

{{WML Tags}}
== Animation and sound ==

Several key/tags of the [unit] and [attack] tags do not affect gameplay,
but are available to control the way units and their attacks
will be animated and heard.

All images assume that units are facing right;
when units are facing left the images will be reversed.
If a unit is attacking north or south then an "orthogonal" image
may be displayed for the unit's missile (see [missile_frame]).
The input file is displayed when the unit is attacking northwards,
and flipped horizontally when the unit attacks southwards.

All times (see ''begin'', ''end'', ''time'')
are measured in milliseconds, or 1000ths of seconds.
Unit movement is automatically animated based on these times;
the attacking unit or missile begins in the center of the hex at the lowest ''begin'' time,
then slides continuously to the center of the defender's hex, which it reaches at time=0.
If the attack is short-range,
the unit will then slide continuously back onto its own hex until the highest ''end'' time.

* '''[frame]''' In WML, animations are made using the '''[frame]''' tag. It describes one frame of an animation. The following keys are recognized for '''[frame]''':
** ''begin'' when to start displaying this frame
** ''end'' when to stop displaying this frame
** ''image'' the image to display during this frame to represent the unit
** ''halo'' comma separated list of halo images to be displayed around the unit. The duration of images can be given with colons after the image name - else these images will be given equal amounts of time, based on the time between ''begin'' and ''end''. It is recommended that you allow for at least 50 time units per image; i.e. ''end'' - ''beginning'' > 50 * number of halos. ''halo'' is generally used only for long-range attack animations (both [frame] and [missile_frame]). Example: <pre>halo = "img1:10,img2:20,img3:10"</pre>
** ''halo_x'',''halo_y'' pixel offset between the center of the ''halo'' images and the center of the unit.
** ''sound'' {{DevFeature}} the sound to play (at the begining) when this frame is displayed: if a comma-separated list, one is chosen randomly.

The following display key/tags are recognized for '''[unit]''':
* ''image'' the unit image displayed on the main map when the unit is resting, and on the status table when the unit is selected. Also the default for all other unit images.
* ''profile'' the image displayed when the unit is talking. See [message], [[InterfaceActionsWML]].
* ''image_moving'' the image displayed while the unit is moving, this is deprecated in 1.1.x, see '''[movement_animation]''' below.
* ''image_long'' the image displayed while the unit is using a long-range (ranged) attack (can be overloaded; see '''[frame]''', '''[attack]''').
* ''image_short'' the image displayed while the unit is using a short-range (melee) attack (can be overloaded; see '''[frame]''', '''[attack]''').
* ''image_leading'',''image_healing'' the images displayed for this unit while using the 'leadership', 'heals', or 'cures' ability, if present. See also [[AbilitiesWML]].
* ''image_halo_healing'' a halo (see above) used together with image_healing
* '''[teleport_anim]''' describes an animation for when this unit teleports.
** '''[frame]''' see '''[frame]''' above. The frames before time 0 are displayed at the original location; the ones after are displayed at the new location.
* ''image_defensive'' default for ''image_defensive_long'' and ''image_defensive_short'' this is deprecated in 1.1.x see '''[defend]'''.
* ''image_defensive_long'' default image when the unit is defending against a long-range attack. This is deprecated in 1.1.x see '''[defend]'''.
* ''image_defensive_short'' default image when the unit is defending against a short-range attack. This is depecated in 1.1.x see '''[defend]'''.
* '''[defend]''' describes an animation for when this unit defends. Multiple [defend]s tags can be used.
** ''range'' if this key is present, the attack must be at this range in order for the animation to trigger. Values 'short', 'long'. {{DevFeature}}: this is a comma separated list of ranges to filter the defensive animation, values must be the same than the one in the ''range'' flag of the corresponding attack (melee and ranged for standard wesnoth)
** ''hits'' if this key is present, the attack must either hit('yes') or miss('no') in order for this animation to trigger.
** '''[frame]''' defense animation. See '''[frame]''' above.
* ''get_hit_sound'' the sound played (at time=0) when this unit is hit. {{DevFeature}} If a comma-separated list, one is chosen at random.
* ''die_sound'' the sound played (at time=0) when the unit dies. {{DevFeature}} If a comma-separated list, one is chosen at random.
* '''[death]''' describes an animation for when this unit is killed. Times before 0 are not allowed for this animation; the first frame's begin time will be displayed immediately following the unit's defense animation, regardless of whether it is before or after 0.
** '''[frame]''' death animation. See '''[frame]''' above.
* '''[extra_anim]''' {{DevFeature}} describes a unit animation that will be displayed on a '''[animate_unit]''' wml action
** ''flag'' this tag will be used to choose the animation to play. If a unit has more than one animaiton with a given tag, a random one will be choosen
** '''[frame]''' the animation itself, see '''[frame]''' above
* '''[movement_anim]''' describe an animation to use when the unit is moving. multiple animations are allowed
** ''terrain'' a comma separated list of letters, this animation will only be used on these terrains
** ''direction'' a comma separated list of directions, the animations will only be used when moving in these directions

The following display tags are recognized for '''[attack]''' (deprecated in 1.1.x, use the '''[animation]''' tag described in [[unitWML]] which has the same syntax):
* ''hits'' {{DevFeature}} if this key is present, the attack must either hit('yes') or miss('no') in order for this animation to trigger.
* ''direction'' (only in an [animation] tag ) a comma separated list of directions, the animations will only be used when moving in these directions

* '''[frame]''' unit's attack animation. For melee attacks ('''range=short'''), this animation is moved toward the enemy; otherwise it is stationary. See '''[frame]''' above for syntax.
* '''[missile_frame]''' missile's animation during the attack. Only valid for ranged attacks ('''range=long''').
** ''begin'',''end'',''halo'',''halo_x'',''halo_y'' same as in '''[frame]''' above.
** ''image'' the image to display when the unit is attacking orthogonally.
** ''image_diagonal'' the image to display if the unit is attacking diagonally.
* '''[sound]''' describes a sound to play during the attack (deprecated in 1.1.x, please use the sound= line in frames instead)
** ''sound'' the sound to play if the attack hits. {{DevFeature}} If a comma-separated list, one is chosen at random.
** ''sound_miss'' the sound to play if the attack misses. {{DevFeature}} If a comma-separated list, one is chosen at random.
** ''time'' when to start playing the sound

== See Also ==

* [[UnitWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

InterfaceActionsWML

2006-03-25T11:57:04Z

Rusty: r10777: comma-separated sound list

{{WML Tags}}
== Interface actions ==

Interface actions are actions that do not have an effect on gameplay;
instead, they show something to the player. The main interface tags
are '''[message]''' and '''[objectives]''', but several other tags affect
the interface also.

== [message] ==
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.

The following key/tags are accepted for [message]:
* standard unit filter - the unit whose profile and name are displayed. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed). '''[message]''' elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.

* ''speaker'' an alternative to standard unit filter
** 'narrator' the dialog box is displayed without a caption for the unit speaking or a unit image
** 'unit' the primary unit for the event is speaking
** 'second_unit' the secondary unit for the event is speaking

* ''message'' (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')
* ''image'' (default: profile image of speaker) the image to display next to the message.
* ''caption'' (default: name of speaker) the caption to display under the image. Name to be displayed.
* ''sound'' a sound effect (wav file) to play as the message is displayed. {{DevFeature}} This can be a comma-separated list, from which one will be randomly chosen.
* '''[option]''' zero or more '''[option]''' elements may be present. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option.
** ''message'' (translatable) the text displayed for the option (see [[DescriptionWML]])
** '''[command]''' an element containing actions which are executed if the option is selected.

Text formatting options for '''[message]'''
* An asterisk (*) as the first character causes the line to be boldfaced.
* An at symbol (@) as the first character causes the line to be green, as done with victory conditions.
* A pound symbol (#) as the first character causes the line to be red, as done with defeat conditions.
* A backquote (`) as the first character causes the line to be smaller.
* If used, the caption key text is boldfaced.

== [objectives] ==
The other tag used for plot development is '''[objectives]'''.
The '''[objectives]''' tag overwrites any previously set objectives,
and displays text which should describe the objectives of the scenario.
Scenario objectives are displayed on the player's first turn after the tag is used,
or as part of the event if it triggers during that player's turn.
Objectives can also be accessed at any time in a scenario using the
"Scenario Objectives" game menu option, making this tag useful for
scenario-specific information that the player may need to refer to during play.

This tag renders the ''objectives'' attribute of [scenario] obsolete (see ''objectives'', [[ScenarioWML]]).
Instead of using ''objectives'', use '''[objectives]''' to set scenario objectives inside a prestart event.
It can also be used to overwrite the starting objectives mid-scenario.

Attributes of '''[objectives]''':
* ''side'' Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides.
* ''summary'' Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.
* ''note'' Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.
* ''victory_string'' Default ' _ "Victory:"', this text precedes the victory objectives.
* ''defeat_string'' Default ' _ "Defeat:"', this text precedes the defeat objectives.
* ''silent'' Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.

Tags of '''[objectives]''':
* '''[objective]''' describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.
** ''description'' text for the specific win or loss condition.
** ''condition'' The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'')

== Other interface tags ==

The following tags are also action tags:
* '''[item]''' makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something.
** ''x'', ''y'' the location to place the item.
** ''image'' the image (in ''images/ ''as .png) to place on the hex.
** ''halo'' an image to place centered on the hex. Use this instead of ''image'' if the image is bigger than the hex.
* '''[removeitem]''' removes any graphical items on a given hex
** ''x'', ''y'' the hex to remove items off
* '''[print]''' displays a message across the screen. The message will disappear after a certain time.
** ''text'' (translatable) the text to display.
** ''size'' (default=12) the pointsize of the font to use
** ''duration'' (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.
** ''red'', ''green'', ''blue'' (default=0,0,0) the color to display the text in. Values vary from 0-255.
* '''[move_unit_fake]''' moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.
** ''type'' the type of the unit whose image to use
** ''x'' a comma-seperated list of x locations to move along
** ''y'' a comma-seperated list of y locations to move along (x and y values are matched pairs)
* '''[hide_unit]''' makes the given unit become invisible. Useful in conjunction with '''[move_unit_fake]''' to move a leader unit into position on-screen. Only one unit may be hidden at a time.
** ''x'', ''y'' location of the unit to be hidden. (NOT a standard unit filter! Just x and y.)
* '''[unhide_unit]''' stops the currently hidden unit from being hidden.
* '''[scroll]''' Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.
** ''x'', ''y'' the number of pixels to scroll along the x and y axis
* '''[scroll_to]''' Scroll to a given hex (new in 0.9.2)
** ''x'', ''y'' the hex to scroll to
* '''[scroll_to_unit]''' Scroll to a given unit
** standard unit filter
* '''[sound]''' Plays a sound
** ''name'' the filename of the sound to play (in ''sounds/'' as .wav)
* '''[music]''' Switches to playing different music
** ''name'' the filename of the music to play (in ''music/'' as .ogg)
** {{DevFeature}} see [[MusicListWML]] for the correct syntax
* '''[colour_adjust]''' tints the colour of the screen.
** ''red'', ''green'', ''blue'' values from -255 to 255, the amount to tint by for each colour
* '''[delay]''' pauses the game
** ''time'' the time to pause in milliseconds
* '''[redraw]''' redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn)
* '''[unit_overlay]''' sets an image that will be drawn over a particular unit, and follow it around
** ''x'', ''y'' the location of the unit to overlay on
** ''image'' the image to place on the unit
* '''[remove_unit_overlay]''' removes a particular overlayed image from a unit
** ''x'', ''y'' the location of the unit to remove an overlay from
** ''image'' the image to remove from the unit
* '''[animate_unit]''' uses the custom animation of a unit to animate it on screen (if the unit has the corresponding animation)
** ''flag'' the key to find the good custom animation in the unit description see the '''[extra_anim]''' description in [[AnimationWML]]
** '''[filter]''' a standard unit filter see [[FilterWML]] by default, the unit at the event location will be animated. You can use this tag to choose what unit to animate

== See Also ==
* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

SingleUnitWML

2006-03-19T10:06:25Z

Rusty: fade_in (needed for tutorial)

== how to describe a single unit ==

This tag, '''[unit]''', describes a single unit on the map, for example Konrad.
It is different from the [unit] in [units], which describes a class of units.

The following keys are recognized:
* ''type'' the ID of the unit's unit type. See [[UnitWML]].

* ''side'' the side that the unit is on.

* ''gender'' can be set to male or female to designate the gender of the unit. Default is male.

* ''x'', ''y'' the location of the unit. If a location isn't provided and the side the unit will belong to has a recall list, the unit will be created on the recall list.

* ''description'' used in standard unit filter ([[FilterWML]]). Note that this field is not filled in with names created at random when recruiting units. Nor is it affected by a player renaming a unit. So when designing maps you don't have to worry about naming conflicts.

* ''user_description'' the name of the unit that is shown to the user. Default ''description''.

* ''generate_description'' if set to "yes", will generate a new name (user_description) for the unit, as if the unit was a freshly-recruited one.

* ''unrenamable'' if 'yes', the user_description cannot be changed by the player (which is only possible when the unit is on the player's side anyway).

* ''traits_description'' the description of the unit's traits which is displayed. However if it is not specified explicitly, the unit's actual traits' names will be used instead, so it is normally not necessary to set this.

* ''random_traits'' {{DevFeature}} choose the traits randomly, just like a recruited unit. '''Don't use this in a MP Scenario as this will cause an Out of Sync (OOS) error'''.

* ''canrecruit'' a special key for leaders.
** '0' default. Unit cannot recruit.
** '1' unit can recruit.
: Normally when a team controls no units with '''canrecruit=1''', that team loses. However, even if your team has lost you continue to play with whatever units you still have until the scenario is over. Usually scenarios end when only one team is left with a leader that can recruit, but special victory conditions can be set up in campaigns. Normally you want to set the leader of a side with '''canrecruit=1'''. If you don't want the leader to recruit, it is usually better to just not give him any unit types to recruit, than to make a special victory condition.

* ''upkeep'' the amount of upkeep the unit costs.
** "free" default for scenario-generated units. Unit does not cost upkeep
** "loyal" unit costs 1 upkeep. Can be changed by the effect 'loyal' (see [[EffectWML]])
** "full" unit costs ''level'' upkeep (see [[UnitWML]]). Default for recruited units

* ''overlays'' a list of images that are overlayed on the unit.

* ''goto_x'', ''goto_y'' UI settings that control courses. Default is 0,0 i.e. the unit is not on a course.

* ''hitpoints'' the HP of the unit. Default is the max HP for ''type''.

* ''experience'' the XP of the unit. Default is 0.

* ''moves'' number of move points the unit has left. Default is the movement for ''type''.

* ''resting'' whether the unit has not moved yet this turn. Used to decide whether to give a unit rest healing.

* ''role'' used in standard unit filter ([[FilterWML]]). Can be set using [role] (see [[InternalActionsWML]]).

* ''ai_special'' causes the unit to act differently.
** "guardian" the unit will not move, except to attack something in the turn it moves (so, it only can move if an enemy unit gets within range of it).

* ''facing'' which way the unit is facing (this only affects how the unit is displayed).
** "normal" (default) unit is facing to the right.
** "reverse" unit is facing to the left.

* ''profile'' {{DevFeature}} sets a default portrait image for this unit. If the unit type already has a portrait set, this is used instead for this unit.
** "unit_image" if given instead of a filename, uses the unit's base image as the portrait (in the same manner that unit types without portraits do by default).

* ''fade_in'' {{DevFeature}} fades the unit in, like when it's recruited/recalled.

* '''[status]''' the status of the unit. This affects different features of the unit, for example whether the unit loses health each turn. Default for all keys is 'off', but this can be changed by the scenario or by special abilities (see [[AbilitiesWML]]). The status of a unit is displayed on the Status Table; each status modification ''statusmod'' is represented by the image '''misc/statusmod.png'''.
** ''poisoned'' if 'on', the unit loses 8 HP each turn. See also ''heals'', ''cures'', [[AbilitiesWML]].
** ''slowed'' if 'on', the unit has 50% of its normal movement and -1 strike on each attack with strikes>1. When the controller of the unit's turn is over, ''slowed'' is set to 'off' {{DevFeature}} slow now halves damage instead of removing one strike
** ''stone'' if 'on', the unit cannot move, attack, or be attacked.
** ''ambush'' if 'on', the unit cannot be seen by opponents.

* '''[variables]''' a set of variables that will be stored when this unit is stored (See [store_unit], [[InternalActionsWML]]). The attribute '''variable'''='''value''' means that when the unit is stored in the array ''unit'', the variable ''unit''.variables.''variable'' will have the value ''value'' (See [[VariablesWML]]).

* '''[modifications]''' changes that have been made to the unit.
** '''[trait]''' a trait the unit has. Same format as [trait], [[UnitsWML]].
** '''[object]''' an object the unit has. Same format as [object], [[DirectActionsWML]].

== See Also ==

* [[UnitWML]]
* [[ReferenceWML]]

EventWML

2006-03-19T09:58:35Z

Rusty: ''ai turn'' tag for tutorial

== the [event] tag ==

This tag is a subtag of [scenario] which is used to describe a set of actions
which trigger at a certain point in the scenario.

keys and tags that describe when the event should trigger:
<ul><li> ''name'' this is not like a normal 'name' key. It is a basic description of when the event will trigger.
* ''prestart'' the event is triggered before a scenario 'starts' -- before anything is shown on the screen at all. You can use this event to set up things like village ownership. For things displayed on-screen such as character dialog, use 'start'.
* ''start'' this event triggers after the map is shown but before the scenario begins
* ''new turn'' this event triggers whenever the last player ends their turn. See also '''first_time_only=no'''. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.
* ''side turn'' this event triggers 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.
* ''turn ''X'''' this event triggers at the start of turn ''X''. ''X'' cannot be 1.
* ''time over'' this event triggers on turn ''turns''. (''turns'' is specified in [scenario])
* ''enemies defeated'' this event triggers when all units with '''canrecruit=1''' (i.e. all leaders) not allied with side 1 are killed.
* ''victory'' in this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this 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]])
* ''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]])
* ''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 .

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'' {{DevFeature}} this event triggers when the attacker (''primary_unit'') hits the defender (''secondary_unit'').
* ''attacker_misses'' {{DevFeature}} same as ''attacker_hits'', but is triggered when the attacker misses.
* ''defender_hits'' {{DevFeature}} this event triggers when the attacker (''primary_unit'') is hit in retaliation by the defender (''secondary_unit'').
* ''defender_misses'' {{DevFeature}} same as ''defender_hits'', but is triggered when the defender misses.
* ''attack_end'' {{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'' {{DevFeature}} this event triggers just before ''primary_unit'' is going to advance to another unit.
* ''post_advance'' {{DevFeature}} this event triggers just after ''primary_unit'' has advanced to another unit.
* ''select'' {{DevFeature}} triggers when a unit is selected. Mainly useful for the tutorial.

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.
</li></ul>

''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]''' {{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.

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: internal actions ([[InternalActionsWML]]) which are used by WML internally,
display actions ([[InterfaceActionsWML]]) which show something to the user,
and direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay.

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".

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

InternalActionsWML

2006-03-12T09:31:03Z

Rusty: Example of poison doesn't work (at least in current 1.1.1+svn)

== Internal actions ==

Internal actions are actions that WML uses internally that do not directly affect gameplay, for example storing a variable.

The internal actions '''[if]''', '''[while]''', and '''[event]''' describe when/whether sets of actions should be executed.

== [if] ==

Executes different sets of actions based on whether the conditions described in the condition tags are true or not.

Condition tags:
* '''[have_unit]''' a unit passing this filter with >0 HP exists
** standard unit filter

* '''[and]''' {{DevFeature}} If an [and] is present, all must evaluate to true in order for the [if] to evaluate true. Useful as a bracket for complex conditions.
** condition tags as in [if] - if these evaluate to true, [and] evaluates to true.

* '''[or]''' If an [or] is present, one must evaluate to true in order for the [if] to evaluate true
** condition tags as in [if] - if these evaluate to true, [or] evaluates to true.

* '''[not]''' {{DevFeature}} If a [not] is present, .
** condition tags as in [if] - if these evaluate to true, [not] evaluates to false.

* '''[variable]''' tests something about the value of a WML variable (see [[VariablesWML]])
** ''name'' the name of the variable to test the value of Only one of these keys should be used:
** ''equals'' $name is equal (string wise) to ''equals''
***''(to compare numbers, use numerical_equals, see below)''
** ''not_equals'' $name is not equal to ''not_equals''
** ''greater_than'' $name is numerically greater than ''greater_than''
** ''less_than'' $name is less than ''less_than''
** ''greater_than_equal_to'' $name is not less than ''greater_than_equal_to''
** ''less_than_equal_to'' $name is not greater than ''less_than_equal_to''
** ''numerical_not_equals'' $name is greater than or less than ''numerical_not_equals''
** ''numerical_equals'' $name is not greater than or less than ''numerical_equals''

After condition tags:
* '''[then]''' contains a set of action tags which should be executed if all conditions are true, or all conditions in any single [or] are true
* '''[else]''' contains a set of action tags which should be executed if any condition is false, and all [or] tags are false

== [while] ==

executes commands if all conditions are true.
Continues to execute them until a condition is not true.

Executes a maximum of 1024 iterations per invocation.
Condition tags are the same as for [if]

After condition tags:
* '''[do]''' contains actions that should be executed repeatedly until some condition is false.

The [while] tag is useful for iterating over an array.
An ''array'' is a list of values.
The ''number''th value in the array ''array'' is stored in the WML variable '''''array''[number]'''.
Note that if ''number'' is the value of the variable ''variable'',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.
The macros 'FOREACH' and 'NEXT' ([[UtilWML]]) can be used to iterate over an array;
i.e. run a set of actions once per element of the array.

== [event] == this adds a new event to the scenario.
The event is in the normal format for an '''[event]''' tag (See [[EventWML]]).
This is useful if you want an event that can only be triggered when a prior event is fulfilled

These tags describe actions that affect the values of WML variables
(see [[VariablesWML]] for information on WML variables,
and [[UtilWML]] for convenient macro shortcuts for some of these):
* '''[set_variable]''' manipulates a WML variable.
** ''name'' the name of the variable to manipulate
** ''value'' set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.
** ''format'' set the variable to the given value. Interprets the dollar sign to a higher degree than most actions. (see [[VariablesWML]])
** ''to_variable'' Fully processes its value as in ''format'', and then gets the variable with that name.
** ''add'' add the given amount to the variable. To subtract, add a negative number.
** ''multiply'' multiply the variable by the given amount. To divide, multiply by a decimal. To negate, multiply by -1.
** ''random'' the variable will be randomly set. You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'. You may provide a range of numbers (integers), e.g. 'random=3..5'. You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''.

* '''[store_unit]''' stores details about units into game variables. Common usage is to manipulate a unit by using [store_unit] to store it into a variable, followed by manipulation of the variable, and then [unstore_unit] to re-create the unit with the modified variables. Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]]
** '''[filter]''' (standard unit filter) all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.
** ''variable'' the name of the variable into which to store the unit(s)
** ''mode'' {{DevFeature}} defaults to ''always_clear'', which clears the variable, whether or not a match is found. If mode is set to ''replace'', the variable will only be cleared if a match is found. If mode is set to ''append'', the variable will not be cleared.
** ''kill'' if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later.
:When a unit is stored, the following values may be manipulated with '''[set_variable]'''
:* description
:* experience
:* facing
:* gender
:* canrecruit
:* overlays
:* goto_x
:* goto_y
:* hitpoints
:* moves
:* resting
:* side
:* type
:* unrenamable
:* upkeep
:* user_description
:* profile {{DevFeature}}
:* x
:* y
:* [variables]
:* [status]
:* [modifications]
Variables, status, and modifications are children of the stored unit variable. Example:
[set_variable]
name=unit_store.status.poisoned
value=on
[/set_variable]

* '''[store_starting_location]''' Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x' and 'y'.
** ''side'' the side whose starting location is to be stored
** ''variable'' (default='location'): the name of the variable to store the location in
* '''[store_locations]''' Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y'.
** standard location filter- a location or location range which specifies the locations to store. You must specify this or no locations will be stored.
** ''variable'' the name of the variable (array) into which to store the locations
** ''terrain'' a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, locations will only be chosen if the letter of the terrain type of that location is listed.
** ''radius'' if present, any locations which are within ''radius'' hexes of the location filter will also be stored
** '''[filter]''' (standard unit filter) only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.
* '''[store_gold]''' stores the gold for a certain side in a variable.
** ''side'' (default=1) the side for which the gold should be stored
** ''variable'' (default='gold') the name of the variable to store the gold in
* '''[clear_variable]''' This will delete the given variable or array. This is good to use to clean up the set of variables -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario. {{DevFeature}} Tags and variables of stored units can also be cleared, meaning that [trait]s and [object]s, for example, can be removed.
** ''name'' the name of the variable to clear.
* '''[role]''' tries to find a unit to assign a role to. This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]). However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [if]) to see whether a role was assigned. This tag uses a Standard Unit Filter with the modification to order the search by type, mark only the first unit found with the role, and the role attribute is not used in the search. If for some reason you want to search for units that have or don't have existing roles, you can use one or more [not] filters. The will check recall lists in addition to units on the map. In normal use, you will probably want to include a ''side'' attribute to force the unit to be on a particular side.
** ''role'' the value to store as the unit's role. This role is not used in the Standard Unit Filter when doing the search for the unit to assign this role to.
** ''type'' a comma-separated list of possible types the unit can be. If any types are given, then units will be searched by type in the order listed. If no type is given, then no particular order with respect to type is guaranteed.

== See Also ==
* [[VariablesWML]]
* [[DirectActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

BuildingScenariosSimple

2006-03-10T01:46:44Z

Rusty: Encourage id numbering for stats.wesnoth.org

I will show you a very simple scenario file,
then explain each line of it.
This file is not fully functional, but it shows you
the basics needed to describe what this scenario is all about.

[scenario]

id=1_test
next_scenario=2_test-more

name=A Simple Test Scenario
map_data="{campaigns/Test_Campaign/testmap}{~campaigns/Test_Campaign/testmap}"
turns=20

{DAWN}
{MORNING}
{AFTERNOON}
{DUSK}
{FIRST_WATCH}
{SECOND_WATCH}

music=wesnoth-1.ogg

[event]
name=prestart
[objectives]
side=1
[objective]
description= _ "Defeat Enemy Leader"
condition=win
[/objective]
[objective]
description= _ "Death of Konrad"
condition=lose
[/objective]
[/objectives]
[/event]

First, every scenario must be enclosed in a tag;
the '''[scenario]''' tag is used for campaign scenarios.
The first set of keys in the scenario tag
describe the very basics of this scenario.
The ''id'' is the computer's name for your scenario,
and is not displayed during the game, but will be used on http://stats.wesnoth.org to display game statistics (they will be graphed there in numerical order, so it's a good idea to number the ids).
It is neccesary to put this name somewhere else,
such as a campaign tag, as well, in order to actually play the scenario.
Where you put the ID for the scenario
indicates how you would play this scenario in-game.
For example, if your scenario is for a campaign,
you need to list it as the scenario following another scenario in the campaign.

The ''next_scenario'' key lists the scenario
that is played after this one is won,
with units from this scenario available for recall.
The value of this key should be the same
as the value of the '''id''' key in the scenario following it.
If your scenario is not part of a campaign,
putting '''next_scenario=null''' or skipping this line
will cause the "End" screen to be displayed when you win.

The ''name'' key is shown on the introduction screen(which usually contains the
map graphic) before each scenario is played.
It is also the default name for saves on the level.
The next key, ''map_data'', is a link to the map file.
Since we may not know exactly where this campaign will be installed we write
two possible locations of the map data.
The quotes are necessary because Wesnoth map data takes up multiple lines,
so quotes are used instead to determine where the data begins and ends.
The map file must be a valid Wesnoth map file; see [[BuildingMaps]].
Finally, the last key in the top set of keys is ''turns''.
This sets an event on the specified turn causing the player to lose.

The next section is a set of IDs. This section tells the game how a day should
progress. This listing above is the normal day used throughout Wesnoth. If you
want the entire scenario to take place at night, remove all the IDs except for
'''{SECOND_WATCH}'''. This can be useful if you have Konrad
fighting against the Undead and wanted the Undead to have the upper hand the
whole time. Remember though, by setting this to a single ID and not the normal
day listed above, your scenario will effectively be taking place during one day
or night, not many days as the majority currently are.

The ''music'' key is a filename pointing to the music which plays.
This music file must be in the ''music/'' directory and must be in .ogg format.

The next part sets the objectives for the scenario. This is done inside an '''[event]''' tag, and to have the objectives set before the scenario starts, we must specify '''name=prestart'''. Inside the [event] tag, we have an '''[objectives]''' (plural) tag, which contains any number of '''[objective]''' (singular) tags.
For each tag, if ''condition'' is "win", the text of ''description'' will be displayed in green after "Victory" in the Scenario Objectives. If ''condition'' is "lose", the text of ''description'' will be displayed in red after "Defeat" in the Scenario Objectives.

The ' _ ' facilitates translation using Gettext (see [[GetText]]).

Note that ''ANY'' Victory or Defeat objective can be met to win or lose the scenario,
but a single Victory objective may have multiple parts.

So far so good. The last necessary part of a scenario describes what the players (Human and
Computer) start with and can do. Each of the players is described through
the '''[side]''' tag.

.
.
.

[side]
side=1
controller=human
team_name=2

type=Commander
description=Konrad
canrecruit=1

recruit=Elvish Fighter,Elvish Archer,Horseman,Mage,Elvish Shaman

{GOLD 100 50 0}
{INCOME 10 5 0}
[/side]

[/scenario]

From the above example above you can see
a sample '''[side]''' for the human player, Konrad.
The first key, ''side'',
is the location where this player starts on the map,
and is also the ID for this side.
It is a number from 1 to 9.
The next key that describes this player is ''controller''.
The possible values are 'human'
and 'ai', with 'ai' as the default.
After this, the ''team_name'' key describes which team the side is on.
In this example Konrad is on team "2", which by default contains side 2.
However, if you change the team_name of side 2,
Konrad will no longer be allied with it.

The next set of keys describe the player's leader.
First we have ''canrecruit''.
This key can be '0' or '1', which is "no" or "yes" respectively.
If you say no, then the player's leader will not be able to recruit.
And if he can't recruit, he's not really a leader, is he?
Any team without a canrecruit=1 unit automatically loses, so be sure to use this key.
The next key, ''type'', is the type of unit the leader will be.
The possible values are listed at [[UnitTables]].
The ''description'' is the name and description of the leader.
All of these keys are ignored for the human player on all campaign scenarios except the first,
since the leader from the previous scenario is used instead.
However, the ''type'' key is still neccesary to prevent the scenario from crashing.

Next we have the '''recruit''' key which is a comma-separated
list of units. The possible values are listed in [[UnitTables]].

The last two things are IDs.
'''{GOLD}''' inputs any 3 positive numbers.
These indicate the amount of money the player will start with.
The first value indicates the value on the EASY difficulty level;
second NORMAL, third HARD.
When this is inside the ''controller=human'' in a campaign file
then the actual gold the player gets will be the maximum of this value,
and the amount of gold the player retained from the previous scenario.
The '''INCOME''' id is similar, but indicates the base income instead of the base gold.
The defaults for each of these values are 100 gold and 2 base income.

Now, to make this scenario playable, we need to make a campaign for it.
This should usually be stored in its own file in '''data/campaigns/'''.
Note: All files, the campaign file and the scenario file, one for each scenario level, must be saved with the ending
.cfg (for example: testcampaign.cfg, level1.cfg).
[campaign]
name= _ "Test Campaign"
first_scenario=test-1
difficulties=EASY,NORMAL,HARD

difficulty_descriptions= _ "&elvish-fighter.png=Easy;*&elvish-hero.png=Medium;&elvish-champion.png=Hard"
icon=elvish-fighter.png
[/campaign]

Campaigns are enclosed in the '''[campaign]''' tag. The first key is ''name'', which is
displayed on the campaign selector box. The second key is ''first_scenario'', which is
the ID of the first scenario of the campaign (Other scenarios are indicated using
''next_scenario'').

The attribute '''difficulties=EASY,NORMAL,HARD'''
tells the computer to give the macro '''EASY''' a value
if the first difficulty choice is chosen,
'''NORMAL''' if the second is chosen, and '''HARD''' if the third is chosen.
The expression '''#ifdef''' can be used later to test these macros.
It is recommended that you do not use any names other than
'''EASY''', '''NORMAL''', and '''HARD''' for your macros,
because if you do then the macros '''{GOLD}''' and '''{INCOME}''' will not work properly.

Two optional keys in '''[campaign]''' are ''difficulty_descriptions'' and ''icon''.
''icon'' has value equal to an image.
''difficulty_descriptions'' must have the same number of inputs as '''difficulties''', most commonly three, separated by
semicolons.
These inputs then map on to the difficulties, so that if you have set difficulties to
"difficulties=EASY,NORMAL,HARD",
the first input will specify the display
on easy, the second on normal and the third (and last) on hard.
Each difficulty display is an '''&''' sign, then the image to display,
then an equals sign, then the text to display.
Place an '''*''' sign before the display which you wish to be default difficulty, and it will be selected when the player
has chosen the campaign.

== See Also ==
* [[BuildingMaps]]
* [[ScenarioWML]]
* [[BuildingScenarios]]

EventWML

2006-02-27T01:57:35Z

Rusty: Oops, there *was* a recruit there already.

== the [event] tag ==

This tag is a subtag of [scenario] which is used to describe a set of actions
which trigger at a certain point in the scenario.

keys and tags that describe when the event should trigger:
<ul><li> ''name'' this is not like a normal 'name' key. It is a basic description of when the event will trigger.
* ''prestart'' the event is triggered before a scenario 'starts' -- before anything is shown on the screen at all. You can use this event to set up things like village ownership. For things displayed on-screen such as character dialog, use 'start'.
* ''start'' this event triggers after the map is shown but before the scenario begins
* ''new turn'' this event triggers whenever the last player ends their turn. See also '''first_time_only=no'''. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.
* ''side turn'' this event triggers 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.
* ''turn ''X'''' this event triggers at the start of turn ''X''. ''X'' cannot be 1.
* ''time over'' this event triggers on turn ''turns''. (''turns'' is specified in [scenario])
* ''enemies defeated'' this event triggers when all units with '''canrecruit=1''' (i.e. all leaders) not allied with side 1 are killed.
* ''victory'' in this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this 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]])
* ''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]])

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'' {{DevFeature}} this event triggers when the attacker (''primary_unit'') hits the defender (''secondary_unit'').
* ''attacker_misses'' {{DevFeature}} same as ''attacker_hits'', but is triggered when the attacker misses.
* ''defender_hits'' {{DevFeature}} this event triggers when the attacker (''primary_unit'') is hit in retaliation by the defender (''secondary_unit'').
* ''defender_misses'' {{DevFeature}} same as ''defender_hits'', but is triggered when the defender misses.
* ''attack_end'' {{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'' {{DevFeature}} this event triggers just before ''primary_unit'' is going to advance to another unit.
* ''post_advance'' {{DevFeature}} this event triggers just after ''primary_unit'' has advanced to another unit.
* ''select'' {{DevFeature}} triggers when a unit is selected. Mainly useful for the tutorial.

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.
</li></ul>

''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]''' {{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.

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: internal actions ([[InternalActionsWML]]) which are used by WML internally,
display actions ([[InterfaceActionsWML]]) which show something to the user,
and direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay.

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".

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

EventWML

2006-02-26T10:50:13Z

Rusty: Document select (r10305), and previously undocumented "recruit"

== the [event] tag ==

This tag is a subtag of [scenario] which is used to describe a set of actions
which trigger at a certain point in the scenario.

keys and tags that describe when the event should trigger:
<ul><li> ''name'' this is not like a normal 'name' key. It is a basic description of when the event will trigger.
* ''prestart'' the event is triggered before a scenario 'starts' -- before anything is shown on the screen at all. You can use this event to set up things like village ownership. For things displayed on-screen such as character dialog, use 'start'.
* ''start'' this event triggers after the map is shown but before the scenario begins
* ''new turn'' this event triggers whenever the last player ends their turn. See also '''first_time_only=no'''. When the last player ends their turn, before any events of this type trigger, the value of the WML variable '''turn_number''' is set to the number of the turn that is beginning.
* ''side turn'' this event triggers 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.
* ''turn ''X'''' this event triggers at the start of turn ''X''. ''X'' cannot be 1.
* ''time over'' this event triggers on turn ''turns''. (''turns'' is specified in [scenario])
* ''enemies defeated'' this event triggers when all units with '''canrecruit=1''' (i.e. all leaders) not allied with side 1 are killed.
* ''victory'' in this scenario, any tag of the form '''[endlevel] result=victory [/endlevel]''' will be automatically preceded by all actions in this 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]])
* ''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]])

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'' {{DevFeature}} this event triggers when the attacker (''primary_unit'') hits the defender (''secondary_unit'').
* ''attacker_misses'' {{DevFeature}} same as ''attacker_hits'', but is triggered when the attacker misses.
* ''defender_hits'' {{DevFeature}} this event triggers when the attacker (''primary_unit'') is hit in retaliation by the defender (''secondary_unit'').
* ''defender_misses'' {{DevFeature}} same as ''defender_hits'', but is triggered when the defender misses.
* ''attack_end'' {{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'' {{DevFeature}} this event triggers just before ''primary_unit'' is going to advance to another unit.
* ''post_advance'' {{DevFeature}} this event triggers just after ''primary_unit'' has advanced to another unit.
* ''recruit'' triggers when a unit is recruited.
* ''select'' {{DevFeature}} triggers when a unit is selected. Mainly useful for the tutorial.

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.
</li></ul>

''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]''' {{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.

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: internal actions ([[InternalActionsWML]]) which are used by WML internally,
display actions ([[InterfaceActionsWML]]) which show something to the user,
and direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay.

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".

== See Also ==

* [[DirectActionsWML]]
* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[FilterWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

MusicListWML

2006-02-22T02:37:38Z

Rusty: Provide an example

== the [music] tag ==
{{DevFeature}}

This tag is a subtag of [scenario] and [event] which is used to describe a music track to play. You can repeat this tag as many times as you like; if you set the ''append'' tag to ''yes'' they will form a playlist from which tracks will be selected at random.

Tags describe the music track:
* ''name'' specifies the music file, relative to '"music/"'. This is compulsory.
* ''append=yes'' specifies this is to be added to the current playlist. Without this, the current playlist is replaced by this track.
* ''play_once=yes'' immediately switch to playing this track, but then return to the play list, which is unchanged.
* ''immediate=yes'' immediately switch to playing this track. Without this, the song will play when the entire [event] is over or the current song ends. This exists to force music changes '''during''' dialog exchange or other [event] which take significant time.
* ''ms_before'' (optional) specifies how many milliseconds to delay before playing this track. Currently this does not apply when the scenario first starts, or with ''play_once'' or ''immediate''.
* ''ms_after'' (optional) specifies how many milliseconds to delay after playing this track.

=== Example ===
This creates a new playlist with three entries in it. The second track is always preceeded by 1/2 a second of silence.
[music]
name=background-music-1.ogg
[/music]
[music]
name=background-music-2.ogg
ms_before=500
append=yes
[/music]
[music]
name=background-music-3.ogg
append=yes
[/music]

[[Category: WML Reference]]

MusicListWML

2006-02-11T01:54:10Z

Rusty: Clarify the use of "immediate" (ie. it's exceptional).

CommandMode

2006-02-08T06:39:10Z

Rusty: /* Command Mode */

== Command Mode ==

You can access command mode by typing ' ''':''' ' in a single player or multiplayer scenario.
(Prior to version 1.1.1, you need to type shift - semicolon( ''';''' ). However this isn't possible on all keyboards; if your keyboard doesn't have ':' above ';' you can change the hotkey in the Preferences, or you could edit '''game.cfg''' by hand.')

Several vi-like commands are available in command mode. They are defined in ''playturn.cpp'' in the ''turn_info::do_command()'' function:
;<nowiki>:q or :q!</nowiki>
:quit the scenario (without prompting)
;<nowiki>:w</nowiki>
:save the game (without prompting)
;<nowiki>:wq</nowiki>
:save the game and quit the scenario (without prompting)
;<nowiki>:refresh</nowiki>
:redraw the screen
;<nowiki>:droid</nowiki> ''side''
:toggle player on side between human and AI players. If a human controls the side, the player himself has to issue this command.
;<nowiki>:kick</nowiki> ''username''
:kick a user in multiplayer. They will be able to rejoin the game. Generally a friendly way to remove someone who is having connection or other difficulties.
;<nowiki>:ban</nowiki> ''username''
:kick and ban a user in multiplayer, and the IP address used by that username
;<nowiki>:control</nowiki> ''side'' ''username''
:change the controller for ''side'' (write here number of the side) to ''username'' (write here nick of player or observer)
;<nowiki>:clear</nowiki>
:clear chat messages
;<nowiki>:debug</nowiki>
:switch debug mode on (does not work in multiplayer). Debug mode is turned off by quitting the game.
;<nowiki>:theme</nowiki>
:bring up theme selection menu

===Extra Debugging Commands===
[[DebugMode]] enables additional commands in command mode:

;<nowiki>:n</nowiki>
:skip to next scenario by triggering a win event
;<nowiki>:gold</nowiki> ''amount''
:add ''amount'' gold to the current player's side
;<nowiki>:create</nowiki> ''unit_type''
:create a unit of type specified at last selected hex
;<nowiki>:unit</nowiki> ''attribute=value''
:when a unit is selected, this will set the unit's ''attribute'' to ''value''. See [[SingleUnitWML]] for possible values.

== See Also ==

* [[DebugMode]]
* [[DeveloperResources]]

MusicListWML

2006-01-30T06:15:45Z

Rusty: Mark it as SVN-only

== the [music] tag ==
{{DevFeature}}

This tag is a subtag of [scenario] and [event] which is used to describe a music track to play. You can repeat this tag as many times as you like; if you set the ''append'' tag to ''yes'' they will form a playlist from which tracks will be selected at random.

Tags describe the music track:
* ''name'' specifies the music file, relative to '"music/"'. This is compulsory.
* ''append=yes'' specifies this is to be added to the current playlist. Without this, the current playlist is replaced by this track.
* ''play_once=yes'' immediately switch to playing this track, but then return to the play list, which is unchanged.
* ''immediate=yes'' immediately switch to playing this track. Without this, the song will play when the entire [event] is over or the current song ends.
* ''ms_before'' (optional) specifies how many milliseconds to delay before playing this track. Currently this does not apply when the scenario first starts, or with ''play_once'' or ''immediate''.
* ''ms_after'' (optional) specifies how many milliseconds to delay after playing this track.

[[Category: WML Reference]]

MusicListWML

2006-01-26T23:40:21Z

Rusty: It's name= not music=

== the [music] tag ==

This tag is a subtag of [scenario] and [event] which is used to describe a music track to play. You can repeat this tag as many times as you like; if you set the ''append'' tag to ''yes'' they will form a playlist from which tracks will be selected at random.

Tags describe the music track:
* ''name'' specifies the music file, relative to '"music/"'. This is compulsory.
* ''append=yes'' specifies this is to be added to the current playlist. Without this, the current playlist is replaced by this track.
* ''play_once=yes'' immediately switch to playing this track, but then return to the play list, which is unchanged.
* ''immediate=yes'' immediately switch to playing this track, then continue on the modified playlist. Without this, we wait until the entire event is over before starting on the modified playlist (aborting the current track only if it's not on the new playlist).
* ''ms_before'' (optional) specifies how many milliseconds to delay before playing this track. Currently this does not apply when the scenario first starts, or with ''play_once'' or ''immediate''.
* ''ms_after'' (optional) specifies how many milliseconds to delay after playing this track.

[[Category: WML Reference]]

MusicListWML

2006-01-20T10:46:35Z

Rusty: /* the [music-list] tag */

== the [music] tag ==

This tag is a subtag of [scenario] and [event] which is used to describe a music track to play. You can repeat this tag as many times as you like; if you set the ''append'' tag to ''yes'' they will form a playlist from which tracks will be selected at random.

Tags describe the music track:
* ''music'' specifies the music file, relative to '"music/"'. This is compulsory.
* ''append=yes'' specifies this is to be added to the current playlist. Without this, the current playlist is replaced by this track.
* ''play_once=yes'' immediately switch to playing this track, but then return to the play list, which is unchanged.
* ''immediate=yes'' immediately switch to playing this track, then continue on the modified playlist. Without this, we wait until the entire event is over before starting on the modified playlist (aborting the current track only if it's not on the new playlist).
* ''ms_before'' (optional) specifies how many milliseconds to delay before playing this track. Currently this does not apply when the scenario first starts, or with ''play_once'' or ''immediate''.
* ''ms_after'' (optional) specifies how many milliseconds to delay after playing this track.

MusicListWML

2006-01-19T23:26:11Z

Rusty:

== the [music-list] tag ==

This tag is a subtag of [scenario] which is used to describe a music track to play. You can repeat this tag as many times as you like: one will be selected at random during scenario play.

Tags describe the music:
* ''file'' specifies the music file, relative to '"music/"'. This is compulsory.
* ''ms_before'' (optional) specifies how many milliseconds to delay before playing this track. Currently this does not apply when the scenario first starts.
* ''ms_after'' (optional) specifies how many milliseconds to delay after playing this track.

ScenarioWML

2006-01-19T23:03:55Z

Rusty: music_list doco.

== the toplevel tags [multiplayer], [test], [tutorial], [scenario] ==

The top level tags '''[multiplayer]''', '''[test]''', '''[tutorial]''' and '''[scenario]''' are all formatted the same way.
The difference between these tags is the way that the scenarios they describe are accessed.

The keys ''id'' and ''next_scenario'' affect how scenarios can be accessed.
Whenever a scenario is won, the scenario with id=''next_scenario'' of the same tag type will be played.
Units from the first scenario will be available for recall in the second.

Some scenarios can be played without playing other scenarios first
(in this case there is nothing on the recall list).
These scenarios are called ''initial scenario''s.

A list of initial scenarios, and how to access them:

* All '''[multiplayer]''' scenarios are initial scenarios listed in the multiplayer scenario selector screen (accessed by the "multiplayer" button).

* The '''[test]''' scenario with the attribute '''id=test''' is an initial scenario. This test scenario can be accessed by running the game in test mode. (note: this is NOT the same as debug mode. It can be accessed using -t or --test) You can speed up scenario development a lot by this when used in a clever way: Move a scenario into ~campaigns (so that it will be read even without its campaign being loaded), change it to a [test] scenario, and change the ID to 'test'. Then run Wesnoth in test mode. This saves about a minute for each time you want to test changes to your scenario. However it should not be used for balancing as there will be no recallable units...

* The '''[tutorial]''' scenario with the attribute '''id=tutorial''' is an initial scenario. The tutorial is accessed by clicking on the "tutorial" button.

* Any '''[scenario]''' scenario with an id listed in the value of ''first_scenario'' in a campaign tag (see [[CampaignWML]]) is an initial scenario accessed by selecting that campaign after clicking on the "campaign" button.

== The [scenario] tag ==

The following keys and tags are recognized in '''[scenario]''' tags:

* ''id'' A unique identifier for this scenario.

* ''next_scenario'' The id of the scenario to load when the current one is won. This can be changed dynamically, to build non-linear campaigns.

* ''description'' (translatable) only for multiplayer maps. Will show up as a tooltip when mousing over the minimap in the multiplayer setup screen. Only in >0.8.5

* ''name'' (translatable) is shown in several places in the level, including the intro screen. It is also the default name for saves on the level.

* ''map_data'' inputs valid Wesnoth map data. See [[BuildingMaps]] for a description of the Wesnoth map syntax.

* ''turns'' sets an event on turn ''turns'' causing the player to lose. See also [[EventWML]]

* ''turn_at'' the turn to start on (default=1)

* '''[music_list]''' specifies the music tracks to play during this scenario, see [[MusicListWML]]. This was introduced after 1.1, obsoleting the old ''music'' tag, which specified the music to play relative to the '"music/'".

* ''theme'' the UI theme that should be used when playing this scenario. See [[Using_custom_themes_in_campaigns]]

* ''objectives'' (translatable) the text displayed in the Scenario Objectives box in-game. Now obsolete; see '''[objectives]''', [[InterfaceActionsWML]].

* ''victory_when_enemies_defeated'' when this is set to 'yes'(default), the player wins once all non-allied units with '''canrecruit=1''' (aka leaders) are killed. (Currently this only controls the win condition for when all enemies are defeated; it does not prevent the player from losing if he has no leader.)

* ''disallow_recall'' when this is set to 'no'(default), the player is allowed to recall units from previous scenarios.

* ''experience_modifier'' the percentage that required XP to level up (for all units in the scenario) is multiplied by. Default 100. Note that when used in a campaign, weird things (like units being above the required XP to level up) can happen if this value is different for different scenarios.

* '''[story]''' describes the intro screen. See [[IntroWML]]

* '''[label]''' sets a label
** ''x'', ''y'' location to set label
** ''text'' the label

* '''[time]''', '''[illuminated_time]''' how a day should progress. See [[TimeWML]]

* '''[time_area]''' how a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] and [illuminated_time] tags in the [scenario] tag
** standard location filter
** '''[time]''', '''[illuminated_time]''' how a day should progress in those locations. See [[TimeWML]]

* '''[side]''' describes one player. See [[SideWML]]

* '''[event]''' describes an event that may be triggered at a certain point of the scenario. See [[EventWML]]

* ''map_generation'' another way to generate a map. The map will be generated randomly
** "default" the default random map generator

* '''[generator]''' if this is present, the map and scenario will be generated randomly. See [[MapGeneratorWML]]

== See Also ==

* [[EventWML]]
* [[ReferenceWML]]