The Battle for Wesnoth Wiki - User contributions [en]

EventWML

2008-05-25T20:48:11Z

Segfault: /* The [event] tag */

{{WML Tags}}
== The [event] tag ==

This tag is a subtag of the [scenario], [unit] and [era] tags which is used to describe a set of actions which trigger at a certain point in a scenario. When used in a [scenario] tag (also includes [multiplayer], [tutorial] and [test]), the event only occurs in that scenario. When used in a [unit] type definition, the event will occur in all scenarios in which a unit of that type appears in. When used in an [era], the event will occur in any scenario which is played using that era.

Keys and tags that describe when the event should trigger:
* '''name''': this is not like a normal 'name' key. It is a basic description of when the event will trigger. {{DevFeature}} '''name''' can accept a list of commas separated descriptions for which the event must be triggered. Example: '''name= attacker_misses, defender_misses'''.
* '''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 a side is about to start its turn. Before 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. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.
* '''turn refresh''': this event triggers just before a side is taking control after healing, calculating income, and restoring unit movement and status.
* '''turn X''': (for X some number) 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=yes''' (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 side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.

Filters can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]

* '''moveto'''': triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on.
* '''sighted''': this event triggers when the primary unit moves to a location where the secondary unit is in sight range of the primary unit. Works only in shroud or fog.
* '''attack''': this event triggers when the primary unit attacks the secondary_unit.
* '''attacker_hits''': this event triggers when the the primary unit (the attacker) hits the secondary unit (the defender). {{DevFeature}} A variable '''$damage_inflicted''' allow to check the number of hitpoints inflicted by the attacker.
* '''attacker_misses''': same as ''attacker_hits'', but is triggered when the attacker misses.
* '''defender_hits''': this event triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender). {{DevFeature}} A variable '''$damage_inflicted''' allow to check the number of hitpoints inflicted by the defender.
* '''defender_misses''': same as ''defender_hits'', but is triggered when the defender misses.
* '''attack_end''': 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 the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).
* '''last breath''': this event triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.
* '''die''': this event triggers when the primary unit is killed by the secondary unit.
* '''capture''': this event triggers when the 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 the 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.). {{DevFeature}} The '''recruit''' will no longer triggers on recalls.
* '''prerecruit''': this event triggers when the primary unit is recruited, but before it is displayed. {{DevFeature}} The '''prerecruit''' will no longer triggers on recalls.
* '''advance''': this event triggers just before the primary unit is going to advance to another unit.
* '''post_advance''': this event triggers just after the primary unit has advanced to another unit.
* '''select''': triggers when the primary unit is selected. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''
* '''menu item X''': triggers when a WML menu item with id=X is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''
* {{DevFeature}} '''prerecall''': triggers when a unit is recalled, but before it is displayed. This event is not trigger when a unit is recruit.
* {{DevFeature}} '''recall''': triggers after a unit is recalled. This event is not trigger when a unit is recruit.
* {{DevFeature}} other events with a custom name may be invoked from [fire_event]

An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.

The primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the speaker= key. 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 the primary unit matches this filter.
** [[StandardUnitFilter]]: selection criteria
* '''[filter_second]''': is like [filter], but for the secondary unit.
** [[StandardUnitFilter]]: selection criteria
* '''[special_filter]''' and '''[special_filter_second]''': can be used to set some additional filtering criteria for the primary unit and the 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''. ({{DevFeature}} renamed to [filter_attack] and [filter_second_attack])
** '''weapon''': the name of the weapon used.

=== Actions triggered by [event] ===

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

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

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

=== Nested events ===

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

Example:

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

# moving to 5,8 will trigger this event only on turn 10 and after
[/event]
[/event]

Nested events are nice for spawning a new event that does a simple task, but this technique is not reccommended for creating very complex tasks since the nested event will use different variable substitution rules than a normal event. For example, a variable substitution "$var" will be evaluated when it is created initially, but "$|var" would be evaluated later when it is triggered.

== See Also ==

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

[[Category: WML Reference]]

EasyCoding

2008-05-25T20:44:18Z

Segfault: /* WML related features */

== Foreword ==
This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

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

--[[User:Boucman|Boucman]] 20:48, 3 October 2006 (CEST)

Since bugs are sometimes a good opportunity to get a first idea of the code, i will add some here that are easy to fix as soon as i stumble upon them (the one i had in mind is fixed already ;-).

--Yogi Bear, 28 February 2008

== MP related features ==

=== Add TTL to wesnothd bans ===
As per FR #3638 [https://gna.org/bugs/?3638]

''Working on it:'' Lao

=== Use different font for in-game chat ===
Since commas and dots are apparently hard to tell apart. As per FR #7470 [https://gna.org/bugs/?7470]

''Working on it:'' kthakore

=== Allow lists for /ignore and similar ===
As per FR #7492 [https://gna.org/bugs/?7492]

== WML related features ==

=== Make [removeitem] able to only remove a specific image ===
Currently a [removeitem] always removes all images on the given hex. It should be made to support an image= key which, if given, would make it only remove that image. If not specified, then all images would be removed just like now.

--[[User:xonev|xonev]] 13 May 2008 - Patch submitted

=== WML configurable village income / upkeep ===
Preferably as a [scenario], [side] or [campaign] keys. As per FR #6301 [https://gna.org/bugs/?6301]

=== Add support of [if] for [scenario] ===
As per FR #4539 [https://gna.org/bugs/?4539]

=== Make [have_unit] optionaly use full SUF ===
[have_unit] by default uses SUF but does not apply it to recall list. Introduce an optional key that will allow to lift that limitation.

=== Side-specific results ===
Giving result=defeat or result=victory for specific sides. ([http://gna.org/bugs/index.php?4960 FR #4960]) -- [[User:dlr365|dlr365]] -- patch submitted [https://gna.org/bugs/index.php?4960]

=== Support for leaderless multiplayergames ===
Add support for the WML key victory_when_enemies_defeated= in the scenario tag during multiplayergames. ([https://gna.org/bugs/index.php?8106 FR #8106])

=== Allow a single [clear_variable] to clear multiple variables ===
Currently the name= key of [clear_variable] only takes a single variable name. However it'd be very handy to be able to clear multiple variables at the same time, so name= should also be made to also understand a comma-separated list:

[clear_variable]
name=var1,var2,var3
[/clear_variable]

Commas don't need to be valid characters in variable names, so the fact that it's ambiguous whether "name=var1,var2,var3" refers to three variables or just one variable named "var1,var2,var3" shouldn't cause any problems.

=== Other Ideas ===
See [[FutureWML]]; some ideas there are easier than others.

== Improvements to FormulaAI ==

Add new formula functions, or minor improvements to the formula language. Make it easier to debug the formula language.

== GUI related features ==
=== Change map paths from dots to dashes ===
Or even better allow dashes and allow choice between the two. As per FR #5522 [https://gna.org/bugs/?5522]

-------------------

Note at the moment Mordante is working on a new GUI system, these
changes will probably affect the way these items need to be implemented.
Contact Mordante on IRC before starting to work on these.

--[[User:SkeletonCrew|SkeletonCrew]] 14:04, 9 March 2008 (EDT)

=== Theme Changes ===

* show number of owned villages/total villages (FR: #3135) (--[[User:Alink|alink]] done but must update help, doc, tooltip...)
* allow custom themes to display values of WML variables ([http://gna.org/bugs/index.php?6209 FR #6209])
* hide the hourglass item from the statusbar when there is no timer

=== Widget Changes ===
* show side number, name and team association information in the status table
* make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* input history (chat, commands, ..) - note: rujasu is working on this feature

== Miscellaneous ==

=== More powerful village naming ===
'''Adding mountain names and other features to village names, having a second random name in village names'''

Currently the village naming engine has a very good structure that could allow
more powerfull names to be generated.
Understanding how it works should be quite easy, and a few usefull improvements could be added.

* Currently villages can use lake names and river names, this should be extended to other features like bridges, swamps, mountains etc...
* It would be nice to have a separate list of "first sylabus" and "last sylabus" for naming. That's not really needed in english, but some translations could use it
* Again, it is common to have villages with more than one "random" word in them. having a $name2 variable would be nice

ACardboardRobot 2/2/07

=== Debug Mode ===
* New debug command functionality (setting additional status.variables, possibly terrain)

=== Add minimal regexp to friend list ===

Lots of people use multiple nicks, usually postfixed with a number... it would be nice to have minimal regexp support in friend list to easily get who's there...

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]

EasyCoding

2008-05-25T20:43:39Z

Segfault: /* Enabling checking of damage dealt in WML */

DirectActionsWML

2008-05-19T20:57:20Z

Segfault: /* Direct actions */

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay.

The following tags are actions:
* '''[endlevel]''': ends the scenario.
** '''result''': before the scenario is over, all events with ''name=result'' are triggered. The message ''result_message'' with the heading ''result_heading'' (see [[LanguageWML]]) are displayed. If ''result=victory'', the player progresses to the next level; if ''result=defeat'', the game returns to the main menu. These last two are rarely used: ''result=continue'' behaves identically to ''result=victory'' except the player's gold is not reduced to 80%, and it does not bring up a "Victory" message or the gold changing message (since it doesn't change); ''result=continue_no_save'' works similarly, except the player is not asked whether to save the game, and is taken directly to the next scenario without any messages. Unless ''result=defeat'', the following keys can also be used:
** '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes.
** '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
** When the result is "victory" the following keys can be used:
*** '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
*** '''carryover_add''': if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.
* '''[unit]''': places a unit on the map. For syntax see [[SingleUnitWML]].{{Short Note:Predefined Macro|GENERIC_UNIT}}
* '''[recall]''': recalls a unit. The unit is recalled free of charge, and is placed near the leader.
** [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored.
** '''x,y''': the unit is placed here instead of next to the leader.
** '''show''': if not "no", display the unit being recalled.
* '''[teleport]''': teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be teleported.
** '''x,y''': the position to teleport to.
* '''[terrain_mask]''': changes the terrain on the map. See [[TerrainMaskWML]].
* '''[terrain]''': changes the terrain on the map.
** '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
** '''x,y''': the position (or range of positions) to change.
* '''[gold]''': give one side gold.
** '''amount''': the amount of gold to give.
** '''side''': (default=1) the number of the side to give the gold to.
* '''[unstore_unit]''': creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also '''[store_unit]''', '''[while]''' and [clear_variable] in [[InternalActionsWML]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
** '''variable''': the name of the variable.
** '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''text''': (translatable) floating text to display above the unit, such as a damage amount
** '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''advance''': if the XP has been modified then there will be tried to advance the unit, default true.
* '''[allow_recruit]''': allows a side to recruit units it couldn't previously recruit.
** '''type''': the types of units that the side can now recruit.
** '''side''': (default=1) the number of the side that is being allowed to recruit the units.
* '''[disallow_recruit]''': prevents a side from recruiting units it could previously recruit.
** '''type''': the types of units that the side can no longer recruit.
** '''side''': (default=1) the number of the side that may no longer recruit the units.
* '''[set_recruit]''': sets the units a side can recruit.
** '''recruit''': the types of units that the side can now recruit.
** '''side''': (default=1) the number of the side that is having its recruitment set.
* '''[modify_side]''': modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'
** '''side''': (default=1) the number of the side that is to be changed.
** '''income''': the income given at the begining of each turn.
** '''team_name''': the team in which the side plays the scenario.
** '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
** '''gold''': the amount of gold the side owns.
** '''village_gold''': the income setting per village for the side.
** '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag.
** '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
** '''shroud''': a boolean string describing the status of Shroud for the side.
** {{DevFeature}} '''[ai]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''[modify_turns]''': modifies the turn limit in the middle of a scenario.
** '''value''': the new turn limit.
** '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
* '''[capture_village]''': changes the ownership of a village.
** '''side''': the side that takes control of the village. If not given, the village will become neutral.
** '''x, y''': the location of the village.
* '''[kill]''': Removes all units (including units in a recall list) that match the filter from the game.
** [[StandardUnitFilter]]: selection criterion
** '''animate''': if 'yes', displays the unit dying (fading away).
** '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that any 'die' events triggered by this are executed immediately, interrupting the current event and thus causing the x1, y1, x2, and y2 variables to be reset for that 'die' event, which in turn causes those variables to be invalid for the remainder of this event.
* '''[unstone]''': Unstones all units that match the filter.
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be unstoned. If no unit matches the filter, then nothing happens (probably). If absent, all units on the map are unstoned.
* '''[object]''': gives some unit an object and removes all items on the tile the unit is on.
** '''id''': when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per level. In a campaign objects with the same id can be assigned once per level.
** '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
** '''duration''': if 'level', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).
** '''[filter]''': [[StandardUnitFilter]] the first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
** '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
** '''silent''': whether or not messages should be suppressed. Default is "no".
** '''image''': the displayed image of the object.
** '''name''': (translatable) displayed as a caption of the image.

** '''user_description''': {{DevFeature}} (translatable) displayed as a message of the image. In 1.4 and older versions this is just '''description'''; that will still be expected for compatibility.
** '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.
** If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
** The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.
* '''[remove_shroud]''': removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
** '''side''': (default=1) the side for which to remove shroud.
** [[StandardLocationFilter]]: the range of tiles for which shroud should be removed.
* '''[place_shroud]''': places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
** '''side''': (default=1) the side for which to place shroud.
** [[StandardLocationFilter]]: the range of tiles on which shroud should be placed.
* '''[allow_undo]''': allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move is undone. It is up to the scenario designer to avoid abusing this command.
** Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the move the first time.
* {{DevFeature}} '''[heal_unit]''': heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser than the parameter '''amount''' if the unit is fully healed).
** '''[filter]''': [[StandardUnitFilter]] the first unit matching the filter will be healed.
** '''[secondary_unit_filter]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true).
** '''amount''': the maximum points the unit will be healed.
** '''animate''': a boolean which indicate if the healing animations must be played.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

DirectActionsWML

2008-05-19T20:56:23Z

Segfault: /* Direct actions */ adding heal_unit action

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay.

The following tags are actions:
* '''[endlevel]''': ends the scenario.
** '''result''': before the scenario is over, all events with ''name=result'' are triggered. The message ''result_message'' with the heading ''result_heading'' (see [[LanguageWML]]) are displayed. If ''result=victory'', the player progresses to the next level; if ''result=defeat'', the game returns to the main menu. These last two are rarely used: ''result=continue'' behaves identically to ''result=victory'' except the player's gold is not reduced to 80%, and it does not bring up a "Victory" message or the gold changing message (since it doesn't change); ''result=continue_no_save'' works similarly, except the player is not asked whether to save the game, and is taken directly to the next scenario without any messages. Unless ''result=defeat'', the following keys can also be used:
** '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes.
** '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
** When the result is "victory" the following keys can be used:
*** '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
*** '''carryover_add''': if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.
* '''[unit]''': places a unit on the map. For syntax see [[SingleUnitWML]].{{Short Note:Predefined Macro|GENERIC_UNIT}}
* '''[recall]''': recalls a unit. The unit is recalled free of charge, and is placed near the leader.
** [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored.
** '''x,y''': the unit is placed here instead of next to the leader.
** '''show''': if not "no", display the unit being recalled.
* '''[teleport]''': teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be teleported.
** '''x,y''': the position to teleport to.
* '''[terrain_mask]''': changes the terrain on the map. See [[TerrainMaskWML]].
* '''[terrain]''': changes the terrain on the map.
** '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
** '''x,y''': the position (or range of positions) to change.
* '''[gold]''': give one side gold.
** '''amount''': the amount of gold to give.
** '''side''': (default=1) the number of the side to give the gold to.
* '''[unstore_unit]''': creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also '''[store_unit]''', '''[while]''' and [clear_variable] in [[InternalActionsWML]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
** '''variable''': the name of the variable.
** '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''text''': (translatable) floating text to display above the unit, such as a damage amount
** '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''advance''': if the XP has been modified then there will be tried to advance the unit, default true.
* '''[allow_recruit]''': allows a side to recruit units it couldn't previously recruit.
** '''type''': the types of units that the side can now recruit.
** '''side''': (default=1) the number of the side that is being allowed to recruit the units.
* '''[disallow_recruit]''': prevents a side from recruiting units it could previously recruit.
** '''type''': the types of units that the side can no longer recruit.
** '''side''': (default=1) the number of the side that may no longer recruit the units.
* '''[set_recruit]''': sets the units a side can recruit.
** '''recruit''': the types of units that the side can now recruit.
** '''side''': (default=1) the number of the side that is having its recruitment set.
* '''[modify_side]''': modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'
** '''side''': (default=1) the number of the side that is to be changed.
** '''income''': the income given at the begining of each turn.
** '''team_name''': the team in which the side plays the scenario.
** '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
** '''gold''': the amount of gold the side owns.
** '''village_gold''': the income setting per village for the side.
** '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag.
** '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
** '''shroud''': a boolean string describing the status of Shroud for the side.
** {{DevFeature}} '''[ai]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''[modify_turns]''': modifies the turn limit in the middle of a scenario.
** '''value''': the new turn limit.
** '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
* '''[capture_village]''': changes the ownership of a village.
** '''side''': the side that takes control of the village. If not given, the village will become neutral.
** '''x, y''': the location of the village.
* '''[kill]''': Removes all units (including units in a recall list) that match the filter from the game.
** [[StandardUnitFilter]]: selection criterion
** '''animate''': if 'yes', displays the unit dying (fading away).
** '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that any 'die' events triggered by this are executed immediately, interrupting the current event and thus causing the x1, y1, x2, and y2 variables to be reset for that 'die' event, which in turn causes those variables to be invalid for the remainder of this event.
* '''[unstone]''': Unstones all units that match the filter.
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be unstoned. If no unit matches the filter, then nothing happens (probably). If absent, all units on the map are unstoned.
* '''[object]''': gives some unit an object and removes all items on the tile the unit is on.
** '''id''': when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per level. In a campaign objects with the same id can be assigned once per level.
** '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
** '''duration''': if 'level', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).
** '''[filter]''': [[StandardUnitFilter]] the first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
** '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
** '''silent''': whether or not messages should be suppressed. Default is "no".
** '''image''': the displayed image of the object.
** '''name''': (translatable) displayed as a caption of the image.

** '''user_description''': {{DevFeature}} (translatable) displayed as a message of the image. In 1.4 and older versions this is just '''description'''; that will still be expected for compatibility.
** '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.
** If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
** The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.
* '''[remove_shroud]''': removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
** '''side''': (default=1) the side for which to remove shroud.
** [[StandardLocationFilter]]: the range of tiles for which shroud should be removed.
* '''[place_shroud]''': places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
** '''side''': (default=1) the side for which to place shroud.
** [[StandardLocationFilter]]: the range of tiles on which shroud should be placed.
* '''[allow_undo]''': allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move is undone. It is up to the scenario designer to avoid abusing this command.
** Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the move the first time.
* {{DevFeature}} '''[heal_unit]''': heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser than the parameter '''amount''' if the unit is fully healed).
** '''[filter]''': [[StandardUnitFilter]] the first unit matching the filter will be healed.
** '''[secondary_unit_filter]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to true).
** '''amount''': the maximum points the units will be healed.
** '''animate''': a boolean which indicate if the healing animations must be played.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

DirectActionsWML

2008-05-18T14:48:34Z

Segfault: /* Direct actions */

{{WML Tags}}
== Direct actions ==

Direct actions are actions that have a direct effect on gameplay.

The following tags are actions:
* '''[endlevel]''': ends the scenario.
** '''result''': before the scenario is over, all events with ''name=result'' are triggered. The message ''result_message'' with the heading ''result_heading'' (see [[LanguageWML]]) are displayed. If ''result=victory'', the player progresses to the next level; if ''result=defeat'', the game returns to the main menu. These last two are rarely used: ''result=continue'' behaves identically to ''result=victory'' except the player's gold is not reduced to 80%, and it does not bring up a "Victory" message or the gold changing message (since it doesn't change); ''result=continue_no_save'' works similarly, except the player is not asked whether to save the game, and is taken directly to the next scenario without any messages. Unless ''result=defeat'', the following keys can also be used:
** '''bonus''': whether the player should get bonus gold (maximum possible gold that could have been earned by waiting the level out). The default is bonus=yes.
** '''next_scenario''': (default specified in '''[scenario]''' tag) the ID of the next scenario that should be played. All units that side 1 controls at this point become available for recall in ''next_scenario''.
** When the result is "victory" the following keys can be used:
*** '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.
*** '''carryover_add''': if true the gold will be added to the starting gold the next scenario, if false the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is false.
* '''[unit]''': places a unit on the map. For syntax see [[SingleUnitWML]].{{Short Note:Predefined Macro|GENERIC_UNIT}}
* '''[recall]''': recalls a unit. The unit is recalled free of charge, and is placed near the leader.
** [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored.
** '''x,y''': the unit is placed here instead of next to the leader.
** '''show''': if not "no", display the unit being recalled.
* '''[teleport]''': teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be teleported.
** '''x,y''': the position to teleport to.
* '''[terrain_mask]''': changes the terrain on the map. See [[TerrainMaskWML]].
* '''[terrain]''': changes the terrain on the map.
** '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.
** '''x,y''': the position (or range of positions) to change.
* '''[gold]''': give one side gold.
** '''amount''': the amount of gold to give.
** '''side''': (default=1) the number of the side to give the gold to.
* '''[unstore_unit]''': creates a unit from a game variable, and activates it on the playing field. This must be a specific variable describing a unit, and may not be an array -- to unstore an entire array, iterate over it. The variable is not cleared. See also '''[store_unit]''', '''[while]''' and [clear_variable] in [[InternalActionsWML]]. Note units with a negative amount of hitpoints will be unstored with 1 hitpoint.
** '''variable''': the name of the variable.
** '''find_vacant''': whether the unit should be placed on the nearest vacant tile to its specified location. If this is set to 'no'(default), then any unit on the same tile as the unit being unstored will be destroyed.
** '''text''': (translatable) floating text to display above the unit, such as a damage amount
** '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. You may find it convenient to use the {COLOR_HARM} or {COLOR_HEAL} macro instead. (Use {COLOR_HARM} or {COLOR_HEAL} instead of the whole red,green,blue= line.)
** '''advance''': if the XP has been modified then there will be tried to advance the unit, default true.
* '''[allow_recruit]''': allows a side to recruit units it couldn't previously recruit.
** '''type''': the types of units that the side can now recruit.
** '''side''': (default=1) the number of the side that is being allowed to recruit the units.
* '''[disallow_recruit]''': prevents a side from recruiting units it could previously recruit.
** '''type''': the types of units that the side can no longer recruit.
** '''side''': (default=1) the number of the side that may no longer recruit the units.
* '''[set_recruit]''': sets the units a side can recruit.
** '''recruit''': the types of units that the side can now recruit.
** '''side''': (default=1) the number of the side that is having its recruitment set.
* '''[modify_side]''': modifies some details of a given side in the middle of a scenario. '''The following listed properties are the only properties that [modify_side] can affect!'
** '''side''': (default=1) the number of the side that is to be changed.
** '''income''': the income given at the begining of each turn.
** '''team_name''': the team in which the side plays the scenario.
** '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.
** '''gold''': the amount of gold the side owns.
** '''village_gold''': the income setting per village for the side.
** '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag.
** '''fog''': a boolean string (yes/no) describing the status of Fog for the side.
** '''shroud''': a boolean string describing the status of Shroud for the side.
** {{DevFeature}} '''[ai]''': replaces a side's AI parameters with the new specified ones. Uses the same syntax described in [[AiWML]].
* '''[modify_turns]''': modifies the turn limit in the middle of a scenario.
** '''value''': the new turn limit.
** '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).
* '''[capture_village]''': changes the ownership of a village.
** '''side''': the side that takes control of the village. If not given, the village will become neutral.
** '''x, y''': the location of the village.
* '''[kill]''': Removes all units (including units in a recall list) that match the filter from the game.
** [[StandardUnitFilter]]: selection criterion
** '''animate''': if 'yes', displays the unit dying (fading away).
** '''fire_event''': if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that any 'die' events triggered by this are executed immediately, interrupting the current event and thus causing the x1, y1, x2, and y2 variables to be reset for that 'die' event, which in turn causes those variables to be invalid for the remainder of this event.
* '''[unstone]''': Unstones all units that match the filter.
** '''[filter]''': [[StandardUnitFilter]] all units matching the filter will be unstoned. If no unit matches the filter, then nothing happens (probably). If absent, all units on the map are unstoned.
* '''[object]''': gives some unit an object and removes all items on the tile the unit is on.
** '''id''': when the object is picked up, a flag is set for ''id''. The object cannot be picked up if a flag for ''id'' has been set. This means that any object with an id can only be used once, even if first_time_only=no is set for the event. This restriction is per level. In a campaign objects with the same id can be assigned once per level.
** '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].
** '''duration''': if 'level', effects only last until the end of the level (note : 'level' is the scenario, so this doesn't mean it last until the unit levels-up).
** '''[filter]''': [[StandardUnitFilter]] the first unit found that matches the filter will be given the object. If no unit matches the filter, then a message is displayed and the object is not removed.
** '''[then]''': a subtag that lets you execute actions if the filter conditions are met. The most common action that should be inside here is a '''[removeitem]''' tag, but you could probably put any tags that otherwise work in a [then] tag.
** '''silent''': whether or not messages should be suppressed. Default is "no".
** '''image''': the displayed image of the object.
** '''name''': (translatable) displayed as a caption of the image.

** '''user_description''': {{DevFeature}} (translatable) displayed as a message of the image. In 1.4 and older versions this is just '''description'''; that will still be expected for compatibility.
** '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.
** If you do not supply a filter, the object action will be applied to a unit at the location of the moveto event. Currently this isn't recommended as it is not clear that this will continue working this way. Instead it is better to explicitly include a location filter.
** The object action does not act on units in the recall list. There is a feature request in to allow this, but it is not clear whether or not it will be accepted.
* '''[remove_shroud]''': removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).
** '''side''': (default=1) the side for which to remove shroud.
** [[StandardLocationFilter]]: the range of tiles for which shroud should be removed.
* '''[place_shroud]''': places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).
** '''side''': (default=1) the side for which to place shroud.
** [[StandardLocationFilter]]: the range of tiles on which shroud should be placed.
* '''[allow_undo]''': allows the player to undo the event that this tag is inside. Has an effect only inside moveto events. If the move is undone, only the position of the unit will be restored; any altered variables or changes to the game will remain changed after the move is undone. It is up to the scenario designer to avoid abusing this command.
** Technically, if '''[allow_undo]''' is inside an '''[event]''' with ''first_time_only=yes'' (the default setting), and the user undoes the event, then the state of the game has changed in this way: the event will not fire a second time, even though the user undid the move the first time.
* {{DevFeature}} '''[heal_unit]''': heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be lesser than the parameter '''amount''' if the unit is fully healed).
** [filter]: StandardUnitFilter the first unit matching the filter will be healed.
** amount: the maximum points the units will be healed.

== Useful Macros ==
There are some predefined macros that you find useful for direct actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])
* '''{FULL_HEAL}''': Brings a unit to full HP
* '''{LOYAL_UNIT}''': Create a loyal unit
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain

== See Also ==

* [[InternalActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

EasyCoding

2008-04-06T12:41:16Z

Segfault: Undo revision 25120 by Segfault (Talk)

== Foreword ==
This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

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

--[[User:Boucman|Boucman]] 20:48, 3 October 2006 (CEST)

Since bugs are sometimes a good opportunity to get a first idea of the code, i will add some here that are easy to fix as soon as i stumble upon them (the one i had in mind is fixed already ;-).

--Yogi Bear, 28 February 2008

== MP related features ==
=== Add TTL to wesnothd bans ===
As per FR #3638 [https://gna.org/bugs/?3638]
=== Use different font for in-game chat ===
Since commas and dots are apparently hard to tell apart. As per FR #7470 [https://gna.org/bugs/?7470]
=== Allow lists for /ignore and similar ===
As per FR #7492 [https://gna.org/bugs/?7492]

== WML related features ==

=== WML configurable village income / upkeep ===
Preferably as a [scenario], [side] or [campaign] keys. As per FR #6301 [https://gna.org/bugs/?6301]
=== Add support of [if] for [scenario] ===
As per FR #4539 [https://gna.org/bugs/?4539]

=== Make [have_unit] optionaly use full SUF ===
[have_unit] by default uses SUF but does not apply it to recall list. Introduce an optional key that will allow to lift that limitation.
=== Side-specific results ===
Giving result=defeat or result=victory for specific sides. ([http://gna.org/bugs/index.php?4960 FR #4960]) -- [[User:dlr365|dlr365]] -- patch submitted [https://gna.org/bugs/index.php?4960]

=== Enabling checking of damage dealt in WML ===
A WML variable should be set when triggering some combat-related events, allowing WML to know the amount of damage being dealt. ([http://gna.org/bugs/index.php?7673 FR #7673])
=== Support for leaderless multiplayergames ===
Add support for the WML key victory_when_enemies_defeated= in the scenario tag during multiplayergames. ([https://gna.org/bugs/index.php?8106 FR #8106])
=== Other Ideas ===
See [[FutureWML]]; some ideas there are easier than others.

== Improvements to FormulaAI ==

Add new formula functions, or minor improvements to the formula language. Make it easier to debug the formula language.

== GUI related features ==
=== Change map paths from dots to dashes ===
Or even better allow dashes and allow choice between the two. As per FR #5522 [https://gna.org/bugs/?5522]

-------------------

Note at the moment Mordante is working on a new GUI system, these
changes will probably affect the way these items need to be implemented.
Contact Mordante on IRC before starting to work on these.

--[[User:SkeletonCrew|SkeletonCrew]] 14:04, 9 March 2008 (EDT)

=== Theme Changes ===
* show number of owned villages/total villages (FR: #3135) (--[[User:Alink|alink]] done but must update help, doc, tooltip...)
* allow custom themes to display values of WML variables ([http://gna.org/bugs/index.php?6209 FR #6209])
* hide the hourglass item from the statusbar when there is no timer

=== Widget Changes ===
* show side number, name and team association information in the status table
* make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* input history (chat, commands, ..) - note: rujasu is working on this feature

== Miscellaneous ==
=== More powerful village naming ===
'''Adding mountain names and other features to village names, having a second random name in village names'''

Currently the village naming engine has a very good structure that could allow
more powerfull names to be generated.
Understanding how it works should be quite easy, and a few usefull improvements could be added.

* Currently villages can use lake names and river names, this should be extended to other features like bridges, swamps, mountains etc...
* It would be nice to have a separate list of "first sylabus" and "last sylabus" for naming. That's not really needed in english, but some translations could use it
* Again, it is common to have villages with more than one "random" word in them. having a $name2 variable would be nice

ACardboardRobot 2/2/07

=== Debug Mode ===
* New debug command functionality (setting additional status.variables, possibly terrain)

=== Add minimal regexp to friend list ===

Lots of people use multiple nicks, usually postfixed with a number... it would be nice to have minimal regexp support in friend list to easily get who's there...

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]

EasyCoding

2008-04-06T12:40:42Z

Segfault: /* WML related features */

== Foreword ==
This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

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

--[[User:Boucman|Boucman]] 20:48, 3 October 2006 (CEST)

Since bugs are sometimes a good opportunity to get a first idea of the code, i will add some here that are easy to fix as soon as i stumble upon them (the one i had in mind is fixed already ;-).

--Yogi Bear, 28 February 2008

== MP related features ==
=== Add TTL to wesnothd bans ===
As per FR #3638 [https://gna.org/bugs/?3638]
=== Use different font for in-game chat ===
Since commas and dots are apparently hard to tell apart. As per FR #7470 [https://gna.org/bugs/?7470]
=== Allow lists for /ignore and similar ===
As per FR #7492 [https://gna.org/bugs/?7492]

== WML related features ==

=== WML configurable village income / upkeep ===
Preferably as a [scenario], [side] or [campaign] keys. As per FR #6301 [https://gna.org/bugs/?6301]
=== Add support of [if] for [scenario] ===
As per FR #4539 [https://gna.org/bugs/?4539]
=== Make [have_unit] optionaly use full SUF ===
[have_unit] by default uses SUF but does not apply it to recall list. Introduce an optional key that will allow to lift that limitation.
=== Side-specific results ===
Giving result=defeat or result=victory for specific sides. ([http://gna.org/bugs/index.php?4960 FR #4960]) -- [[User:dlr365|dlr365]] -- patch submitted [https://gna.org/bugs/index.php?4960]

=== Enabling checking of damage dealt in WML ===
A WML variable should be set when triggering some combat-related events, allowing WML to know the amount of damage being dealt. ([http://gna.org/bugs/index.php?7673 FR #7673])
=== Support for leaderless multiplayergames ===
Add support for the WML key victory_when_enemies_defeated= in the scenario tag during multiplayergames. ([https://gna.org/bugs/index.php?8106 FR #8106])
=== Other Ideas ===
See [[FutureWML]]; some ideas there are easier than others.

== Improvements to FormulaAI ==

Add new formula functions, or minor improvements to the formula language. Make it easier to debug the formula language.

== GUI related features ==
=== Change map paths from dots to dashes ===
Or even better allow dashes and allow choice between the two. As per FR #5522 [https://gna.org/bugs/?5522]

-------------------

Note at the moment Mordante is working on a new GUI system, these
changes will probably affect the way these items need to be implemented.
Contact Mordante on IRC before starting to work on these.

--[[User:SkeletonCrew|SkeletonCrew]] 14:04, 9 March 2008 (EDT)

=== Theme Changes ===
* show number of owned villages/total villages (FR: #3135) (--[[User:Alink|alink]] done but must update help, doc, tooltip...)
* allow custom themes to display values of WML variables ([http://gna.org/bugs/index.php?6209 FR #6209])
* hide the hourglass item from the statusbar when there is no timer

=== Widget Changes ===
* show side number, name and team association information in the status table
* make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* input history (chat, commands, ..) - note: rujasu is working on this feature

== Miscellaneous ==
=== More powerful village naming ===
'''Adding mountain names and other features to village names, having a second random name in village names'''

Currently the village naming engine has a very good structure that could allow
more powerfull names to be generated.
Understanding how it works should be quite easy, and a few usefull improvements could be added.

* Currently villages can use lake names and river names, this should be extended to other features like bridges, swamps, mountains etc...
* It would be nice to have a separate list of "first sylabus" and "last sylabus" for naming. That's not really needed in english, but some translations could use it
* Again, it is common to have villages with more than one "random" word in them. having a $name2 variable would be nice

ACardboardRobot 2/2/07

=== Debug Mode ===
* New debug command functionality (setting additional status.variables, possibly terrain)

=== Add minimal regexp to friend list ===

Lots of people use multiple nicks, usually postfixed with a number... it would be nice to have minimal regexp support in friend list to easily get who's there...

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]

EasyCoding

2008-04-06T12:40:04Z

Segfault: /* Allow an event multiple types */

== Foreword ==
This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

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

--[[User:Boucman|Boucman]] 20:48, 3 October 2006 (CEST)

Since bugs are sometimes a good opportunity to get a first idea of the code, i will add some here that are easy to fix as soon as i stumble upon them (the one i had in mind is fixed already ;-).

--Yogi Bear, 28 February 2008

== MP related features ==
=== Add TTL to wesnothd bans ===
As per FR #3638 [https://gna.org/bugs/?3638]
=== Use different font for in-game chat ===
Since commas and dots are apparently hard to tell apart. As per FR #7470 [https://gna.org/bugs/?7470]
=== Allow lists for /ignore and similar ===
As per FR #7492 [https://gna.org/bugs/?7492]

== WML related features ==

=== WML configurable village income / upkeep ===
Preferably as a [scenario], [side] or [campaign] keys. As per FR #6301 [https://gna.org/bugs/?6301]
=== Add support of [if] for [scenario] ===
As per FR #4539 [https://gna.org/bugs/?4539]

=== Make [have_unit] optionaly use full SUF ===
[have_unit] by default uses SUF but does not apply it to recall list. Introduce an optional key that will allow to lift that limitation.
=== Side-specific results ===
Giving result=defeat or result=victory for specific sides. ([http://gna.org/bugs/index.php?4960 FR #4960]) -- [[User:dlr365|dlr365]] -- patch submitted [https://gna.org/bugs/index.php?4960]

=== Enabling checking of damage dealt in WML ===
A WML variable should be set when triggering some combat-related events, allowing WML to know the amount of damage being dealt. ([http://gna.org/bugs/index.php?7673 FR #7673])
=== Support for leaderless multiplayergames ===
Add support for the WML key victory_when_enemies_defeated= in the scenario tag during multiplayergames. ([https://gna.org/bugs/index.php?8106 FR #8106])
=== Other Ideas ===
See [[FutureWML]]; some ideas there are easier than others.

== Improvements to FormulaAI ==

Add new formula functions, or minor improvements to the formula language. Make it easier to debug the formula language.

== GUI related features ==
=== Change map paths from dots to dashes ===
Or even better allow dashes and allow choice between the two. As per FR #5522 [https://gna.org/bugs/?5522]

-------------------

Note at the moment Mordante is working on a new GUI system, these
changes will probably affect the way these items need to be implemented.
Contact Mordante on IRC before starting to work on these.

--[[User:SkeletonCrew|SkeletonCrew]] 14:04, 9 March 2008 (EDT)

=== Theme Changes ===
* show number of owned villages/total villages (FR: #3135) (--[[User:Alink|alink]] done but must update help, doc, tooltip...)
* allow custom themes to display values of WML variables ([http://gna.org/bugs/index.php?6209 FR #6209])
* hide the hourglass item from the statusbar when there is no timer

=== Widget Changes ===
* show side number, name and team association information in the status table
* make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* input history (chat, commands, ..) - note: rujasu is working on this feature

== Miscellaneous ==
=== More powerful village naming ===
'''Adding mountain names and other features to village names, having a second random name in village names'''

Currently the village naming engine has a very good structure that could allow
more powerfull names to be generated.
Understanding how it works should be quite easy, and a few usefull improvements could be added.

* Currently villages can use lake names and river names, this should be extended to other features like bridges, swamps, mountains etc...
* It would be nice to have a separate list of "first sylabus" and "last sylabus" for naming. That's not really needed in english, but some translations could use it
* Again, it is common to have villages with more than one "random" word in them. having a $name2 variable would be nice

ACardboardRobot 2/2/07

=== Debug Mode ===
* New debug command functionality (setting additional status.variables, possibly terrain)

=== Add minimal regexp to friend list ===

Lots of people use multiple nicks, usually postfixed with a number... it would be nice to have minimal regexp support in friend list to easily get who's there...

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]

EventWML

2008-04-06T12:39:11Z

Segfault: /* The [event] tag */

{{WML Tags}}
== The [event] tag ==

This tag is a subtag of [scenario] (or [unit] - see '''event''', [[UnitWML]]) 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:
* '''name''': this is not like a normal 'name' key. It is a basic description of when the event will trigger. {{DevFeature}} '''name''' can accept a list of commas separated descriptions for which the event must be triggered. Example: '''name= attacker_misses, defender_misses'''.
* '''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 a side is about to start its turn. Before 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. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.
* '''turn refresh''': this event triggers just before a side is taking control after healing, calculating income, and restoring unit movement and status.
* '''turn X''': (for X some number) 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=yes''' (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 side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.

Filters can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]

* '''moveto'''': triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on.
* '''sighted''': this event triggers when the primary unit moves to a location where the secondary unit is in sight range of the primary unit. Works only in shroud or fog.
* '''attack''': this event triggers when the primary unit attacks the secondary_unit.
* '''attacker_hits''': this event triggers when the the primary unit (the attacker) hits the secondary unit (the defender).
* '''attacker_misses''': same as ''attacker_hits'', but is triggered when the attacker misses.
* '''defender_hits''': this event triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender).
* '''defender_misses''': same as ''defender_hits'', but is triggered when the defender misses.
* '''attack_end''': 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 the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).
* '''last breath''': this event triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.
* '''die''': this event triggers when the primary unit is killed by the secondary unit.
* '''capture''': this event triggers when the 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 the 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.). {{DevFeature}} The '''recruit''' will no longer triggers on recalls.
* '''prerecruit''': this event triggers when the primary unit is recruited, but before it is displayed. {{DevFeature}} The '''prerecruit''' will no longer triggers on recalls.
* '''advance''': this event triggers just before the primary unit is going to advance to another unit.
* '''post_advance''': this event triggers just after the primary unit has advanced to another unit.
* '''select''': triggers when the primary unit is selected. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''
* '''menu item X''': triggers when a WML menu item with id=X is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''
* {{DevFeature}} '''prerecall''': triggers when a unit is recalled, but before it is displayed. This event is not trigger when a unit is recruit.
* {{DevFeature}} '''recall''': triggers after a unit is recalled. This event is not trigger when a unit is recruit.
* {{DevFeature}} other events with a custom name may be invoked from [fire_event]

An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.

The primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the speaker= key. 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 the primary unit matches this filter.
** [[StandardUnitFilter]]: selection criteria
* '''[filter_second]''': is like [filter], but for the secondary unit.
** [[StandardUnitFilter]]: selection criteria
* '''[special_filter]''' and '''[special_filter_second]''': can be used to set some additional filtering criteria for the primary unit and the 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 code for the terrain the unit is on.

=== Actions triggered by [event] ===

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

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

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

=== Nested events ===

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

Example:

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

# moving to 5,8 will trigger this event only on turn 10 and after
[/event]
[/event]

== See Also ==

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

[[Category: WML Reference]]

EasyCoding

2008-04-04T21:12:42Z

Segfault: /* Allow an event multiple types */

== Foreword ==
This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

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

--[[User:Boucman|Boucman]] 20:48, 3 October 2006 (CEST)

Since bugs are sometimes a good opportunity to get a first idea of the code, i will add some here that are easy to fix as soon as i stumble upon them (the one i had in mind is fixed already ;-).

--Yogi Bear, 28 February 2008

== MP related features ==
=== Add TTL to wesnothd bans ===
As per FR #3638 [https://gna.org/bugs/?3638]
=== Use different font for in-game chat ===
Since commas and dots are apparently hard to tell apart. As per FR #7470 [https://gna.org/bugs/?7470]
=== Allow lists for /ignore and similar ===
As per FR #7492 [https://gna.org/bugs/?7492]

== WML related features ==

=== WML configurable village income / upkeep ===
Preferably as a [scenario], [side] or [campaign] keys. As per FR #6301 [https://gna.org/bugs/?6301]
=== Add support of [if] for [scenario] ===
As per FR #4539 [https://gna.org/bugs/?4539]
=== Allow an event multiple types ===
--[[User:Segfault|Segfault]] 04 April 2008

At the moment an [event] can only trigger on one kind of an event: a '''name=moveto''' only triggers on a move, a '''name=die''' only triggers on a death, and so on. However, it'd sometimes be useful to be able to define a list of types: if you'd have an [event] with '''name=attacker_misses,defender_misses''', then that event would trigger both on the attacker missing and defender missing. Currently, you'd have to create two identical [event]s to do this.

=== Make [have_unit] optionaly use full SUF ===
[have_unit] by default uses SUF but does not apply it to recall list. Introduce an optional key that will allow to lift that limitation.
=== Side-specific results ===
Giving result=defeat or result=victory for specific sides. ([http://gna.org/bugs/index.php?4960 FR #4960]) -- [[User:dlr365|dlr365]] -- patch submitted [https://gna.org/bugs/index.php?4960]

=== Enabling checking of damage dealt in WML ===
A WML variable should be set when triggering some combat-related events, allowing WML to know the amount of damage being dealt. ([http://gna.org/bugs/index.php?7673 FR #7673])
=== Support for leaderless multiplayergames ===
Add support for the WML key victory_when_enemies_defeated= in the scenario tag during multiplayergames. ([https://gna.org/bugs/index.php?8106 FR #8106])
=== Other Ideas ===
See [[FutureWML]]; some ideas there are easier than others.

== Improvements to FormulaAI ==

Add new formula functions, or minor improvements to the formula language. Make it easier to debug the formula language.

== GUI related features ==
=== Change map paths from dots to dashes ===
Or even better allow dashes and allow choice between the two. As per FR #5522 [https://gna.org/bugs/?5522]

-------------------

Note at the moment Mordante is working on a new GUI system, these
changes will probably affect the way these items need to be implemented.
Contact Mordante on IRC before starting to work on these.

--[[User:SkeletonCrew|SkeletonCrew]] 14:04, 9 March 2008 (EDT)

=== Theme Changes ===
* show number of owned villages/total villages (FR: #3135) (--[[User:Alink|alink]] done but must update help, doc, tooltip...)
* allow custom themes to display values of WML variables ([http://gna.org/bugs/index.php?6209 FR #6209])
* hide the hourglass item from the statusbar when there is no timer

=== Widget Changes ===
* show side number, name and team association information in the status table
* make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* input history (chat, commands, ..) - note: rujasu is working on this feature

== Miscellaneous ==
=== More powerful village naming ===
'''Adding mountain names and other features to village names, having a second random name in village names'''

Currently the village naming engine has a very good structure that could allow
more powerfull names to be generated.
Understanding how it works should be quite easy, and a few usefull improvements could be added.

* Currently villages can use lake names and river names, this should be extended to other features like bridges, swamps, mountains etc...
* It would be nice to have a separate list of "first sylabus" and "last sylabus" for naming. That's not really needed in english, but some translations could use it
* Again, it is common to have villages with more than one "random" word in them. having a $name2 variable would be nice

ACardboardRobot 2/2/07

=== Debug Mode ===
* New debug command functionality (setting additional status.variables, possibly terrain)

=== Add minimal regexp to friend list ===

Lots of people use multiple nicks, usually postfixed with a number... it would be nice to have minimal regexp support in friend list to easily get who's there...

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]

EventWML

2008-04-04T19:55:09Z

Segfault: /* The [event] tag */

{{WML Tags}}
== The [event] tag ==

This tag is a subtag of [scenario] (or [unit] - see '''event''', [[UnitWML]]) 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:
* '''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 a side is about to start its turn. Before 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. This is before any healing takes place for that side, before calculating income, and before restoring unit movement and status.
* '''turn refresh''': this event triggers just before a side is taking control after healing, calculating income, and restoring unit movement and status.
* '''turn X''': (for X some number) 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=yes''' (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 side. This is called after ''side turn'', and thus the WML variable '''side_number''' still holds the number of this side.

Filters can be applied to the following event triggers (see [[FilterWML]]; see also below). The actions specified in the event tag will be executed only if the filter returns true.
These event triggers are all actions by units ('''moveto''', '''attack''') or things that happen to units ('''recruit''', '''advance'''). When one of these events is triggered, the position of the active unit (referred to as the '''primary unit''') is stored in the variables '''x1''' and '''y1''' and the position of any unit that primary unit does something to is stored in the variables '''x2''' and '''y2''' (this unit is referred to as the '''secondary unit''' below). '' These units are also automatically stored in the variables 'unit' and 'second_unit' as if they had been stored using the '''[store_unit]''' tag. see [[SingleUnitWML]]

* '''moveto'''': triggers after the primary unit moves. Typically this is used when the primary unit gets to a particular location and a filter for the location of the primary unit is included; remember that this is the location that the primary unit lands on, not the location it started on or any location it travels on.
* '''sighted''': this event triggers when the primary unit moves to a location where the secondary unit is in sight range of the primary unit. Works only in shroud or fog.
* '''attack''': this event triggers when the primary unit attacks the secondary_unit.
* '''attacker_hits''': this event triggers when the the primary unit (the attacker) hits the secondary unit (the defender).
* '''attacker_misses''': same as ''attacker_hits'', but is triggered when the attacker misses.
* '''defender_hits''': this event triggers when the primary unit (the attacker) is hit in retaliation by the secondary unit (the defender).
* '''defender_misses''': same as ''defender_hits'', but is triggered when the defender misses.
* '''attack_end''': 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 the primary unit is hit by an attack with the 'stones' ability (See ''stones'', [[AbilitiesWML]]) by the secondary unit (the unit with the 'stones' ability).
* '''last breath''': this event triggers when the primary unit is killed by the secondary unit, but before the death animation is triggered.
* '''die''': this event triggers when the primary unit is killed by the secondary unit.
* '''capture''': this event triggers when the 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 the 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.). {{DevFeature}} The '''recruit''' will no longer triggers on recalls.
* '''prerecruit''': this event triggers when the primary unit is recruited, but before it is displayed. {{DevFeature}} The '''prerecruit''' will no longer triggers on recalls.
* '''advance''': this event triggers just before the primary unit is going to advance to another unit.
* '''post_advance''': this event triggers just after the primary unit has advanced to another unit.
* '''select''': triggers when the primary unit is selected. ''Note: in networked multiplayer, these events are only executed by the client on which the event is triggered, leading to out of sync errors if you modify the game state in the event.''
* '''menu item X''': triggers when a WML menu item with id=X is selected. ''Note: if the menu item has a [command], this event may be executed before or after the command; there is no guarantee.''
* {{DevFeature}} '''prerecall''': triggers when a unit is recalled, but before it is displayed. This event is not trigger when a unit is recruit.
* {{DevFeature}} '''recall''': triggers after a unit is recalled. This event is not trigger when a unit is recruit.
* {{DevFeature}} other events with a custom name may be invoked from [fire_event]

An '''[allow_undo]''' tag anywhere within a moveto event will cancel any lack of undo functionality the event would have caused. Note that undo functionality will only move the unit back to its former location; it will not other changes to the game caused by the event. Thus it is up to the scenario designer to use this tag correctly.

The primary unit can be referred to as '''unit''' and the secondary unit can be referred to as '''second_unit''' in [message] tags using the speaker= key. 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 the primary unit matches this filter.
** [[StandardUnitFilter]]: selection criteria
* '''[filter_second]''': is like [filter], but for the secondary unit.
** [[StandardUnitFilter]]: selection criteria
* '''[special_filter]''' and '''[special_filter_second]''': can be used to set some additional filtering criteria for the primary unit and the 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 code for the terrain the unit is on.

=== Actions triggered by [event] ===

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

There are 3 main types of actions:
* direct actions ([[DirectActionsWML]]) which have a direct effect on gameplay
* display actions ([[InterfaceActionsWML]]) which show something to the user
* internal actions ([[InternalActionsWML]]) which are used by WML internally

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

=== Nested events ===

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

Example:

[event]
name=turn 10

[event]
name=moveto

[filter]
x,y=5,8
[/filter]

# moving to 5,8 will trigger this event only on turn 10 and after
[/event]
[/event]

== See Also ==

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

[[Category: WML Reference]]

EasyCoding

2008-04-04T19:46:40Z

Segfault: /* Recall Event */

== Foreword ==
This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

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

--[[User:Boucman|Boucman]] 20:48, 3 October 2006 (CEST)

Since bugs are sometimes a good opportunity to get a first idea of the code, i will add some here that are easy to fix as soon as i stumble upon them (the one i had in mind is fixed already ;-).

--Yogi Bear, 28 February 2008

== MP related features ==
=== Add TTL to wesnothd bans ===
As per FR #3638 [https://gna.org/bugs/?3638]
=== Use different font for in-game chat ===
Since commas and dots are apparently hard to tell apart. As per FR #7470 [https://gna.org/bugs/?7470]
=== Allow lists for /ignore and similar ===
As per FR #7492 [https://gna.org/bugs/?7492]

== WML related features ==

=== WML configurable village income / upkeep ===
Preferably as a [scenario], [side] or [campaign] keys. As per FR #6301 [https://gna.org/bugs/?6301]
=== Add support of [if] for [scenario] ===
As per FR #4539 [https://gna.org/bugs/?4539]
=== Allow an event multiple types ===
At the moment an [event] can only trigger on one kind of an event: a '''name=moveto''' only triggers on a move, a '''name=die''' only triggers on a death, and so on. However, it'd sometimes be useful to be able to define a list of types: if you'd have an [event] with '''name=attacker_misses,defender_misses''', then that event would trigger both on the attacker missing and defender missing. Currently, you'd have to create two identical [event]s to do this.
=== Cause preprocesor to throw a warning on undefined macro ===
At the moment preprocesor silently ignores undefined WML macros, make it throw a warning to the stderr or screen on encountering one.
-- patch submitted [https://gna.org/patch/?1035] by cjhopman
=== Make [have_unit] optionaly use full SUF ===
[have_unit] by default uses SUF but does not apply it to recall list. Introduce an optional key that will allow to lift that limitation.
=== Side-specific results ===
Giving result=defeat or result=victory for specific sides. ([http://gna.org/bugs/index.php?4960 FR #4960]) -- [[User:dlr365|dlr365]] -- patch submitted [https://gna.org/bugs/index.php?4960]
=== Recall Event ===
WML event trigger for recalling (the current one triggers on both recalls and recruits) ([http://gna.org/bugs/index.php?3622 FR #3622]) (please read the comments of the report for a proper description of how this should work) -- patch submitted [https://gna.org/patch/?1029]

=== Enabling checking of damage dealt in WML ===
A WML variable should be set when triggering some combat-related events, allowing WML to know the amount of damage being dealt. ([http://gna.org/bugs/index.php?7673 FR #7673])
=== Support for leaderless multiplayergames ===
Add support for the WML key victory_when_enemies_defeated= in the scenario tag during multiplayergames. ([https://gna.org/bugs/index.php?8106 FR #8106])
=== Other Ideas ===
See [[FutureWML]]; some ideas there are easier than others.

== Improvements to FormulaAI ==

Add new formula functions, or minor improvements to the formula language. Make it easier to debug the formula language.

== GUI related features ==
=== Change map paths from dots to dashes ===
Or even better allow dashes and allow choice between the two. As per FR #5522 [https://gna.org/bugs/?5522]

-------------------

Note at the moment Mordante is working on a new GUI system, these
changes will probably affect the way these items need to be implemented.
Contact Mordante on IRC before starting to work on these.

--[[User:SkeletonCrew|SkeletonCrew]] 14:04, 9 March 2008 (EDT)

=== Theme Changes ===
* show number of owned villages/total villages (FR: #3135) (--[[User:Alink|alink]] done but must update help, doc, tooltip...)
* allow custom themes to display values of WML variables ([http://gna.org/bugs/index.php?6209 FR #6209])
* hide the hourglass item from the statusbar when there is no timer

=== Widget Changes ===
* show side number, name and team association information in the status table
* make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* input history (chat, commands, ..) - note: rujasu is working on this feature

== Miscellaneous ==
=== More powerful village naming ===
'''Adding mountain names and other features to village names, having a second random name in village names'''

Currently the village naming engine has a very good structure that could allow
more powerfull names to be generated.
Understanding how it works should be quite easy, and a few usefull improvements could be added.

* Currently villages can use lake names and river names, this should be extended to other features like bridges, swamps, mountains etc...
* It would be nice to have a separate list of "first sylabus" and "last sylabus" for naming. That's not really needed in english, but some translations could use it
* Again, it is common to have villages with more than one "random" word in them. having a $name2 variable would be nice

ACardboardRobot 2/2/07

=== Debug Mode ===
* New debug command functionality (setting additional status.variables, possibly terrain)

=== Additional Commandline Options ===
'''Done''' by lao, actually in trunk, revision 25325.

It would be nice if one could start Wesnoth from commandline specifying whether one wants to connect to a mp-server, load the last savegame or wants to start a campaign. More detailed information and examples are given in the [http://www.wesnoth.org/forum/viewtopic.php?f=12&t=20243 idea forum].

=== Add minimal regexp to friend list ===

Lots of people use multiple nicks, usually postfixed with a number... it would be nice to have minimal regexp support in friend list to easily get who's there...

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]