https://wiki.wesnoth.org/api.php?action=feedcontributions&user=Doofus-01&feedformat=atomThe Battle for Wesnoth Wiki - User contributions [en]2024-03-29T12:38:53ZUser contributionsMediaWiki 1.31.16https://wiki.wesnoth.org/index.php?title=LuaAPI/types/widget&diff=71821LuaAPI/types/widget2023-11-23T12:28:58Z<p>Doofus-01: /* label */</p>
<hr />
<div><div class="tright"> __TOC__ </div><br />
<br />
The '''widget''' userdata offers access to a widget of a GUI2 dialog. While there is only one type of widget userdata that covers all widgets including the window itself, the properties of a widget userdata are different for each type of widget. Indexing a widget's userdata can either be used to access a child widget or to set or get a property of a widget. Some properties are read-only or write-only; the properties depend on the type of the widget.<br />
<br />
An example of accessing a child widget:<br />
<br />
<syntaxhighlight lang=lua><br />
function preshow(dialog)<br />
local okay_button = dialog.okay_button<br />
-- okay_button is now a handle to the the widget's child with the id 'okay_button' <br />
end<br />
</syntaxhighlight><br />
<br />
== Widget Attributes ==<br />
<br />
=== selected ===<br />
<br />
* ''widget''.'''selected''' &harr; ''boolean''<br />
* Available on: '''[toggle_button]''', '''[toggle_panel]'''<br />
<br />
Whether the item is selected or not. Note that this should only be used for widgets that have only 2 states. In particular, there exist 3-State toggle_buttons (for example in listbox headers). For those, selected_index must be used instead.<br />
<br />
=== selected_index ===<br />
<br />
* ''widget''.'''selected_index''' &harr; ''index''<br />
* Available on: '''[listbox]''', '''[multi_page]''', '''[stacked_widget]''', '''[menu_button]''', '''[toggle_button]''', '''[toggle_panel]'''<br />
<br />
The selected index of the item. For '''[toggle_button]''' and '''[toggle_panel]''', this is the same as '''selected''' only encoded as a number (1 for false or 2 for true) instead of a boolean.<br />
<br />
=== text ===<br />
<br />
* ''widget''.'''text''' &harr; ''text''<br />
* Available on: '''[text_box]'''<br />
<br />
The text of the textbox.<br />
<br />
=== value ===<br />
<br />
* ''widget''.'''value''' &harr; ''position''<br />
* Available on: '''[slider]'''<br />
<br />
The current position of the slider.<br />
<br />
=== percentage ===<br />
<br />
* ''widget''.'''percentage''' &harr; ''position''<br />
* Available on: '''[progress_bar]'''<br />
<br />
The current position of the progress bar, between 0 and 100.<br />
<br />
=== selected_item_path ===<br />
<br />
* ''widget''.'''selected_item_path''' &rarr; ''array of indices''<br />
* Available on: '''[treeview]'''<br />
<br />
A table describing the currently selected node. If for example, in the following treeview, Item 9 is selected, the result will be {2,1,3}.<br />
<br />
+Section1<br />
+Subsection11<br />
*Item1<br />
*Item2<br />
*Item3<br />
+Subsection12<br />
*Item4<br />
*Item5<br />
*Item6<br />
+Section2<br />
+Subsection21<br />
*Item7<br />
*Item8<br />
*Item9<br />
+Subsection22<br />
*Item10<br />
*Item11<br />
*Item12<br />
<br />
=== path ===<br />
<br />
* ''widget''.'''path''' &rarr; ''array of indices''<br />
* Available on: '''[tree_view_node]'''<br />
<br />
A table describing this node in the overall treeview. See [[#selected_item_path|selected_item_path]] for the meaning of the table..<br />
<br />
=== unfolded ===<br />
<br />
* ''widget''.'''unfolded''' &larr; ''boolean''<br />
* Available on: '''[tree_view_node]'''<br />
<br />
Control whether a tree node is currently expanded or not.<br />
<br />
=== unit ===<br />
<br />
* ''widget''.'''unit''' &larr; ''unit or unit type''<br />
* Available on: '''[unit_preview_pane]'''<br />
<br />
Change the displayed unit or unit type in the preview pane.<br />
<br />
=== item_count ===<br />
<br />
* ''widget''.'''item_count''' &rarr; ''number of items''<br />
* Available on: '''[multi_page]''', '''[listbox]'''<br />
<br />
The number of items in the container widget.<br />
<br />
=== use_markup ===<br />
<br />
* ''widget''.'''use_markup''' &rarr; ''boolean''<br />
* Available on: Most widgets, in particular '''[label]''', '''[button]'''<br />
<br />
Sets whether the widget's label will parse [[Pango formatting]].<br />
<br />
=== label ===<br />
<br />
* ''widget''.'''label''' &larr; ''text''<br />
* Available on: Most widgets, in particular '''[label]''', '''[button]''', '''[image]'''<br />
<br />
The widget's label. Technically this is a special string used in the widget's wml definition. It usually does what one would expect, but also sets the image for '''image''' widgets. For '''[text_box]''', use '''text''' for initial values.<br />
<br />
=== marked_up_text ===<br />
<br />
* ''widget''.'''marked_up_text''' &larr; ''text''<br />
* Available on: Most widgets, in particular '''[label]''', '''[button]'''<br />
<br />
Shortcut for setting label and use_markup=yes.<br />
<br />
=== enabled ===<br />
<br />
* ''widget''.'''enabled''' &larr; ''boolean''<br />
* Available on: All widgets<br />
<br />
=== tooltip ===<br />
<br />
* ''widget''.'''tooltip''' &larr; ''text''<br />
* Available on: All widgets<br />
<br />
=== visible ===<br />
<br />
* ''widget''.'''visible''' &larr; ''visibility string''<br />
* Available on: All widgets<br />
<br />
Determines whether the widget is visible onscreen. The following visibility statuses are recognized:<br />
{| clasS="wikitable"<br />
! String value !! Boolean shorthand !! Meaning<br />
|-<br />
| visible || true || The widget is visible and handles events.<br />
|-<br />
| hidden || || The widget is not visible, doesn't handle events, but still takes up space on the dialog grid.<br />
|-<br />
| invisible || false || The widget is not visible, doesn't handle events, and does not take up space on the dialog grid.<br />
|}<br />
<br />
=== type ===<br />
<br />
* ''widget''.'''type''' &rarr; ''string''<br />
* Available on: All widgets<br />
<br />
Returns a string specifying the type of the widget.<br />
<br />
== Widget callbacks ==<br />
<br />
=== on_modified ===<br />
<br />
* ''widget''.'''on_modified''' &larr; '''function'''()<br />
* Available on: Most widgets, in particular '''[slider]''', '''[toggle_button]''', '''[listbox]''', '''[menu_button]''', '''[text_box]'''<br />
<br />
Triggers when the user changes the value of the widget.<br />
<br />
=== on_left_click ===<br />
<br />
* ''widget''.'''on_left_click''' &larr; '''function'''()<br />
* Available on: All widgets<br />
<br />
Triggers when the user clicks on the widget.<br />
<br />
=== on_button_click ===<br />
<br />
* ''widget''.'''on_button_click''' &larr; '''function'''()<br />
* Available on: '''[button]''', '''[repeating_button]'''<br />
<br />
Triggers when the user clicks on the button. This can differ from '''on_left_click''', depending on the type of widget. For example, on a '''[repeating_button]''' it will fire multiple times if the user holds the mouse button down.<br />
<br />
== Widget methods ==<br />
<br />
Any function defined in the [[LuaAPI/gui/widget|gui.widget]] module and taking a widget as its first parameter can be called as a method of a widget. This includes any functions that are added to the module by user code. Note that these methods are available even if the widget itself doesn't support that function, so in some cases it may be necessary to check '''widget.type''' befor calling the method.<br />
<br />
[[Category:Lua Reference]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=DirectActionsWML&diff=71342DirectActionsWML2023-05-28T23:09:55Z<p>Doofus-01: /* [terrain] */</p>
<hr />
<div>{{WML Tags}}<br />
== Direct actions ==<br />
<br />
Direct actions are actions that have a direct effect on gameplay. They can be used inside of [[EventWML|events]].<br />
<br />
The following tags are actions:<br />
<br />
=== [endlevel] ===<br />
Ends the scenario.<br />
* '''result''': before the scenario is over, all events with ''name=result'' are triggered. If ''result=victory'', the player progresses to the next level (i.e., the next scenario in single player); if ''result=defeat'', the game returns to the main menu. <br />
<br />
When the result is "victory" the following keys can be used:<br />
* '''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. {{DevFeature1.13|2}} Alternatively, a number, defining the bonus multiple (1.0 meaning full).<br />
* '''carryover_report''': whether the player should receive a summary of the scenario outcome, the default is carryover_report=yes.<br />
* '''save''': whether a start-of-scenario save should be created for the next scenario, the default is save=yes. Do not confuse this with saving of replays for the current scenario.<br />
* '''replay_save''': whether a replay save for the current scenario is allowed, the default is replay_save=yes. If yes, the player's settings in preferences will be used to determine if a replay is saved. If no, will override and not save a replay.<br />
* '''linger_mode''': If ...=yes, the screen is greyed out and there's the possibility to save before advancing to the next scenario, the default is linger_mode=yes.<br />
* '''reveal_map''': (Multiplayer only) (Default is 'yes') If 'no', shroud doesn't disappear when game ended.<br />
* '''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''.<br />
* '''carryover_percentage''': by default 80% of the gold is carried over to the next scenario, with this key the amount can be changed.<br />
* '''carryover_add''': if yes the gold will be added to the starting gold the next scenario, if no the next scenario will start with the amount of the current scenario (after taxes) or the minimum in the next scenario. Default is no.<br />
* '''music''': (default specified in '''[scenario]''' or '''[game_config]''' tags) a comma-separated list of music tracks from which one will be chosen and played once after any events related to the end of level result are executed; by default, victory_music is used on victory, and defeat_music on defeat.<br />
* '''end_credits''': Whether to display the credits screen at the end of a single-player campaign. Defaults to ''yes''. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].<br />
* '''end_text''': (translatable) Text that is shown centered in a black screen at the end of a campaign. Defaults to "The End". Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].<br />
* '''end_text_duration''': Delay, in milliseconds, before displaying the game credits at the end of a campaign. In other words, for how much time '''end_text''' is displayed on screen. Defaults to 3500. Note that this has cumulative effects over the campaign - it persists even if the endlevel does not trigger the end of the campaign. See also [[CampaignWML]].<br />
* <strike>'''[next_scenario_settings]''': Any tags or attribute children of this optional argument to [endlevel] are merged into the scenario/multiplayer tag of the *next* scenario. This allows you to e.g. reconfigure the [side] tags or settings, just before load. </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.<br />
* <strike>'''[next_scenario_append]''': Any tags of this optional argument are appended at high level to the next scenario. This is most appropriate for [event] tags, although you may find other uses. Example test scenario for these features: https://gna.org/support/download.php?file_id=20119 </strike> This feature was removed in 1.11.17, it might be redesigned and reintroduced.<br />
* '''[result]''' {{DevFeature1.13|0}} Allows specification of a side specific result, this is for competitive multiplayer scenarios/campaigns where it might happen that one player wins but another player loses. The following attributes are accepted and have the same effect as in '''[endlevel]''':<br />
** '''result'''<br />
** '''bonus'''<br />
** '''carryover_percentage'''<br />
** '''carryover_add'''<br />
<br />
And there is also<br />
** '''side''' The number of the side for which these results should apply.<br />
<br />
=== [unit] ===<br />
Creates a unit (either on the map, on a recall list, or into a variable for later use.) For syntax see [[SingleUnitWML]].<br />
* {{Short Note:Predefined Macro|GENERIC_UNIT}}<br />
<br />
This tag can also recall an existing unit, which happens when:<br />
* the '''id=''' attribute is used<br />
* a unit with that '''id=''' already exists<br />
* (might be unnecessary) the existing unit is on the side's recall list<br />
in this case, the unit is recalled at the '''x,y=''' or '''location_id=''' given, and any other data in the tag is ignored.<br />
<br />
Campaign authors: a usual way to recall plot-necessary heroes is to use a macro with the data for creating that hero. This helps during debugging, because you can skip to scenarios and the recall-or-create functionality means that any units which are normally met in a previous scenario are automatically created (otherwise some scenarios may be an instant loss). This can only be used for units that must survive the previous scenarios, as it would recreate units if they died in a previous scenario.<br />
For example,<br />
[https://github.com/wesnoth/wesnoth/blob/1.14.7/data/campaigns/Heir_To_The_Throne/utils/httt_utils.cfg#L685 HttT's NEED_DELFADOR macro].<br />
<br />
=== [recall] ===<br />
Recalls a unit taking into account any [[SingleUnitWML|filter_recall]] of the leader. The unit is recalled free of charge, and is placed near its leader, e.g., if multiple leaders are present, near the first found which would be able to normally recall it.<br />
<br />
If neither a valid map location is provided nor a leader on the map would be able to recall it, the tag is ignored.<br />
<br />
* [[StandardUnitFilter]]: the first matching unit will be recalled. If no units match this tag is ignored. Do not use a [filter] tag. If a comma separated list is given, every unit currently considered for recall is checked against all the types (not each single one of the types against all units).<br />
* '''x,y''': the unit is placed here instead of next to the leader.<br />
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to recall to. Used instead of '''x,y'''.<br />
* '''show''': yes/no, default yes: whether the unit is animated (faded in) or instantly displayed<br />
* '''fire_event''': boolean yes|no (default no); whether any according prerecall or recall events shall be fired.<br />
* '''check_passability''': (boolean yes|no, default yes): If yes, checks for terrain passability when placing the unit (a nearby passable hex is chosen).<br />
* '''[secondary_unit]''': {{DevFeature1.13|?}} If present and show=yes, a matching unit will be chosen and their recruiting animation played.<br />
<br />
=== [teleport] ===<br />
Teleports a unit on map. {{Short Note:Predefined Macro|TELEPORT_UNIT}}<br />
* '''[filter]''': [[StandardUnitFilter]] the first unit matching this filter will be teleported.<br />
* '''x,y''': the hex to teleport to. If that hex is occupied, the closest unoccupied hex will be used instead.<br />
* '''location_id''': {{DevFeature1.15|0}} the name of a special map location to teleport to. Used instead of '''x,y'''.<br />
* '''clear_shroud''': should shroud be cleared on arrival<br />
* '''animate''': should a teleport animation be played (if the unit doesn't have a teleport animation, it will fade out/fade in)<br />
* '''check_passability''': (boolean yes|no, default yes): normally, units will not be teleported into terrain that is impassable for them. Setting this attribute to "no" permits it.<br />
<br />
(Note: There is also a ability named teleport, see [[AbilitiesWML]].)<br />
<br />
=== [terrain_mask] ===<br />
Changes the terrain on the map. See [[TerrainMaskWML]].<br />
<br />
=== [terrain] ===<br />
Changes the terrain on the map.<br />
* '''terrain''': the character of the terrain to use. See [[TerrainCodesWML]] to see what letter a type of terrain uses.<br />
* [[StandardLocationFilter]]. This [[StandardLocationFilter]]'s terrain= key is used for the new terrain, filtering by terrain can be done with a nested [[StandardLocationFilter]]: [and]terrain=terrain_string_to_be_filtered_for.<br />
* '''layer''': (overlay|base|both, default=both) only change the specified layer.<br />
* '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.<br />
* '''location_id''': This key sets a string as a way to mark the hex or hexes for later reference. It is very similar to the leader starting position, and can also be set that way in the map editor.<br />
<br />
If you want to remove the overlays from a terrain and leave only the base, use:<br />
layer=overlay<br />
terrain="^"<br />
<br />
<b>Note:</b> When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages is that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.<br />
<br />
=== [gold] ===<br />
Gives sides gold.<br />
* '''amount''': the amount of gold to give.<br />
* '''side''': (default=1) the number of the side to give the gold to. Can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [unstore_unit] ===<br />
Creates a unit from a game variable, and activates it on the playing field or recall list. This must be a specific variable describing a unit, and may not be an array (if it is, only the first unit will be unstored).<br />
<br />
This may be useful in different contexts:<br />
* To update a unit on the map after having edited its WML. This usage is common, but discouraged - if possible, you should use [[#.5Bmodify_unit.5B|[modify_unit]]] or [[#.5Bobject.5B|[object]]] instead.<br />
* To place a previously-defined unit into the scenario, if it was directly defined in a WML variable, using [unit] with the key '''to_variable'''. This usage is rather uncommon.<br />
* To place a unit back into the game that was removed earlier, for example a hero that leaves the party for awhile and then comes back.<br />
<br />
The variable is not cleared. To unstore units from an array variable, iterate over the array. See [[SyntaxWML]] and [[VariablesWML/How to use variables]] for more information about variable usage. See also [[InternalActionsWML#.5Bstore_unit.5D|[store_unit]]], [[ConditionalActionsWML|For]], [[ConditionalActionsWML#.5Bwhile.5D|[while]]] and [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]].<br />
<br />
The tag takes the following keys:<br />
* '''variable''': This is required to indicate the name of the variable to read the unit from.<br />
* '''Placement keys''':<br />
** '''x''' ,'''y''': By default, the unit will be placed at the location specified in the variable, but if these keys are present, the unit will be placed at that location instead. To place the unit on the recall list of its side, use '''x,y=recall,recall'''. (If you want to change the said, you need to first update ''$unit.side'' in the variable before unstoring.)<br />
** '''location_id''': {{DevFeature1.15|0}} The name of a special map location to unstore to. Used instead of '''x,y'''.<br />
** '''find_vacant''' (yes|no, default no): 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.<br />
** '''check_passability''' (yes|no, default yes): Only relevant if '''find_vacant=yes'''. In that case, this determines whether game will try to find a passable tile for the unit. If set to no, the unit may be placed on an impassable tile. Note that if both '''find_vacant''' and '''check_passability''' are set, then the unit's position may be shifted even if there is not a unit on the target space, if that space is not passable for the unit.<br />
* '''Animation keys''' (these determine the visual effect of how the unit is placed or updated):<br />
** '''text''': (translatable) A floating text to display above the unit, such as a damage amount.<br />
** '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above<br />
** '''red''', '''green''', '''blue''': (default=0,0,0) the color of the text. 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.)<br />
** '''animate''': (boolean yes|no, default yes) Determines whether to play any animations associated with the unstore. Currently this only affects the advancement animation ("levelout" and "levelin", defaulting to a fade to white and back) if the unit ends up advancing.<br />
* '''Side-effect keys''' (these directly modify the behaviour of the action):<br />
** '''advance''': (default=yes) if yes the unit is advanced if it has enough XP. When modifying XP, make sure to do it from inside a [[EventWML#Multiplayer_safety|synchronized event]] or it may lead to OOS errors, especially when several advancement paths exist. Note that advance and post advance events are called, so infinite loops can happen.<br />
** '''fire_event''' (yes|no, default no): Whether any advance/post advance events shall be fired if an advancement takes place. This also affects whether the unit placed event is fired.<br />
<br />
Units can be unstored with negative (or zero) hit points. This can be useful if modifying a unit in its last_breath event (as the unit's death is already the next step), but tends to look wrong in other cases. In particular, it is possible to have units with negative hit points in play. Such units are aberrations, subject to unusual behavior as the game compensates for them. (For example, such units are currently automatically hit&ndash;and killed&ndash;in combat.) The details of the unusual behavior are subject to change between stable releases without warning.<br />
<br />
=== [allow_recruit] ===<br />
Allows a side to recruit units it couldn't previously recruit. Any leader on this side will now be able to recruit the new units.<br />
* '''type''': the types of units that the side can now recruit.<br />
* '''side''': (default=1) the number of the side that is being allowed to recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [allow_extra_recruit] ===<br />
Allows a leader to recruit units it couldn't previously recruit.<br />
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[allow_recruit]'''.<br />
* '''extra_recruit''': the types of units that the leader can now recruit.<br />
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br />
<br />
=== [disallow_recruit] ===<br />
Prevents a side from recruiting units it could previously recruit. No leader on this side will be able to recruit the specified units anymore, unless that leader has the same unit in their personal '''extra_recruit''' list.<br />
* '''type''': the types of units that the side can no longer recruit. {{DevFeature1.13|0}} If omitted, all recruits for matching sides will be disallowed.<br />
* '''side''': (default=1) the number of the side that may no longer recruit the units. This can be a comma-separated list note: Default side=1 for empty side= is deprecated.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [disallow_extra_recruit] ===<br />
Prevents a leader from recruiting units it could previously recruit. This won't prevent the leader from recruiting that unit if the unit is in the '''[side]recruit=''' list β you must use '''[disallow_recruit]''' in that case.<br />
* '''extra_recruit''': the types of units that the leader can no longer recruit.<br />
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br />
<br />
=== [set_recruit] ===<br />
Sets the units a side can recruit. Any leader on this side will now be able to recruit these units.<br />
* '''recruit''': the types of units that the side can now recruit.<br />
* '''side''': The number of the side that is having its recruitment set. This can be a comma-separated list.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [set_extra_recruit] === <br />
Sets the units a leader can recruit.<br />
These types are in addition to the types the leader can recruit because of '''[side]recruit=''' and '''[set_recruit]'''.<br />
* '''extra_recruit''': the types of units that the leader can now recruit.<br />
* '''[[StandardUnitFilter]]''': All units matching this filter are modified. Does not match on recall list units.<br />
<br />
=== [modify_side] ===<br />
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!'''<br />
* '''side''': (default=1) the number of the side that is to be changed. note: Default side=1 for empty side= is deprecated.<br />
* '''[filter_side]''' with a [[StandardSideFilter]] as argument<br />
* '''income''': the income given at the begining of each turn.<br />
* '''recruit''': a list of unit types, replacing the side's current recruitment list.<br />
* '''team_name''': the team in which the side plays the scenario.<br />
* '''user_team_name''': a translatable string representing the team's description. This has no effect on alliances. Defaults to ''team_name''.<br />
* '''side_name''': {{DevFeature1.13|?}} a translatable string representing the side leader's description.<br />
* '''gold''': the amount of gold the side owns.<br />
* '''village_gold''': the income setting per village for the side.<br />
* '''controller''': the identifier string of the side's controller. Uses the same syntax of the ''controller'' key in the [[SideWML|[side]]] tag. warning: in multiplayer, changing the controller of a side might result in OOS during some events like, for example 'side_turn_end'; see [https://github.com/wesnoth/wesnoth/issues/2563 issue #2563].<br />
* '''fog''': a boolean string (yes/no) describing the status of Fog for the side.<br />
* '''shroud''': a boolean string describing the status of Shroud for the side.<br />
* '''hidden''': a boolean string specifying whether side is shown in status table.<br />
* '''color''': a team color range specification, name (e.g. "red", "blue"), or number (e.g. "1", "2") for this side. The default color range names, numbers, and definitions can be found in data/core/team_colors.cfg.<br />
* '''[ai]''': sets/changes AI parameters for the side. Only parameters that are specified in the tag are changed, this does not reset others to their default values. Uses the same syntax as described in [[AiWML]]. Note that [modify_side][ai] works for all simple AI parameters and some, but not all, of the composite ones. If in doubt, use [[AiWML#Adding_and_Deleting_Aspects_with_the_.5Bmodify_ai.5D_Tag|[modify_ai]]]] instead, which always works. {{DevFeature1.13|?}} If this contains an '''ai_algorithm''', the AI parameters will be reset to those of the indicated AI before adding any additional parameters included in the tag. In other words, this allows replacing the AI config rather than appending to it.<br />
* '''switch_ai''': replaces a side ai with a new AI from specified file(ignoring those AI parameters above). Path to file follows the usual WML convention.<br />
* '''reset_maps''': If set to "yes", then the shroud is spread to all hexes, covering the parts of the map that had already been explored by the side, including hexes currently seen. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if shroud is on, but this is evaluated after shroud= (and before shroud_data=).<br />
* '''reset_view''': If set to "yes", then the fog of war is spread to all hexes, covering the parts of the map that had already been seen this turn by the side, including hexes currently seen, excluding hexes affected by multi-turn {{tag|DirectActionsWML|lift_fog}}. (Seen hexes will be cleared at the end of most events; they can also be manually cleared with {{tag|InterfaceActionsWML|redraw}}.) This is only effective if fog is on, but this is evaluated after fog=.<br />
* '''share_maps''': change the share_maps side attribute. Be sure to use shroud=yes for that side and have it as an ally<br />
* '''share_view''': change the share_view side attribute. Be sure to use fog=yes for that side and have it as an ally<br />
* '''share_vision''': change both the above at the same time<br />
* '''shroud_data''': changes to the side's shroud, using the same format as when defining the [side].<br />
* '''suppress_end_turn_confirmation''': Boolean value controlling whether or not a player is asked for confirmation when skipping a turn.<br />
* '''scroll_to_leader''': Boolean value controlling whether or not the game view scrolls to the side leader at the start of their turn when present.<br />
* '''flag''': Flag animation for villages owned by this side (see [[SideWML|[side]]]).<br />
* '''flag_icon''': Flag icon used for this side in the status bar (see [[SideWML|[side]]]).<br />
* '''village_support''': The number of unit levels this side is able to support (does not pay upkeep on) per village it controls.<br />
* '''defeat_condition''' {{DevFeature1.13|0}}: When the side is considered defeated (see [[SideWML|[side]]]).<br />
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the side; uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.<br />
* '''[variables]''' {{DevFeature1.15|3}} The contents of this tag is merged into the side's variables.<br />
<br />
=== [modify_turns] ===<br />
Modifies the turn limit in the middle of a scenario.<br />
* '''value''': the new turn limit.<br />
* '''add''': if used instead of ''value'', specifies the number of turns to add to the current limit (can be negative).<br />
* '''current''': changes the current turn number after applying turn limit modifications, if any. It is not possible to change the turn number to exceed the turn limit (1 <= current turns <= max turns).<br />
<br />
=== [allow_end_turn] ===<br />
Allows human players to end their turn through the user interface if they were previously affected by the '''[disallow_end_turn]''' action. This action doesn't take any arguments.<br />
<br />
=== [disallow_end_turn] ===<br />
Disallows human players to end their turn through the user interface. This action doesn't require arguments.<br />
* '''reason''' (translatable): {{DevFeature1.15|0}} Allows to optionally specify a reason.<br />
<br />
=== [capture_village] ===<br />
Changes the ownership of a village.<br />
* [[StandardLocationFilter]]: all village locations matching the filter are affected.<br />
* '''side''': the side that takes control of the village. This side needs to have a leader (canrecruit=yes). If the side key is not given, the village will become neutral (unless [filter_side] is present, in which case that side fiter decides, see below).<br />
* '''[filter_side]''' with [[StandardSideFilter]] tags and keys as arguments; if both this tag and inline side= are present it's an error. Otherwise, the first matching side gets ownership (or the village becomes neutral if none match).<br />
* '''fire_event''' (boolean yes|no, default: no): Whether any capture events shall be fired.<br />
<br />
=== [kill] ===<br />
Removes all units (including units in a recall list) that match the filter from the game.<br />
* [[StandardUnitFilter]]: Selection criterion; do not use a [filter] tag.<br />
* '''animate''' (default 'no'): if 'yes', displays the unit dying (fading away). {{DevFeature1.13|8}} If '''[secondary_unit]''' is given, also plays the victory animation of that unit.<br />
* '''fire_event''' (default 'no'): if 'yes', triggers any appropriate 'die' events (See [[EventWML]]). Note that events are only fired for killed units that have been on the map (as opposed to recall list).<br />
* '''[secondary_unit]''' with a [[StandardUnitFilter]] as argument. Do not use a [filter] tag. Has an effect only if fire_event=yes ({{DevFeature1.13|8}} or if it has a victory animation and animate=yes). The first on-map unit matching the filter becomes second_unit in any fired die and last breath events. If an on-map unit matches and if there are several units killed with a single [kill] tag, second_unit is this same unit for all of them. If no on-map unit matches or [secondary_unit] isn't present, the variable second_unit in each of the die and last breath events is always the same as the variable unit (the dying unit).<br />
* '''[primary_attack]''' {{DevFeature1.13|8}} The attacker's weapon to use for matching the animation. Useful for example on the wose, whose death animation depends on the damage type it was killed by. If a secondary unit is specified, this is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the unit. However, if there is no secondary unit specified, it is instead treated as an [[UnitTypeWML#Attacks|weapon definition]], and the animation will be run as if an imaginary unit possessing that weapon was the attacker.<br />
* '''[secondary_attack]''' {{DevFeature1.13|8}} Similar to the above, but for the defender's weapon. This is taken as a [[StandardWeaponFilter]] and used to find a matching weapon on the dying unit.<br />
<br />
=== [move_unit] ===<br />
Moves a unit along a path on the map. The path can be specified exactly, or as a series of waypoints that the unit will pass through.<br />
* [[StandardUnitFilter]] as argument; do not use a [filter] tag. All units matching the filter are moved. If the target location is occupied, the nearest free location is chosen.<br />
* '''to_x''' (unsigned integer): The units are moved to this x coordinate. Can be a comma-separated list, in which case the unit follows this given path during the move.<br />
* '''to_y''' (unsigned integer): The units are moved to this y coordinate. Can be a comma-separated list.<br />
* '''dir''' (string): {{DevFeature1.15|0}} Performs a relative movement instead of an absolute movement. For example, dir=n,n,nw will move two spaces north and then one space to the northwest. This is used instead of '''to_x''' and '''to_y'''.<br />
* '''to_location''': {{DevFeature1.15|0}} Moves matching units to locations placed in the map editor with the "New Location" button. Can be a comma-separated list. This is used instead of '''to_x''' and '''to_y'''.<br />
* '''check_passability''' (boolean yes|no, default yes): Whether the terrain the unit is moved to should be checked for suiting the unit. (If it does not, a nearby suitable hex is chosen.)<br />
* '''force_scroll''': Whether to scroll the map or not even when [[InterfaceActionsWML#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to using [[InterfaceActionsWML#.5Bmove_unit_fake.5D|[move_unit_fake]]]'s default value.<br />
* '''clear_shroud''': {{DevFeature1.15|0}} (boolean yes|no, default no) Whether to remove shroud and fog after the unit was moved, but before events are fired. It will not clear all alongside the path, only around the target destination.<br />
* '''fire_event''' (boolean yes|no, default no): Whether any according moveto events shall be fired. The target location ($x1, $y1 in the event) may not be the same location that the unit was tried to be moved to, if the original target location is occupied or impassable.<br />
<br />
=== [modify_ai] ===<br />
Changes AI objects (aspects, goals, candidate actions or stages) for a specified side. See [[Modifying_AI_Components#The_.5Bmodify_ai.5D_Tag|Modifying AI Components]] for full description.<br />
<br />
* '''action''' (string): Takes values 'add', 'change', 'delete' or 'try_delete' to do just that for the AI object.<br />
* '''path''' (string): Describes which AI object is to be modified. <br />
* '''[facet]''', '''[goal]''', '''[candidate_action]''' or '''[stage]''': Details about the AI object to be modified.<br />
* [[StandardSideFilter]] tags and keys; default for empty side= is all sides, as usual in a SSF.<br />
<br />
=== [modify_unit] ===<br />
works similar to the MODIFY_UNIT macro.<br />
* '''[filter]''' with a [[StandardUnitFilter]] as argument. All units matching this filter are modified. Matches on recall list units too.<br />
* '''[object]''', '''[trait]''', {{DevFeature1.13|5}} '''[advancement]''' - The given modifications will be immediately applied to all units matching the filter. ([object] is described further [[#.5Bobject.5D|below]])<br />
** '''delayed_variable_substitution''' {{DevFeature1.13|5}} (boolean yes|no, default no): If set to "yes", the wml block contained in this [object], [trait], or [advancement] is not variable-substituted at execution time of the event containing this [modify_unit]. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.<br />
** Do not use a '''[modifications]''' tag, as this may skip some of the special-case handling for newly added objects, traits and advancements, and will potentially overwrite existing modifications.<br />
* '''[effect]''' {{DevFeature1.13|6}} Applies the effect directly to the unit. See [[EffectWML]].<br />
* '''[set_variable]''', '''[clear_variable]''' {{DevFeature1.15|3}} Sets or clears a variable within the unit (saved inside the unit's [variables] tag); uses the same syntax as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] or [[InternalActionsWML#.5Bclear_variable.5D|[clear_variable]]] in ActionWML.<br />
* Accepts generally the syntax inside of wml unit variables created by [store_unit] which can be viewed in a savefile or by using the [[CommandMode|inspect command]]. Cannot remove things or add/alter unit animations. Subtags with the same name must be written in the correct order to match them with the tag they are supposed to modify. Note that keys will be processed in arbitrary order, which may cause problems if you use formulas that depend on other formulas. To work around this you may need to use the tag twice with the same filter.<br />
example usage (see also the test scenario):<br />
<syntaxhighlight lang='wml'><br />
[modify_unit]<br />
[filter]<br />
x,y=38,6<br />
[/filter]<br />
hitpoints=10<br />
{TRAIT_HEALTHY}<br />
[/modify_unit]<br />
</syntaxhighlight><br />
<br />
The unit which is currently modified is accessible via $this_unit, e.g. hitpoints = "$($this_unit.hitpoints / 2)" to set the hitpoints of all units to half of their particular maxima. This this_unit variable is independent from the this_unit variable available in the SUF used to determine which units to modify (first all matching units are gathered, and then all those are modified).<br />
<br />
'''Note:''' Some some properties of the units are reset sometimes (for example when the unit advances or when [remove_object] is called), so it's usually better to change them with [object] ([object] inside [modify_unit]) than to change those properties directly via [modify_unit]. The following properties are _not_ reset in [remove_object] and are thus safe to use directly in [modify_unit]:<br />
* '''side'''<br />
* '''gender'''<br />
* '''name'''<br />
* '''canrecruit'''<br />
* '''unrenamable'''<br />
* '''extra_recruit'''<br />
* '''[variables]'''<br />
* '''facing'''<br />
* '''x, y'''<br />
* '''goto_x, goto_y'''<br />
* '''hitpoints'''<br />
* '''experience'''<br />
* '''moves'''<br />
* '''[status]'''<br />
* '''attacks_left'''<br />
* '''role'''<br />
<br />
=== [transform_unit] ===<br />
Transforms every unit on the map matching the filter to the given unit type. Keeps intact hit points, experience and status. If the unit is transformed to a non-living type (undead or mechanical), it will be also unpoisoned. Hit points will be changed if necessary to respect the transformed unit's maximum hit points. Regardless of anything else, the unit will be rebuilt. Thus, transforming a unit to its current type is a way to force a rebuild, for example after manually removing a modification.<br />
* [[StandardUnitFilter]]: do not use a [filter] tag.<br />
* '''transform_to''': the unit type in which all the units matching the filter will be transformed. If missing, the units will follow their normal advancement.<br />
<br />
=== [petrify] ===<br />
<br />
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are petrified. Recall list units are included.<br />
<br />
=== [unpetrify] ===<br />
* [[StandardUnitFilter]] as an argument. Do not use a [filter] tag. All units matching this filter are unpetrified. Recall list units are included.<br />
<br />
=== [object] ===<br />
Gives some unit an object which modifies their stats in some way. This tag can also be used in places that don't support ActionWML, such as [[#.5Bmodify_unit.5D|[modify_unit]]] or [[SingleUnitWML|[unit][modifications]]]. The following is supported in all these places:<br />
* '''[effect]''': one or more effect elements may be listed. See [[EffectWML]] for a description of [effect].<br />
* '''duration''':<br />
**if 'scenario', effects only last until the end of the scenario.<br />
**if 'forever' or not set, effects never wear off.<br />
** if 'turn', effects only last until the start of the unit's next turn (when the unit refreshes movement and attacks). (Like other start-of-turn behavior, objects with a duration of "turn" won't expire before turn 2.)<br />
** {{DevFeature1.13|1}} if 'turn end' or 'turn_end', effects only last until the end of the unit's next turn (exactly like the slowed status).<br />
* Other keys, such as '''id''', may be used to remove the object later, but are not used by the engine. An '''[object]''' tag can contain any arbitrary data that may be helpful to identify the object to remove later using a [[FilterWML#Filtering_on_WML_data|WML filter]].<br />
<br />
The following is supported only when using '''[object]''' as ActionWML:<br />
* '''id''': (Optional) By default, an object with a defined ID can only be picked up once per scenario, even if it is removed later or first_time_only=no is set for the event. You can remove this restriction by setting take_only_once=no. For filtering objects, it might be simpler to use a custom key such as item_id. The id string can contain only letters, numbers and underscores. The ID is also commonly used to manually remove the object later, for example with [[#.5Bremove_object.5D|[remove_object]]].<br />
* '''take_only_once''': (default yes) {{DevFeature1.13|6}} If set to "no", the object's ID does not prevent it from being taken more than once.<br />
* '''delayed_variable_substitution''' (boolean yes|no, default no): If set to "yes", the wml block contained in this [object] is not variable-substituted at execution time of the event where this [object] is within. You need this for any effect that uses variable substitution or when using [effect][filter] with a $this_unit. {{DevFeature1.13|9}} This is no longer needed when adding ABILITY_TELEPORT, ABILITY_LEADERSHIP or SPECIAL_BACKSTAB.<br />
* '''[filter]''' with a [[StandardUnitFilter]] as argument. The first unit found that matches the filter will be given the object. Only on-map units are considered. If no unit matches or no [filter] is supplied, it tries to apply the object to the unit at the $x1,$y1 location of the event where this [object] is in. The case of no unit being at that spot is handled in the same way as no unit matching a given filter ([else] commands executed, cannot_use_message displayed). Note that units on the recall list will not be checked. To add an [object] to a unit on the recall list you have to use '''[modify_unit][object]'''.<br />
* '''[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 '''[remove_item]''' tag, but you could probably put any tags that otherwise work in a [then] tag.<br />
* '''[else]''': a subtag that lets you execute actions if the filter conditions are *not* met.<br />
* '''silent''': whether or not messages should be suppressed. Default is "no". {{DevFeature1.13|2}} If no description is provided, this defaults to yes, but can still be overridden.<br />
* '''image''': the displayed image of the object.<br />
* '''name''': (translatable) displayed as a caption of the image.<br />
* '''description''': (translatable) displayed as a message of the image.<br />
* '''cannot_use_message''': (translatable) displayed instead of '''description''' if no unit passes the filter test.<br />
<br />
=== [remove_object] ===<br />
{{DevFeature1.13|6}}<br />
<br />
Removes an object from matching units.<br />
<br />
* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching objects removed. Use no [filter] tag.<br />
* '''object_id''': The id of the object to be removed.<br />
<br />
Note that some unit properties are not restored ideally, e.g. current unit's health reversion might not work as expected (max_hitpoints will though). {{DevFeature1.15|0}} This was fixed.<br />
<br />
Note that [remove_object] works the following way: <br />
<br />
# Remove the object from the unit<br />
# Rebuild the unit to make the changes effective.<br />
<br />
Step 2 implies that changes done for example via [modify_unit] (or via the [store_unit] + [set_variable] + [unstore_unit] technique) will be reset if those changes change a property that is a property of the unit type. See the note under [[#.5Bmodify_unit.5D|[modify_unit]]] to get a list of properties that can safely be changed via [modify_unit].<br />
<br />
=== [remove_trait] ===<br />
{{DevFeature1.15|2}}<br />
<br />
* [[StandardUnitFilter]]: All units on the map (but not the recall list) matching the filter have matching traits removed. Use no [filter] tag.<br />
* '''trait_id''': The id of the object to be removed.<br />
<br />
=== [remove_shroud] ===<br />
Removes some shroud from the map for a certain side (only relevant for sides that have shroud=yes).<br />
* '''side''': (default=1) the side for which to remove shroud. This can be a comma-separated list of sides. note: Default side=1 for empty side= is deprecated.<br />
* '''[filter_side]''' with a [[StandardSideFilter]] as argument<br />
* [[StandardLocationFilter]]: the range of tiles for which shroud should be removed<br />
<br />
=== [place_shroud] ===<br />
Places some shroud on the map for a certain side (only relevant for sides that have shroud=yes).<br />
* '''side''': (default=1) the side for which to place shroud. This can be a comma-separated list. note: Default side=1 for empty side= is deprecated.<br />
* '''[filter_side]''' with a [[StandardSideFilter]] as argument<br />
* [[StandardLocationFilter]]: the range of tiles on which shroud should be placed<br />
<br />
=== [lift_fog] ===<br />
Lifts the fog of war from parts of the map for a certain side (only relevant for sides that have fog=yes), allowing a player to witness what occurs there even if that player has no units within vision range.<br />
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.<br />
* [[StandardLocationFilter]]: the tiles from which fog should be lifted.<br />
* '''multiturn''': ''yes/no, default:no''. The default (not multiturn) causes fog to be removed in the same way that normal vision works; the cleared tiles will remain cleared until fog is recalculated (which normally happens when a side ends its turn). When multiturn is set to "yes", the cleared tiles remain clear until {{tag||reset_fog}} cancels the clearing. This allows tiles to remain clear for multiple turns, or to be refogged before the end of the current turn (without also refogging all tiles). Multiturn lifted fog is not shared with allies (even when share_vision=all).<br />
<br />
=== [reset_fog] ===<br />
The primary use of this tag is to remove multiturn lifted fog (created by {{tag||lift_fog}}), which causes the fog to reset to what it would have been had WML not interfered. (That is, hexes that a side's units could not see at any point this turn will be re-fogged, while seen hexes remain defogged.)<br />
* '''[filter_side]''' with a [[StandardSideFilter]] indicating which sides should be affected.<br />
* [[StandardLocationFilter]]: the fog reset will be restricted to these tiles.<br />
* '''reset_view''': ''yes/no, default: no'' If set to "yes", then in addition to removing multiturn fog, the side's current view is canceled (independent of the SLF). This means that all hexes will become fogged for the side unless multiturn fog exists outside the tiles selected by the SLF. Normally, one would want the currently seen hexes to become clear of fog; this is done automatically at the end of many events, and it can be done manually with {{tag|InterfaceActionsWML|redraw}}.<br />
Omitting both the SSF and the SLF would cancel all earlier uses of [lift_fog].<br />
Additionally setting reset_view="yes" would cause the side's entire map to be fogged (unless an ally keeps hexes clear by sharing its view).<br />
<br />
=== [allow_undo] ===<br />
Normally when an event with a handler fires, the player's undo stack is cleared, preventing all actions performed so far from being undone. Including this tag in the event handler prevents the stack from being cleared for this reason, allowing the player to undo actions. (However, the stack might still be cleared for other reasons, such as fog being cleared or combat occurring.) In the common cases, this means '''[allow_undo]''' allows the current action to be undone even though an event was handled. There is a less common case, though &mdash; specifically when handling a menu item, where there is no current action &mdash; and in this case, '''[allow_undo]''' means merely that earlier actions can still be undone.<br />
* Using this tag in a menu item has an additional side effect in 1.11. Starting with version 1.11.1, executing a WML menu item normally counts as doing something as far as the "you have not started your turn yet" dialog is concerned. However, a menu item whose handler includes '''[allow_undo]''' will not count.<br />
<br />
The types of actions that can be undone are movement, recalling, and dismissing a unit from the recall list. If an action is undone, only the position (or existence) of the involved unit will be restored; any altered variables or changes to the game will remain changed after the action is undone. It is up to the scenario designer to avoid abusing this command.<br />
* 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 action the first time.<br />
* Although recalling can be undone, recruitment can not be undone; this seems to apply even when the recruit's traits are not randomly-generated (tested on 1.12.6 and 1.14.4+dev).<br />
<br />
If an '''[event]''' uses both '''[allow_undo]''' and [[InternalActionsWML#.5Bfire_event.5D|'''[fire_event]''']] then the '''[allow_undo]''' must be after the '''[fire_event]'''.<br />
<br />
Due to a bug in 1.12 ([http://web.archive.org/web/20170330000414/http://gna.org/bugs/?23323 https://gna.org/bugs/?23323]) '''[allow_undo]''' should not be used in events that use one of the following things because it might cause OOS: <br />
* [message] with [option]s<br />
* [get_global_variable]<br />
* wesnoth.synchronize_choice<br />
<br />
While in 1.13 using '''[allow_undo]''' together with those things won't give you a guaranteed OOS, there are some non-obvious situations where it will, for example assume the following event:<br />
<br />
[event]<br />
name="moveto"<br />
[message]<br />
message = "message"<br />
[option]<br />
label = "option 1"<br />
[command]<br />
[/command]<br />
[/option]<br />
[option]<br />
label = "option 2"<br />
[command]<br />
[/command]<br />
[/option]<br />
[/message]<br />
[allow_undo]<br />
[/allow_undo]<br />
[/event]<br />
<br />
It will cause OOS when the message is undone: since the event is already executed (erased) on one client only , the clients will disagree about how many choices happen during the next moveto action.<br />
<br />
=== [on_undo] ===<br />
{{DevFeature1.13|2}}<br />
Contains commands to execute when the player undoes the action which triggered the parent event.<br />
*'''delayed_variable_substitution''' {{DevFeature1.13|5}}: ''yes/no, default no (always no before 1.13.5)'' As in [[EventWML]], specifies whether to perform variable substitution when the parent event is run, or when the contents are run. If delayed substitution is used, [[SyntaxWML#Automatically_Stored_Variables|automatically stored variables]] from the parent event context are available, but may occasionally have unexpected values. (In particular, $unit.x and $unit.y may not have the expected value when undoing a move event, though $x1 and $y1 should be correct.)<br />
<br />
Note:<br />
It is not clear where whether the actionwml in [on_undo] in executed before or after the action is undone. Also, specially for enter/leave_hex events the units position when executing the [on_undo] code is usually different than when executing the original event. The recommended way to work around these issues is to refer to the unit by id instead of position and store all other needed information variables as 'upvalues'. You can also move the actual undo code to an external event. For example<br />
[event]<br />
name="undo_blah"<br />
first_time_only=no<br />
[store_unit]<br />
id="$moved_unit_id"<br />
[/store_unit]<br />
... do undo stuff stuff<br />
[/event]<br />
<br />
...<br />
... in some other event<br />
[on_undo]<br />
# store ''upvalues<br />
{VARIABLE moved_unit_id $unit.id}<br />
# call actual undo handler<br />
[fire_event]<br />
name = "undo_blah"<br />
[/fire_event]<br />
[on_undo]<br />
<br />
=== [on_redo] ===<br />
{{DevFeature1.13|2}}<br />
Same as [on_undo], except executes the commands on redo. Note that the parent event is not triggered again on a redo.<br />
<br />
{{DevFeature1.13|8}} [on_redo] is deprecated and has no effect anymore.<br />
<br />
Note that [on_redo] is not guaranteed to be called when redoing an action, the engine might also decide to just fire the original events again.<br />
<br />
=== [cancel_action] ===<br />
Although Wesnoth 1.12 does not have this tag, it is the default behavior of '''enter_hex'''/'''exit_hex''' [event] in that version.<br />
<br />
{{DevFeature1.13|9}} In this version, [cancel_action] is recognised, but has no effect (a bug).<br />
<br />
{{DevFeature1.13|11}}<br />
In an '''enter_hex'''/'''exit_hex''' [event], interrupt the movement, leaving the unit where it is. This is intended to be used with an event that gives the player new information, to let the player choose whether to change their plans. For example, if the player has commanded a unit to move from (1,1) to (3,3) and attack a unit on (4,4); then a [cancel_action] inside an '''enter_hex''' [event] on (2,2) would make the unit stop on (2,2). A [cancel_action] inside an enter_hex [event] on (3,3) would let the player choose whether to attack.<br />
<br />
=== [heal_unit] ===<br />
Heal a unit. The variable '''$heal_amount''' will be set to the exact number of points healed (i.e can be less than the parameter '''amount''' if the unit is fully healed). $heal_amount contains only the number of hitpoints the first unit that was found got healed. When the variable is not needed, use {CLEAR_VARIABLE heal_amount} after this tag.<br />
<br />
{{DevFeature1.17|0}} The '''$heal_amount''' variable is no longer set. Use the '''variable''' key instead.<br />
* '''[filter]''': [[StandardUnitFilter]] All matching on-map units are healed. If no filter is supplied, it is tried to take the unit at $x1, $y1.<br />
* '''[filter_second]''': [[StandardUnitFilter]] all the units matching the filter ''and'' having the ''heals'' ability will have their animation played (if ''animate'' is set to yes) for each of the units healed.<br />
* '''amount''': (integer, default full) the maximum points the unit(s) will be healed. This can't be used to set the unit's hitpoints below 1 or above the unit's maximum hitpoints. If "full", it fully heals the unit.<br />
* '''animate''': a boolean which indicate if the healing animations must be played. (default no)<br />
* '''moves''': (integer, default 0) The maximum current movement points the units will be "healed". Can't set below 0 or above max_moves. If "full", sets moves to max_moves.<br />
* '''restore_attacks''': (boolean, default no) Whether the units' attacks_left should be reset to their max_attacks (usually 1).<br />
* '''restore_statuses''': (boolean, default yes) Whether standard statuses should be reset to "no". This affects poisoned, slowed, petrified and unhealable.<br />
* '''variable''': {{DevFeature1.17|0}} creates an array with the given name; each item of the array has two fields, ''id='' (the ID of the unit being healed) and ''heal_amount='' (the amount of HPs the unit has been healed by).<br />
<br />
=== [harm_unit] ===<br />
Harms every unit matching the filter, for the specific damage amount.<br />
* '''[filter]''': [[StandardUnitFilter]] all matching units will be harmed (required).<br />
* '''[filter_second]''': [[StandardUnitFilter]] if present, the first matching unit will attack all the units matching the filter above.<br />
* '''amount''': the amount of damage that will be done (required).<br />
* '''alignment''': (default neutral) applies an alignment to the damage, this means that if alignment=chaotic, the damage will be increased at night and reduced at day.<br />
* '''damage_type''': if present, amount will be altered by unit resistance to the damage type specified.<br />
* '''kill''': (default yes) if yes, when a harmed unit goes to or below 0 HP, it is killed; if no its HP are set to 1.<br />
* '''fire_event''': (default no) if yes, when a unit is killed by harming, the corresponding events are fired. If yes, also the corresponding advance and post advance events are fired.<br />
* '''animate''': (default no) if yes, scrolls to each unit before harming it and plays its defense (or attack, if it's the harmer) and death animations. Special values supported, other than the usual yes and no, are "attacker", that means only the harmer will be animated, and "defender", that means only the harmed units will be animated. If the supplied value is yes, attacker or defender also advancement animations are played.<br />
* '''[primary_attack], [secondary_attack]''': these set the weapon against which the harmed units will defend, and that the harming unit will use to attack, respectively (notice this is the opposite of '''[filter]''' and '''[filter_second]''' above). This allows for playing specific defense and attack animations. Both tags are expected to contain a [[FilterWML#Filtering_Weapons|Standard Weapon Filter]].<br />
* '''delay''': if animate=yes, sets the delay (in milliseconds, default 500) between each unit harming.<br />
* '''variable''': if present, the damage caused to the unit, altered by resistances, will be stored in a WML array with the given name, under the ''harm_amount='' key. {{DevFeature1.17|0}} Each item of the array also has an ''id='' key, which contains the ID of the unit being harmed.<br />
* '''poisoned, slowed, petrified, unhealable''': (default no) if yes, every harmed unit that doesn't already have such status will have it set.<br />
* '''experience''': if yes, and there is a harmer, experience will be attributed like in regular combat.<br />
* '''resistance_multiplier''': the harmed unit's resistance is multiplied by the supplied value; this means that a value lower than 1 increases it, and a value greater than 1 decreases it. Default value is 1, that means no modification.<br />
<br />
=== [time_area] ===<br />
How a day should progress in a given area. Everywhere not specified in a [time_area] tag is affected by the [time] tags in the [scenario] tag.<br />
* [[StandardLocationFilter]]: the locations to affect. ''note: only for [event][time_area]s - at scenario toplevel [time_area] does not support [[StandardLocationFilter]], only location ranges''<br />
* '''[time]''': one or more tags describing the new schedule, see [[TimeWML]].<br />
* '''id''': an unique identifier assigned to a time_area. Optional, unless you want to remove the time_area later or reference it from a location filter elsewhere. Can be a comma-separated list when removing time_areas, see below.<br />
* '''remove''': (boolean) yes/no value. Indicates whether the specified time_area should be removed. Requires an identifier. If no identifier is used, however, all time_areas are removed.<br />
* '''current_time''': The time slot number (starting with zero) active at the creation of the area.<br />
<br />
''Example:'' (caves in parts of a map)<br />
<syntaxhighlight lang=wml><br />
[time_area]<br />
id = cave_area<br />
x = 1-2,4-5<br />
y = 1-2,1-2<br />
{UNDERGROUND}<br />
[/time_area]<br />
</syntaxhighlight><br />
<br />
Specifying an id allows the area to be referenced from location filters. Example:<br />
<syntaxhighlight lang=wml><br />
[time_area]<br />
id = glyphs<br />
x = 9,14<br />
y = 11,3<br />
[/time_area]<br />
[event]<br />
name = moveto<br />
first_time_only=no<br />
[filter]<br />
side = 1<br />
[filter_location]<br />
area = glyphs<br />
[/filter_location]<br />
[/filter]<br />
# Do something, for example healing the unit<br />
[/event]<br />
</syntaxhighlight><br />
<br />
=== [remove_time_area] ===<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
This is a syntactic shortcut for [time_area] remove=.<br />
* '''id''': Comma-separated list of time area ids to remove.<br />
<br />
=== [end_turn] ===<br />
End the current side's turn. The current event is finished before the turn is ended. Also, if the current event (where the tag appears) has been fired by another event, that event (and the complete stack of other possible parent events) is ended before [end_turn] comes into affect. Also, events following the event stack that fired [end_turn] are not omitted (e.g. [end_turn] is used by a side turn event and a turn refresh event does something afterwards).<br />
<br />
=== [replace_map] ===<br />
<br />
Replaces the entire map.<br />
* '''map_data''': Content of a wesnoth map file. (This key used to be just '''map='''.) Example:<br />
map_data="{campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map}"<br />
* '''map_file''': {{DevFeature1.13|?}} Path to a Wesnoth map file; can be used instead of '''map'''. The file will be loaded when the tag is executed, rather than being embedded wholesale in the preprocessed WML. Example:<br />
map_file=campaigns/Heir_To_The_Throne/maps/01_The_Elves_Besieged.map<br />
{{DevFeature1.15|3}} If the file is not found directly, it will be searched for in the [[BinaryPathWML|[binary_path]]]. Assuming a standard campaign or add-on layout, the example above can be replaced by:<br />
map_file=01_The_Elves_Besieged.map<br />
* '''expand''': if 'yes', allows the map size to increase. The expansion direction is currently always bottom-right.<br />
* '''shrink''': if 'yes', allows the map size to decrease. If the map size is reduced, any units that would no longer be on the map due to its coordinates no longer existing will be put into the recall list.<br />
Note: When a hex changes from a village terrain to a non-village terrain, and a team owned that village it loses that village. When a hex changes from a non-village terrain to a village terrain and there is a unit on that hex it does not automatically capture the village. The reason for not capturing villages it that there are too many choices to make; should a unit lose its movement points, should capture events be fired. It is easier to do this as wanted by the author in WML.<br />
<br />
=== [replace_schedule] ===<br />
Replace the time of day schedule of the entire scenario.<br />
* [[TimeWML]]: the new schedule.<br />
* '''current_time''': The time slot number (starting with zero) active at schedule replacement.<br />
<br />
=== [tunnel] ===<br />
<br />
Create a tunnel between some locations, later usable by units to move from source hex to target hex (using the movement cost of unit on the target terrain).<br />
<br />
'''Behavior Change as of Wesnoth 1.13.6:''' Vision is now possible (and enabled by default) through tunnels and allied units on the exit hex do not block a tunnel by default any more. This is done in order for moves through tunnels to be consistent with other moves. The previous behavior can still be accomplished by using the new optional keys listed below.<br />
<br />
* '''[filter]''': (required) [[StandardUnitFilter]] the units which can use the tunnel. Leave empty for "all units".<br />
* '''[source]''': (required) [[StandardLocationFilter]] the source hex(es).<br />
* '''[target]''': (required) [[StandardLocationFilter]] the target hex(es).<br />
* '''id''': (optional) identifier for the tunnel, to allow removing.<br />
* '''remove''': (boolean, default: no) If yes, removes all defined tunnels with the same ID (then only id= is necessary).<br />
* '''bidirectional''': (boolean, default: yes) If yes, creates also a tunnel in the other direction. <br />
* '''always_visible''': (boolean, default: no) If yes, the possible movement of enemies under fog can be seen.<br />
* '''allow_vision''': (boolean, default: yes) {{DevFeature1.13|6}} If no, vision through a tunnel is not possible. Note that in that case the tunnel cannot be used if the tunnel exit is under shroud (which previously was ''always'' the case).<br />
* '''pass_allied_units''': (boolean, default: yes) {{DevFeature1.13|6}} If no, allied (including own) units on the exit hex block a tunnel.<br />
* '''delayed_variable_substitution''' (boolean, default: yes): If yes, the WML block contained in this [tunnel] is not variable-substituted at execution time of the event where this [tunnel] is within. Instead, variables are substituted when the tunnel is used by a unit. See [[EventWML#Nested_Events]]<br />
<br />
(Note: The tunnel tag can also be used inside the [[AbilitiesWML|[teleport]]] ability, without remove= and id=).<br />
<br />
=== [do_command] ===<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
Executes a command, specified using the same syntax as a [command] tag in [[ReplayWML]]. Not all [command]'s are valid: only these are accepted<br />
<br />
* [attack]<br />
* [move]<br />
* [recruit]<br />
* [recall]<br />
* [disband]<br />
* [fire_event]<br />
* [lua_ai] {{DevFeature1.13|12}} This has been removed and is replaced with [custom_command]<br />
<br />
The tags corresponding to player actions generally use the same codepath as if a player had ordered it. That means for example that only moves that player would be allowed to do are possible, and movement is interrupted when sighting enemy unit.<br />
<br />
One purpose of this tag is to allow scripting of noninteractive scenarios -- without a tag like this, this might require elaborate mechanisms to coerce ais in order to test these code paths.<br />
<br />
This command should be replay safe if it is either invoked in a synced context, ''or'' invoked in code that is never synced, like AI code, a select event, or a menu item with `synced = false`. However, if you use desynchronized logic ''during'' an event that is otherwise synced, invoking [do_command] based on that desynchronized logic will result in out-of-sync errors during the replay; in this case, you must explicitly synchronize which command to do using something like the lua function wesnoth.sync.evaluate_single.<br />
<br />
=== [put_to_recall_list] ===<br />
<br />
{{DevFeature1.13|0}}<br />
<br />
Puts a unit to the recall list of its side.<br />
* '''[[StandardUnitFilter]]''': the unit(s) to get put to the recall list.<br />
* '''heal''': (default=no) Whether the unit should be refreshed, similar to the unit moving to the recall list at the end of a scenario.<br />
<br />
=== [set_achievement] ===<br />
<br />
{{DevFeature1.17|13}}<br />
<br />
Sets the specified achievement as completed and shows a popup stating it's been completed. The popup is not shown if the achievement has already been achieved.<br />
<br />
* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.<br />
* '''id''': The id of the achievement.<br />
<br />
=== [set_sub_achievement] ===<br />
<br />
{{DevFeature1.17|17}}<br />
<br />
Sets the specified sub-achievement as completed.<br />
<br />
* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.<br />
* '''id''': The id of the achievement.<br />
* '''sub_id''': The id of the sub-achievement.<br />
<br />
=== [progress_achievement] ===<br />
<br />
{{DevFeature1.17|13}}<br />
<br />
Progress an achievement by the specified amount, with an optional limit for how far the achievement can be progressed.<br />
<br />
* '''content_for''': The [[AchievementsWML|[achievements_group]]] that this achievement is part of.<br />
* '''id''': The id of the achievement.<br />
* '''amount''': The amount to increment the achievement.<br />
* '''limit''': (optional) Using this attribute will prevent achievements from progressing past this value.<br />
<br />
== Useful Macros ==<br />
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 [https://www.wesnoth.org/macro-reference.html here].<br />
* '''{MOVE_UNIT}''': Moves a unit to another location in the map and the player sees the movement (unlike [teleport])<br />
* '''{FULL_HEAL}''': Brings a unit to full HP<br />
* '''{LOYAL_UNIT}''': Create a loyal unit<br />
* '''{MODIFY_TERRAIN_MASK}''': Modify an area of terrain<br />
<br />
== See Also ==<br />
<br />
* [[InternalActionsWML]]<br />
* [[InterfaceActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=StandardLocationFilter&diff=71341StandardLocationFilter2023-05-28T23:04:09Z<p>Doofus-01: </p>
<hr />
<div>{{WML Tags}}<br />
From [[FilterWML]], this is the standard way of filtering on locations.<br />
The term [[StandardLocationFilter]] means that the set of such keys and tags (see below) can appear at that point. Sometimes a [[StandardLocationFilter]] needs to be included in a [filter_location] tag. There are however many tags which accept the [[StandardLocationFilter]] directly as an argument such as [store_locations]. Generally, if the tag [filter_location] is not mentioned to be a possible subtag of the outer tag in question, then don't put it.<br />
<br />
== Attributes ==<br />
The following attributes and sub-tags are permitted:<br />
<br />
* '''time_of_day''': filter matches only on a given time of day (one of lawful, chaotic, or neutral). Note: ''chaotic'', ''lawful'', and ''neutral''; these are not times of day, these are ''alignments''. To match against 'dawn', 'dusk', 'first watch' etc., use the '''time_of_day_id''' key described below.<br />
* '''time_of_day_id''': this accepts a list of one or more actual times of day, separated by commas. These IDs are taken from '''data/core/macros/schedules.cfg'''. Permissible values are case-sensitive: dawn, morning, afternoon, dusk, first_watch, second_watch, indoors, underground and deep_underground.<br />
* '''terrain''': comma separated list of terrains. (See also: [[#Filtering_Terrains|Filtering Terrains]]).<br />
* '''x,y''': the same as in the unit filter; supports any range ([[StandardLocationFilter#Notes_about_Coordinate_Usage|notes]])<br />
* '''location_id''': {{DevFeature1.13|?}} Matches a special location set in the map. This can also be a side number to match that side's starting location. Note: this does not accept a comma separated list, one has to use [or] tags. {{DevFeature1.15|0}} Accepts a comma separated list. This key can be set in the map editor or with the [terrain] tag.<br />
* '''area''': matches locations assigned to the [[DirectActionsWML#.5Btime_area.5D|[time_area]]] with the given id.<br />
* '''include_borders''': {{DevFeature1.13|0}} whether the SLF will include border hexes or not. Will override the default behavior of the tag this appears in.<br />
* '''[filter]''' with a [[StandardUnitFilter]] as argument; if present a unit must also be there<br />
* '''owner_side''': If a valid side number, restricts stored locations to villages belonging to this side. If 0, restricts to all unowned locations (the whole map except villages which belong to some valid side). A hex is considered a village if and only if its [ [[TerrainWML|terrain_type]] ]gives_income= parameter was set to yes (which means a side can own that hex).<br />
* '''gives_income''': {{DevFeature1.15|11}} Matches whether or not a hex gives income, based on its terrain_type settings.<br />
* '''[filter_vision]''': this tests whether or not the location is currently visible<br />
** '''visible''': yes or no, default yes. "yes" filters for visible locations, "no" filters for invisible locations.<br />
** '''respect_fog''': yes or no, default yes. "yes" filters for locations that are clear of both fog and shroud, "no" filters for locations that are clear of shroud.<br />
** [[StandardSideFilter]] tags and keys as arguments. If there is '''at least one''' matching side which can see the location then the filter matches, and otherwise it fails to match.<br />
*'''[filter_owner]''': If present, inline owner_side= is ignored. Restricts stored locations to villages, each of which must belong to any of the matching sides. If no sides match, restricts to unowned villages (and only these).<br />
**'''[[StandardSideFilter]]''' tags and keys as arguments<br />
* '''find_in''': name of an array or container variable; if present, the location will not match unless it is also found stored in the variable<br />
* '''radius''': matches if any location within the radius matches this filter ([[StandardLocationFilter#Notes_about_Radius_Usage|notes]])<br />
* '''[filter_radius]''': a standard location filter; normally the radius extends outwards from matching locations one step at a time without checking any additional information-- however, if this tag is present, the radius will be restricted so that it can only expand outwards in the directions where it passes the given location filter<br />
* '''[and]''': an extra location filter. Unless a location matches the [and] filter, then it will be excluded. ''Note: [and],[or],and [not] extra location filters are considered after everything else in the containing filter (except radius, which is considered last in 1.3.8 and greater); they are then processed in the order encountered.''<br />
* '''[or]''': an extra location filter. If a location matches the [or] filter, then it will count as a match regardless of conditions in previous filters or the containing filter.<br />
* '''[not]''': an extra location filter. If a location matches the [not] filter, then that location will be excluded.<br />
* '''[filter_adjacent_location]''': a standard location filter; if present the correct number of adjacent locations must match this filter<br />
** '''count''': a number, range, or comma separated range; default "1-6"<br />
** '''adjacent''': a comma separated list of directions; default "n,ne,se,s,sw,nw" (see [[#Directions|notes]])<br />
* '''formula''': {{DevFeature1.13|5}} a [[Wesnoth Formula Language]] formula. Some terrain-specific variables, for example "light" and "castle", can be used in the filter [[#Wesnoth_Formula_Language|(see list below)]]. Do not surround the formula in <code>$(...)</code>, since that will erase the <tt>self</tt> variable.<br />
* '''lua_function''': {{DevFeature1.13|5}} the name of a [[LuaWML|Lua]] function in the global environment that takes arguments <code>x, y</code> and returns true if the given location matches the filter. Non-global functions can now be used here by building a dot-separated "path". Note that this is not actually interpreted as Lua code even though it superficially resembles it, so using a Lua keyword in the path will work, for example "my_filter_functions.goto" will correctly use the function which in actual Lua code would need to be referenced as <code>my_filter_functions["goto"]</code>.<br />
<br />
==Notes about Coordinate Usage==<br />
<br />
When specifying coordinates, the following keys are used:<br />
* '''x''': the first coordinate<br />
* '''y''': the second coordinate<br />
<br />
While some locations should only be one hex (like the starting position of a unit),<br />
others filter over multiple hexes.<br />
The following syntax is used to filter over multiple hexes:<br />
<br />
Dashes('''-''') are used to have the location be a range of hexes.<br />
There must be values before and after the dash;<br />
everything in between these numbers (inclusively) is part of the range.<br />
<br />
Commas(''',''') are used to separate coordinates into a list.<br />
The '''x''' and '''y''' lists are then paired up, with each pair representing one hex or range. <br />
E.g. in order to specify multiple locations 1,4 and 2,5, use:<br />
<br />
<syntaxhighlight lang='wml'><br />
[tag]<br />
x=1,2<br />
y=4,5<br />
[/tag]<br />
</syntaxhighlight><br />
<br />
You should have the same number of commas in each list, and both '''x''' and '''y''' are always lists. For example, this does not mean the locations (1,4) and (2,4):<br />
<syntaxhighlight lang='wml'><br />
[tag]<br />
x=1,2<br />
y=4 # bad example, implementation-defined behavior<br />
[/tag]<br />
</syntaxhighlight><br />
<br />
A pair can have a single value for one coordinate and a range for the other. This matches (1,4) and the entire column from (2,1) downwards:<br />
<syntaxhighlight lang='wml'><br />
[tag]<br />
x=1, 2<br />
y=4,1-999<br />
[/tag]<br />
</syntaxhighlight><br />
<br />
Providing only '''x''' or only '''y''' is valid. This matches the entire columns from (1,1) and (2,1) downwards:<br />
<syntaxhighlight lang='wml'><br />
[tag]<br />
x=1,2<br />
[/tag]<br />
</syntaxhighlight><br />
<br />
Note: although the ordering of locations in a list generally does not matter,<br />
the action '''[move_unit_fake]''' takes in a list of hexes,<br />
and moves an image onto each of those hexes in order.<br />
<br />
==Notes about Radius Usage==<br />
If you aren't storing any locations successfully, it may be because you put the radius or filters in the wrong place for them to combine correctly.<br />
<br />
<syntaxhighlight lang='wml'><br />
[have_location]<br />
terrain=Gg^Vh<br />
[and]<br />
x=$x1<br />
y=$y1<br />
radius=1<br />
[/and]<br />
[/have_location]<br />
</syntaxhighlight><br />
<br />
Note that the use of [and] here causes the radius to have a very different meaning. Normally, all of the criteria besides radius are checked, producing a set of hexes to which the radius is applied. This means, for example, that if you're trying to find "a hex without a unit on it within 5 hexes of (15, 23)", the code:<br />
<br />
<syntaxhighlight lang='wml'><br />
[have_location]<br />
x,y=15,23<br />
radius=5 # oops... this time it won't work as expected<br />
[not]<br />
[filter]<br />
[/filter]<br />
[/not]<br />
[have_location]<br />
</syntaxhighlight><br />
<br />
will not work! First, it looks for a hex with x=15, y=23 without a unit on it. Then, it returns that hex and all hexes within 5 of it. If (15, 23) happens to be occupied, then it will return no hexes, because "all hexes within 5 hexes of (no hexes)" is still "no hexes". Instead, put an [and] around the x,y and radius requirements, and it will separately find "(15, 23) and all hexes within 5 of it" and "each of those hexes that doesn't have a unit on it", producing the desired result.<br />
<br />
== Directions ==<br />
<br />
Some attributes expect a direction or list of directions. Valid base directions are n, ne, nw, s, se, sw, and there are three operators supported as well:<br />
<br />
* To take the opposite direction, use - (eg -n is the same as s)<br />
* {{DevFeature1.13|2}} To rotate clockwise, use :cw (eg n:cw is the same as ne)<br />
* {{DevFeature1.13|2}} To rotate counterclockwise, use :ccw (eg n:ccw is the same as nw)<br />
<br />
You can't apply multiple rotation operators - for example, "n:cw:ccw" is not a valid direction. If for some reason you really need multiple rotations, you can use parentheses (so, "(n:cw):ccw" is valid and is the same as n). Similarly, "--n" is not valid, but "-(-n)" is valid and is the same as n.<br />
<br />
This syntax is mainly useful when used in conjunction with variable substitution in the adjacent key in [filter_adjacent_location] and in [filter_adjacent] (in [[StandardUnitFilter]]), but will work anywhere a direction is expected. For example, using [modify_unit] to change a unit's direction:<br />
<br />
<syntaxhighlight lang='wml'><br />
[modify_unit]<br />
[filter]<br />
# ... Whatever filter you need<br />
[/filter]<br />
facing=-$this_unit.facing<br />
[/modify_unit]<br />
</syntaxhighlight><br />
<br />
That will cause the matched units to turn around.<br />
<br />
== Filtering Terrains ==<br />
<br />
The '''terrain=''' key allows you to filter based on the terrain of a space, for example:<br />
<br />
<syntaxhighlight lang='wml'><br />
[event]<br />
[filter]<br />
[filter_location]<br />
terrain=Ch <br />
[/filter_location]<br />
[/filter]<br />
[/event]<br />
</syntaxhighlight><br />
<br />
At some places the terrains can be filtered with a match list. This list is a comma separated list of [[TerrainCodesWML|terrain strings]] and patterns which will be processed in order. As soon as a pattern matching the reference terrain is found, the result of the filter will be determined.<br />
<br />
Normally, if one of the patterns matches, the filter is considered successful. However, the special pattern <tt>!</tt> inverts this every time it is encountered &ndash; when inverted, the filter is considered ''unsuccessful'' when one of the patterns matches. In other words, <tt>Gg</tt> matches only basic grass, while <tt>!,Gg</tt> matches ''anything but'' basic grass.<br />
<br />
When the end of the list is reached without any matches, normally the result is an unsuccessful match. However, if the match is currently inverted, ie there are an odd number of <tt>!</tt>, then the result is a successful match.<br />
<br />
An individual terrain pattern consists of two parts, the base and the overlay, separated by the <tt>^</tt> character. The overlay (including the preceding <tt>^</tt>) is optional; if omitted, only terrains without overlays can be matched. The pattern may end with the wildcard character <tt>*</tt> (or be composed solely of the wildcard character). The pattern to match any terrain is <tt>*^*</tt>.<br />
<br />
<b>Example 1:</b> <br><br />
ww* matches ww, www, wwW but not WWW <br><br />
!, ww returns false if ww found and true if not <br><br />
!, ww, wa, !, aa returns false if ww or wa found and true if aa found and false if none found.<br />
<br />
<b>Example 2:</b> <br><br />
<nowiki>*</nowiki>^V* matches all village-terrain <br><br />
Notice how the * can be used separately for both layers (base and overlay layers are separated by the ^-character).<br />
<br />
For a list of terrain types and their string codes see [[TerrainCodesWML|TerrainCodesWML]].<br />
<br />
== Wesnoth Formula Language ==<br />
<br />
When using SLF's '''formula''' attribute, the context object is a '''terrain hex object''' with the following properties:<br />
<br />
* '''x''', '''y''', '''loc''': the latter is a '''location object''' such as what would be returned by [[Wesnoth_Formula_Language#loc|loc()]].<br />
* '''id'''<br />
* '''name'''<br />
* '''editor_name'''<br />
* '''description'''<br />
* '''icon'''<br />
* '''light'''<br />
* '''village''': a boolean containing the value of [terrain_type]gives_income=<br />
* '''castle'''<br />
* '''keep'''<br />
* '''healing''': an integer containing the value of [terrain_type]heals=<br />
* '''owner_side'''<br />
<br />
For an up-to-date list, check the C++ function terrain_callable::get_value(const std::string& key) const.<br />
<br />
Some location formulas also have access to a '''teleport_unit''' variable, which is a '''[[StandardUnitFilter#Wesnoth_Formula_Language|unit object]]'''.<br />
<br />
== Tutorial ==<br />
* [[FilterWML/Examples_-_How_to_use_Filter|How To Use Filter (with examples)]]<br />
<br />
== See Also ==<br />
<br />
* [[FilterWML]]<br />
<br />
[[Category: WML Reference]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=1.17_Roadmap&diff=692411.17 Roadmap2022-02-05T13:16:38Z<p>Doofus-01: /* 1.17.15 (04/16/2023) */</p>
<hr />
<div>This page is for consolidating and planning when new features and fixes are intended to land in the 1.17 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=55255 here].<br />
<br />
== Instructions ==<br />
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.<br />
<br />
Additionally, the current set of 1.17 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.18 released by February 2024. This will allow 1.18 to be in the Ubuntu 24.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other specific criteria to use as a final deadline. Alternatively, depending on what plans people have, 1.18 can be scheduled to happen earlier than that (in 2023).<br />
<br />
== 1.17.0 (01/16/2022) ==<br />
* [https://github.com/wesnoth/wesnoth/issues/6292 #6292] Fix+backport "Multi-turn moves are visible to enemy players" (octalot)<br />
* [https://github.com/wesnoth/wesnoth/issues/6283 #6283] Fix+backport "OOS watching MP replays" (Pentarctagon)<br />
* [https://github.com/wesnoth/wesnoth/issues/6285 #6285] Fix+backport "Multiplayer scenarios with custom terrains don't load for non-host" (already done by Pentarctagon)<br />
* [https://github.com/wesnoth/wesnoth/issues/6315 #6315] Fix+backport "[store_unit] and [modify_unit] move units from recall list to map" (octalot or celticminstrel)<br />
<br />
== 1.17.1 (02/20/2022) ==<br />
* [https://github.com/wesnoth/wesnoth/issues/6305 #6305] Fix "[foreach]array=this_item.something does not write back to the outer this_item". Undecided whether to backport. (octalot)<br />
* (no issue logged) Add+backport Editor docs about the pink "D" deprecation marker (octalot)<br />
* [https://github.com/wesnoth/wesnoth/issues/6383 #6383] Fix+backport (Pentarctagon)<br />
* [https://github.com/wesnoth/wesnoth/issues/6400 #6400] Fix+backport show in the terrain help that oases heal (octalot)<br />
* [https://github.com/wesnoth/wesnoth/issues/6422 #6422] Fix+backport hide editor hints about shift+click (octalot)<br />
<br />
== 1.17.2 (03/20/2022) ==<br />
* [https://github.com/wesnoth/wesnoth/issues/6225 #6225] Fix+backport Clarify editor docs about terrain mode, possibly revise error handling UX (octalot)<br />
<br />
== 1.17.3 (04/17/2022) ==<br />
<br />
<br />
== 1.17.4 (05/15/2022) ==<br />
* Add forum_auth support to campaignd (Pentarctagon)<br />
<br />
== 1.17.5 (06/19/2022) ==<br />
* UtBS S12 (The Final Confrontation) Rework (knyghtmare)<br />
* scenario_boss Micro AI (maybe it will be UtBS specific but it remains to be seen) (knyghtmare)<br />
* Untitled RPG scenario/mini-campaign (depends on my schedule) (knyghtmare)<br />
<br />
== 1.17.6 (07/17/2022) ==<br />
<br />
<br />
== 1.17.7 (08/21/2022) ==<br />
* Finish adding code comments for the WML unit tests (Pentarctagon)<br />
<br />
== 1.17.8 (09/18/2022) ==<br />
* [https://github.com/wesnoth/wesnoth/issues/5041 #5041] Draw text on images in [[IntroWML]], useable for place-name labels on the journey-tracker maps (octalot)<br />
* Reorganize the WML unit test file/folder structure so it's easier to find specific tests without using grep (Pentarctagon)<br />
<br />
== 1.17.9 (10/16/2022) ==<br />
<br />
<br />
== 1.17.10 (11/20/2022) ==<br />
* sprite palette cleanup completed (doofus-01)<br />
<br />
== 1.17.11 (12/18/2022) ==<br />
<br />
<br />
== 1.17.12 (01/15/2023) ==<br />
* New multiplayer maps focused on player vs player vs ai (Hejnewar)<br />
* Revert [https://github.com/wesnoth/wesnoth/pull/6463 #6463] removing the deprecated SPECIAL_NOTES macro again (octalot)<br />
<br />
== 1.17.13 (02/19/2023) ==<br />
<br />
<br />
== 1.17.14 (03/19/2023) ==<br />
<br />
<br />
== 1.17.15 (04/16/2023) ==<br />
* finalize sprite palettes and swatches for defined recoloring (doofus-01)<br />
<br />
== 1.17.16 (05/21/2023) ==<br />
<br />
<br />
== 1.17.17 (06/18/2023) ==<br />
<br />
<br />
== 1.17.18 (07/16/2023) ==<br />
<br />
<br />
== 1.17.19 (08/20/2023) ==<br />
<br />
<br />
== 1.17.20 (09/17/2023) ==<br />
* Continue adding more WML/lua unit tests to improve API coverage (Pentarctagon)<br />
* Balance changes focused mostly on higher levels and experience (Hejnewar)<br />
* Hybrid Dunefolk campaign (Hejnewar)<br />
<br />
== 1.17.21 (10/15/2023) (Beta 1) ==<br />
'''This marks the beginning of the feature freeze and string freeze for 1.17;''' the only API changes made past this point must be to fix bugs.<br />
<br />
== 1.17.22 (11/19/2023) (Beta 2) ==<br />
<br />
<br />
== 1.17.23 (12/17/2023) (Beta 3) ==<br />
<br />
<br />
== 1.17.24 (01/21/2024) (RC1) ==<br />
'''This marks the beginning of the API freeze;''' no API changes for for any reason can be made at this point. Additional RC releases will be done as needed.<br />
<br />
== 1.18.0 (02/18/2024) ==<br />
<br />
<br />
[[Category:Roadmaps]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=1.17_Roadmap&diff=692401.17 Roadmap2022-02-05T13:12:42Z<p>Doofus-01: /* 1.17.10 (11/20/2022) */</p>
<hr />
<div>This page is for consolidating and planning when new features and fixes are intended to land in the 1.17 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=55255 here].<br />
<br />
== Instructions ==<br />
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.<br />
<br />
Additionally, the current set of 1.17 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.18 released by February 2024. This will allow 1.18 to be in the Ubuntu 24.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other specific criteria to use as a final deadline. Alternatively, depending on what plans people have, 1.18 can be scheduled to happen earlier than that (in 2023).<br />
<br />
== 1.17.0 (01/16/2022) ==<br />
* [https://github.com/wesnoth/wesnoth/issues/6292 #6292] Fix+backport "Multi-turn moves are visible to enemy players" (octalot)<br />
* [https://github.com/wesnoth/wesnoth/issues/6283 #6283] Fix+backport "OOS watching MP replays" (Pentarctagon)<br />
* [https://github.com/wesnoth/wesnoth/issues/6285 #6285] Fix+backport "Multiplayer scenarios with custom terrains don't load for non-host" (already done by Pentarctagon)<br />
* [https://github.com/wesnoth/wesnoth/issues/6315 #6315] Fix+backport "[store_unit] and [modify_unit] move units from recall list to map" (octalot or celticminstrel)<br />
<br />
== 1.17.1 (02/20/2022) ==<br />
* [https://github.com/wesnoth/wesnoth/issues/6305 #6305] Fix "[foreach]array=this_item.something does not write back to the outer this_item". Undecided whether to backport. (octalot)<br />
* (no issue logged) Add+backport Editor docs about the pink "D" deprecation marker (octalot)<br />
* [https://github.com/wesnoth/wesnoth/issues/6383 #6383] Fix+backport (Pentarctagon)<br />
* [https://github.com/wesnoth/wesnoth/issues/6400 #6400] Fix+backport show in the terrain help that oases heal (octalot)<br />
* [https://github.com/wesnoth/wesnoth/issues/6422 #6422] Fix+backport hide editor hints about shift+click (octalot)<br />
<br />
== 1.17.2 (03/20/2022) ==<br />
* [https://github.com/wesnoth/wesnoth/issues/6225 #6225] Fix+backport Clarify editor docs about terrain mode, possibly revise error handling UX (octalot)<br />
<br />
== 1.17.3 (04/17/2022) ==<br />
<br />
<br />
== 1.17.4 (05/15/2022) ==<br />
* Add forum_auth support to campaignd (Pentarctagon)<br />
<br />
== 1.17.5 (06/19/2022) ==<br />
* UtBS S12 (The Final Confrontation) Rework (knyghtmare)<br />
* scenario_boss Micro AI (maybe it will be UtBS specific but it remains to be seen) (knyghtmare)<br />
* Untitled RPG scenario/mini-campaign (depends on my schedule) (knyghtmare)<br />
<br />
== 1.17.6 (07/17/2022) ==<br />
<br />
<br />
== 1.17.7 (08/21/2022) ==<br />
* Finish adding code comments for the WML unit tests (Pentarctagon)<br />
<br />
== 1.17.8 (09/18/2022) ==<br />
* [https://github.com/wesnoth/wesnoth/issues/5041 #5041] Draw text on images in [[IntroWML]], useable for place-name labels on the journey-tracker maps (octalot)<br />
* Reorganize the WML unit test file/folder structure so it's easier to find specific tests without using grep (Pentarctagon)<br />
<br />
== 1.17.9 (10/16/2022) ==<br />
<br />
<br />
== 1.17.10 (11/20/2022) ==<br />
* sprite palette cleanup completed (doofus-01)<br />
<br />
== 1.17.11 (12/18/2022) ==<br />
<br />
<br />
== 1.17.12 (01/15/2023) ==<br />
* New multiplayer maps focused on player vs player vs ai (Hejnewar)<br />
* Revert [https://github.com/wesnoth/wesnoth/pull/6463 #6463] removing the deprecated SPECIAL_NOTES macro again (octalot)<br />
<br />
== 1.17.13 (02/19/2023) ==<br />
<br />
<br />
== 1.17.14 (03/19/2023) ==<br />
<br />
<br />
== 1.17.15 (04/16/2023) ==<br />
<br />
<br />
== 1.17.16 (05/21/2023) ==<br />
<br />
<br />
== 1.17.17 (06/18/2023) ==<br />
<br />
<br />
== 1.17.18 (07/16/2023) ==<br />
<br />
<br />
== 1.17.19 (08/20/2023) ==<br />
<br />
<br />
== 1.17.20 (09/17/2023) ==<br />
* Continue adding more WML/lua unit tests to improve API coverage (Pentarctagon)<br />
* Balance changes focused mostly on higher levels and experience (Hejnewar)<br />
* Hybrid Dunefolk campaign (Hejnewar)<br />
<br />
== 1.17.21 (10/15/2023) (Beta 1) ==<br />
'''This marks the beginning of the feature freeze and string freeze for 1.17;''' the only API changes made past this point must be to fix bugs.<br />
<br />
== 1.17.22 (11/19/2023) (Beta 2) ==<br />
<br />
<br />
== 1.17.23 (12/17/2023) (Beta 3) ==<br />
<br />
<br />
== 1.17.24 (01/21/2024) (RC1) ==<br />
'''This marks the beginning of the API freeze;''' no API changes for for any reason can be made at this point. Additional RC releases will be done as needed.<br />
<br />
== 1.18.0 (02/18/2024) ==<br />
<br />
<br />
[[Category:Roadmaps]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=ReferenceWML&diff=68544ReferenceWML2021-09-26T23:42:52Z<p>Doofus-01: </p>
<hr />
<div>{{WML Tags}}<br />
== The Wesnoth Markup Language ==<br />
<br />
The Wesnoth Markup Language (WML) is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML. A major feature in WML are macros, which are alike those found in the C language and similarily are handled by a preprocessor. Implementation-wise, WML files are handled mainly by the ''config'' class (and ''simple_wml'' in [[wesnothd]]).<br />
<br />
This page is a collection of pointers to different common WML structures.<br />
<br />
See [[BuildingScenarios]], [[BuildingCampaigns]] and [[BuildingUnits]]<br />
for a tutorial style overview.<br />
<br />
<br />
<br />
''Note: this reference may contain slight inaccuracies, might not list all existing keys and tags or might contain some deprecated syntax. If you find that this reference doesn't give you the answer to how to implement some feature in WML, the most reliable way is to look at the WML code of existing units and campaigns that have done so.''<br />
<br />
== How WML works ==<br />
<br />
* [[SyntaxWML]] Description of WML syntax, and how to use variables<br />
* [[PreprocessorRef]] the WML preprocessor syntax<br />
* [[GrammarWML]] A more formal definition of the WML syntax. More useful for implementing a WML parser than for writing WML documents.<br />
<br />
== WML toplevel tags ==<br />
<br />
The following covers most of the possible toplevel tags in a typical main WML file. Some minor and dev-oriented tags (not intended for use by UMC) are omitted.<br />
<br />
* [[GameConfigWML]] the top level '''[game_config]''' tag<br />
* [[UnitsWML]] the top level '''[units]''' tag<br />
** [[UnitTypeWML]] how to describe a unit type<br />
** [[AnimationWML]] how to animate units<br />
* [[CampaignWML]] the top level '''[campaign]''' tag<br />
* [[CoreWML]] the top level '''[core]''' tag<br />
* [[ScenarioWML]] the top level tags '''[scenario]''', '''[multiplayer]''', '''[test]''', and '''[tutorial]'''<br />
** [[EventWML]] how to describe an event<br />
** [[SideWML]] how to describe a side<br />
** [[MapGeneratorWML]] the random map generator<br />
** [[TimeWML]] how to describe a day<br />
** [[IntroWML]] how to describe the intro screen<br />
* [[EraWML]] the top level '''[era]''' tag<br />
* [[TerrainWML]] the top level '''[terrain_type]''' tag<br />
* [[TerrainGraphicsWML]], the top level '''[terrain_graphics]''' tag<br />
* [[ThemeWML]] the top level '''[theme]''' tag<br />
* [[LanguageWML]] the top level '''[language]''' tag<br />
* [[LocaleWML]] the top level '''[locale]''' tag<br />
* [[HelpWML]] the top level '''[help]''' tag<br />
* [[BinaryPathWML]] the top level '''[binary_path]''' tag<br />
* [[FontsWML]] the top level '''[fonts]''' tag<br />
* [[WesCamp#The_textdomain_declaration|Textdomains]] the '''[textdomain]''' tag<br />
<br />
Some other files use the WML format, but with different tags.<br />
<br />
* [[SavefileWML]] a description of the format of savegames<br />
** [[ReplayWML]] a description of the format of player actions such as moving a unit<br />
** [[StatisticalScenarioWML]] used to generate statistics of a savegame<br />
* [[PblWML]] a description of the format of server-uploadable campaigns<br />
* [[SchemaWML]] a description of WML files that define the structure of other WML files<br />
* [[DiffWML]] used to describe structural differences between preprocessed WML documents<br />
* [[GUIToolkit]] creating dialogs<br />
<br />
== Other WML tags ==<br />
<br />
* [[EventWML]] how to describe an event<br />
** [[FilterWML]] the construct to filter on units, locations, and weapons<br />
** [[ActionWML]] to describe the actions which occur when the event is fired<br />
*** [[ConditionalActionsWML]] actions that encapsulate conditional filters and the actions to execute if the conditions are met<br />
*** [[DirectActionsWML]] actions that directly affect gameplay: for example creating a unit<br />
**** [[SingleUnitWML]] how to describe a unit<br />
*** [[InternalActionsWML]] actions that WML uses internally: for example storing a variable<br />
*** [[InterfaceActionsWML]] actions that do not affect gameplay: for example displaying a message<br />
*** [[LuaWML]] how to code actions with the Lua language (BfW 1.14 and earlier)<br />
*** [[LuaAPI]] how to code actions with the Lua language (BfW 1.16 and later)<br />
* [[AiWML]] how to describe parameters for AI<br />
* [[EffectWML]] the construct to modify a unit<br />
* [[AbilitiesWML]] a list of the different abilities a unit or weapon can have<br />
* [[DescriptionWML]] the structure of WML coded menus like the difficulty chooser of campaigns<br />
* [[EditorWML]] tags controlling the post-1.4 editor's behavior<br />
<br />
== Predefined macros == <br />
<br />
Wesnoth ships with a library of predefined macros you should find useful in writing your own WML.<br />
* [https://www.wesnoth.org/macro-reference.html WML Macros] - description of all such macros.<br />
<br />
== Other ==<br />
<br />
* [[ReferenceWMLSyntax]] how this wiki and the pages it links to should be formatted<br />
* [[ConventionsWML]] how to make your WML more readable<br />
* [[Wml_optimisation]] how to make your WML code more efficient<br />
* [[UsefulWMLFragments]] Various pieces of WML for various purposes. If you have some WML you're proud of that you think others can use, add it here.<br />
* [[Maintenance tools]] for wmlindent, wmllint, wmlscope<br />
* [[CommandMode]] commands are not strictly speaking part of WML, these could be a little hard to find so there's a link here.<br />
* [[MultiplayerServerWML]] is used when communicating with the multiplayer server.<br />
* [[CampaignServerWML]] is used when managing contributed campaigns on the campaign server.<br />
* [[ImagePathFunctions]] are used when applying the color function to images, such as marking units as belonging to a team or in TerrainGraphics.<br />
* [[Pango formatting]] shows ways to enrich descriptions (pango markup, which can generate basic html tags like <nowiki><b>, <i>, <span></nowiki> and others).<br />
* [[Wesnoth_Formula_Language]] (WFL) often used with $() formulas.<br />
* [[PreprocessorRef|Syntax of preprocessor mini-language]] : symbols, macros, file inclusions...<br />
<br />
== See Also ==<br />
<br />
* [[BuildingMaps]] the text-based format for Wesnoth maps<br />
* [[TerrainCodeTableWML]] a list of all terrains, and [[TerrainCodesWML]], on how to use them<br />
* [[MultiHexTutorial]] a description of the multi-hex tiling system<br />
* [[IGNFileFormat]] a description of the ignore file format<br />
* [[CompatibilityStandards#Deprecation_levels_-_When_to_remove_deprecated_features|DeprecationLevels]]<br />
<br />
[[Category: WML Reference]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=LuaAPI/UpdatingFrom14&diff=68316LuaAPI/UpdatingFrom142021-07-05T13:41:19Z<p>Doofus-01: /* GUI2 API */</p>
<hr />
<div><br />
This page contains a summary of the major Lua API changes between 1.12 and 1.15, to help make updating older code simpler.<br />
<br />
In general, when it says "renamed", the new function is a drop-in replacement for the old one. When it says "replaced", the new function probably has a different API (such as different arguments) or might not even be a function at all.<br />
<br />
=== Functions in wesnoth namespace ===<br />
<br />
* '''weesnoth.remove_fog''' renamed to '''wesnoth.sides.remove_fog'''<br />
* '''wesnoth.add_ai_component''' renamed to '''wesnoth.sides.add_ai_component'''<br />
* '''wesnoth.add_fog''' renamed to '''wesnoth.sides.place_fog'''<br />
* '''wesnoth.add_modification''' renamed to '''wesnoth.units.add_modification'''<br />
* '''wesnoth.add_sound_source''' replaced with '''wesnoth.audio.sources''' mapping (write to key)<br />
* '''wesnoth.add_tile_overlay''' renamed to '''wesnoth.interface.add_hex_overlay'''<br />
* '''wesnoth.add_widget_definition''' renamed to '''gui.add_widget_definition'''<br />
* '''wesnoth.advance_unit''' renamed to '''wesnoth.units.advance'''<br />
* '''wesnoth.alert''' renamed to '''gui.alert'''<br />
* '''wesnoth.allow_end_turn''' renamed to '''wesnoth.interface.allow_end_turn'''<br />
* '''wesnoth.append_ai''' renamed to '''wesnoth.sides.append_ai'''<br />
* '''wesnoth.canonical_path''' renamed to '''filesystem.canonical_path'''<br />
* '''wesnoth.change_ai_component''' renamed to '''wesnoth.sides.change_ai_component'''<br />
* '''wesnoth.clear_messages''' renamed to '''wesnoth.interface.clear_chat_messages'''<br />
* '''wesnoth.color_adjust''' replaced with '''wesnoth.interface.color_adjust'''<br />
* '''wesnoth.compare_versions''' replaced with '''wesnoth.version''', which creates a version object that can be compared with standard comparison operators<br />
* '''wesnoth.confirm''' renamed to '''gui.confirm'''<br />
* '''wesnoth.copy_unit''' renamed to '''wesnoth.units.clone'''<br />
* '''wesnoth.create_animator''' renamed to '''wesnoth.units.create_animator'''<br />
* '''wesnoth.create_side''' renamed to '''wesnoth.sides.create'''<br />
* '''wesnoth.create_unit''' renamed to '''wesnoth.units.create'''<br />
* '''wesnoth.create_weapon''' renamed to '''wesnoth.units.create_weapon'''<br />
* '''wesnoth.debug_ai''' renamed to '''wesnoth.sides.debug_ai'''<br />
* '''wesnoth.debug''' renamed to '''wml.tostring'''; in addition, it now produces an output that is valid WML, meaning that <syntaxhighlight lang=lua inline>wml.parse(wml.tostring(wml_table))</syntaxhighlight> will output a clone of '''wml_table''' (though for this purpose there's a separate '''wml.clone''' function which is probably faster).<br />
* '''wesnoth.delay''' renamed to '''wesnoth.interface.delay'''<br />
* '''wesnoth.delete_ai_component''' renamed to '''wesnoth.sides.delete_ai_component'''<br />
* '''wesnoth.deselect_hex''' renamed to '''wesnoth.interface.deselect_hex'''<br />
* '''wesnoth.end_level''' replaced with assignable '''wesnoth.scenario.end_level_data'''<br />
* '''wesnoth.end_turn''' renamed to '''wesnoth.interface.end_turn'''<br />
* '''wesnoth.erase_unit''' renamed to '''wesnoth.units.erase'''<br />
* '''wesnoth.eval_conditiona''' renamed to '''wml.eval_conditional'''<br />
* '''wesnoth.extract_unit''' renamed to '''wesnoth.units.extract'''<br />
* '''wesnoth.find_cost_map''' renamed to '''wesnoth.paths.find_cost_map'''<br />
* '''wesnoth.find_path''' renamed to '''wesnoth.paths.find_path'''<br />
* '''wesnoth.find_reach''' renamed to '''wesnoth.paths.find_reach'''<br />
* '''wesnoth.find_vacant_tile''' renamed to '''wesnoth.paths.find_vacant_tile'''<br />
* '''wesnoth.find_vision_range''' renamed to '''wesnoth.paths.find_vision_range'''<br />
* '''wesnoth.float_label''' renamed to '''wesnoth.interface.float_label'''<br />
* '''wesnoth.format_conjunct_list''' renamed to '''stringx.format_conjunct_list'''<br />
* '''wesnoth.format_disjunct_list''' renamed to '''stringx.format_disjunct_list'''<br />
* '''wesnoth.format''' renamed to '''stringx.vformat''' and can also be called directly on a string literal<br />
* '''wesnoth.gamestate_inspector''' renamed to '''gui.show_inspector'''<br />
* '''wesnoth.get_all_vars''' replaced with read-only variable '''wml.all_variables''' (but it should still be used sparingly)<br />
* '''wesnoth.get_displayed_unit''' renamed to '''wesnoth.interface.get_displayed_unit'''<br />
* '''wesnoth.get_end_level_data''' replaced with readable '''wesnoth.scenario.end_level_data'''<br />
* '''wesnoth.get_image_size''' renamed to '''filesystem.image_size'''<br />
* '''wesnoth.get_max_liminal_bonus''' replaced with read-ony '''wesnoth.current.schedule.liminal_bonus'''<br />
* '''wesnoth.get_mouseover_tile''' renamed to '''wesnoth.interface.get_hovered_hex'''<br />
* '''wesnoth.get_recall_units''' renamed to '''wesnoth.units.find_on_recall'''<br />
* '''wesnoth.get_selected_tile''' renamed to '''wesnoth.interface.get_selected_hex'''<br />
* '''wesnoth.get_side_variable''' and '''wesnoth.set_side_variable''' replaced by '''variables''' member in side data (found in '''wesnoth.sides''' array). This otherwise works the same as '''wml.variables'''.<br />
* '''wesnoth.get_sides''' renamed to '''wesnoth.sides.find'''<br />
* '''wesnoth.get_sound_source''' replaced with '''wesnoth.audio.sources''' mapping (read key)<br />
* '''wesnoth.get_starting_location''' replaced by '''starting_location''' member in side data<br />
* '''wesnoth.get_time_of_day''' replaced with '''wesnoth.schedule.get_time_of_day''' and '''wesnoth.schedule.get_illumination''' as well as '''wesnoth.current.schedule.time_of_day'''<br />
* '''wesnoth.get_time_stamp''' renamed to '''wesnoth.ms_since_init'''<br />
* '''wesnoth.get_traits''' replaced with '''wesnoth.game_config.global_traits'''<br />
* '''wesnoth.get_unit''' renamed to '''wesnoth.units.get'''<br />
* '''wesnoth.get_units''' renamed to '''wesnoth.units.find_on_map'''<br />
* '''wesnoth.get_variable''' and '''wesnoth.set_variable''' are replaced by '''wml.variables''' which can be indexed with a variable path - set a variable by assigning to it<br />
* '''wesnoth.have_file''' renamed to '''filesystem.have_file'''<br />
* '''wesnoth.highlight_hex''' renamed to '''wesnoth.interface.highlight_hex'''<br />
* '''wesnoth.invoke_synced_command''' renamed to '''wesnoth.sync.invoke_command'''<br />
* '''wesnoth.is_enemy''' renamed to '''wesnoth.sides.is_enemy'''<br />
* '''wesnoth.is_fogged''' renamed to '''wesnoth.sides.is_fogged'''<br />
* '''wesnoth.is_shrouded''' renamed to '''wesnoth.sides.is_shrouded'''<br />
* '''wesnoth.is_skipping_messages''' renamed to '''wesnoth.interface.is_skipping_messages'''<br />
* '''wesnoth.lock_view''' renamed to '''wesnoth.interface.lock'''<br />
* '''wesnoth.match_side''' renamed to '''wesnoth.sides.matches'''<br />
* '''wesnoth.match_unit''' renamed to '''wesnoth.units.matches'''<br />
* '''wesnoth.message''' renamed to '''wesnoth.interface.add_chat_message'''<br />
* '''wesnoth.music_list''' renamed to '''wesnoth.audio.music_list'''<br />
* '''wesnoth.open_help''' renamed to '''gui.show_help'''<br />
* '''wesnoth.place_shroud''' replaced with '''wesnoth.sides.place_shroud''' and '''wesnoth.sides.override_shroud'''<br />
* '''wesnoth.play_sound''' renamed to '''wesnoth.audio.play'''<br />
* '''wesnoth.put_recall_unit''' renamed to '''wesnoth.units.to_recall'''<br />
* '''wesnoth.put_unit''' renamed to '''wesnoth.units.to_map'''<br />
* '''wesnoth.random''' renamed to '''mathx.random'''<br />
* '''wesnoth.read_file''' renamed to '''filesystem.read_file'''<br />
* '''wesnoth.remove_modifications''' renamed to '''wesnoth.units.remove_modifications'''<br />
* '''wesnoth.remove_sound_source''' replaced with '''wesnoth.audio.sources''' mapping (assign nil to key)<br />
* '''wesnoth.remove_tile_overlay''' renamed to '''wesnoth.interface.remove_hex_overlay'''<br />
* '''wesnoth.replace_schedule''' renamed to '''wesnoth.schedule.replace'''<br />
* '''wesnoth.scroll_to_tile''' renamed to '''wesnoth.interface.scroll_to_hex'''<br />
* '''wesnoth.scroll''' renamed to '''wesnoth.interface.scroll'''<br />
* '''wesnoth.select_unit''' renamed to '''wesnoth.units.select''' (also available as wesnoth.interface.select_unit)<br />
* '''wesnoth.set_end_campaign_credits''' replaced with assignable '''wesnoth.scenario.show_credits'''<br />
* '''wesnoth.set_end_campaign_text''' replaced with assignable '''wesnoth.scenario.end_text''' and '''wesnoth.scenario.end_text_duration'''<br />
* '''wesnoth.set_next_scenario''' replaced with assignable '''wesnoth.scenario.next'''<br />
* '''wesnoth.set_side_id''' renamed to '''wesnoth.sides.set_id'''<br />
* '''wesnoth.set_time_of_day''' (which was undocumented and unofficial) replaced with assigning '''wesnoth.current.schedule.time_of_day''', though that only covers part of the original functionality<br />
* '''wesnoth.show_lua_console''' renamed to '''gui.show_lua_console'''<br />
* '''wesnoth.show_menu''' renamed to '''gui.show_menu'''<br />
* '''wesnoth.show_message_box''' renamed to '''gui.show_prompt'''<br />
* '''wesnoth.show_message_dialog''' renamed to '''gui.show_narration'''<br />
* '''wesnoth.show_popup_dialog''' renamed to '''gui.show_popup'''<br />
* '''wesnoth.show_story''' renamed to '''gui.show_story'''<br />
* '''wesnoth.skip_messages''' renamed to '''wesnoth.interface.skip_messages'''<br />
* '''wesnoth.sound_volume''' replaced with read-write '''wesnoth.audio.volume'''<br />
* '''wesnoth.switch_ai''' renamed to '''wesnoth.sides.switch_ai'''<br />
* '''wesnoth.synchronize_choice''' renamed to '''wesnoth.sync.evaluate_single'''<br />
* '''wesnoth.synchronize_choices''' renamed to '''wesnoth.sync.evaluate_multiple'''<br />
* '''wesnoth.teleport''' renamed to '''wesnoth.units.teleport'''<br />
* '''wesnoth.theme_items''' renamed to '''wesnoth.interface.game_display''' - it's still a table with the same keys as before<br />
* '''wesnoth.tovconfig''' renamed to '''wml.tovconfig'''<br />
* '''wesnoth.transform_unit''' renamed to '''wesnoth.units.transform'''<br />
* '''wesnoth.unit_ability''' renamed to '''wesnoth.units.ability'''<br />
* '''wesnoth.unit_defense''' renamed to '''wesnoth.units.chance_to_be_hit'''<br />
* '''wesnoth.unit_jamming_cost''' renamed to '''wesnoth.units.jamming_on'''<br />
* '''wesnoth.unit_movement_cost''' renamed to '''wesnoth.units.movement_on'''<br />
* '''wesnoth.unit_resistance''' renamed to '''wesnoth.units.resistance'''<br />
* '''wesnoth.unit_vision_cost''' renamed to '''wesnoth.units.vision_on'''<br />
* '''wesnoth.unsynced''' renamed to '''wesnoth.sync.run_unsynced'''<br />
* '''wesnoth.view_locked''' renamed to '''wesnoth.interface.is_locked'''<br />
* '''wesnoth.wml_matches_filter''' renamed to '''wml.matches_filter'''<br />
* '''wesnoth.zoom''' renamed to '''wesnoth.interface.zoom'''<br />
<br />
==== wesnoth.tovconfig and related functions in plugins ====<br />
<br />
The '''wesnoth.tovconfig''' function has been removed from the plugin context. This will have no effect on most people, as the plugin context is rarely used. A plugin context is any Lua script loaded using the <tt>--plugin</tt> command-line parameter, primarily intended for creating bots on the multiplayer server.<br />
<br />
If you were calling '''wesnoth.tovconfig''' in a plugin, then you have several options for updating your code. If you simply needed to verify that a variable holds a valid WML table, you can use '''wml.valid''' instead. If you need to substitute variables into a WML table, you can also use '''wml.interpolate''' to replicate the behaviour of '''wml.tovconfig''', supplying the variables themselves as an extra argument (another WML table).<br />
<br />
In addition, the helper functions '''parsed''', '''literal''', '''shallow_parsed''', and '''shallow_literal''' are not available in the plugin context.<br />
<br />
==== GUI2 API ====<br />
<br />
There has been a major rehaul of the GUI2 API for arbitrary custom dialogs. See [[LuaAPI/types/widget]] and [[LuaAPI/gui/widget]] for details; the changes are also summarized below.<br />
<br />
* '''wesnoth.add_dialog_tree_node''' renamed to '''gui.widget.add_item_of_type''' and now takes a reference to the widget instead of a path to it; use '''gui.widget.find''' to convert a path to a reference<br />
* '''wesnoth.get_dialog_value''' and '''wesnoth.set_dialog_value''' removed; instead access the appropriate member of the widget, such as '''selected_index''' or '''selected''' or '''text''' or '''value''' or '''percentage''' or '''selected_item_path''' or '''unfolded''' or '''unit''' or '''label'''. Some of these may be write-only.<br />
* '''wesnoth.remove_dialog_item''' renamed to '''gui.widget.remove_items_at''' and now takes a reference to the widget instead of a path to it; use '''gui.widget.find''' to convert a path to a reference.<br />
* '''wesnoth.set_dialog_active''' removed; instead assign the '''enabled''' member of a widget<br />
** A simple example showing the old code commented out, replacement right below <br> <syntaxhighlight lang=lua ><br />
-- local function preshow()<br />
local function preshow(self)<br />
local var_a = true<br />
-- < whatever you are doing to determine if button should be active ><br />
-- wesnoth.set_dialog_active(var_a, "my_button_id")<br />
local widget_handle = self:find('my_button_id')<br />
widget_handle.enabled = var_a<br />
-- ...<br />
end<br />
</syntaxhighlight><br />
<br />
* '''wesnoth.set_dialog_callback''' removed; instead simply assign to a widget's callback handler, eg <syntaxhighlight lang=lua inline>my_widget.on_modified = function() end</syntaxhighlight><br />
* '''wesnoth.set_dialog_canvas''' renamed to '''gui.widget.set_canvas''' and now takes a reference to the widget instead of a path to it; use '''gui.widget.find''' to convert a path to a reference<br />
* '''wesnoth.set_dialog_focus''' renamed to '''gui.widget.focus''' and now takes a reference to the widget instead of a path to it; use '''gui.widget.find''' to convert a path to a reference<br />
* '''wesnoth.set_dialog_markup''' removed; instead assign the '''use_markup''' member of a widget<br />
* '''wesnoth.set_dialog_tooltip''' removed; instead assign the '''tooltip''' member of a widget<br />
* '''wesnoth.set_dialog_visible''' removed; instead assign the '''visible''' member of a widget<br />
* '''wesnoth.show_dialog''' renamed to '''gui.show_dialog'''<br />
* The '''preshow''' and '''postshow''' functions passed to '''gui.show_dialog''' now take a single parameter, which is a reference to the dialog's root widget (a widget of type "window"). This can be passed to '''gui.widget.find''' to look up widgets by their path. You can also access direct child widgets by simply indexing the root widget.<br />
<br />
==== Map API ====<br />
<br />
Due to a major rehaul of the map API, many map functions are now methods on the map object, available as '''wesnoth.current.map''' (abbreviated in the below listing to just '''map''').<br />
<br />
* '''wesnoth.add_time_area''' renamed to '''wesnoth.map.place_area'''<br />
* '''wesnoth.get_locations''' renamed to '''wesnoth.map.find'''<br />
* '''wesnoth.get_map_size''' replaced with '''map.playable_width''', '''map.playable_height''', and '''map.border_size'''<br />
* '''wesnoth.get_terrain_info''' replaced with '''wesnoth.terrain_types'''<br />
* '''wesnoth.get_terrain''' replaced with '''map[{x,y}]'''<br />
* '''wesnoth.get_village_owner''' renamed to '''wesnoth.map.get_owner'''<br />
* '''wesnoth.get_villages''' replaced with '''wesnoth.map.find''' (with '''gives_income = true''')<br />
* '''wesnoth.label''' renamed to '''wesnoth.map.add_label'''<br />
* '''wesnoth.match_location''' renamed to '''wesnoth.map.matches'''<br />
* '''wesnoth.remove_time_area''' renamed to '''wesnoth.map.remove_area'''<br />
* '''wesnoth.set_terrain''' replaced with assigning '''map[{x,y}]''' - helper functions in '''wesnoth.map''' expose the more advanced assignment operations ('''replace_overlay''', '''replace_both''', '''replace_if_failed''') - just assign the result of one of these functions to the hex<br />
* '''wesnoth.set_village_owner''' renamed to '''wesnoth.map.set_owner'''<br />
* '''wesnoth.special_locations''' renamed to '''map.special_locations''' (note: the length operator is no longer supported)<br />
* '''wesnoth.terrain_mask''' replaced with '''map:terrain_mask'''<br />
<br />
The following functions are only available in map generation scripts:<br />
<br />
* '''wesnoth.create_filter''' renamed to '''wesnoth.map.filter'''<br />
* '''wesnoth.create_map''' renamed to '''wesnoth.map.create'''<br />
* '''wesnoth.default_generate_height_map''' renamed to '''wesnoth.map.generate_height_map'''<br />
* '''wesnoth.generate_default_map''' renamed to '''wesnoth.map.generate'''<br />
* '''map:get_locations''' renamed to '''map:find'''<br />
* '''map:get_tiles_radius''' replaced with '''map::find_in_radius''' (and the order of arguments changed)<br />
<br />
=== helper module ===<br />
<br />
The helper module is being phased out, so quite a lot of things have been moved out of it. This section is written under the assumption that you loaded it with <syntaxhighlight lang=lua inline>local helper = wesnoth.require "helper"</syntaxhighlight> or the like, but many people call it '''H''' instead of '''helper''', so keep that in mind.<br />
<br />
* '''helper.child_array''' renamed to '''wml.child_array'''<br />
* '''helper.child_count''' renamed to '''wml.child_count'''<br />
* '''helper.child_range''' renamed to '''wml.child_range'''<br />
* '''helper.distance_between''' renamed to '''wesnoth.map.distance_between'''<br />
* '''helper.find_attack''' renamed to '''wesnoth.units.find_attack'''<br />
* '''helper.get_child''' renamed to '''wml.get_child'''<br />
* '''helper.get_nth_child''' renamed to '''wml.get_nth_child'''<br />
* '''helper.get_user_choice''' renamed to '''gui.get_user_choice'''<br />
* '''helper.get_variable_array''' renamed to '''wml.array_access.get'''<br />
* '''helper.get_variable_proxy_array''' renamed to '''wml.array_access.get_proxy'''<br />
* '''helper.literal''' renamed to '''wml.literal'''<br />
* '''helper.modify_unit''' renamed to '''wesnoth.units.modify'''<br />
* '''helper.move_unit_fake''' renamed to '''wesnoth.interface.move_unit_fake'''<br />
* '''helper.parsed''' renamed to '''wml.parsed'''<br />
* '''helper.rand''' renamed to '''mathx.random_choice'''<br />
* '''helper.round''' renamed to '''mathx.round'''<br />
* '''helper.set_variable_array''' renamed to '''wml.array_access.set'''<br />
* '''helper.set_wml_tag_metatable''' replaced with '''wml.tag''', which is a table that works exactly the same as what this function would return<br />
* '''helper.set_wml_var_metatable''' replaced with '''wml.variable.proxy''', which is a table that works exactly the same as what this function would return<br />
* '''helper.shallow_literal''' renamed to '''wml.shallow_literal'''<br />
* '''helper.shallow_parsed''' renamed to '''wml.shallow_parsed'''<br />
* '''helper.shuffle''' renamed to '''mathx.shuffle'''<br />
* '''helper.wml_error''' renamed to '''wml.error'''<br />
<br />
=== items module ===<br />
<br />
There were also a few things in an "items" module that have been moved into the main API.<br />
<br />
* '''items.place_halo''' renamed to '''wesnoth.interface.add_item_halo'''<br />
* '''items.place_image''' renamed to '''wesnoth.interface.add_item_image'''<br />
* '''items.remove''' renamed to '''wesnoth.interface.remove_item'''<br />
<br />
[[Category:Lua Reference]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=Release_Notes_1.15.4&diff=65949Release Notes 1.15.42020-08-22T11:53:00Z<p>Doofus-01: /* New Content */</p>
<hr />
<div>== New Content ==<br />
=== Addon titles and descriptions made translatable ===<br />
It's now possible to add translated titles and descriptions to your addons, so they will show up in the target language when browsing the in-game addon manager. The original English title is also displayed below and can be searched for in addition to translations. If you want to add a translated title and description to your addon, see the [https://wiki.wesnoth.org/PblWml#.5Btranslation.5D wiki page].<br />
<br />
=== Units ===<br />
==== Dunefolk ====<br />
Most of the Dunefolk faction's units have new/updated animations. There is also a new unit called falconer, which is a branch in the skirmisher line.<br />
<br />
=== Knalgan Alliance ===<br />
The Poacher and Trapper sprites and animations have been improved.<br />
<br />
=== Multiplayer ===<br />
==== World Conquest ====<br />
The add-on World Conquest II (now called World Conquest) has been added to mainline Wesnoth. World Conquest is a coop multiplayer campaign of 5 scenarios for 1-3 players. It features highly randomized maps for replayability as well as custom item and training systems.<br />
<br />
==== Lobby ====<br />
A new '''Information''' button has been added to the multiplayer lobby. This will show server related information as well as list any ongoing tournaments being held.<br />
<br />
=== Terrain ===<br />
An earthy variation to rockbound caves has been added, using terrain code "Uhe".<br />
Ancient/weathered variations of the stone floor tiles and walls have been added, with terrain codes "Ias" and "Xoa".<br />
<br />
== Changes To Existing Content ==<br />
<br />
=== Campaign changes ===<br />
<br />
==== Under the Burning Suns ====<br />
Under the Burning Suns has been fully rebalanced, including all scenarios and all units in the Quenoth faction. Generally, the campaign is now more challenging. There was also some incremental progress on the Quenoth unit sprites.<br />
<br />
==== Delfador's Memoirs ====<br />
Multiple issues have been fixed with the twelfth scenario of Delfador's Memoirs, including to dialogue and the AI. This should make the dialog flow better and the AI behave more appropriately.<br />
<br />
=== Balance changes ===<br />
==== Drakes ====<br />
Drake Burner line and Armageddon Drake cold resistance changed from -50% to -40% - this small change is supposed to make Burner more prevalent in matchup against Undead as well as counterweight newly buffed Ghost.<br />
<br />
==== Dunefolk ====<br />
Dune Spearmaster shield damage changed from 14 to 13 - this high impact damage on unit called Spearmaster was taking away from his lore identity and was making him too good against Undead and other impact vulnerable units. <br />
<br />
==== Knalgan Alliance ====<br />
Dwarvish Dragonguard hp changed from 59 to 63 - this is update to previous changes of dwarf level ups<br />
<br />
Dwarvish Steelclad hp changed from 55 to 57 - Steelclad was earlier nerfed in order to help balance scenarios against ai but it turned out to be affecting competitive 1 vs 1 too much so we are reverting this change partially.<br />
<br />
Poacher hp changed from 32 to 33 - main reason for this change are matchups against Loyalists and Drakes, this change is supposed to provide slight boost in not only strength but also amount of level ups that this unit receives thus allowing Knalgan player to get initiative thru them more often.<br />
<br />
==== Loyalists ====<br />
Heavy Infantryman cold resistance changed from -10% to 0 - this unit was not excelling in matchup against Undead where it should be doing so. This change is supposed to help with this problem.<br />
<br />
==== Northerners ====<br />
Troll Rocklobber hp changed from 49 to 51 - Rocklobber was level up that was simply not up to pair with usual Troll.<br />
<br />
==== Rebels ====<br />
Merman Hunter hp changed from 30 to 33 - this unit was weakest unit that was dedicated to water control. This was hurting Rebels too much on maps with lots of water. We hope that this change will provide them enough strength in this area.<br />
<br />
Elvish Shaman ranged damage changed from 3 to 4 - Shaman was not used as much as we would like to see it in play, this change is supposed to help her receive just a bit more of spotlight in competitive matches.<br />
<br />
Wose cold resistance changed from 10% to 0 - Wose was highly problematic unit in matchup against Undead, it allowed Rebels to play completely defensively until they had enough Woses to crush their opponent. This change should allow Adepts to kill Woses faster and thus make it much harder for Rebels to just defend. <br />
<br />
==== Undead ====<br />
Banebow hp changed form 50 to 55 - this unit had very low amount of hp for level 3 unit. <br />
<br />
Bone Shooter hp changed from 40 to 42 - this units had very low amount of hp for level 2 unit and its performance as a leader was also subpar.<br />
<br />
Ghost cost changed from 20 to 19 - matchups where Ghost can perform well are also ones where Undead are not in greatest shape, at the same time Ghost is easily countered outside of these matchups. This change is supposed to help both Ghost and Undead as a whole perform better in competitive matches.<br />
<br />
==== Monsters ====<br />
Various changes to Wyvern, Wyvern Rider, Roc, Falcon and Elder Falcon - changes to these units are supposed to make them more lore friendly.<br />
<br />
== Fixes ==<br />
=== Graphics engine memory leak fix ===<br />
An issue dating back to version 1.13.13 was found in the gameβs graphics engine that would result in large memory leaks over time, particularly evident after performing a few save-reloading or game initialization (Campaign mode, Multiplayer, Map Editor) cycles. On Windows and other systems running 32-bit builds of the game, this could eventually result in a game session crashing due to reaching platform-mandated memory limits. Furthermore, either 32-bit or 64-bit systems with small amounts of available RAM could perceive substantial performance degradation during long game sessions, or even crashes in other running software.<br />
<br />
=== Scenario configuration files created by the scenario editor ===<br />
The scenario editor creates .cfg files; but if you edit that .cfg by hand and then use the scenario editor again, the editor will completely rewrite it, likely removing any hand-edited WML. A comment warning about this is now added at the top of these .cfg files.<br />
<br />
The editor-generated .cfg files can be thought of as an extended format for map files. Itβs possible to create a separate .cfg file with hand-edited WML, and then load the editor-generated file with ''[scenario]map_file=example.cfg''. Support for this requires some bug-fixes that were added in this release.<br />
<br />
=== Add-on manager downloading the same add-on twice when updating ===<br />
Previously, when Add-on A depended on Add-on B and both add-ons needed to be updated, Add-on B would be downloaded by the in-game add-on manager twice. This has now been fixed, so that Add-on B will only be downloaded once.<br />
<br />
=== Creating a game when a map contains an invalid terrain ===<br />
When trying to create a game when one of the maps or scenarios used an invalid or unknown terrain, Wesnoth would crash. This has been fixed and Wesnoth now will correctly show an error when selecting the map with the bad terrain instead of crashing.<br />
<br />
=== Handling of high resolution monitors ===<br />
For screens that have a higher resolution, such as 4K monitors, text would previously be displayed far smaller than it should have been. This has been partially fixed, and most text should now be displayed at a more normal size.<br />
<br />
== General/Misc ==<br />
=== Python2 removal complete ===<br />
All tools that were written in Python2 have now been ported to Python3, or removed if they seemed obsolete.<br />
<br />
=== Build report ===<br />
The build report (which is very useful to us and should be included in all reports of bugs and other issues!) now additionally contains information on the monitor, sound configuration, and all installed add-ons.<br />
<br />
=== Timestamps on replay file names ===<br />
The date and time is now added to the file name of replays. This will avoid needing to manually enter a different file name after playing the same scenario multiple times.<br />
<br />
=== Eclipse UMC plugin deprecated ===<br />
The Eclipse plugin for UMC (User Made Content) is now formally deprecated, though it has effectively been unsupported for a few years now. Anyone who is still using this plugin should instead use other supported editors such as Notepad++ or Visual Studio Code.<br />
<br />
== Newly Introduced Issues ==<br />
<br />
[[Category:Release_Notes]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=Release_Notes_1.15.4&diff=65948Release Notes 1.15.42020-08-22T11:42:48Z<p>Doofus-01: /* Dunefolk */</p>
<hr />
<div>== New Content ==<br />
=== Addon titles and descriptions made translatable ===<br />
It's now possible to add translated titles and descriptions to your addons, so they will show up in the target language when browsing the in-game addon manager. The original English title is also displayed below and can be searched for in addition to translations. If you want to add a translated title and description to your addon, see the [https://wiki.wesnoth.org/PblWml#.5Btranslation.5D wiki page].<br />
<br />
=== Units ===<br />
==== Dunefolk ====<br />
Most of the Dunefolk faction's units have new/updated animations. There is also a new unit called falconer, which is a branch in the skirmisher line.<br />
<br />
=== Knalgan Alliance ===<br />
The Poacher and Trapper sprites and animations have been improved.<br />
<br />
=== Multiplayer ===<br />
==== World Conquest ====<br />
The add-on World Conquest II (now called World Conquest) has been added to mainline Wesnoth. World Conquest is a coop multiplayer campaign of 5 scenarios for 1-3 players. It features highly randomized maps for replayability as well as custom item and training systems.<br />
<br />
==== Lobby ====<br />
A new '''Information''' button has been added to the multiplayer lobby. This will show server related information as well as list any ongoing tournaments being held.<br />
<br />
== Changes To Existing Content ==<br />
<br />
=== Campaign changes ===<br />
<br />
==== Under the Burning Suns ====<br />
Under the Burning Suns has been fully rebalanced, including all scenarios and all units in the Quenoth faction. Generally, the campaign is now more challenging. There was also some incremental progress on the Quenoth unit sprites.<br />
<br />
==== Delfador's Memoirs ====<br />
Multiple issues have been fixed with the twelfth scenario of Delfador's Memoirs, including to dialogue and the AI. This should make the dialog flow better and the AI behave more appropriately.<br />
<br />
=== Balance changes ===<br />
==== Drakes ====<br />
Drake Burner line and Armageddon Drake cold resistance changed from -50% to -40% - this small change is supposed to make Burner more prevalent in matchup against Undead as well as counterweight newly buffed Ghost.<br />
<br />
==== Dunefolk ====<br />
Dune Spearmaster shield damage changed from 14 to 13 - this high impact damage on unit called Spearmaster was taking away from his lore identity and was making him too good against Undead and other impact vulnerable units. <br />
<br />
==== Knalgan Alliance ====<br />
Dwarvish Dragonguard hp changed from 59 to 63 - this is update to previous changes of dwarf level ups<br />
<br />
Dwarvish Steelclad hp changed from 55 to 57 - Steelclad was earlier nerfed in order to help balance scenarios against ai but it turned out to be affecting competitive 1 vs 1 too much so we are reverting this change partially.<br />
<br />
Poacher hp changed from 32 to 33 - main reason for this change are matchups against Loyalists and Drakes, this change is supposed to provide slight boost in not only strength but also amount of level ups that this unit receives thus allowing Knalgan player to get initiative thru them more often.<br />
<br />
==== Loyalists ====<br />
Heavy Infantryman cold resistance changed from -10% to 0 - this unit was not excelling in matchup against Undead where it should be doing so. This change is supposed to help with this problem.<br />
<br />
==== Northerners ====<br />
Troll Rocklobber hp changed from 49 to 51 - Rocklobber was level up that was simply not up to pair with usual Troll.<br />
<br />
==== Rebels ====<br />
Merman Hunter hp changed from 30 to 33 - this unit was weakest unit that was dedicated to water control. This was hurting Rebels too much on maps with lots of water. We hope that this change will provide them enough strength in this area.<br />
<br />
Elvish Shaman ranged damage changed from 3 to 4 - Shaman was not used as much as we would like to see it in play, this change is supposed to help her receive just a bit more of spotlight in competitive matches.<br />
<br />
Wose cold resistance changed from 10% to 0 - Wose was highly problematic unit in matchup against Undead, it allowed Rebels to play completely defensively until they had enough Woses to crush their opponent. This change should allow Adepts to kill Woses faster and thus make it much harder for Rebels to just defend. <br />
<br />
==== Undead ====<br />
Banebow hp changed form 50 to 55 - this unit had very low amount of hp for level 3 unit. <br />
<br />
Bone Shooter hp changed from 40 to 42 - this units had very low amount of hp for level 2 unit and its performance as a leader was also subpar.<br />
<br />
Ghost cost changed from 20 to 19 - matchups where Ghost can perform well are also ones where Undead are not in greatest shape, at the same time Ghost is easily countered outside of these matchups. This change is supposed to help both Ghost and Undead as a whole perform better in competitive matches.<br />
<br />
==== Monsters ====<br />
Various changes to Wyvern, Wyvern Rider, Roc, Falcon and Elder Falcon - changes to these units are supposed to make them more lore friendly.<br />
<br />
== Fixes ==<br />
=== Graphics engine memory leak fix ===<br />
An issue dating back to version 1.13.13 was found in the gameβs graphics engine that would result in large memory leaks over time, particularly evident after performing a few save-reloading or game initialization (Campaign mode, Multiplayer, Map Editor) cycles. On Windows and other systems running 32-bit builds of the game, this could eventually result in a game session crashing due to reaching platform-mandated memory limits. Furthermore, either 32-bit or 64-bit systems with small amounts of available RAM could perceive substantial performance degradation during long game sessions, or even crashes in other running software.<br />
<br />
=== Scenario configuration files created by the scenario editor ===<br />
The scenario editor creates .cfg files; but if you edit that .cfg by hand and then use the scenario editor again, the editor will completely rewrite it, likely removing any hand-edited WML. A comment warning about this is now added at the top of these .cfg files.<br />
<br />
The editor-generated .cfg files can be thought of as an extended format for map files. Itβs possible to create a separate .cfg file with hand-edited WML, and then load the editor-generated file with ''[scenario]map_file=example.cfg''. Support for this requires some bug-fixes that were added in this release.<br />
<br />
=== Add-on manager downloading the same add-on twice when updating ===<br />
Previously, when Add-on A depended on Add-on B and both add-ons needed to be updated, Add-on B would be downloaded by the in-game add-on manager twice. This has now been fixed, so that Add-on B will only be downloaded once.<br />
<br />
=== Creating a game when a map contains an invalid terrain ===<br />
When trying to create a game when one of the maps or scenarios used an invalid or unknown terrain, Wesnoth would crash. This has been fixed and Wesnoth now will correctly show an error when selecting the map with the bad terrain instead of crashing.<br />
<br />
=== Handling of high resolution monitors ===<br />
For screens that have a higher resolution, such as 4K monitors, text would previously be displayed far smaller than it should have been. This has been partially fixed, and most text should now be displayed at a more normal size.<br />
<br />
== General/Misc ==<br />
=== Python2 removal complete ===<br />
All tools that were written in Python2 have now been ported to Python3, or removed if they seemed obsolete.<br />
<br />
=== Build report ===<br />
The build report (which is very useful to us and should be included in all reports of bugs and other issues!) now additionally contains information on the monitor, sound configuration, and all installed add-ons.<br />
<br />
=== Timestamps on replay file names ===<br />
The date and time is now added to the file name of replays. This will avoid needing to manually enter a different file name after playing the same scenario multiple times.<br />
<br />
=== Eclipse UMC plugin deprecated ===<br />
The Eclipse plugin for UMC (User Made Content) is now formally deprecated, though it has effectively been unsupported for a few years now. Anyone who is still using this plugin should instead use other supported editors such as Notepad++ or Visual Studio Code.<br />
<br />
== Newly Introduced Issues ==<br />
<br />
[[Category:Release_Notes]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=Release_Notes_1.15.4&diff=65947Release Notes 1.15.42020-08-22T11:38:39Z<p>Doofus-01: /* Under the Burning Suns */</p>
<hr />
<div>== New Content ==<br />
=== Addon titles and descriptions made translatable ===<br />
It's now possible to add translated titles and descriptions to your addons, so they will show up in the target language when browsing the in-game addon manager. The original English title is also displayed below and can be searched for in addition to translations. If you want to add a translated title and description to your addon, see the [https://wiki.wesnoth.org/PblWml#.5Btranslation.5D wiki page].<br />
<br />
=== Units ===<br />
==== Dunefolk ====<br />
Most of the Dunefolk faction's units have new/updated animations.<br />
<br />
=== Knalgan Alliance ===<br />
The Poacher and Trapper sprites and animations have been improved.<br />
<br />
=== Multiplayer ===<br />
==== World Conquest ====<br />
The add-on World Conquest II (now called World Conquest) has been added to mainline Wesnoth. World Conquest is a coop multiplayer campaign of 5 scenarios for 1-3 players. It features highly randomized maps for replayability as well as custom item and training systems.<br />
<br />
==== Lobby ====<br />
A new '''Information''' button has been added to the multiplayer lobby. This will show server related information as well as list any ongoing tournaments being held.<br />
<br />
== Changes To Existing Content ==<br />
<br />
=== Campaign changes ===<br />
<br />
==== Under the Burning Suns ====<br />
Under the Burning Suns has been fully rebalanced, including all scenarios and all units in the Quenoth faction. Generally, the campaign is now more challenging. There was also some incremental progress on the Quenoth unit sprites.<br />
<br />
==== Delfador's Memoirs ====<br />
Multiple issues have been fixed with the twelfth scenario of Delfador's Memoirs, including to dialogue and the AI. This should make the dialog flow better and the AI behave more appropriately.<br />
<br />
=== Balance changes ===<br />
==== Drakes ====<br />
Drake Burner line and Armageddon Drake cold resistance changed from -50% to -40% - this small change is supposed to make Burner more prevalent in matchup against Undead as well as counterweight newly buffed Ghost.<br />
<br />
==== Dunefolk ====<br />
Dune Spearmaster shield damage changed from 14 to 13 - this high impact damage on unit called Spearmaster was taking away from his lore identity and was making him too good against Undead and other impact vulnerable units. <br />
<br />
==== Knalgan Alliance ====<br />
Dwarvish Dragonguard hp changed from 59 to 63 - this is update to previous changes of dwarf level ups<br />
<br />
Dwarvish Steelclad hp changed from 55 to 57 - Steelclad was earlier nerfed in order to help balance scenarios against ai but it turned out to be affecting competitive 1 vs 1 too much so we are reverting this change partially.<br />
<br />
Poacher hp changed from 32 to 33 - main reason for this change are matchups against Loyalists and Drakes, this change is supposed to provide slight boost in not only strength but also amount of level ups that this unit receives thus allowing Knalgan player to get initiative thru them more often.<br />
<br />
==== Loyalists ====<br />
Heavy Infantryman cold resistance changed from -10% to 0 - this unit was not excelling in matchup against Undead where it should be doing so. This change is supposed to help with this problem.<br />
<br />
==== Northerners ====<br />
Troll Rocklobber hp changed from 49 to 51 - Rocklobber was level up that was simply not up to pair with usual Troll.<br />
<br />
==== Rebels ====<br />
Merman Hunter hp changed from 30 to 33 - this unit was weakest unit that was dedicated to water control. This was hurting Rebels too much on maps with lots of water. We hope that this change will provide them enough strength in this area.<br />
<br />
Elvish Shaman ranged damage changed from 3 to 4 - Shaman was not used as much as we would like to see it in play, this change is supposed to help her receive just a bit more of spotlight in competitive matches.<br />
<br />
Wose cold resistance changed from 10% to 0 - Wose was highly problematic unit in matchup against Undead, it allowed Rebels to play completely defensively until they had enough Woses to crush their opponent. This change should allow Adepts to kill Woses faster and thus make it much harder for Rebels to just defend. <br />
<br />
==== Undead ====<br />
Banebow hp changed form 50 to 55 - this unit had very low amount of hp for level 3 unit. <br />
<br />
Bone Shooter hp changed from 40 to 42 - this units had very low amount of hp for level 2 unit and its performance as a leader was also subpar.<br />
<br />
Ghost cost changed from 20 to 19 - matchups where Ghost can perform well are also ones where Undead are not in greatest shape, at the same time Ghost is easily countered outside of these matchups. This change is supposed to help both Ghost and Undead as a whole perform better in competitive matches.<br />
<br />
==== Monsters ====<br />
Various changes to Wyvern, Wyvern Rider, Roc, Falcon and Elder Falcon - changes to these units are supposed to make them more lore friendly.<br />
<br />
== Fixes ==<br />
=== Graphics engine memory leak fix ===<br />
An issue dating back to version 1.13.13 was found in the gameβs graphics engine that would result in large memory leaks over time, particularly evident after performing a few save-reloading or game initialization (Campaign mode, Multiplayer, Map Editor) cycles. On Windows and other systems running 32-bit builds of the game, this could eventually result in a game session crashing due to reaching platform-mandated memory limits. Furthermore, either 32-bit or 64-bit systems with small amounts of available RAM could perceive substantial performance degradation during long game sessions, or even crashes in other running software.<br />
<br />
=== Scenario configuration files created by the scenario editor ===<br />
The scenario editor creates .cfg files; but if you edit that .cfg by hand and then use the scenario editor again, the editor will completely rewrite it, likely removing any hand-edited WML. A comment warning about this is now added at the top of these .cfg files.<br />
<br />
The editor-generated .cfg files can be thought of as an extended format for map files. Itβs possible to create a separate .cfg file with hand-edited WML, and then load the editor-generated file with ''[scenario]map_file=example.cfg''. Support for this requires some bug-fixes that were added in this release.<br />
<br />
=== Add-on manager downloading the same add-on twice when updating ===<br />
Previously, when Add-on A depended on Add-on B and both add-ons needed to be updated, Add-on B would be downloaded by the in-game add-on manager twice. This has now been fixed, so that Add-on B will only be downloaded once.<br />
<br />
=== Creating a game when a map contains an invalid terrain ===<br />
When trying to create a game when one of the maps or scenarios used an invalid or unknown terrain, Wesnoth would crash. This has been fixed and Wesnoth now will correctly show an error when selecting the map with the bad terrain instead of crashing.<br />
<br />
=== Handling of high resolution monitors ===<br />
For screens that have a higher resolution, such as 4K monitors, text would previously be displayed far smaller than it should have been. This has been partially fixed, and most text should now be displayed at a more normal size.<br />
<br />
== General/Misc ==<br />
=== Python2 removal complete ===<br />
All tools that were written in Python2 have now been ported to Python3, or removed if they seemed obsolete.<br />
<br />
=== Build report ===<br />
The build report (which is very useful to us and should be included in all reports of bugs and other issues!) now additionally contains information on the monitor, sound configuration, and all installed add-ons.<br />
<br />
=== Timestamps on replay file names ===<br />
The date and time is now added to the file name of replays. This will avoid needing to manually enter a different file name after playing the same scenario multiple times.<br />
<br />
=== Eclipse UMC plugin deprecated ===<br />
The Eclipse plugin for UMC (User Made Content) is now formally deprecated, though it has effectively been unsupported for a few years now. Anyone who is still using this plugin should instead use other supported editors such as Notepad++ or Visual Studio Code.<br />
<br />
== Newly Introduced Issues ==<br />
<br />
[[Category:Release_Notes]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=1.15_Roadmap&diff=658691.15 Roadmap2020-08-08T16:32:02Z<p>Doofus-01: /* 1.15.6 (10/17/2020) */</p>
<hr />
<div>This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.<br />
<br />
== Instructions ==<br />
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.<br />
<br />
Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.<br />
<br />
== 1.15.4 (08/22/2020) ==<br />
<br />
* Mainlining World conquest II (gfgtdf)<br />
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)<br />
* Fix #5004 (Pentarctagon)<br />
* Fix #4898 (Pentarctagon)<br />
* Add the logger level statements needed to fix #4898 (Pentarctagon)<br />
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)<br />
* Add Royal Warrior portrait (LordBob)<br />
* Drop the python2 wmlparser and wmlparser2. This would finish issue #1508, and it now seems to be at the "remove it and see if anyone wants it back" stage. (octalot).<br />
* Either drop or document the l10n-track file, issue #4717 (octalot)<br />
<br />
== 1.15.5 (09/19/2020) ==<br />
<br />
* Campaignd storage rework and incremental updates (#5038), then incremental uploads (kabachuha)<br />
* Campaignd support for different min wesnoth versions (gfgtdf)<br />
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)<br />
* Improve the documentation for the editor, following from the discussion in PR #4999 (octalot)<br />
* Fix issue #4876, by making UtBS's Quenoth elves not share their help pages with forest elves (octalot)<br />
<br />
== 1.15.6 (10/17/2020) ==<br />
<br />
* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)<br />
* Re-add the dunefolk faction to WCII (gfgtdf)<br />
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)<br />
* Implement a game history viewer by utilizing queryd (Pentarctagon)<br />
* Add Wose shaman portrait (Lordbob)<br />
* Look how practical the new mainline macros are (Sevu)<br />
* PR with changes to mainline macros (Sevu)<br />
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)<br />
* Add a help page for gold/silver crowns and loyal marker, issue #4455. (octalot)<br />
* PR for new animals/monsters, art to be finalized later (doofus-01)<br />
<br />
== 1.15.7 (11/21/2020) ==<br />
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)<br />
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)<br />
* Rebalance prices of monster units & Chocobone (Sevu)<br />
* Mainline Visual Map Pack (Sevu)<br />
<br />
== 1.15.8 (12/19/2020) ==<br />
* Add SQL support to campaignd using mariadbpp (Pentarctagon)<br />
* Store add-on upload history in the database (Pentarctagon)<br />
* Revamp Duelist line portraits (Lordbob)<br />
* Sprites and basic animations for any approved new animals (doofus-01)<br />
* Mainline Undead Empire (an ANL scenario) (Sevu)<br />
<br />
== 1.15.9 (01/16/2021) ==<br />
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate email or passphrase value (Pentarctagon)<br />
* Reorganize scenario/era/modification data in the <nowiki>game_info</nowiki> and <nowiki>game_modification_info</nowiki> database tables into a separate <nowiki>game_content_info</nowiki> table (Pentarctagon)<br />
* PR for Ghoul line portraits (doofus-01)<br />
* Draw text on images in [[IntroWML]], useable for place-name labels on the journey-tracker maps. (octalot)<br />
* Handling of vision and movement, issues #3356, #4179. (octalot)<br />
<br />
== 1.15.10 (02/20/2021) ==<br />
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)<br />
* Add missing story art for tRoW (Lordbob)<br />
* Either merge or reject a refactor of terrain handling, as described in issue #4279, Ford^Overlay: Costs for worst(best(a, b), c, d) terrain are worst(a, b, c, d). (octalot)<br />
* Remove the wesnoth-ai textdomain, as suggested in #4669 (octalot)<br />
<br />
== 1.15.11 (03/20/2021) ==<br />
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)<br />
* Portraits for any new animals added in earlier milestones (doofus-01)<br />
<br />
== 1.15.12 (04/17/2021) ==<br />
* Add story art for UtBS (Lordbob)<br />
<br />
== 1.15.13 (05/15/2021) ==<br />
* <br />
<br />
== 1.15.14 (06/19/2021) ==<br />
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)<br />
* Possibly work on an UtBS dialogue touchup. (nemaara)<br />
* By this time, hopefully move around the campaigns so that they're more correctly ordered in difficulty (either rebalancing or simply changing their difficulty ratings). Applies especially to EI. (nemaara)<br />
<br />
== 1.15.15 (07/17/2021) ==<br />
* <br />
<br />
<br />
[[Category:Roadmaps]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=1.15_Roadmap&diff=658681.15 Roadmap2020-08-08T16:31:23Z<p>Doofus-01: /* 1.15.4 (08/22/2020) */</p>
<hr />
<div>This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.<br />
<br />
== Instructions ==<br />
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.<br />
<br />
Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.<br />
<br />
== 1.15.4 (08/22/2020) ==<br />
<br />
* Mainlining World conquest II (gfgtdf)<br />
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)<br />
* Fix #5004 (Pentarctagon)<br />
* Fix #4898 (Pentarctagon)<br />
* Add the logger level statements needed to fix #4898 (Pentarctagon)<br />
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)<br />
* Add Royal Warrior portrait (LordBob)<br />
* Drop the python2 wmlparser and wmlparser2. This would finish issue #1508, and it now seems to be at the "remove it and see if anyone wants it back" stage. (octalot).<br />
* Either drop or document the l10n-track file, issue #4717 (octalot)<br />
<br />
== 1.15.5 (09/19/2020) ==<br />
<br />
* Campaignd storage rework and incremental updates (#5038), then incremental uploads (kabachuha)<br />
* Campaignd support for different min wesnoth versions (gfgtdf)<br />
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)<br />
* Improve the documentation for the editor, following from the discussion in PR #4999 (octalot)<br />
* Fix issue #4876, by making UtBS's Quenoth elves not share their help pages with forest elves (octalot)<br />
<br />
== 1.15.6 (10/17/2020) ==<br />
<br />
* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)<br />
* Re-add the dunefolk faction to WCII (gfgtdf)<br />
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)<br />
* Implement a game history viewer by utilizing queryd (Pentarctagon)<br />
* Add Wose shaman portrait (Lordbob)<br />
* Look how practical the new mainline macros are (Sevu)<br />
* PR with changes to mainline macros (Sevu)<br />
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)<br />
* Add a help page for gold/silver crowns and loyal marker, issue #4455. (octalot)<br />
<br />
== 1.15.7 (11/21/2020) ==<br />
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)<br />
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)<br />
* Rebalance prices of monster units & Chocobone (Sevu)<br />
* Mainline Visual Map Pack (Sevu)<br />
<br />
== 1.15.8 (12/19/2020) ==<br />
* Add SQL support to campaignd using mariadbpp (Pentarctagon)<br />
* Store add-on upload history in the database (Pentarctagon)<br />
* Revamp Duelist line portraits (Lordbob)<br />
* Sprites and basic animations for any approved new animals (doofus-01)<br />
* Mainline Undead Empire (an ANL scenario) (Sevu)<br />
<br />
== 1.15.9 (01/16/2021) ==<br />
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate email or passphrase value (Pentarctagon)<br />
* Reorganize scenario/era/modification data in the <nowiki>game_info</nowiki> and <nowiki>game_modification_info</nowiki> database tables into a separate <nowiki>game_content_info</nowiki> table (Pentarctagon)<br />
* PR for Ghoul line portraits (doofus-01)<br />
* Draw text on images in [[IntroWML]], useable for place-name labels on the journey-tracker maps. (octalot)<br />
* Handling of vision and movement, issues #3356, #4179. (octalot)<br />
<br />
== 1.15.10 (02/20/2021) ==<br />
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)<br />
* Add missing story art for tRoW (Lordbob)<br />
* Either merge or reject a refactor of terrain handling, as described in issue #4279, Ford^Overlay: Costs for worst(best(a, b), c, d) terrain are worst(a, b, c, d). (octalot)<br />
* Remove the wesnoth-ai textdomain, as suggested in #4669 (octalot)<br />
<br />
== 1.15.11 (03/20/2021) ==<br />
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)<br />
* Portraits for any new animals added in earlier milestones (doofus-01)<br />
<br />
== 1.15.12 (04/17/2021) ==<br />
* Add story art for UtBS (Lordbob)<br />
<br />
== 1.15.13 (05/15/2021) ==<br />
* <br />
<br />
== 1.15.14 (06/19/2021) ==<br />
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)<br />
* Possibly work on an UtBS dialogue touchup. (nemaara)<br />
* By this time, hopefully move around the campaigns so that they're more correctly ordered in difficulty (either rebalancing or simply changing their difficulty ratings). Applies especially to EI. (nemaara)<br />
<br />
== 1.15.15 (07/17/2021) ==<br />
* <br />
<br />
<br />
[[Category:Roadmaps]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=1.15_Roadmap&diff=658301.15 Roadmap2020-07-26T15:27:32Z<p>Doofus-01: /* 1.15.14 (06/19/2021) */</p>
<hr />
<div>This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.<br />
<br />
== Instructions ==<br />
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.<br />
<br />
Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.<br />
<br />
== 1.15.4 (08/22/2020) ==<br />
<br />
* Mainlining World conquest II (gfgtdf)<br />
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)<br />
* Add the logger level statements needed to fix #4898 (Pentarctagon)<br />
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)<br />
* Add Royal Warrior portrait (LordBob)<br />
* PR for new animals/monsters, art to be finalized later (doofus-01)<br />
<br />
== 1.15.5 (09/19/2020) ==<br />
<br />
* Campaignd support for different min wesnoth versions (gfgtdf)<br />
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)<br />
<br />
== 1.15.6 (10/17/2020) ==<br />
<br />
* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)<br />
* Re-add the dunefolk faction to WCII (gfgtdf)<br />
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)<br />
* Implement a game history viewer by utilizing queryd (Pentarctagon)<br />
* Add Wose shaman portrait (Lordbob)<br />
* Look how practical the new mainline macros are (Sevu)<br />
* PR with changes to mainline macros (Sevu)<br />
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)<br />
<br />
== 1.15.7 (11/21/2020) ==<br />
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)<br />
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)<br />
* Rebalance prices of monster units & Chocobone (Sevu)<br />
* Mainline Visual Map Pack (Sevu)<br />
<br />
== 1.15.8 (12/19/2020) ==<br />
* Add SQL support to campaignd using mariadbpp (Pentarctagon)<br />
* Store add-on upload history in the database (Pentarctagon)<br />
* Revamp Duelist line portraits (Lordbob)<br />
* Sprites and basic animations for any approved new animals (doofus-01)<br />
<br />
== 1.15.9 (01/16/2021) ==<br />
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)<br />
* PR for Ghoul line portraits (doofus-01)<br />
<br />
== 1.15.10 (02/20/2021) ==<br />
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)<br />
* Add missing story art for tRoW (Lordbob)<br />
<br />
== 1.15.11 (03/20/2021) ==<br />
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)<br />
* Portraits for any new animals added in earlier milestones (doofus-01)<br />
<br />
== 1.15.12 (04/17/2021) ==<br />
* Add story art for UtBS (Lordbob)<br />
<br />
== 1.15.13 (05/15/2021) ==<br />
* <br />
<br />
== 1.15.14 (06/19/2021) ==<br />
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)<br />
<br />
== 1.15.15 (07/17/2021) ==<br />
* <br />
<br />
<br />
[[Category:Roadmaps]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=1.15_Roadmap&diff=658291.15 Roadmap2020-07-26T15:26:46Z<p>Doofus-01: /* 1.15.6 (10/17/2020) */</p>
<hr />
<div>This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.<br />
<br />
== Instructions ==<br />
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.<br />
<br />
Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.<br />
<br />
== 1.15.4 (08/22/2020) ==<br />
<br />
* Mainlining World conquest II (gfgtdf)<br />
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)<br />
* Add the logger level statements needed to fix #4898 (Pentarctagon)<br />
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)<br />
* Add Royal Warrior portrait (LordBob)<br />
* PR for new animals/monsters, art to be finalized later (doofus-01)<br />
<br />
== 1.15.5 (09/19/2020) ==<br />
<br />
* Campaignd support for different min wesnoth versions (gfgtdf)<br />
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)<br />
<br />
== 1.15.6 (10/17/2020) ==<br />
<br />
* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)<br />
* Re-add the dunefolk faction to WCII (gfgtdf)<br />
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)<br />
* Implement a game history viewer by utilizing queryd (Pentarctagon)<br />
* Add Wose shaman portrait (Lordbob)<br />
* Look how practical the new mainline macros are (Sevu)<br />
* PR with changes to mainline macros (Sevu)<br />
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)<br />
<br />
== 1.15.7 (11/21/2020) ==<br />
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)<br />
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)<br />
* Rebalance prices of monster units & Chocobone (Sevu)<br />
* Mainline Visual Map Pack (Sevu)<br />
<br />
== 1.15.8 (12/19/2020) ==<br />
* Add SQL support to campaignd using mariadbpp (Pentarctagon)<br />
* Store add-on upload history in the database (Pentarctagon)<br />
* Revamp Duelist line portraits (Lordbob)<br />
* Sprites and basic animations for any approved new animals (doofus-01)<br />
<br />
== 1.15.9 (01/16/2021) ==<br />
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)<br />
* PR for Ghoul line portraits (doofus-01)<br />
<br />
== 1.15.10 (02/20/2021) ==<br />
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)<br />
* Add missing story art for tRoW (Lordbob)<br />
<br />
== 1.15.11 (03/20/2021) ==<br />
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)<br />
* Portraits for any new animals added in earlier milestones (doofus-01)<br />
<br />
== 1.15.12 (04/17/2021) ==<br />
* Add story art for UtBS (Lordbob)<br />
<br />
== 1.15.13 (05/15/2021) ==<br />
* <br />
<br />
== 1.15.14 (06/19/2021) ==<br />
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)<br />
* Add scenery images appropriate for camps & interiors of major factions (doofus-01)<br />
<br />
== 1.15.15 (07/17/2021) ==<br />
* <br />
<br />
<br />
[[Category:Roadmaps]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=1.15_Roadmap&diff=658281.15 Roadmap2020-07-26T15:25:24Z<p>Doofus-01: /* 1.15.5 (09/19/2020) */</p>
<hr />
<div>This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.<br />
<br />
== Instructions ==<br />
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.<br />
<br />
Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.<br />
<br />
== 1.15.4 (08/22/2020) ==<br />
<br />
* Mainlining World conquest II (gfgtdf)<br />
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)<br />
* Add the logger level statements needed to fix #4898 (Pentarctagon)<br />
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)<br />
* Add Royal Warrior portrait (LordBob)<br />
* PR for new animals/monsters, art to be finalized later (doofus-01)<br />
<br />
== 1.15.5 (09/19/2020) ==<br />
<br />
* Campaignd support for different min wesnoth versions (gfgtdf)<br />
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)<br />
<br />
== 1.15.6 (10/17/2020) ==<br />
<br />
* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)<br />
* Re-add the dunefolk faction to WCII (gfgtdf)<br />
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)<br />
* Implement a game history viewer by utilizing queryd (Pentarctagon)<br />
* Add Wose shaman portrait (Lordbob)<br />
* Look how practical the new mainline macros are (Sevu)<br />
* PR with changes to mainline macros (Sevu)<br />
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)<br />
* PR for windows overlay to ^Xo*-type wall terrain (doofus-01)<br />
<br />
== 1.15.7 (11/21/2020) ==<br />
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)<br />
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)<br />
* Rebalance prices of monster units & Chocobone (Sevu)<br />
* Mainline Visual Map Pack (Sevu)<br />
<br />
== 1.15.8 (12/19/2020) ==<br />
* Add SQL support to campaignd using mariadbpp (Pentarctagon)<br />
* Store add-on upload history in the database (Pentarctagon)<br />
* Revamp Duelist line portraits (Lordbob)<br />
* Sprites and basic animations for any approved new animals (doofus-01)<br />
<br />
== 1.15.9 (01/16/2021) ==<br />
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)<br />
* PR for Ghoul line portraits (doofus-01)<br />
<br />
== 1.15.10 (02/20/2021) ==<br />
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)<br />
* Add missing story art for tRoW (Lordbob)<br />
<br />
== 1.15.11 (03/20/2021) ==<br />
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)<br />
* Portraits for any new animals added in earlier milestones (doofus-01)<br />
<br />
== 1.15.12 (04/17/2021) ==<br />
* Add story art for UtBS (Lordbob)<br />
<br />
== 1.15.13 (05/15/2021) ==<br />
* <br />
<br />
== 1.15.14 (06/19/2021) ==<br />
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)<br />
* Add scenery images appropriate for camps & interiors of major factions (doofus-01)<br />
<br />
== 1.15.15 (07/17/2021) ==<br />
* <br />
<br />
<br />
[[Category:Roadmaps]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=1.15_Roadmap&diff=658261.15 Roadmap2020-07-26T02:06:51Z<p>Doofus-01: /* 1.15.14 (06/19/2021) */</p>
<hr />
<div>This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.<br />
<br />
== Instructions ==<br />
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.<br />
<br />
Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.<br />
<br />
== 1.15.4 (08/22/2020) ==<br />
<br />
* Mainlining World conquest II (gfgtdf)<br />
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)<br />
* Add the logger level statements needed to fix #4898 (Pentarctagon)<br />
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)<br />
* Add Royal Warrior portrait (LordBob)<br />
* PR for new animals/monsters, art to be finalized later (doofus-01)<br />
<br />
== 1.15.5 (09/19/2020) ==<br />
<br />
* Campaignd support for different min wesnoth versions (gfgtdf)<br />
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)<br />
* PR for smaller-scale "villages" (like a bedroll or shelter) for occasions where a village makes no sense. (doofus-01)<br />
<br />
== 1.15.6 (10/17/2020) ==<br />
<br />
* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)<br />
* Re-add the dunefolk faction to WCII (gfgtdf)<br />
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)<br />
* Implement a game history viewer by utilizing queryd (Pentarctagon)<br />
* Add Wose shaman portrait (Lordbob)<br />
* Look how practical the new mainline macros are (Sevu)<br />
* PR with changes to mainline macros (Sevu)<br />
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)<br />
* PR for windows overlay to ^Xo*-type wall terrain (doofus-01)<br />
<br />
== 1.15.7 (11/21/2020) ==<br />
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)<br />
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)<br />
* Rebalance prices of monster units & Chocobone (Sevu)<br />
* Mainline Visual Map Pack (Sevu)<br />
<br />
== 1.15.8 (12/19/2020) ==<br />
* Add SQL support to campaignd using mariadbpp (Pentarctagon)<br />
* Store add-on upload history in the database (Pentarctagon)<br />
* Revamp Duelist line portraits (Lordbob)<br />
* Sprites and basic animations for any approved new animals (doofus-01)<br />
<br />
== 1.15.9 (01/16/2021) ==<br />
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)<br />
* PR for Ghoul line portraits (doofus-01)<br />
<br />
== 1.15.10 (02/20/2021) ==<br />
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)<br />
* Add missing story art for tRoW (Lordbob)<br />
<br />
== 1.15.11 (03/20/2021) ==<br />
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)<br />
* Portraits for any new animals added in earlier milestones (doofus-01)<br />
<br />
== 1.15.12 (04/17/2021) ==<br />
* Add story art for UtBS (Lordbob)<br />
<br />
== 1.15.13 (05/15/2021) ==<br />
* <br />
<br />
== 1.15.14 (06/19/2021) ==<br />
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob)<br />
* Add scenery images appropriate for camps & interiors of major factions (doofus-01)<br />
<br />
== 1.15.15 (07/17/2021) ==<br />
* <br />
<br />
<br />
[[Category:Roadmaps]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=1.15_Roadmap&diff=658251.15 Roadmap2020-07-26T02:01:09Z<p>Doofus-01: /* 1.15.11 (03/20/2021) */</p>
<hr />
<div>This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.<br />
<br />
== Instructions ==<br />
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.<br />
<br />
Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.<br />
<br />
== 1.15.4 (08/22/2020) ==<br />
<br />
* Mainlining World conquest II (gfgtdf)<br />
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)<br />
* Add the logger level statements needed to fix #4898 (Pentarctagon)<br />
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)<br />
* Add Royal Warrior portrait (LordBob)<br />
* PR for new animals/monsters, art to be finalized later (doofus-01)<br />
<br />
== 1.15.5 (09/19/2020) ==<br />
<br />
* Campaignd support for different min wesnoth versions (gfgtdf)<br />
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)<br />
* PR for smaller-scale "villages" (like a bedroll or shelter) for occasions where a village makes no sense. (doofus-01)<br />
<br />
== 1.15.6 (10/17/2020) ==<br />
<br />
* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)<br />
* Re-add the dunefolk faction to WCII (gfgtdf)<br />
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)<br />
* Implement a game history viewer by utilizing queryd (Pentarctagon)<br />
* Add Wose shaman portrait (Lordbob)<br />
* Look how practical the new mainline macros are (Sevu)<br />
* PR with changes to mainline macros (Sevu)<br />
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)<br />
* PR for windows overlay to ^Xo*-type wall terrain (doofus-01)<br />
<br />
== 1.15.7 (11/21/2020) ==<br />
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)<br />
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)<br />
* Rebalance prices of monster units & Chocobone (Sevu)<br />
* Mainline Visual Map Pack (Sevu)<br />
<br />
== 1.15.8 (12/19/2020) ==<br />
* Add SQL support to campaignd using mariadbpp (Pentarctagon)<br />
* Store add-on upload history in the database (Pentarctagon)<br />
* Revamp Duelist line portraits (Lordbob)<br />
* Sprites and basic animations for any approved new animals (doofus-01)<br />
<br />
== 1.15.9 (01/16/2021) ==<br />
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)<br />
* PR for Ghoul line portraits (doofus-01)<br />
<br />
== 1.15.10 (02/20/2021) ==<br />
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)<br />
* Add missing story art for tRoW (Lordbob)<br />
<br />
== 1.15.11 (03/20/2021) ==<br />
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)<br />
* Portraits for any new animals added in earlier milestones (doofus-01)<br />
<br />
== 1.15.12 (04/17/2021) ==<br />
* Add story art for UtBS (Lordbob)<br />
<br />
== 1.15.13 (05/15/2021) ==<br />
* <br />
<br />
== 1.15.14 (06/19/2021) ==<br />
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob) <br />
<br />
== 1.15.15 (07/17/2021) ==<br />
* <br />
<br />
<br />
[[Category:Roadmaps]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=1.15_Roadmap&diff=658241.15 Roadmap2020-07-26T01:58:44Z<p>Doofus-01: /* 1.15.8 (12/19/2020) */</p>
<hr />
<div>This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.<br />
<br />
== Instructions ==<br />
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.<br />
<br />
Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.<br />
<br />
== 1.15.4 (08/22/2020) ==<br />
<br />
* Mainlining World conquest II (gfgtdf)<br />
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)<br />
* Add the logger level statements needed to fix #4898 (Pentarctagon)<br />
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)<br />
* Add Royal Warrior portrait (LordBob)<br />
* PR for new animals/monsters, art to be finalized later (doofus-01)<br />
<br />
== 1.15.5 (09/19/2020) ==<br />
<br />
* Campaignd support for different min wesnoth versions (gfgtdf)<br />
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)<br />
* PR for smaller-scale "villages" (like a bedroll or shelter) for occasions where a village makes no sense. (doofus-01)<br />
<br />
== 1.15.6 (10/17/2020) ==<br />
<br />
* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)<br />
* Re-add the dunefolk faction to WCII (gfgtdf)<br />
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)<br />
* Implement a game history viewer by utilizing queryd (Pentarctagon)<br />
* Add Wose shaman portrait (Lordbob)<br />
* Look how practical the new mainline macros are (Sevu)<br />
* PR with changes to mainline macros (Sevu)<br />
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)<br />
* PR for windows overlay to ^Xo*-type wall terrain (doofus-01)<br />
<br />
== 1.15.7 (11/21/2020) ==<br />
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)<br />
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)<br />
* Rebalance prices of monster units & Chocobone (Sevu)<br />
* Mainline Visual Map Pack (Sevu)<br />
<br />
== 1.15.8 (12/19/2020) ==<br />
* Add SQL support to campaignd using mariadbpp (Pentarctagon)<br />
* Store add-on upload history in the database (Pentarctagon)<br />
* Revamp Duelist line portraits (Lordbob)<br />
* Sprites and basic animations for any approved new animals (doofus-01)<br />
<br />
== 1.15.9 (01/16/2021) ==<br />
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)<br />
* PR for Ghoul line portraits (doofus-01)<br />
<br />
== 1.15.10 (02/20/2021) ==<br />
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)<br />
* Add missing story art for tRoW (Lordbob)<br />
<br />
== 1.15.11 (03/20/2021) ==<br />
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)<br />
<br />
== 1.15.12 (04/17/2021) ==<br />
* Add story art for UtBS (Lordbob)<br />
<br />
== 1.15.13 (05/15/2021) ==<br />
* <br />
<br />
== 1.15.14 (06/19/2021) ==<br />
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob) <br />
<br />
== 1.15.15 (07/17/2021) ==<br />
* <br />
<br />
<br />
[[Category:Roadmaps]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=1.15_Roadmap&diff=658231.15 Roadmap2020-07-26T01:56:47Z<p>Doofus-01: /* 1.15.4 (08/22/2020) */</p>
<hr />
<div>This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.<br />
<br />
== Instructions ==<br />
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.<br />
<br />
Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.<br />
<br />
== 1.15.4 (08/22/2020) ==<br />
<br />
* Mainlining World conquest II (gfgtdf)<br />
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)<br />
* Add the logger level statements needed to fix #4898 (Pentarctagon)<br />
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)<br />
* Add Royal Warrior portrait (LordBob)<br />
* PR for new animals/monsters, art to be finalized later (doofus-01)<br />
<br />
== 1.15.5 (09/19/2020) ==<br />
<br />
* Campaignd support for different min wesnoth versions (gfgtdf)<br />
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)<br />
* PR for smaller-scale "villages" (like a bedroll or shelter) for occasions where a village makes no sense. (doofus-01)<br />
<br />
== 1.15.6 (10/17/2020) ==<br />
<br />
* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)<br />
* Re-add the dunefolk faction to WCII (gfgtdf)<br />
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)<br />
* Implement a game history viewer by utilizing queryd (Pentarctagon)<br />
* Add Wose shaman portrait (Lordbob)<br />
* Look how practical the new mainline macros are (Sevu)<br />
* PR with changes to mainline macros (Sevu)<br />
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)<br />
* PR for windows overlay to ^Xo*-type wall terrain (doofus-01)<br />
<br />
== 1.15.7 (11/21/2020) ==<br />
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)<br />
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)<br />
* Rebalance prices of monster units & Chocobone (Sevu)<br />
* Mainline Visual Map Pack (Sevu)<br />
<br />
== 1.15.8 (12/19/2020) ==<br />
* Add SQL support to campaignd using mariadbpp (Pentarctagon)<br />
* Store add-on upload history in the database (Pentarctagon)<br />
* Revamp Duelist line portraits (Lordbob)<br />
<br />
== 1.15.9 (01/16/2021) ==<br />
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)<br />
* PR for Ghoul line portraits (doofus-01)<br />
<br />
== 1.15.10 (02/20/2021) ==<br />
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)<br />
* Add missing story art for tRoW (Lordbob)<br />
<br />
== 1.15.11 (03/20/2021) ==<br />
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)<br />
<br />
== 1.15.12 (04/17/2021) ==<br />
* Add story art for UtBS (Lordbob)<br />
<br />
== 1.15.13 (05/15/2021) ==<br />
* <br />
<br />
== 1.15.14 (06/19/2021) ==<br />
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob) <br />
<br />
== 1.15.15 (07/17/2021) ==<br />
* <br />
<br />
<br />
[[Category:Roadmaps]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=1.15_Roadmap&diff=658221.15 Roadmap2020-07-26T01:53:57Z<p>Doofus-01: /* 1.15.9 (01/16/2021) */</p>
<hr />
<div>This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.<br />
<br />
== Instructions ==<br />
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.<br />
<br />
Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.<br />
<br />
== 1.15.4 (08/22/2020) ==<br />
<br />
* Mainlining World conquest II (gfgtdf)<br />
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)<br />
* Add the logger level statements needed to fix #4898 (Pentarctagon)<br />
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)<br />
* Add Royal Warrior portrait (LordBob)<br />
<br />
== 1.15.5 (09/19/2020) ==<br />
<br />
* Campaignd support for different min wesnoth versions (gfgtdf)<br />
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)<br />
* PR for smaller-scale "villages" (like a bedroll or shelter) for occasions where a village makes no sense. (doofus-01)<br />
<br />
== 1.15.6 (10/17/2020) ==<br />
<br />
* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)<br />
* Re-add the dunefolk faction to WCII (gfgtdf)<br />
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)<br />
* Implement a game history viewer by utilizing queryd (Pentarctagon)<br />
* Add Wose shaman portrait (Lordbob)<br />
* Look how practical the new mainline macros are (Sevu)<br />
* PR with changes to mainline macros (Sevu)<br />
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)<br />
* PR for windows overlay to ^Xo*-type wall terrain (doofus-01)<br />
<br />
== 1.15.7 (11/21/2020) ==<br />
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)<br />
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)<br />
* Rebalance prices of monster units & Chocobone (Sevu)<br />
* Mainline Visual Map Pack (Sevu)<br />
<br />
== 1.15.8 (12/19/2020) ==<br />
* Add SQL support to campaignd using mariadbpp (Pentarctagon)<br />
* Store add-on upload history in the database (Pentarctagon)<br />
* Revamp Duelist line portraits (Lordbob)<br />
<br />
== 1.15.9 (01/16/2021) ==<br />
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)<br />
* PR for Ghoul line portraits (doofus-01)<br />
<br />
== 1.15.10 (02/20/2021) ==<br />
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)<br />
* Add missing story art for tRoW (Lordbob)<br />
<br />
== 1.15.11 (03/20/2021) ==<br />
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)<br />
<br />
== 1.15.12 (04/17/2021) ==<br />
* Add story art for UtBS (Lordbob)<br />
<br />
== 1.15.13 (05/15/2021) ==<br />
* <br />
<br />
== 1.15.14 (06/19/2021) ==<br />
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob) <br />
<br />
== 1.15.15 (07/17/2021) ==<br />
* <br />
<br />
<br />
[[Category:Roadmaps]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=1.15_Roadmap&diff=658211.15 Roadmap2020-07-26T01:52:06Z<p>Doofus-01: /* 1.15.5 (09/19/2020) */</p>
<hr />
<div>This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.<br />
<br />
== Instructions ==<br />
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.<br />
<br />
Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.<br />
<br />
== 1.15.4 (08/22/2020) ==<br />
<br />
* Mainlining World conquest II (gfgtdf)<br />
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)<br />
* Add the logger level statements needed to fix #4898 (Pentarctagon)<br />
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)<br />
* Add Royal Warrior portrait (LordBob)<br />
<br />
== 1.15.5 (09/19/2020) ==<br />
<br />
* Campaignd support for different min wesnoth versions (gfgtdf)<br />
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)<br />
* PR for smaller-scale "villages" (like a bedroll or shelter) for occasions where a village makes no sense. (doofus-01)<br />
<br />
== 1.15.6 (10/17/2020) ==<br />
<br />
* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)<br />
* Re-add the dunefolk faction to WCII (gfgtdf)<br />
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)<br />
* Implement a game history viewer by utilizing queryd (Pentarctagon)<br />
* Add Wose shaman portrait (Lordbob)<br />
* Look how practical the new mainline macros are (Sevu)<br />
* PR with changes to mainline macros (Sevu)<br />
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)<br />
* PR for windows overlay to ^Xo*-type wall terrain (doofus-01)<br />
<br />
== 1.15.7 (11/21/2020) ==<br />
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)<br />
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)<br />
* Rebalance prices of monster units & Chocobone (Sevu)<br />
* Mainline Visual Map Pack (Sevu)<br />
<br />
== 1.15.8 (12/19/2020) ==<br />
* Add SQL support to campaignd using mariadbpp (Pentarctagon)<br />
* Store add-on upload history in the database (Pentarctagon)<br />
* Revamp Duelist line portraits (Lordbob)<br />
<br />
== 1.15.9 (01/16/2021) ==<br />
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)<br />
<br />
== 1.15.10 (02/20/2021) ==<br />
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)<br />
* Add missing story art for tRoW (Lordbob)<br />
<br />
== 1.15.11 (03/20/2021) ==<br />
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)<br />
<br />
== 1.15.12 (04/17/2021) ==<br />
* Add story art for UtBS (Lordbob)<br />
<br />
== 1.15.13 (05/15/2021) ==<br />
* <br />
<br />
== 1.15.14 (06/19/2021) ==<br />
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob) <br />
<br />
== 1.15.15 (07/17/2021) ==<br />
* <br />
<br />
<br />
[[Category:Roadmaps]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=1.15_Roadmap&diff=658201.15 Roadmap2020-07-26T01:46:54Z<p>Doofus-01: /* 1.15.6 (10/17/2020) */</p>
<hr />
<div>This page is for consolidating and planning when new features and fixes are intended to land in the 1.15 development branch. The release schedule for Development releases can be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52785 here]. A thread for discussing this roadmap can also be found [https://forums.wesnoth.org/viewtopic.php?f=2&t=52786 here]. As a reminder, there is also the previous [https://github.com/wesnoth/wesnoth/issues/4750 1.16 Checklist] issue on github, for those who added items to that.<br />
<br />
== Instructions ==<br />
Place the feature or fix you intend to implement within the section of the point release that you intend to have it implemented by, as well as your forum username in parenthesis after the feature description. The point release something is planned to be released with is not set in stone, and can be updated as needed depending on the circumstances.<br />
<br />
Additionally, the current set of 1.15 point releases is not final, and can be increased or decreased based on what features and fixes are planned. The only hard deadline, which ''hopefully'' is not an issue, is to have 1.16 released by February 2022. This will allow 1.16 to be in the Ubuntu 22.04 LTS release's repositories, and while I realize we don't plan Wesnoth's releases around any distro's schedule, there are also currently no other criteria to use as a final deadline and February 2022 is easily more than enough time to plan out and implement 1.16, especially given how long 1.14/1.15 have already been going.<br />
<br />
== 1.15.4 (08/22/2020) ==<br />
<br />
* Mainlining World conquest II (gfgtdf)<br />
* Have #4884 merged, as a lot of the rest of what I want to do depends on this (Pentarctagon)<br />
* Add the logger level statements needed to fix #4898 (Pentarctagon)<br />
* Add missing Naga portraits - 1 new portrait, 3 level up variants (Lordbob)<br />
* Add Royal Warrior portrait (LordBob)<br />
<br />
== 1.15.5 (09/19/2020) ==<br />
<br />
* Campaignd support for different min wesnoth versions (gfgtdf)<br />
* Add Mechanical unit portraits - 2 new portraits, 2 variants (Lordbob)<br />
<br />
== 1.15.6 (10/17/2020) ==<br />
<br />
* Api to query abilities and traits by id, whcih are then uses by the {TRAIT...}, {ABILITY...} macros (gfgtdf)<br />
* Re-add the dunefolk faction to WCII (gfgtdf)<br />
* Create the queryd program. Its purpose would be to execute SQL separate from wesnothd, so that queries that could potentially take several seconds or longer to complete won't block wesnothd from continuing to run until the query completes (Pentarctagon)<br />
* Implement a game history viewer by utilizing queryd (Pentarctagon)<br />
* Add Wose shaman portrait (Lordbob)<br />
* Look how practical the new mainline macros are (Sevu)<br />
* PR with changes to mainline macros (Sevu)<br />
* Branch for Lua rewrite of ANL, having an ANL Lua module which can be reused by UMC. (Sevu)<br />
* PR for windows overlay to ^Xo*-type wall terrain (doofus-01)<br />
<br />
== 1.15.7 (11/21/2020) ==<br />
* Implement an MP reporting dialog as a replacement for the <nowiki>/query report <message></nowiki> command that's available now. This could include functionality such as searching for the username(s) to report, searching for a particular game to report (currently running or already ended, if already ended then automatically include a link to the game's replay), and inserting a PM to the MP Moderators group from the reporter (though I'm not sure if this part is actually possible) (Pentarctagon)<br />
* Add missing Monsters & Creatures portraits - 5-8 portraits (Lordbob)<br />
* Rebalance prices of monster units & Chocobone (Sevu)<br />
* Mainline Visual Map Pack (Sevu)<br />
<br />
== 1.15.8 (12/19/2020) ==<br />
* Add SQL support to campaignd using mariadbpp (Pentarctagon)<br />
* Store add-on upload history in the database (Pentarctagon)<br />
* Revamp Duelist line portraits (Lordbob)<br />
<br />
== 1.15.9 (01/16/2021) ==<br />
* Add a <nowiki>forum_auth=yes|no</nowiki> attribute to _server.pbl to allow authenticating via the add-on author's forum username and password. Add-on authors utilizing this then wouldn't need to provide a separate author, email, or passphrase value, and would be more secure by not needing to store the passphrase for these add-ons in plaintext as is currently done (Pentarctagon)<br />
<br />
== 1.15.10 (02/20/2021) ==<br />
* Have the Travis-CI MP unit tests validate database functionality (Pentarctagon)<br />
* Add missing story art for tRoW (Lordbob)<br />
<br />
== 1.15.11 (03/20/2021) ==<br />
* Remove the scenario editor functionality, keeping specific features that are useful, such as being able to place unit sprites (Pentarctagon)<br />
<br />
== 1.15.12 (04/17/2021) ==<br />
* Add story art for UtBS (Lordbob)<br />
<br />
== 1.15.13 (05/15/2021) ==<br />
* <br />
<br />
== 1.15.14 (06/19/2021) ==<br />
* Add Dunefolk portraits. Next year is quite long-term, but the Dunefolk are plenty so I want to work on them in the background rather than take too much at once and burn myself out. (Lordbob) <br />
<br />
== 1.15.15 (07/17/2021) ==<br />
* <br />
<br />
<br />
[[Category:Roadmaps]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=PblWML&diff=65385PblWML2020-02-17T02:44:19Z<p>Doofus-01: /* type */</p>
<hr />
<div>{{WML Tags}}<br />
<br />
To upload an add-on you have made, you need a '''_server.pbl''' file in your add-on's directory, at the same level as the '''_main.cfg''' file. When you upload the add-on, the entire directory and subdirectories containing the _server.pbl file will be published. Your add-on must be based entirely on these paths.<br />
<br />
See [[AddonStructure]] for more on setting up the add-on folder if you have not done so, and [[Distributing_content]] for more on uploading an add-on to the server with this file.<br />
<br />
<b>Note:</b> Be aware that translations in the .pbl-files are '''not''' used, so don't mark these strings as translatable.<br />
<br />
== What goes into a .pbl file? ==<br />
<br />
'''Note:''' ''You should '''not''' use special formatting or coloring in any of these keys when uploading to the official server.'''''<br />
<br />
The following keys are recognized for .pbl files:<br />
<br />
=== icon ===<br />
: An image, displayed leftmost in the add-ons download dialog. It must be a standard Wesnoth file and '''not a custom one'''. A custom file will only work for users who already have the relevant add-on installed. This is not related to the icon used for entries in the campaigns menu -- see [[CampaignWML]] for more information.<br />
<br />
: If the icon is a unit with magenta team-color bits, please use [[ImagePathFunctions]] to recolor it.<br />
<br />
: {{DevFeature1.13|12}} Instead of a standard Wesnoth image, a [[DataURI]] can also be used. This way, an image can be directly included into the _server.pbl file. Take care to leave no trailing newline.<br />
<br />
=== title ===<br />
: Displayed to the right of the icon, it is just text. It should usually be the same as the name of your add-on when it is played.<br />
: '''This value is required'''.<br />
<br />
=== version ===<br />
: Displayed to the right of the title; it is merely text. However, starting with Wesnoth 1.6, the required format is '''x.y.z''' where '''x''', '''y''' and '''z''' are numbers β and a value for '''x''' greater than ''0'' implies the add-on is complete, feature-wise. Trailing non-numeric elements are allowed, but nothing should appear before or between these numbers. The string of numbers will be modified on the server by inserting or appending zeros as neccesary to meet the required format. All this is necessary for the βUpdate Allβ button to work correctly. ([[#Version Key Examples|See Examples]])<br />
: '''This value is required'''.<br />
<br />
=== author ===<br />
: Displayed to the right of the version; it is merely text. Put your name or nickname here. If several people have contributed significantly to the add-on you may want to list all of their names.<br />
: '''This value is required'''.<br />
<br />
=== passphrase ===<br />
: Not displayed. It prevents others from modifying the version of your add-on on the server. You do not need to input a passphrase when initially publishing a add-on; if you do not, one will be randomly generated for you and replaced in your local copy of the .pbl file.<br />
: '''SECURITY NOTE:''' If you do specify a passphrase of your own, note that it is stored in '''clear text''' form in the server; '''do NOT use a password you would normally use for any other services or web sites!'''<br />
<br />
=== description ===<br />
: This can be used to provide a brief description of your add-on, and for pre-1.0 versions, let people know how playable it is. The description can be viewed by users by clicking on the Description button in the built-in client, or by moving their mouse over the add-on's icon in the web interface.<br />
: '''This value is required'''.<br />
<br />
=== dependencies ===<br />
: An optional list of dependencies (a comma separated list of ''addon-name'' β the directory names of the needed add-ons), which should be provided if your add-on relies on other user-made content to work properly. ([[#Dependency Key Example|See Example]])<br />
<br />
=== tags ===<br />
{{DevFeature1.13|12}}<br />
: An optional string including a comma-separated list of keywords used for matching add-ons when typing terms into the Filter box on the top left of the Add-ons Manager. There are no specific requirements on the syntax of the keywords listed here, but a general recommendation is to keep them relevant for players. For example, one might include the add-on's acronym in the tags, the names or acronyms of add-ons to which it is related, and so on.<br />
<br />
=== core ===<br />
{{DevFeature1.13|0}}<br />
: An optional string defining the id of the core which the addon is designed for. Defaults to "''default''". Don't specify for an addon which is of type "''core''" itself.<br />
<br />
=== translate ===<br />
: If set to ''true'', the add-on will be sent to and updated with [[WesCamp|WesCamp-i18n]]. (NOTE: this is a new and experimental function, which will automatically update the translations in your add-on. Make sure you make backups of your add-on in case of problems.)<br />
<br />
: You should make sure your add-on complies with some very specific [[WesCamp#Preparing_your_add-on_for_WesCamp|conventions]] required to ease the process for translators as well as technical requirements.<br />
<br />
: Note: As of April 4th, 2015, WesCamp appears to have been abandoned for about a year. It might be back soon, it might not. Instead, please refer to [[GettextForWesnothDevelopers#Gettext_for_UMC_Developers]].<br />
<br />
=== type ===<br />
: Indicates the type of the add-on; used to filter listings in the downloads manager dialog. Acceptable values are:<br />
<br />
:* ''core'': replaces the whole wml tree. {{DevFeature1.13|0}}<br />
:* ''campaign'': single player campaign.<br />
:* ''scenario'': single player scenario.<br />
:* ''campaign_sp_mp'': hybrid campaign.<br />
:* ''era'': multiplayer era.<br />
:* ''faction'': multiplayer stand-alone faction, or add-on for other available era.<br />
:* ''map_pack'': multiplayer map-pack.<br />
:* ''campaign_mp'': multiplayer campaign.<br />
:* ''scenario_mp'': multiplayer scenario. (See the note below.)<br />
:* ''mod_mp'': multiplayer modification ({{DevFeature1.13|11}} can also used for single-player modifications, although it's still called ''mod_mp'').<br />
:* ''media'': miscellaneous resources for UMC authors/users, for example, music packs, packages of general-purpose WML, etc. <small>Note: Shows as Resources, not Media, in the add-ons interface</small><br />
:* ''other'': The type to use when no other type fits.<br />
: '''Note:''' If your add-on contains two or more separate multiplayer scenarios, use ''map_pack''.<br />
<br />
: '''This value is required'''.<br />
<br />
=== email ===<br />
: Hidden e-mail address used by the server administrators to contact content authors in case of major issues. Again, this will only be seen by the server administrators and it is required that you provide one in case you need to be contacted about your add-on.<br />
: '''This value is required'''.<br />
<br />
=== [feedback] ===<br />
: The [feedback] tag includes information used by the server to provide the client with a website URL for players to post feedback on an add-on and communicate with the maintainers. At this time, the official add-ons server is configured to take a single parameter described below.<br />
<br />
==== topic_id ====<br />
: Topic id from the [http://forums.wesnoth.org/ Wesnoth.org forums] for the add-on's feedback or development topic maintained by the add-on uploader or author. For existing topics, this topic_id corresponds to the series of digits in the ''t=YYYYY'' portion of a URL like <code><nowiki>http://forums.wesnoth.org/viewtopic.php?f=XX&t=YYYYY</nowiki></code>. You must take special care to ensure this information is valid before uploading if you want players to be able to reach you!<br />
<br />
<br />
The add-on server keeps track of some other information about uploaded content, including when they were uploaded, what languages they have been at least partly translated into, how large they are on the server and the number of times they have been downloaded. For more information about this you can read [[CampaignServerWML]].<br />
<br />
== Examples ==<br />
<br />
=== Dependency Key Example ===<br />
<br />
The following dependency key could be used when the add-on needs the ''Imperial_Era'' and ''Era_of_Myths'' to be installed before it will work properly:<br />
<br />
dependencies=Imperial_Era,Era_of_Myths<br />
<br />
=== Version Key Examples ===<br />
<br />
The following are examples of '''good''' version values:<br />
<br />
version="1.5"<br />
version="0.11.4"<br />
version="0.1.4beta"<br />
version="1.5c"<br />
<br />
The following are examples of '''bad''' version values:<br />
<br />
version="Beta1.5"<br />
version="Incomplete (0.3.4)"<br />
<br />
In both of the above examples the version number as read by the server will be '''0.0.0Beta1.5''' and '''0.0.0Incomplete (0.3.4)'''. You can clearly see why this will not be a good thing with the ''Update add-ons'' feature.<br />
<br />
Finally, here are some example version numbers and how they will be interpreted by the ''Update add-ons'' button. The number on the left will be considered an earlier number than the number on the right in each example.<br />
<br />
0.5 < 1.0<br />
1.5 < 1.5c<br />
1.0 < 1.0.1<br />
1.0c < 1.0.1a<br />
1.0.1a < 1.0.1c<br />
1.0 Final < 1.0.1 Beta<br />
<br />
=== Example .pbl File ===<br />
<br />
<syntaxhighlight lang=wml><br />
title="My Campaign"<br />
type="campaign"<br />
icon="misc/ball.png"<br />
version="0.1.2"<br />
author="Me, artwork by myself"<br />
passphrase="This is like a password; see the security note in the documentation above before choosing a value of your own"<br />
description="You get to kill a lot of bad guys. But only the first map is done."<br />
email="name@example.com"<br />
[feedback]<br />
topic_id=12345<br />
[/feedback]<br />
</syntaxhighlight><br />
<br />
== See Also ==<br />
<br />
* [[IGNFileFormat]]<br />
* [[FancyAddonIcons]]<br />
* [[ReferenceWML]]<br />
* [[CampaignServerWML]]<br />
<br />
[[Category: WML Reference]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=InterfaceActionsWML&diff=65277InterfaceActionsWML2020-01-06T04:12:50Z<p>Doofus-01: /* [remove_item] */</p>
<hr />
<div>{{WML Tags}}<br />
== Interface actions ==<br />
<br />
Part of [[ActionWML]], interface actions are actions that do not have a direct effect on gameplay;<br />
instead, they show something to the player. The main interface tags<br />
are '''[message]''' and '''[objectives]''', but several other tags affect<br />
the interface also.<br />
<br />
== [inspect] ==<br />
This user interface instantly displays the gamestate inspector dialog at the current scenario state (the same one that can be brought up with [[CommandMode|the ''':inspect''' command]]), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.<br />
<br />
* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.<br />
<br />
== [message] ==<br />
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.<br />
<br />
The following key/tags are accepted for [message]:<br />
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed).<br>[message] elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.<br />
<br />
* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:<br />
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image<br />
** '''unit''': the primary unit for the event is speaking<br />
** '''second_unit''': {{DevFeature1.13|6}} the secondary unit for the event is speaking<br />
<br />
* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')<br />
* '''male_message''', '''female_message''': {{DevFeature1.13|2}} (translatable) Used instead of ''message'' if the unit's gender matches. Never used if there is no unit (ie ''speaker=narrator''). {{DevFeature1.13|6}} This matches the primary unit, not the secondary unit.<br />
* '''wait_description''': {{DevFeature1.13|2}} the description of this message displayed when other players in a mp game wait for one player doing input in a [message] (with [option]s or [text_input]).<br />
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])<br />
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will <b>not</b> work with messages that take user input ([option]/[text_input]), which can only ever be shown to the current player. {{DevFeature1.13|0}} side_for= is now also accepted for messages with user input, it specifies on which side the message is shown (defaults to the currently playing side). For messages with input it does not accept a comma seperated list only a single number.<br />
* '''image''': (default: profile image of speaker) the image to display to the left of the message text. Append ~RIGHT() if you want the image to appear on the right side. <br />
** {{DevFeature1.13|0}} <b>none:</b> display no image<br />
* '''mirror''': {{DevFeature1.13|5}}whether to mirror the image specified by the '''image''' attribute.<br />
* '''second_image''': {{DevFeature1.13|6}}same as the '''image''' attribute, but the image is displayed on the right of the message text.<br />
* '''second_mirror''': {{DevFeature1.13|6}}same as '''mirror''', but for the '''second_image''' attribute.<br />
* '''image_pos''': {{DevFeature1.13|5}} whether to show the image on the left or right; supercedes the use of ~RIGHT() described above<br />
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.<br />
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.<br />
* '''highlight''': {{DevFeature1.13|5}} Boolean specifying whether to highlight the speaker. Defaults to ''yes''.<br />
* '''sound''': a sound effect (wav file) to play as the message is displayed. This can be a comma-separated list, from which one will be randomly chosen.<br />
* '''voice''': {{DevFeature1.13|?}} a sound to be played as the message is displayed. This can also be a comma-separated list, from which one will be randomly chosen. This is intended for voiceovers for the message.<br />
* '''[option]''': No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option. ''Note: Messages with options will not be shown at all in prestart events''<br />
** '''message''': (translatable) the text displayed for the option. {{DevFeature1.15|1}} This is now a synonym for '''description='''.<br />
** '''image''', '''label''', '''description''', '''default''': See [[DescriptionWML#WML_Format|DescriptionWML]].<br />
** '''value''': {{DevFeature1.13|?}} Gives the option a value to be stored in a variable.<br />
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])<br />
** '''[command]''': an element containing actions which are executed if the option is selected.<br />
* '''variable''': {{DevFeature1.13|?}} If present, either the index or the value of the chosen option will be stored in the specified variable. Option indexing starts from 1. If option has '''[show_if]''' condition evaluated as false, then it is hidden and excluded from the indexing.<br />
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message. ''Note: Messages with text_input will not be shown at all in prestart events''<br />
** '''variable''': the variable that the user's input will be written to<br />
** '''label''': a text label to the left of the input field<br />
** '''max_length''': the maximum number of characters that may be typed into the field<br />
** '''text''': text that is written into the field in the beginning<br />
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.<br />
<br />
=== Formatting ===<br />
'''[message]''' and other tags such as unit names (user_description), objectives, and floating text can make use of [https://developer.gnome.org/pango/stable/pango-Markup.html Pango markup formatting codes].<br />
<br />
Remember to use single quotes (') instead of double quotes (") within the formatting string, as double quotes cannot be escaped, and the string will appear fragmented and possibly cause errors. Escaping markup is described in https://github.com/wesnoth/wesnoth/blob/master/src/font/pango/escape.hpp#L35-L39.<br />
<br />
For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:<br />
<br />
<nowiki><span color='#BCB088' size='large' font-style='italic'>You are victorious!</span></nowiki><br />
<br />
<br />
These are the codes taken from the Pango markup formatting guide:<br />
<br />
*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".<br />
*'''font_family''', '''face''': A font family name.<br />
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.<br />
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.<br />
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.<br />
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.<br />
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.<br />
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.<br />
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.<br />
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.<br />
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.<br />
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.<br />
*'''strikethrough''': 'true' or 'false' whether to strike through the text.<br />
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'<br />
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.<br />
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.<br />
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.<br />
*'''gravity_hint''': One of 'natural', 'strong', 'line'.<br />
<br />
The following pango attributes are also available directly as attributes of the '''[message]''' tag:<br />
{{DevFeature1.13|4}}<br />
<br />
*'''font'''<br />
*'''font_family'''<br />
*'''font_size'''<br />
*'''font_style'''<br />
*'''font_weight'''<br />
*'''font_variant'''<br />
*'''font_stretch'''<br />
*'''color'''<br />
*'''bgcolor'''<br />
*'''underline'''<br />
*'''underline_color'''<br />
*'''rise'''<br />
*'''strikethrough'''<br />
*'''strikethrough_color'''<br />
*'''fallback'''<br />
*'''letter_spacing'''<br />
*'''gravity'''<br />
*'''gravity_hint'''<br />
<br />
== [objectives] ==<br />
The other tag used for plot development is '''[objectives]'''.<br />
The '''[objectives]''' tag overwrites any previously set objectives,<br />
and displays text which should describe the objectives of the scenario.<br />
Scenario objectives are displayed on the player's first turn after the tag is used,<br />
or as part of the event if it triggers during that player's turn.<br />
Objectives can also be accessed at any time in a scenario using the<br />
"Scenario Objectives" game menu option, making this tag useful for<br />
scenario-specific information that the player may need to refer to during play.<br />
<br />
Attributes of '''[objectives]''':<br />
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.<br />
* '''[[StandardSideFilter]]''' tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.<br />
* '''bullet''': Default 'β’ '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].<br />
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.<br />
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.<br />
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives. Can be set to "" too.<br />
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives. Can be set to "" too.<br />
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.<br />
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.<br />
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.<br />
* '''delayed_variable_substitution''': {{DevFeature1.13|8}} If set to yes, any variables or [insert_tag] are not substituted right away. Instead, they are substituted whenever the objectives are actually viewed.<br />
<br />
Tags of '''[objectives]''':<br />
* '''[objective]''': describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.<br />
** '''bullet''': Default 'β’ ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.<br />
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.<br />
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.<br />
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.<br />
** '''description''': text for the specific win or loss condition.<br />
** '''caption''': a text which will be displayed above the ''description''. This can be used to display a subcategory of objectives below ''victory_string'' or ''defeat_string''.<br />
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'').<br />
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.<br />
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only, or when manually opening the scenario objectives.<br />
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].<br />
** '''bullet''': Default 'β’ ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.<br />
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.<br />
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.<br />
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.<br />
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.<br />
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.<br />
** '''[show_if]''': {{DevFeature1.13|11}} Gold carryover will not be shown if the specified condition isn't met. Conditional gold carryover is refreshed at '''[show_objectives]''' time only.<br />
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.<br />
** '''bullet''': Default 'β’ ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.<br />
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.<br />
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.<br />
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.<br />
** '''description''': the text of the note.<br />
** '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.<br />
<br />
== [set_menu_item] ==<br />
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.<br />
<br />
'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu. {{DevFeature1.13|0}} This limitation is being removed in a [http://forums.wesnoth.org/viewtopic.php?p=572554#p572554 future version] of Wesnoth.<br />
<br />
* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.<br />
* '''description''': the in-game text that will appear for this item in the menu.<br />
* '''image''': the image to display next to this item.<br />
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].<br />
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS<br />
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp. <br />
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.<br />
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.<br />
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:<br />
** '''key''': a string that contains the key to assign to this.<br />
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.<br />
** '''repeat_on_hold''' {{DevFeature1.13|12}}: if ''yes'' (default ''no''), holding the hotkey will repeat the action continuously, unless it blocks input with something like '''[message]'''. Due to a bug, versions older than 1.13.12 always repeat the action, with no way to disable it.<br />
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.<br />
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.<br />
<br />
== [clear_menu_item] ==<br />
<br />
Removes a menu item from the scenario.<br />
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).<br />
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.<br />
<br />
== Other interface tags ==<br />
<br />
The following tags are also action tags:<br />
<br />
=== [change_theme] ===<br />
<br />
{{DevFeature1.13|8}}<br />
<br />
Change the current interface theme.<br />
<br />
* '''theme''': The ID of the new theme. Use <code>theme=</code> (empty key) to switch back to the theme that the player has selected in Preferences. On <b>1.14.2</b> and later it is also possible to omit the key entirely to achieve the same effect (on previous versions this will crash the Lua engine).<br />
<br />
=== [item] ===<br />
Makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt><br />
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)<br />
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctions#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''<br />
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image (https://github.com/wesnoth/wesnoth/issues/1219).<br />
* '''name''' an id that can be used to remove the item.<br />
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''<br />
or equivalently (requires Wesnoth 1.11.2+):<br />
''halo=scenery/fire[1~8].png:100''<br />
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas. {{DevFeature1.15|0}} In 1.14 the '''[side]team_name''' attribute was expected to be a substring of this '''team_name'''. In 1.15 both are expected to be comma-separated lists of names and the item is visible if the lists intersect. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])<br />
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.<br />
* '''redraw''': (boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.<br />
* '''[filter_team]''': {{DevFeature1.15|0}} A [[StandardSideFilter]]. Set '''team_name''' to the union of all '''[side]team_name''' attributes of all sides that match the SSF. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])<br />
* {{DevFeature1.15|0}} If both '''team_name''' and '''[filter_team]''' are set, '''team_name''' is ignored.<br />
<br />
=== [remove_item] ===<br />
Removes any graphical items on a given hex.<br />
* [[StandardLocationFilter]]: the hexes to remove items off<br />
* '''image''': if specified, only removes the given image item (This image name must include any [[ImagePathFunctions|image path functions]] appended to the original image name.)<br />
* '''name''': removes an item with a previously defined name.<br />
''Note: The filtering on this tag is not what a normal person would expect. Filtering on the item's halo key or name key will most likely fail. This should be fixed some day, see https://github.com/wesnoth/wesnoth/issues/4689 For now, use the SLF and/or image key.''<br />
<br />
=== [print] ===<br />
Displays a message across the screen. The message will disappear after a certain time.<br />
* '''text''': (translatable) the text to display.<br />
* '''size''': (default=12) the pointsize of the font to use<br />
* '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.<br />
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. {{DevFeature1.13|x}} Use of red, green, blue is now deprecated; use color=0,0,0 instead.<br />
<br />
=== [move_unit_fake] ===<br />
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.<br />
* '''type''': the type of the unit whose image to use<br />
* '''x''': a comma-separated list of x locations to move along<br />
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)<br />
* '''side''': the side of the fake unit, used for team-coloring the fake unit<br />
* '''gender''': the gender of the fake unit. Example: gender=female<br />
* '''variation''': the variation of the fake unit. Example: variation=undead<br />
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.<br />
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.<br />
<br />
=== [move_units_fake] ===<br />
moves multiple images of units along paths on the map. These units are moved in lockstep.<br />
* '''force_scroll''': {{DevFeature1.15|0}} Has the same meaning as in [move_unit_fake] but a different default.<br />
* '''[fake_unit]''': A fake unit to move<br />
** '''type''': the type of unit whose image to use<br />
** '''x''': a comma-separated list of x locations to move along<br />
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)<br />
** '''side''': the side of the fake unit, used for team-coloring the fake unit<br />
** '''skip_steps''': the number of steps to skip before this unit starts moving<br />
<br />
=== [hide_unit] ===<br />
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.<br />
* [[StandardUnitFilter]]: All matching units will be hidden<br />
<br />
=== [unhide_unit] ===<br />
Stops the currently hidden units from being hidden.<br />
* [[StandardUnitFilter]]: Only the matching units will be unhidden<br />
<br />
=== [lock_view] ===<br />
Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.<br />
<br />
This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.<br />
<br />
{{DevFeature1.13|8}} This now also blocks the player from zooming the gamemap view. WML or Lua zoom will continue to work normally.<br />
<br />
=== [unlock_view] ===<br />
Unlocks gamemap view scrolling for human players.<br />
<br />
=== [scroll] ===<br />
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.<br />
* '''x''', '''y''': the number of pixels to scroll along the x and y axis<br />
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.<br />
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.<br />
<br />
=== [scroll_to] ===<br />
Scroll to a given hex<br />
* [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.<br />
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.<br />
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').<br />
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex being scrolled to (defaults to ''no'').<br />
* '''side''': the side or sides for which this should happen. By default, the [scroll_to] happens for everyone.<br />
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to] happens for everyone.<br />
<br />
=== [scroll_to_unit] ===<br />
Scroll to a given unit<br />
* [[StandardUnitFilter]]<br />
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.<br />
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').<br />
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex the unit is on (defaults to ''no'').<br />
* '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.<br />
* '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.<br />
<br />
=== [select_unit] ===<br />
Selects a given unit.<br />
* [[StandardUnitFilter]]: The first unit found will be selected.<br />
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)<br />
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').<br />
<br />
=== [sound]===<br />
Plays a sound<br />
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg). This can be a comma-separated list, from which one sound will be chosen randomly.<br />
* '''repeat''': repeats the sound for a specified additional number of times (default=0)<br />
<br />
=== [sound_source] ===<br />
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.<br />
* '''id''': a unique identification key of the sound source<br />
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source<br />
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play<br />
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)<br />
* '''check_fogged''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged<br />
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded<br />
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source<br />
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly<br />
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center<br />
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)<br />
<br />
=== [story] ===<br />
{{DevFeature1.13|8}}<br />
<br />
Shows the story screen.<br />
* '''title''': Default title used if a part does not specify one β unlike the intro storyscreen, the scenario name is not used as a default title.<br />
* '''[part]''': As [[IntroWML]].<br />
<br />
=== [remove_sound_source] ===<br />
Removes a previously defined sound source.<br />
* '''id''': the identification key of the sound source to remove<br />
<br />
=== [music]===<br />
Switches to playing different music<br />
* '''name''': the filename of the music to play (in ''music/'' as .ogg)<br />
* see [[MusicListWML]] for the correct syntax<br />
===[volume]===<br />
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100: <br />
* '''music''': Changes the music volume.<br />
* '''sound''': Changes the sound volume.<br />
=== [color_adjust]===<br />
Tints the color of the screen.<br />
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color<br />
=== [delay] ===<br />
Pauses the game.<br />
* '''time''': the time to pause in milliseconds<br />
* '''accelerate ''' (boolean yes|no, default no): {{DevFeature1.13|0}} whether the delay is affected by acceleration. When [delay] is used to make an animation, this should be set to yes so that your animation matches the ones generated by the game.<br />
<br />
=== [redraw] ===<br />
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).<br />
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. Useful if you, for example, spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).<br />
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.<br />
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.<br />
<br />
=== [unit_overlay] ===<br />
Sets an image that will be drawn over a particular unit, and follow it around<br />
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])<br />
* '''image''': the image to place on the unit<br />
<br />
=== [remove_unit_overlay] ===<br />
Removes a particular overlayed image from a unit<br />
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])<br />
* '''image''': the image to remove from the unit<br />
Using remove_object is also possible, see https://github.com/wesnoth/wesnoth/commit/26c2f941f2bcdd89528481e114c0375ad2a46271<br />
<br />
=== [animate_unit] ===<br />
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).<br />
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''<br />
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.<br />
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].<br />
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.<br />
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)<br />
* '''text''': a text to hover during the animation <br />
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above<br />
* '''red''': red value for the text color (0-255)<br />
* '''green''': green value for the text color<br />
* '''blue''': blue value for the text color<br />
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)<br />
* '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.<br />
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated<br />
<br />
=== [label] ===<br />
Places a label on the map.<br />
* '''x''', '''y''': the location of the label. {{DevFeature1.13|1}} (only for [event][label]: full [[StandardLocationFilter|SLF]] support)<br />
* '''text''': what the label should say<br />
* '''team_name''': if specified, the label will only be visible to the given team.<br />
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.<br />
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.<br />
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.<br />
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.<br />
* '''category''': the Show/Hide Labels dialog allows showing/hiding all labels of a given category by toggling a checkbox.<br />
* '''tooltip''': A tooltip visible when mouseovering the hex the label is on<br />
* '''side''': the number of the side that placed the label. Can be 0 for labels placed by WML.<br />
<br />
=== [floating_text]===<br />
Floats text (similar to the damage and healing numbers) on the given locations.<br />
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.<br />
* '''text''': the text to display.<br />
<br />
The default text color is <span style="color: #6b8cff;">'''#6b8cff'''</span>. To change the color, use [[#Formatting|Pango markup]]. For example:<br />
<br />
<pre><br />
# Float some golden yellow text at 20,20.<br />
[floating_text]<br />
x,y=20,20<br />
text="<span color='#cccc33'>" + _ "Your text here" + "</span>"<br />
[/floating_text]<br />
</pre><br />
<br />
=== [deprecated_message] ===<br />
Shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.<br />
* '''message''': the message to show.<br />
* '''level''': {{DevFeature1.13|10}} The deprecation level, a number from 1 to 3.<br />
* '''what''': {{DevFeature1.13|10}} The name of the thing being deprecated. Use this instead of '''message''' if possible; a stock message will be generated from it. Use '''message''' only if more information is required; it will be appended to the stock message. This should not be translatable<br />
* '''version''': {{DevFeature1.13|10}} For deprecation levels 2 and 3, this indicates the version in which the feature could be removed. It does ''not'' indicate the version in which it became deprecated. <br />
<br />
The meanings of the deprecation levels are as follows:<br />
<br />
# Deprecated, but will only be removed if absolutely necessary. The '''version''' key is ignored.<br />
# It will be removed no earlier than a specified version.<br />
# It will be removed in the next stable version<br />
# It has already been removed, leaving just a stub to inform users of how to update their code.<br />
<br />
Note that as of 1.13.11, deprecation messages show only in the log, not in the chat message area. The '''message''' can be translatable, but does not need to be.<br />
<br />
=== [wml_message] ===<br />
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.<br />
* '''message''': the message to show.<br />
* '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.<br />
<br />
Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.<br />
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).<br />
<br />
=== [test_condition] ===<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
Evaluates the contained conditional tags. If they evaluate to the expected value, it prints out a message to the console explaining which part of the condition caused this result in a way similar to [wml_message]. This can be used if your conditional test is failing and you're not sure why.<br />
<br />
* '''result''': Whether you expect the conditions to fail or succeed. If no (the default), a message will be printed if the conditional tags fail. If yes, a message will instead be printed if the conditional tags pass.<br />
* '''logger''': Same as for [wml_message]. Defaults to "warning".<br />
<br />
=== [open_help] ===<br />
Opens the in-game help.<br />
* '''topic''': the id of the topic to open<br />
=== [show_objectives] ===<br />
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)<br />
* '''side''': the side to show the objectives. If not set, all sides are used.<br />
* '''[[StandardSideFilter]]''' tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.<br />
<br />
=== [chat] ===<br />
Displays a message in the chat area, not visible for observers. Alternative unconditionally visible for everyone: [[LuaWML:Display#wesnoth.message]]. {{DevFeature1.13|9}} can be visible for observers.<br />
* '''speaker''': (default="WML") A string for the name of the sender of the message.<br />
* '''message''': The message that should be displayed.<br />
* '''observable''' (boolean yes|no, default yes): {{DevFeature1.13|9}} Whether the message is displayed for observers.<br />
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.<br />
<br />
=== [zoom] ===<br />
<br />
{{DevFeature1.13|8}}<br />
<br />
Changes the zoom level of the map.<br />
<br />
* '''factor''': The new zoom factor<br />
* '''relative''': If yes, zoom relative to current zoom level. Otherwise, set the absolute zoom level. Default no.<br />
<br />
== Useful Macros ==<br />
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].<br />
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units<br />
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations<br />
* '''{SET_IMAGE}''' Places an image on the map which has no other function.<br />
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.<br />
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.<br />
<br />
== See Also ==<br />
* [[DirectActionsWML]]<br />
* [[InternalActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=InterfaceActionsWML&diff=65276InterfaceActionsWML2020-01-06T04:12:07Z<p>Doofus-01: /* [remove_item] */</p>
<hr />
<div>{{WML Tags}}<br />
== Interface actions ==<br />
<br />
Part of [[ActionWML]], interface actions are actions that do not have a direct effect on gameplay;<br />
instead, they show something to the player. The main interface tags<br />
are '''[message]''' and '''[objectives]''', but several other tags affect<br />
the interface also.<br />
<br />
== [inspect] ==<br />
This user interface instantly displays the gamestate inspector dialog at the current scenario state (the same one that can be brought up with [[CommandMode|the ''':inspect''' command]]), which can be used to inspect the values of WML variables, AI configuration, recall lists, and more.<br />
<br />
* '''name''': optional attribute to specify the name of this gamestate inspector dialog. It is just a label to help differentiate between different invocations of gamestate inspector dialog.<br />
<br />
== [message] ==<br />
The most commonly used interface action is [message], which displays a message to the user in a dialog box. It can also be used to take input from the user.<br />
<br />
The following key/tags are accepted for [message]:<br />
* [[StandardUnitFilter]]: The unit whose profile and name are displayed. Do not use a [filter] tag. If no unit matching this filter is found, the message is not displayed (The unit has probably been killed).<br>[message] elements should be constructed so that it is either guaranteed that a certain unit is alive, or so that dialog flows smoothly even if the message isn't displayed.<br />
<br />
* '''speaker''': an alternative to standard unit filter. You may specify as the value of the speaker attribute a unit id or any of the following special values:<br />
** '''narrator''': the dialog box is displayed without a caption for the unit speaking or a unit image<br />
** '''unit''': the primary unit for the event is speaking<br />
** '''second_unit''': {{DevFeature1.13|6}} the secondary unit for the event is speaking<br />
<br />
* '''message''': (translatable) the text to display to the right of the image. ''message'' is sometimes multiple lines; if it is, be sure to use quotes(''' ' ''' or ''' " ''')<br />
* '''male_message''', '''female_message''': {{DevFeature1.13|2}} (translatable) Used instead of ''message'' if the unit's gender matches. Never used if there is no unit (ie ''speaker=narrator''). {{DevFeature1.13|6}} This matches the primary unit, not the secondary unit.<br />
* '''wait_description''': {{DevFeature1.13|2}} the description of this message displayed when other players in a mp game wait for one player doing input in a [message] (with [option]s or [text_input]).<br />
* '''[show_if]''': if present then this message will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])<br />
* '''side_for''': (default: all sides) comma-separated list of sides for who message is shown. This will <b>not</b> work with messages that take user input ([option]/[text_input]), which can only ever be shown to the current player. {{DevFeature1.13|0}} side_for= is now also accepted for messages with user input, it specifies on which side the message is shown (defaults to the currently playing side). For messages with input it does not accept a comma seperated list only a single number.<br />
* '''image''': (default: profile image of speaker) the image to display to the left of the message text. Append ~RIGHT() if you want the image to appear on the right side. <br />
** {{DevFeature1.13|0}} <b>none:</b> display no image<br />
* '''mirror''': {{DevFeature1.13|5}}whether to mirror the image specified by the '''image''' attribute.<br />
* '''second_image''': {{DevFeature1.13|6}}same as the '''image''' attribute, but the image is displayed on the right of the message text.<br />
* '''second_mirror''': {{DevFeature1.13|6}}same as '''mirror''', but for the '''second_image''' attribute.<br />
* '''image_pos''': {{DevFeature1.13|5}} whether to show the image on the left or right; supercedes the use of ~RIGHT() described above<br />
* '''caption''': (default: name of speaker) the caption to display beside the image. Name to be displayed. Note: use a translation mark to avoid wmllint errors.<br />
* '''scroll''': Boolean specifying whether the game view should scroll to the speaking unit. Defaults to ''yes''.<br />
* '''highlight''': {{DevFeature1.13|5}} Boolean specifying whether to highlight the speaker. Defaults to ''yes''.<br />
* '''sound''': a sound effect (wav file) to play as the message is displayed. This can be a comma-separated list, from which one will be randomly chosen.<br />
* '''voice''': {{DevFeature1.13|?}} a sound to be played as the message is displayed. This can also be a comma-separated list, from which one will be randomly chosen. This is intended for voiceovers for the message.<br />
* '''[option]''': No '''[option]''' elements have to be used. If '''[option]''' elements are present, then each option will be displayed in a menu for the user to select one option. ''Note: Messages with options will not be shown at all in prestart events''<br />
** '''message''': (translatable) the text displayed for the option. {{DevFeature1.15|1}} This is now a synonym for '''description='''.<br />
** '''image''', '''label''', '''description''', '''default''': See [[DescriptionWML#WML_Format|DescriptionWML]].<br />
** '''value''': {{DevFeature1.13|?}} Gives the option a value to be stored in a variable.<br />
** '''[show_if]''': if present then this option will only be displayed if the conditional statement in this tag is passed (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]])<br />
** '''[command]''': an element containing actions which are executed if the option is selected.<br />
* '''variable''': {{DevFeature1.13|?}} If present, either the index or the value of the chosen option will be stored in the specified variable. Option indexing starts from 1. If option has '''[show_if]''' condition evaluated as false, then it is hidden and excluded from the indexing.<br />
* '''[text_input]''': there can be only one [text_input] tag. this adds a text input field to the message. ''Note: Messages with text_input will not be shown at all in prestart events''<br />
** '''variable''': the variable that the user's input will be written to<br />
** '''label''': a text label to the left of the input field<br />
** '''max_length''': the maximum number of characters that may be typed into the field<br />
** '''text''': text that is written into the field in the beginning<br />
* Check [[EventWML#Multiplayer_safety]] to find out in which events you can safely use '''[option]''' and '''[text_input]''' without causing OOS.<br />
<br />
=== Formatting ===<br />
'''[message]''' and other tags such as unit names (user_description), objectives, and floating text can make use of [https://developer.gnome.org/pango/stable/pango-Markup.html Pango markup formatting codes].<br />
<br />
Remember to use single quotes (') instead of double quotes (") within the formatting string, as double quotes cannot be escaped, and the string will appear fragmented and possibly cause errors. Escaping markup is described in https://github.com/wesnoth/wesnoth/blob/master/src/font/pango/escape.hpp#L35-L39.<br />
<br />
For example, if you wanted to write "You are victorious!" in large, italic, gold letters, you might write it this way:<br />
<br />
<nowiki><span color='#BCB088' size='large' font-style='italic'>You are victorious!</span></nowiki><br />
<br />
<br />
These are the codes taken from the Pango markup formatting guide:<br />
<br />
*'''font''', '''font_desc''': A font description string, such as "Sans Italic 12".<br />
*'''font_family''', '''face''': A font family name.<br />
*'''font_size''', '''size''': Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'.<br />
*'''font_style''', '''style''': One of 'normal', 'oblique', 'italic'.<br />
*'''font_weight''', '''weight''': One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight.<br />
*'''font_variant''', '''variant''': One of 'normal' or 'smallcaps'.<br />
*'''font_stretch''', '''stretch''': One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'.<br />
*'''foreground''', '''fgcolor''', '''color''': An RGB color specification such as '#00FF00' or a color name such as 'red'.<br />
*'''background, bgcolor''': An RGB color specification such as '#00FF00' or a color name such as 'red'.<br />
*'''underline''': One of 'none', 'single', 'double', 'low', 'error'.<br />
*'''underline_color''': The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'.<br />
*'''rise''': Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.<br />
*'''strikethrough''': 'true' or 'false' whether to strike through the text.<br />
*'''strikethrough_color''': The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'<br />
*'''fallback''': 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.<br />
*'''letter_spacing''': Inter-letter spacing in 1024ths of a point.<br />
*'''gravity''': One of 'south', 'east', 'north', 'west', 'auto'.<br />
*'''gravity_hint''': One of 'natural', 'strong', 'line'.<br />
<br />
The following pango attributes are also available directly as attributes of the '''[message]''' tag:<br />
{{DevFeature1.13|4}}<br />
<br />
*'''font'''<br />
*'''font_family'''<br />
*'''font_size'''<br />
*'''font_style'''<br />
*'''font_weight'''<br />
*'''font_variant'''<br />
*'''font_stretch'''<br />
*'''color'''<br />
*'''bgcolor'''<br />
*'''underline'''<br />
*'''underline_color'''<br />
*'''rise'''<br />
*'''strikethrough'''<br />
*'''strikethrough_color'''<br />
*'''fallback'''<br />
*'''letter_spacing'''<br />
*'''gravity'''<br />
*'''gravity_hint'''<br />
<br />
== [objectives] ==<br />
The other tag used for plot development is '''[objectives]'''.<br />
The '''[objectives]''' tag overwrites any previously set objectives,<br />
and displays text which should describe the objectives of the scenario.<br />
Scenario objectives are displayed on the player's first turn after the tag is used,<br />
or as part of the event if it triggers during that player's turn.<br />
Objectives can also be accessed at any time in a scenario using the<br />
"Scenario Objectives" game menu option, making this tag useful for<br />
scenario-specific information that the player may need to refer to during play.<br />
<br />
Attributes of '''[objectives]''':<br />
* '''side''': Default '0'. The side to set the objectives for. A value of 0 sets objectives for all sides. note: There are side-specific objectives and default objectives, which are used in case a side doesn't have specific ones. Specifying 0 sets the default ones.<br />
* '''[[StandardSideFilter]]''' tags and keys: Sets the objectives of all matching sides to these passed specifications (the rest of this [objectives] tag). If no sides (such as when passing side=0) or all sides match, sets the default objectives, and the side specific ones for the matching sides otherwise.<br />
* '''bullet''': Default 'β’ '. Replaces the default bullet, with whatever is passed, for all objectives, gold carryover notes, and notes defined with [note].<br />
* '''summary''': Displayed first in the objectives text, this should describe the basic objective for the overall scenario. Can be omitted.<br />
* '''note''': Displayed last in the objectives text, this is sometimes used for hints or additional information. Can be omitted.<br />
* '''victory_string''': Default ' _ "Victory:"', this text precedes the victory objectives. Can be set to "" too.<br />
* '''defeat_string''': Default ' _ "Defeat:"', this text precedes the defeat objectives. Can be set to "" too.<br />
* '''gold_carryover_string''': Default ' _ "Gold carryover:"', this text precedes the gold carryover information.<br />
* '''notes_string''': Default ' _ "Notes:"', this text precedes the notes.<br />
* '''silent''': Default: not present. If set to "yes", the objectives are silently changed. Else, they will be shown to the user when appropriate.<br />
* '''delayed_variable_substitution''': {{DevFeature1.13|8}} If set to yes, any variables or [insert_tag] are not substituted right away. Instead, they are substituted whenever the objectives are actually viewed.<br />
<br />
Tags of '''[objectives]''':<br />
* '''[objective]''': describes a win or loss condition. Most scenarios have multiple win or loss conditions, so use a separate [objective] subtag for each line; this helps with translations.<br />
** '''bullet''': Default 'β’ ' or whatever is set in the parent [objectives] block. Replaces the default bullet, with whatever is provided, for the objective defined by the [objective] block.<br />
** '''red''': Default '0' for winning objectives, '255' for losing objectives. Overrides the default red coloring of the entire objective, including the bullet.<br />
** '''green''': Default '255' for winning objectives, '0' for losing objectives. Overrides the default green coloring of the entire objective, including the bullet.<br />
** '''blue''': Default '0'. Overrides the default blue coloring of the entire objective, including the bullet.<br />
** '''description''': text for the specific win or loss condition.<br />
** '''caption''': a text which will be displayed above the ''description''. This can be used to display a subcategory of objectives below ''victory_string'' or ''defeat_string''.<br />
** '''condition''': The color and placement of the text. Values are 'win'(colored green, placed after ''victory_string'') and 'lose'(colored red, placed after ''defeat_string'').<br />
** '''show_turn_counter''': If set to yes, displays the number of turns remaining in the scenario. Default is no.<br />
** '''[show_if]''': A condition that disables the objective if it doesn't hold. Conditional objectives are refreshed at '''[show_objectives]''' time only, or when manually opening the scenario objectives.<br />
* '''[gold_carryover]''': describes how the gold carryover works in this scenario. This is intended to be a more convenient way of displaying carryover information than using the note= key in [objectives].<br />
** '''bullet''': Default 'β’ ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided.<br />
** '''red''': Default '255'. Overrides the default red coloring of the entire objective, including the bullet.<br />
** '''green''': Default '255'. Overrides the default green coloring of the entire objective, including the bullet.<br />
** '''blue''': Default '192'. Overrides the default blue coloring of the entire objective, including the bullet.<br />
** '''bonus''' (boolean): whether an early finish bonus is granted. If omitted, early finish bonus is not mentioned.<br />
** '''carryover_percentage''': the amount of carryover gold. If omitted, the amount is not mentioned.<br />
** '''[show_if]''': {{DevFeature1.13|11}} Gold carryover will not be shown if the specified condition isn't met. Conditional gold carryover is refreshed at '''[show_objectives]''' time only.<br />
* '''[note]''': describes a note, usually used for hints or additional information. This is an easier way of adding several notes than concatenating them together into a single string to use with the ''note='' key.<br />
** '''bullet''': Default 'β’ ' or whatever is set in the parent [objectives] block. Replaces the default bullet with whatever is provided for the note defined by the [note] block.<br />
** '''red''': Default '255'. Overrides the default red coloring of the entire note, including the bullet.<br />
** '''green''': Default '255'. Overrides the default green coloring of the entire note, including the bullet.<br />
** '''blue''': Default '255'. Overrides the default blue coloring of the entire note, including the bullet.<br />
** '''description''': the text of the note.<br />
** '''[show_if]''': The note will not be shown if the specified condition isn't met. Conditional notes are refreshed at '''[show_objectives]''' time only.<br />
<br />
== [set_menu_item] ==<br />
This tag is used to add a custom option in the right-click context menu which can then be used to trigger arbitrary WML commands. The menu items can be set and modified during any event, for example during "start" or "prestart" events. The user can also assign hotkeys to these WML commands unless specified otherwise. When the hotkey is pressed the event will be fired/filtered at the current mouse position.<br />
<br />
'''Note:''' Due to limitations in portable devices where there are no scroll bars for context menus, there is a hard-coded limit of 7 custom WML menu items. If you really need to have more than 7 menu items, try combining some of them in a submenu. {{DevFeature1.13|0}} This limitation is being removed in a [http://forums.wesnoth.org/viewtopic.php?p=572554#p572554 future version] of Wesnoth.<br />
<br />
* '''id''': the unique id for this menu item. If a menu item with this id already exists, it allows you to set specific changes to that item.<br />
* '''description''': the in-game text that will appear for this item in the menu.<br />
* '''image''': the image to display next to this item.<br />
* '''needs_select''': if ''yes'' (default ''no''), then the latest select event (see [[EventWML]]) that triggered before this menu item was chosen will be transmitted over the network before this menu item action will be. This only has any effect in networked multiplayer, and is intended to allow more elaborate menu item behaviour there without causing out of sync errors. If you don't know what this means, just leave it. {{DevFeature1.13|6}} ''needs_select=yes'' is deprecated, consider using manual variable syncing with [sync_variable].<br />
* '''synced''' {{DevFeature1.13|1}}: if ''no'' (default ''yes'') the command handler will only be run on the client that invoked the menu item; this means that changing the gamestate in a command handler of a menu item with ''synced=no'' will cause OOS<br />
* '''use_hotkey''': if ''no'' (default ''yes''), then the user cannot assign hotkeys to this menu item. If ''only'', the menu item is only accessible via hotkeys, not via right-click context; you can use this in combination with [default_hotkey] if you want custom hotkeys in your campaign/mp. <br />
* '''[show_if]''': If present, the menu item will only be available if the conditional statement (see [[ConditionalActionsWML#Condition_Tags|ConditionalActionsWML]]) within evaluates to true. When this is evaluated, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked, so it's possible to for example only enable the option on empty hexes or on a particular unit.<br />
* '''[filter_location]''': contains a location filter similar to the one found inside Single Unit Filters (see [[FilterWML]]). The menu item will only be available on matching locations.<br />
* '''[default_hotkey]''': contains a hotkey WML to specify what hotkey to assign to this, '''if the user has no hotkey assigned to this yet'''. (Unlike the rest of a menu item definition, modifying this tag has no effect on the game; it is only effective when initially defining a menu item.) Hotkey WML matches the format in the preferences file and contains the following keys:<br />
** '''key''': a string that contains the key to assign to this.<br />
** '''alt''', '''shift''', '''cmd'''(apple only), '''ctrl''': boolean values.<br />
** '''repeat_on_hold''' {{DevFeature1.13|12}}: if ''yes'' (default ''no''), holding the hotkey will repeat the action continuously, unless it blocks input with something like '''[message]'''. Due to a bug, versions older than 1.13.12 always repeat the action, with no way to disable it.<br />
* '''[command]''': contains the WML actions to be executed when the menu item is selected. Again, the WML variables ''$x1'' and ''$y1'' will point to the location on which the context menu was invoked on.<br />
** '''delayed_variable_substitution ''' (boolean yes|no, default: yes): If no, forces a variable substitution run onto the wml included in this [command] block. Use this, if you want variables which are to substitute to get the values they have at execution time of the event where this set_menu_item appears. Other than that, they get the values they have at invocation time of the menu item.<br />
<br />
== [clear_menu_item] ==<br />
<br />
Removes a menu item from the scenario.<br />
Normally menu items are, including all their defining wml, automatically carried over between scenarios. This tag prevents this. (The behavior is comparable to set_variable/clear_variable).<br />
* '''id''': (string): id of the menu item to clear. Can be a comma-separated list.<br />
<br />
== Other interface tags ==<br />
<br />
The following tags are also action tags:<br />
<br />
=== [change_theme] ===<br />
<br />
{{DevFeature1.13|8}}<br />
<br />
Change the current interface theme.<br />
<br />
* '''theme''': The ID of the new theme. Use <code>theme=</code> (empty key) to switch back to the theme that the player has selected in Preferences. On <b>1.14.2</b> and later it is also possible to omit the key entirely to achieve the same effect (on previous versions this will crash the Lua engine).<br />
<br />
=== [item] ===<br />
Makes a graphical item appear on a certain hex. Note this only places the graphics for an item. It does not make the item do anything. Use a moveto event to make moving onto the item do something. <tt>''('''Hint:''' There are a number of predefined items that are used in various campaigns that you can make use of. You can find [http://www.wesnoth.org/macro-reference.xhtml#file:items.cfg a list of them] if you look into the items.cfg file in the wesnoth install directory (under /data/core/macros).)''</tt><br />
* '''x''', '''y''': the location to place the item. (only for [event][item]: full [[StandardLocationFilter|SLF]] support)<br />
* '''image''': the image (in ''images/'' as .png) to place on the hex. This image is aligned with the top-left of the hex (which is 72 pixels wide and 72 pixels tall). It is drawn underneath units. ''('''Hint:''' If using an image smaller than 72x72, then it might be useful to [[ImagePathFunctions#Blit_Function|BLIT]] the image onto <tt>misc/blank-hex.png</tt> (a blank 72x72 image).)''<br />
* '''halo''': an image to place centered on the hex. It is drawn on top of units. Use this instead of ''image'' if the image is bigger than the hex or if you want to animate an image (https://github.com/wesnoth/wesnoth/issues/1219).<br />
* '''name''' an id that can be used to remove the item.<br />
''Example (where the integer after the colon is the duration of each frame or square bracket expansion as per AnimationWML is used): halo=scenery/fire1.png:100,scenery/fire2.png:100,scenery/fire3.png:100,scenery/fire4.png:100,scenery/fire5.png:100,scenery/fire6.png:100,scenery/fire7.png:100,scenery/fire8.png:100''<br />
or equivalently (requires Wesnoth 1.11.2+):<br />
''halo=scenery/fire[1~8].png:100''<br />
* '''team_name''': name of the team for which the item is to be displayed (hidden for others). For multiple teams just put all the names in one string, for example separated by commas. {{DevFeature1.15|0}} In 1.14 the '''[side]team_name''' attribute was expected to be a substring of this '''team_name'''. In 1.15 both are expected to be comma-separated lists of names and the item is visible if the lists intersect. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])<br />
* '''visible_in_fog''': whether the item should be visible through fog or not. Default yes.<br />
* '''redraw''': (boolean yes|no, default: yes): If no, disables implicit calls to [[InterfaceActionsWML#.5Bredraw.5D|[redraw]]] when placing the items.<br />
* '''[filter_team]''': {{DevFeature1.15|0}} A [[StandardSideFilter]]. Set '''team_name''' to the union of all '''[side]team_name''' attributes of all sides that match the SSF. ([[https://github.com/wesnoth/wesnoth/pull/3533|#3533]])<br />
* {{DevFeature1.15|0}} If both '''team_name''' and '''[filter_team]''' are set, '''team_name''' is ignored.<br />
<br />
=== [remove_item] ===<br />
Removes any graphical items on a given hex.<br />
* [[StandardLocationFilter]]: the hexes to remove items off<br />
* '''image''': if specified, only removes the given image item (This image name must include any [[ImagePathFunctions|image path functions]] appended to the original image name.)<br />
* '''name''': removes an item with a previously defined name.<br />
''Note: The filtering on this tag is not what a normal person would expect. Filtering on the item's halo key or name key will most likely fail. This should be fixed some day, but for now see https://github.com/wesnoth/wesnoth/issues/4689 For now, use the SLF and/or image key.''<br />
<br />
=== [print] ===<br />
Displays a message across the screen. The message will disappear after a certain time.<br />
* '''text''': (translatable) the text to display.<br />
* '''size''': (default=12) the pointsize of the font to use<br />
* '''duration''': (default=50) the length of time to display the text for. This is measured in the number of 'frames'. A frame in Wesnoth is usually displayed for around 30ms.<br />
* '''red''', '''green''', '''blue''': (default=0,0,0) the color to display the text in. Values vary from 0-255. {{DevFeature1.13|x}} Use of red, green, blue is now deprecated; use color=0,0,0 instead.<br />
<br />
=== [move_unit_fake] ===<br />
Moves an image of a unit along a certain path on the map. The path does not need to be a continuous list of adjacent hexes, so for example only the start and end points can be given, in which case the straightest line between those points will be calculated and used.<br />
* '''type''': the type of the unit whose image to use<br />
* '''x''': a comma-separated list of x locations to move along<br />
* '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)<br />
* '''side''': the side of the fake unit, used for team-coloring the fake unit<br />
* '''gender''': the gender of the fake unit. Example: gender=female<br />
* '''variation''': the variation of the fake unit. Example: variation=undead<br />
* '''image_mods''': [[ImagePathFunctions|image path functions]] sequence to be applied on the fake unit.<br />
* '''force_scroll''': Whether to scroll the map or not even when [[#.5Block_view.5D|[lock_view]]] is in effect or ''Follow Unit Actions'' is disabled in ''Advanced Preferences''. Defaults to ''yes'' starting with version '''1.11.6'''; the attribute did not exist in previous versions and this action behaved as if ''no'' was passed instead.<br />
<br />
=== [move_units_fake] ===<br />
moves multiple images of units along paths on the map. These units are moved in lockstep.<br />
* '''force_scroll''': {{DevFeature1.15|0}} Has the same meaning as in [move_unit_fake] but a different default.<br />
* '''[fake_unit]''': A fake unit to move<br />
** '''type''': the type of unit whose image to use<br />
** '''x''': a comma-separated list of x locations to move along<br />
** '''y''': a comma-separated list of y locations to move along (x and y values are matched pairs)<br />
** '''side''': the side of the fake unit, used for team-coloring the fake unit<br />
** '''skip_steps''': the number of steps to skip before this unit starts moving<br />
<br />
=== [hide_unit] ===<br />
Temporarily prevents the engine from displaying the given unit. The unit does not become invisible, as it would be with the '''[hides]''' ability; it is still the same plain unit, but without an image. Useful in conjunction with '''[move_unit_fake]''': to move a leader unit into position on-screen. Until 1.8 each '''[hide_unit]''' tag only hides one unit.<br />
* [[StandardUnitFilter]]: All matching units will be hidden<br />
<br />
=== [unhide_unit] ===<br />
Stops the currently hidden units from being hidden.<br />
* [[StandardUnitFilter]]: Only the matching units will be unhidden<br />
<br />
=== [lock_view] ===<br />
Locks gamemap view scrolling for human players, so they cannot scroll the gamemap view until it is unlocked. WML or Lua actions such as '''[scroll_to]''' will continue to work normally, as they ignore this restriction; the locked/unlocked state is preserved when saving the current game.<br />
<br />
This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.<br />
<br />
{{DevFeature1.13|8}} This now also blocks the player from zooming the gamemap view. WML or Lua zoom will continue to work normally.<br />
<br />
=== [unlock_view] ===<br />
Unlocks gamemap view scrolling for human players.<br />
<br />
=== [scroll] ===<br />
Scroll a certain number of pixels in a given direction. Useful for earthquake/shaking effects.<br />
* '''x''', '''y''': the number of pixels to scroll along the x and y axis<br />
* '''side''': the side or sides for which this should happen. By default, the [scroll] happens for everyone.<br />
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll] happens for everyone.<br />
<br />
=== [scroll_to] ===<br />
Scroll to a given hex<br />
* [[StandardLocationFilter]], do not use a [filter_location] sub-tag. If more than one location matches the filter, only the first matching location will be used.<br />
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.<br />
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').<br />
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex being scrolled to (defaults to ''no'').<br />
* '''side''': the side or sides for which this should happen. By default, the [scroll_to] happens for everyone.<br />
* '''[filter_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to] happens for everyone.<br />
<br />
=== [scroll_to_unit] ===<br />
Scroll to a given unit<br />
* [[StandardUnitFilter]]<br />
* '''check_fogged''': whether to scroll even to locations covered in fog or shroud. Possible values ''yes'' (don't scroll to fog) and ''no'' (scroll even to fog), with ''no'' as the default.<br />
* '''immediate''': whether to instantly warp to the target hex regardless of the scroll speed setting in Preferences (defaults to ''no'').<br />
* '''highlight''': {{DevFeature1.13|5}} Whether to highlight the hex the unit is on (defaults to ''no'').<br />
* '''for_side''': the side or sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.<br />
* '''[for_side]''': a [[StandardSideFilter]] to select the sides for which this should happen. By default, the [scroll_to_unit] happens for everyone.<br />
<br />
=== [select_unit] ===<br />
Selects a given unit.<br />
* [[StandardUnitFilter]]: The first unit found will be selected.<br />
* '''fire_event''': whether a ''select'' event should be triggered or not (def. ''no''). (Note that select events aren't multiplayer save.)<br />
* '''highlight''': whether the unit's current hex should be highlighted (def. ''yes'').<br />
<br />
=== [sound]===<br />
Plays a sound<br />
* '''name''': the filename of the sound to play (in ''sounds/'' as .wav or .ogg). This can be a comma-separated list, from which one sound will be chosen randomly.<br />
* '''repeat''': repeats the sound for a specified additional number of times (default=0)<br />
<br />
=== [sound_source] ===<br />
Creates a sound source. "Sound sources" is a general name for a mechanism which makes possible for map elements to emit sounds according to some rules, where "map elements" can be specific locations or terrain types. For now, only sound sources tied to locations are supported.<br />
* '''id''': a unique identification key of the sound source<br />
* '''sounds''': a list of comma separated, randomly played sounds associated with the sound source<br />
* '''delay''': a numerical value (in milliseconds) of the minimal delay between two playbacks of the source's sound if the source remains visible on the screen; if one scrolls out and back in, the source will be considered as ready to play<br />
* '''chance''': a percentage (a value from 0 to 100) describing the chance of the source being activated every second after the delay has passed or when the source's location appears on the screen (note that it cannot play more than one file at the same time)<br />
* '''check_fogged''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are fogged<br />
* '''check_shrouded''': possible values ''yes'' and ''no'' - ''yes'' means the source will not play if its locations are shrouded<br />
* '''x,y''': similar to x,y as found in a [[StandardLocationFilter]], these are the locations associated with the sound source<br />
* '''fade_range''' (default = 3): distance in hexes that determines a "circular" area around the one specified by '''full_range''' where sound volume fades out linearly<br />
* '''full_range''' (default = 14): distance in hexes that determines a "circular" area where source plays with full volume, relative to screen center<br />
* '''loop''': number of times a sound sample should be looped if it stays visible. -1 means infinite (~65000)<br />
<br />
=== [story] ===<br />
{{DevFeature1.13|8}}<br />
<br />
Shows the story screen.<br />
* '''title''': Default title used if a part does not specify one β unlike the intro storyscreen, the scenario name is not used as a default title.<br />
* '''[part]''': As [[IntroWML]].<br />
<br />
=== [remove_sound_source] ===<br />
Removes a previously defined sound source.<br />
* '''id''': the identification key of the sound source to remove<br />
<br />
=== [music]===<br />
Switches to playing different music<br />
* '''name''': the filename of the music to play (in ''music/'' as .ogg)<br />
* see [[MusicListWML]] for the correct syntax<br />
===[volume]===<br />
Changes the game volume to a percent of the preferences volume for the game being played. Values can go from 0 to 100: <br />
* '''music''': Changes the music volume.<br />
* '''sound''': Changes the sound volume.<br />
=== [color_adjust]===<br />
Tints the color of the screen.<br />
* '''red''', '''green''', '''blue''': values from -255 to 255, the amount to tint by for each color<br />
=== [delay] ===<br />
Pauses the game.<br />
* '''time''': the time to pause in milliseconds<br />
* '''accelerate ''' (boolean yes|no, default no): {{DevFeature1.13|0}} whether the delay is affected by acceleration. When [delay] is used to make an animation, this should be set to yes so that your animation matches the ones generated by the game.<br />
<br />
=== [redraw] ===<br />
Redraws the screen (this normally isn't done during events, although some of the other interface actions cause the screen or parts of it to be redrawn).<br />
* '''clear_shroud''' (boolean yes|no, default no): If yes, clears fog and shroud around existing units. Useful if you, for example, spawn friendly units in the middle of an event and want the shroud to update accordingly (otherwise units that spawn inside fog would remain invisible for the duration of the event, since the fog would not automatically get cleared around them).<br />
* '''[[StandardSideFilter]]''': the sides for which to recalculate fog and shroud.<br />
* '''side''': If used (forces clear_shroud=yes), clears fog and shroud for that side.<br />
<br />
=== [unit_overlay] ===<br />
Sets an image that will be drawn over a particular unit, and follow it around<br />
* [[StandardUnitFilter]]: All matching units will get the overlay (do not use [filter])<br />
* '''image''': the image to place on the unit<br />
<br />
=== [remove_unit_overlay] ===<br />
Removes a particular overlayed image from a unit<br />
* [[StandardUnitFilter]]: The overlay will get removed from all matching units (do not use [filter])<br />
* '''image''': the image to remove from the unit<br />
Using remove_object is also possible, see https://github.com/wesnoth/wesnoth/commit/26c2f941f2bcdd89528481e114c0375ad2a46271<br />
<br />
=== [animate_unit] ===<br />
Uses an animation of a unit to animate it on screen (if the unit has the corresponding animation).<br />
* '''flag''': The key to find the custom animation in the unit description (see the '''[extra_anim]''' description in [[AnimationWML]]). Standard animations can be triggered with the following keywords: ''leading recruited standing idling levelout levelin healing healed poisoned movement defend attack death victory pre_teleport post_teleport''<br />
* '''[filter]''' with a [[StandardUnitFilter]] as argument, see [[FilterWML]]. By default, the unit at the event location will be animated. You can use this tag to choose any other unit to animate.<br />
* '''[primary_attack]''': If this tag is not present, the filter for animation will be triggered with no attack. If it is here, all attacks from the unit will be filtered, and a matching one will be used to filter the animation. Takes a weapon filter as argument, see [[FilterWML]].<br />
* '''[secondary_attack]''': Similar to '''[primary_attack]'''. May be needed to trigger a defense animation correctly, if there are more than one animations available for the defending unit.<br />
* '''hits''': yes/no/hit/miss/kill: which according variation of a attack/defense animation shall be chosen (required)<br />
* '''text''': a text to hover during the animation <br />
* '''male_text''', '''female_text''': {{DevFeature1.13|2}} (translatable) gender-specific versions of the above<br />
* '''red''': red value for the text color (0-255)<br />
* '''green''': green value for the text color<br />
* '''blue''': blue value for the text color<br />
* '''with_bars''': yes/no: whether to display the status bars during the animation (e.g. the hitpoint bar)<br />
* '''[animate]''': a sub block with the same syntax as '''[animate_unit]''' except that the '''[filter]''' block is mandatory to find the unit. This block will find and animate another unit simultaneously.<br />
* '''[facing]''': a [[StandardLocationFilter]] specifying what direction the unit should be facing when animated<br />
<br />
=== [label] ===<br />
Places a label on the map.<br />
* '''x''', '''y''': the location of the label. {{DevFeature1.13|1}} (only for [event][label]: full [[StandardLocationFilter|SLF]] support)<br />
* '''text''': what the label should say<br />
* '''team_name''': if specified, the label will only be visible to the given team.<br />
* '''color''': color of the label. The format is r,g,b; r, g and b are numbers between 0 and 255.<br />
* '''visible_in_fog''': whether the label should be visible through fog or not. Default yes.<br />
* '''visible_in_shroud''': whether the label should be visible through shroud or not. Default no.<br />
* '''immutable''': whether this label is protected from being removed or changed by players. Default yes.<br />
* '''category''': the Show/Hide Labels dialog allows showing/hiding all labels of a given category by toggling a checkbox.<br />
* '''tooltip''': A tooltip visible when mouseovering the hex the label is on<br />
* '''side''': the number of the side that placed the label. Can be 0 for labels placed by WML.<br />
<br />
=== [floating_text]===<br />
Floats text (similar to the damage and healing numbers) on the given locations.<br />
* [[StandardLocationFilter]]: the text will be floated on all matching locations simultaneously.<br />
* '''text''': the text to display.<br />
<br />
The default text color is <span style="color: #6b8cff;">'''#6b8cff'''</span>. To change the color, use [[#Formatting|Pango markup]]. For example:<br />
<br />
<pre><br />
# Float some golden yellow text at 20,20.<br />
[floating_text]<br />
x,y=20,20<br />
text="<span color='#cccc33'>" + _ "Your text here" + "</span>"<br />
[/floating_text]<br />
</pre><br />
<br />
=== [deprecated_message] ===<br />
Shows a deprecated message in the message area, this feature is only intended to be used to warn about deprecated macros in mainline. The message is not translatable.<br />
* '''message''': the message to show.<br />
* '''level''': {{DevFeature1.13|10}} The deprecation level, a number from 1 to 3.<br />
* '''what''': {{DevFeature1.13|10}} The name of the thing being deprecated. Use this instead of '''message''' if possible; a stock message will be generated from it. Use '''message''' only if more information is required; it will be appended to the stock message. This should not be translatable<br />
* '''version''': {{DevFeature1.13|10}} For deprecation levels 2 and 3, this indicates the version in which the feature could be removed. It does ''not'' indicate the version in which it became deprecated. <br />
<br />
The meanings of the deprecation levels are as follows:<br />
<br />
# Deprecated, but will only be removed if absolutely necessary. The '''version''' key is ignored.<br />
# It will be removed no earlier than a specified version.<br />
# It will be removed in the next stable version<br />
# It has already been removed, leaving just a stub to inform users of how to update their code.<br />
<br />
Note that as of 1.13.11, deprecation messages show only in the log, not in the chat message area. The '''message''' can be translatable, but does not need to be.<br />
<br />
=== [wml_message] ===<br />
Outputs a message to Wesnoth's console output. Intended for campaign designers to output silent text to the console, without annoying the player; then, that text might contain information useful for later bug-reporting. The log domain for it is '''wml''', and the '''debug/dbg''' log level is available for use with the '''logger''' attribute. Depending on the current log level ('''error''' by default), which may be changed with the in-game :log command, or the --log-<level>=wml command line switch, the messages are echoed to the in-game chat.<br />
* '''message''': the message to show.<br />
* '''logger''': the Wesnoth engine output logger that should catch the text; this might be 'err' (the errors log level), 'warn'/'wrn' (the warnings log level) or anything else (the information log level). Not all information will be displayed depending on the log level chosen when starting Wesnoth.<br />
<br />
Note: As of 1.9.4/1.9.5 (r48805) the following "loggers" should work: If in [wml_message]: err/error, warn/wrn/warning, debug/dbg; using the :log command: Only the long forms error, warning, info and debug (this part gathered by trying rather than source inspecting). The long forms are most likely also the only ones working when starting wesnoth with --log-<level>=wml.<br />
For log level warning or error (as during normal play), only wml_messages with logger error or warning display (for both). With logger info or debug, additionally wml_messages with logger info or debug display (for both).<br />
<br />
=== [test_condition] ===<br />
<br />
{{DevFeature1.13|2}}<br />
<br />
Evaluates the contained conditional tags. If they evaluate to the expected value, it prints out a message to the console explaining which part of the condition caused this result in a way similar to [wml_message]. This can be used if your conditional test is failing and you're not sure why.<br />
<br />
* '''result''': Whether you expect the conditions to fail or succeed. If no (the default), a message will be printed if the conditional tags fail. If yes, a message will instead be printed if the conditional tags pass.<br />
* '''logger''': Same as for [wml_message]. Defaults to "warning".<br />
<br />
=== [open_help] ===<br />
Opens the in-game help.<br />
* '''topic''': the id of the topic to open<br />
=== [show_objectives] ===<br />
refreshes the objectives defined by [objectives] and its [show_if] tags, and displays them. (It is also called whenever the user explicitly asks for the objectives; this matters only if the tag was overridden by a [[LuaWML#register_wml_action|Lua]] script.)<br />
* '''side''': the side to show the objectives. If not set, all sides are used.<br />
* '''[[StandardSideFilter]]''' tags and keys: Tag affects the matching sides instead of just all or the one given by the integer value of the side= key.<br />
<br />
=== [chat] ===<br />
Displays a message in the chat area, not visible for observers. Alternative unconditionally visible for everyone: [[LuaWML:Display#wesnoth.message]]. {{DevFeature1.13|9}} can be visible for observers.<br />
* '''speaker''': (default="WML") A string for the name of the sender of the message.<br />
* '''message''': The message that should be displayed.<br />
* '''observable''' (boolean yes|no, default yes): {{DevFeature1.13|9}} Whether the message is displayed for observers.<br />
* '''[[StandardSideFilter]]''' tags and keys as argument; if the same client controls multiple sides that match, then the message will only be displayed once.<br />
<br />
=== [zoom] ===<br />
<br />
{{DevFeature1.13|8}}<br />
<br />
Changes the zoom level of the map.<br />
<br />
* '''factor''': The new zoom factor<br />
* '''relative''': If yes, zoom relative to current zoom level. Otherwise, set the absolute zoom level. Default no.<br />
<br />
== Useful Macros ==<br />
There are some predefined macros that you find useful for interface actions. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].<br />
* '''{HIGHLIGHT_UNIT}''' Highlight a unit on the map. Use this to show important units<br />
* '''{HIGHLIGHT_IMAGE}''' Places and highlights an image on the map. Use this to show important items or locations<br />
* '''{SET_IMAGE}''' Places an image on the map which has no other function.<br />
* '''{QUAKE <soundfile>}''' Creates a tremor-like screenshake and plays <soundfile>. For example, '''{QUAKE (rumble.ogg)}'''.<br />
* '''{FLASH_WHITE}''' Flash the screen white momentarily. You can also replace WHITE with RED, BLUE or GREEN for a different colour.<br />
<br />
== See Also ==<br />
* [[DirectActionsWML]]<br />
* [[InternalActionsWML]]<br />
* [[EventWML]]<br />
* [[ReferenceWML]]<br />
<br />
<br />
[[Category: WML Reference]]<br />
[[Category: ActionsWML]]</div>Doofus-01https://wiki.wesnoth.org/index.php?title=DataURI&diff=59851DataURI2018-07-04T13:06:08Z<p>Doofus-01: adding instructions for using Firefox to get Data URI</p>
<hr />
<div>Instead of referring to an image included in an add-on, an image path may also contain the image directly as a [https://en.wikipedia.org/wiki/Data_URI_scheme Data URI (wikipedia)]. This can be useful for add-on icons in the [[PblWML]] (which may otherwise only contain core images) or for single-file scenarios.<br />
<br />
Beyond these cases, Data URIs are less useful, as they are larger than the images themselves, and clutter up the files that include them.<br />
<br />
== Format ==<br />
<br />
A Data URI appears as follows: <code>data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==</code><br />
<br />
It can be split into the following sections:<br />
<code>data</code> <code>image/png;base64</code> <code>iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==</code><br />
<br />
==== Schema ====<br />
The <code>data:</code> part specifies that this is a Data URI.<br />
<br />
==== Mime type ====<br />
The <code>image/png</code> part specifies that this is a PNG image. Also supported is <code>image/jpeg</code>.<br />
<br />
===== base64 =====<br />
Technically part of the mime type, this specifies that the image data is encoded using Base64.<br />
<br />
==== Data ====<br />
The random-looking characters following the comma are the actual image data.<br />
<br />
== Creating a Data URI ==<br />
Wesnoth does not yet support generating a Data URI for you, but there are alternatives.<br />
<br />
=== Websites ===<br />
There are a large number of Data URI generator websites. Googling for [https://google.com/search?q=data+uri+generator data uri generator] will find them.<br /><br />
<br />
You may be able to directly copy the Data URI with your browser, without going to some strange website. The following works in Firefox 60.1:<br />
* open ''image.png'' directly with browser<br />
* open Inspector (Tools > Web Developer > Inspector)<br />
* mouse over the ''src=file://...'' data, then select Copy > Image Data-URL<br />
You now have the Data URI in your clipboard<br />
<br />
=== Manually ===<br />
Creating a data URI by hand can be accomplished by taking your image, Base64-encoding it and formatting it as shown above.</div>Doofus-01https://wiki.wesnoth.org/index.php?title=Git_for_Wesnoth_Crash_Course&diff=58653Git for Wesnoth Crash Course2017-07-03T03:06:21Z<p>Doofus-01: gitref.org link does not currently lead to a useful web-page, I have tried to provide an alternative resource.</p>
<hr />
<div>== Foreword ==<br />
<br />
'''''(An essay by, mainly, iceiceice.)'''''<br />
<br />
This page is intended for new <cite>Battle for Wesnoth</cite> developers and contributors who have never used '''[//wiki.wesnoth.org/WesnothRepository <cite>Git</cite>]''' before. I'm hoping that it will be written <em>mainly</em> by newbies like myself who have just figured out enough about <cite>Git</cite> to use it successfully, and therefore not include a bunch of information superfluous for that purpose. At the time that I am writing this, I have managed to write about eight GitHub pull requests and get them merged into <cite>Wesnoth</cite>, and I hope you will be able to do the same after reading this.<br />
<br />
== What is <cite>Git</cite>? ==<br />
<br />
The most effective '''"absolute beginner" introduction to <cite>Git</cite>''' that I found when I started is here: '''[http://gitref.org <cite>gitref.org</cite>]'''. - ''(Note: this gitref.org link seems to have died. Another resource, that is only slightly less introductory-level, is '''[https://git-scm.com/book/en/v2 <cite>Pro-Git Book</cite>]'''. Don't worry about reading the whole thing though.)''<br />
<br />
I suggest that you <strong>read this through</strong>, beginning to end, navigating through the pages by using the red arrows at the bottom of each page. You can skip the part about ''"stashing"'', but you should carefully read and understand the parts about:<br />
<br />
* '''''cloning''''' a ''repository'';<br />
* '''''checking out''''' a ''branch'', creating a '''new branch''', and '''merging branches''';<br />
* '''''adding''''' and '''''committing changes''''';<br />
* viewing '''''diffs''''' to make sure you understand exactly what you are committing;<br />
* '''''resetting''''' your repository state in case you make a mistake and need to undo some steps, and using "'''<kbd>git log</kbd>'''" and "'''<kbd>git reflog</kbd>'''" to assist with this; and<br />
* moving content between local and remote repositories, with "'''<kbd>push</kbd>'''" and "'''<kbd>pull</kbd>'''".<br />
<br />
== Setting up our workflow for <cite>Wesnoth</cite> in <cite>Git</cite> ==<br />
<br />
It is common when reading about <cite>Git</cite> to see the terms '''''"upstream"''''' and '''''"downstream"'''''. This is often confusing at the beginning -- after all, information is usually flowing in both directions; sometimes, you are getting code from the <cite>Wesnoth</cite> repository, and sometimes you are sending code to it. Which way is up and which is down?<br />
<br />
Analogously to a river, ''downstream'' is the direction toward which most information flows. Any user that simply wants to build <cite>Wesnoth</cite> from source, and not make any changes to it, will generally do so by cloning or pulling from <https://github.com/wesnoth/wesnoth>. So [https://github.com/wesnoth/wesnoth <code>wesnoth/wesnoth</code>] (the main <cite>Wesnoth</cite> repository) is the <dfn>upstream</dfn> repository, and the users are <dfn>downstream</dfn>.<br />
<br />
If you are a developer, you will '''''fork''''' the upstream repository and edit the source code, and -- hopefully, with work, eventually -- get your edits pulled into the upstream repository. That is the '''<dfn>development cycle</dfn>''', and contributing changes back to upstream is what makes you a developer. <br />
<br />
In this guide, we are going to assume that you will use GitHub in addition to the official <cite>Git</cite> command-line program, because GitHub has many useful tools to offer and makes some things nicely easy, especially when comparing a topic branch to the master branch and seeing diffs in a somewhat more advanced interface, and when making ''pull requests''. Technically, this means that you will have '''<em>two</em> repositories''' -- your <dfn>local repository</dfn> on your computer, and a ''fork'' of the <code>wesnoth/wesnoth</code> repository, on GitHub.<br />
<br />
The first step of becoming a <cite>Wesnoth</cite> developer is to set up these two repositories. Follow the instructions in [https://help.github.com/articles/fork-a-repo/ GitHub's "<cite>Fork A Repo</cite>" help article], which may be summarized as follows:<br />
<br />
<ol><br />
<li><p>'''''Fork''''' the <code>wesnoth/wesnoth</code> repository, using the GitHub website.</p></li><br />
<li><p>'''''Clone''''' the fork onto your computer, with the command "<kbd>git clone</kbd>".</p></li><br />
<li><p>Configure '''<dfn>remotes</dfn>''' (''remote'' repositories that are essentially bookmarked).</p><br />
<p>GitHub's <cite>Fork A Repo</cite> article describes how to set the <code>wesnoth/wesnoth</code> repository as a remote with the name "<code>upstream</code>". Because you cloned from your fork, the fork is automatically set as a remote with the name "<code>origin</code>". You can see your remotes with the command "<kbd>git remote -v</kbd>".</p><br />
<p>You might find this naming scheme confusing, given that the name "<code>origin</code>" might also aptly describe the <code>wesnoth/wesnoth</code> repository. So it might be good to rename that remote to "<code>fork</code>" (with the command "<kbd>git remote rename origin fork</kbd>"). But if you do that, note that much of the GitHub help pages will assume the name "<code>origin</code>".</p></li><br />
</ol><br />
<br />
Additionally, we ask that you configure <cite>Git</cite> to use your full real name or a consistent alias, per the instructions in [https://help.github.com/articles/setting-your-username-in-git/ GitHub's "<cite>Setting your username in Git</cite>" help article], so that we can associate a concrete person with every commit merged into <cite>Wesnoth</cite>. Your GitHub profile should also display the same name.<br />
<br />
== The basic workflow ==<br />
<br />
Here's the picture we now have, with 3 repositories:<br />
<br />
<br />
<br />
upstream<br />
<br />
<br />
origin (fork)<br />
<br />
<br />
local<br />
<br />
<br />
<br />
There are four basic steps in the development cycle, which are as follows:<br />
<br />
# ensuring that your local repository is '''up-to-date''' with the upstream repository;<br />
# creating a '''topic branch''' for your changes;<br />
# '''committing''' your changes to the topic branch and '''pushing''' them to your fork; and<br />
# filing a GitHub '''pull request''', having that request granted, then finally cleaning up.<br />
<br />
=== Keeping your local repository up-to-date ===<br />
<br />
In this step, you will make sure your local <code>master</code> branch is up-to-date with the most recent development changes before beginning work. <br />
<br />
First make sure you are on your <code>master</code> branch:<br />
<br />
git checkout master<br />
git status<br />
<br />
Now, pull the upstream <code>master</code> branch to your local repository:<br />
<br />
<br />
upstream<br />
|<br />
|<br />
| origin (fork)<br />
| <br />
v <br />
local<br />
<br />
<br />
<br />
git pull upstream master<br />
<br />
At this point your local master is up to date. While you are at it, you might as well update your fork as well:<br />
<br />
<br />
<br />
upstream<br />
<br />
<br />
.--> origin (fork)<br />
/ <br />
/ <br />
local --'<br />
<br />
<br />
git push origin master<br />
<br />
At this point, the <code>master</code> branch should be the same in all three repositories.<br />
<br />
=== Creating a topic branch ===<br />
<br />
In this guide, we will <strong><em>never</em> make any changes directly on the <code>master</code> branch</strong>, and will <strong><em>only</em> make code changes on a topic branch</strong>, so regardless of which repository you look at, the <code>master</code> branch should be the same, and <cite>Git</cite> will be comparing your work against the upstream <code>master</code> branch.<br />
<br />
Now you are ready to create a new '''[https://git-scm.com/book/en/Git-Branching-Branching-Workflows#Topic-Branches <dfn>topic branch</dfn>]''', which will hold your work for this patch. We are on the <code>master</code> branch, as running "<kbd>git status</kbd>" will confirm. Create your new topic branch -- named, in this example, "<code>new-feature</code>" -- by running the following command:<br />
<br />
git checkout -b new-feature<br />
<br />
As shown in the <cite>gitref.org</cite> guide, you could also have done this with the following commands:<br />
<br />
git branch new-feature<br />
git checkout new-feature<br />
<br />
Given that you were on the <code>master</code> branch when you created the <code>new-feature</code> topic branch, the <code>new-feature</code> branch will branch off from the ''tip'' of your current <code>master</code> branch, which is best, to avoid conflicts when the <code>new-feature</code> branch is eventually merged upstream.<br />
<br />
=== Committing your changes and pushing to your fork ===<br />
<br />
Now, you will make your changes to <cite>Wesnoth</cite>, test them, and commit them to your local repository, with the commands "<kbd>git add</kbd>" and "<kbd>git commit</kbd>", as shown in the <cite>gitref.org</cite> guide.<br />
<br />
==== Committing guidelines ====<br />
<br />
<ol><br />
<li><br />
<h5 style="font-size: larger"><strong>Write good commit messages</strong></h5><br />
<br />
<p><strong>A commit message should fully explain what changes were made in the commit, and <em>why</em> those changes were made</strong>. A good commit message is structured like an email message.</p><br />
<br />
<p>The first line, which <strong>summarizes</strong> the commit, has special importance -- to quote the <cite>[[DeveloperGuide]]</cite> page, <q cite="http://wiki.wesnoth.org/DeveloperGuide#Commit_messages">This is the first (and often the only) line someone using browsing tools will see</q>. It should ideally be at most 80 characters (TODO: inconsistent with current policy), and is like the subject line of an email message. Commit message summary lines should be written in the imperative present tense, e.g., "Add field to <var>some_class</var>, with accessor methods", "Fix <var>other_class</var>'s constructor", "Delete unnecessary #include", etc.</p><br />
<br />
<p>After the summary line, there must be a blank line, after which comes the '''commit message body''', which is analogous to the body of an email message.</p><br />
<br />
<p>'''Optimally''', a commit's message would be so clearly and comprehensively explanatory that it would answer any questions that anyone might have about the commit, now, the next day, or years into the future -- which is especially important because the author of the commit likely won't always be around to answer those questions.</p><br />
<br />
<p>See also [//wiki.wesnoth.org/DeveloperGuide#Commit_messages the <cite>DeveloperGuide</cite> page's "Commit messages" section] and [https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines the official Git book's "Commit Guidelines" section].</p><br />
</li><br />
<li><br />
<h5 style="font-size: larger"><strong>Make appropriately sized commits</strong></h5><br />
<br />
<p>Each commit should correspond to a <strong>single logical step</strong> in your programming task. The commits constitute the project's development history; people will look at your commits to try to figure out how we got to where we are today, and may at some point need to undo the changes made in some of your commits to fix a future issue.</p><br />
<br />
<p><strong>If you find it difficult to write a succinct commit message that fully explain what changes were made in the commit, and why those changes were made, then the commit is insufficiently fine-grained -- too large and too complicated.</strong> Another guideline is, you should at least think about committing almost every time you compile (depending on your habits).</p><br />
<br />
<p>On the other hand, you shouldn't make a commit for every line of code typed. <strong>If it would never make sense to revert the repository's code to its current state from a future state, you probably shouldn't commit.</strong> For example, if you define a field of an object, but it has no accessors and no way to be used in code, it would never make sense to revert to that time in the repository's history, so those changes should be saved together in a single commit. If you have a commit that merely adjusts whitespace in a file, that should be squashed in with another commit, according to current (2015-07-25) policy.</p><br />
<br />
<p><strong>It is better to commit more often than less often</strong>, because, before you submit your changes to upstream, you will have the opportunity to edit your commit history, and <strong>it is much easier to ''squash'' commits together than to split up an overly-large commit</strong>.</p><br />
<br />
<p>See also [//wiki.wesnoth.org/DeveloperGuide#Commits the <cite>DeveloperGuide</cite> page's "Commits" section].</p><br />
</li><br />
<li><br />
<h5 style="font-size: larger"><strong>Keep the change-logs, release notes, and credits up-to-date</strong></h5><br />
<br />
<p>After committing your changes, add an entry in the '''<code>changelog</code>''' document, and commit it with the message "Update changelog".</p><br />
<br />
<p>We also have a '''<code>players_changelog</code>''' document, which should contain only changes that most players are likely to notice, and be less technical than the main, technical <code>changelog</code>.</p><br />
<br />
<p>There is also a '''<code>RELEASE_NOTES</code>''' document, which basically is copied into the next <cite>Wesnoth</cite> release's release announcement post in the forums, so if there is a new feature or bug fix that should be advertised, add that to <code>RELEASE_NOTES</code>.</p><br />
<br />
<p>If this is your first commit, the development team will ask you to add an appropriate note about yourself in the '''credits document''', '''<code>data/about.cfg</code>'''.</p><br />
<br />
<p>See also [//wiki.wesnoth.org/DeveloperGuide#Changelogs_and_release_notes the <cite>DeveloperGuide</cite> page's "Changelogs and release notes" section].</p><br />
</li><br />
</ol><br />
<br />
Finally, when your branch is ready, push it to your fork.<br />
<br />
<br />
<br />
upstream<br />
<br />
<br />
.--> origin (fork)<br />
/<br />
/<br />
local --'<br />
<br />
<br />
git push origin new-feature<br />
<br />
<br />
Now, if you navigate to your fork's page on GitHub, you should see a message such as "recently pushed branch new-feature (3 minutes ago)". Click "Compare" to compare it against the <code>master</code> branch. You should now see a list of the commits you made on the <code>new-feature</code> branch, and color-highlighted diffs of the files you changed. You can click through the commits in order to see each of the changes you made and understand how your project progressed -- this is exactly what the development team will do when they review your pull request.<br />
<br />
In the GitHub interface, you can always see a list of branches by clicking on "branches" in the line near the middle of the page that looks like the following:<br />
<br />
10,000+ commits 27 branches 248 releases 85 contributors<br />
<br />
You can also look at a specific branch using the "Branch" menu below that line, and you can compare branches using the green "Compare" button to the left of the "Branch" menu.<br />
<br />
=== Cleaning up your branch ===<br />
<br />
Before filing your pull request, if, looking at the diffs and the history (the list of commits) for your topic branch, you saw anything confusing or not quite right, now is your opportunity to change it.<br />
<br />
From the <cite>gitref.org</cite> guide, you should know how to add more commits, and you should know that you can use "<kbd>reset</kbd>" to go back in time and redo things.<br />
<br />
"'''<kbd>reset</kbd>'''" is especially good if your last commit was too big and you want to break it up into a series of smaller commits -- the command "<kbd>git reset "@~"</kbd>" will leave your working directory the same, but jump back in time one commit and unstage all of those changes, so you can add a smaller subset of the files, commit those, then add the others, etc.<br />
<br />
More generally, you can use "'''<kbd>git reflog</kbd>'''" to see how to reset back over any number of commits or other <cite>Git</cite> operations. <br />
<br />
You can also use "'''<kbd>git commit --amend</kbd>'''" to edit the commit message of the most recent commit.<br />
<br />
There are several more advanced cleanup features available with <cite>Git</cite>, but we'll defer any further discussion of them.<br />
<br />
Every time you make changes, you should to push them to your fork to keep it up-to-date. If you rewrote your commit history, then the push would be rejected, because the commit histories won't match. Therefore, to push a rewritten history, you must '''''<strong>force push</strong>''''', which will -- <strong>this is a potentially dangerous operation!</strong> -- discard the old commit history and replace it with the new history:<br />
<br />
<br />
<br />
upstream<br />
<br />
<br />
.--> origin (fork)<br />
/<br />
/<br />
local --'<br />
<br />
<br />
git push --force origin new-feature<br />
<br />
You can and should do this throughout your development if you want to look at the diffs of your changes as you work -- after all, the <cite>Wesnoth</cite> code-base is vast and it is easy to forget exactly where you are in your project. You can and should keep cleaning up in this way until you are satisfied with the result. Doing this, your GitHub fork ends up being rather like a personal Web-based IDE plug-in or extension to help you with development.<br />
<br />
=== Filing a pull request ===<br />
<br />
When you finish working on your feature or bug fix, select your topic branch on your fork (with the "Branch" menu), and click the green button to file a pull request. By default, the target of the pull request -- the repository and branch into which it is requesting that your changes be pulled -- will be "<samp>wesnoth:master</samp>", the <code>master</code> branch of the main <cite>Wesnoth</cite> repository.<br />
<br />
The message that you enter for the pull request should become the commit message of the merge operation performed in the upstream repository if the pull request is granted. (Note: if you are granting someone's PR through the GitHub Web interface, please ensure that this happens.)<br />
<br />
If you fixed a bug, you should say, e.g., "Fixed bug #5678" in the pull-request message, which should automatically link to [https://gna.org/bugs/index.php?group=wesnoth&set=custom&report_id=101&status_id=1&chunksz=150&boxoptionwanted=1 our Gna! bug tracker].<br />
<br />
If you want more information, you could read [https://help.github.com/articles/creating-a-pull-request/ GitHub's "<cite>Creating a pull request</cite>" help article].<br />
<br />
<br />
<br />
upstream <-.<br />
\<br />
\<br />
'- origin (fork)<br />
<br />
<br />
local <br />
<br />
<br />
<br />
You should then see your pull request in [https://github.com/wesnoth/wesnoth/pulls the main <cite>Wesnoth</cite> repository's "pull requests" page].<br />
<br />
At the time of writing this, we also have configured [https://travis-ci.org Travis CI], a [https://en.wikipedia.org/wiki/Continuous_integration continuous integration] system, to automatically try to compile <cite>Wesnoth</cite> with your changes, to make sure that it still works before your pull request is granted. However, it is not mandatory for the Travis build to complete successfully for the pull request to be granted. Additionally, you may still make changes to your pull request by pushing more changes to your topic branch in your fork, after which Travis <em>should</em> try to compile the updated topic branch. You can even still force push to erase the content of the topic branch (on which the pull request is based) and replace it with new content -- however, you shouldn't file a pull request for a topic branch until you are ready for it to be merged.<br />
<br />
Now, wait for a member of the development team to review your pull request. You can often find someone on the development [//wiki.wesnoth.org/Support#IRC IRC] channel, <code>#wesnoth-dev</code>. Additionally, developers may comment directly on your pull request with questions, so you should check it periodically.<br />
<br />
=== Cleaning up at the end ===<br />
<br />
Congratulations, a developer granted your pull request! Now it's time to clean up and update your local repository.<br />
<br />
On the GitHub page for your pull request, you should now see a button with the option "delete this branch". Since the content of new-feature is now merged into master, this branch no longer needs to exist as you won't work on it anymore, and future work will go onto a different branch. So you should delete it, which will delete the branch on *origin*, your github-associated repo.<br />
<br />
Since master has now changed and we want master to be synced up, you should now do step 1 again:<br />
<br />
<br />
upstream<br />
|<br />
|<br />
| origin (fork)<br />
| <br />
v <br />
local<br />
<br />
<br />
git checkout master<br />
git pull upstream master<br />
<br />
At this point git will understand that new-feature has been merged into master, so when you ask to delete this branch from local as well, it will do it:<br />
<br />
git branch -d new-feature<br />
<br />
If you do these steps out of order, i.e. try to delete the branch before before syncing master, it will make a warning "Are you sure? You have unmerged changes on this branch..." etc.<br />
<br />
Finally, sync master on the origin as well:<br />
<br />
<br />
<br />
upstream<br />
<br />
<br />
origin (fork)<br />
/--> <br />
--/ <br />
local <br />
<br />
<br />
git push origin master<br />
<br />
That's the end of the development cycle, and now you can begin on your next patch. Note that throughout the cycle, information only flowed counter-clockwise:<br />
<br />
<br />
upstream<br />
| <--\<br />
| \--<br />
| origin (fork)<br />
| /--> <br />
v --/ <br />
local<br />
<br />
<br />
If for some reason you find yourself doing something where information is flowing the other way, that is a good sign that something is going wrong, at least as far as this guide is concerned! (The exception is the steps in which we set up our repos -- don't overthink this.)<br />
<br />
<br />
== Advanced / Alternative workflows ==<br />
<br />
You can use pull requests as described above whether you have commit access or not -- if you have commit access, then you can click to accept your own pull requests.<br />
<br />
However, if you have commit access, you may prefer not to use github / pull requests at all, and instead to push directly to wesnoth:master. You can still use topic branches to hold your work, and merge them to your local master using git merge, then use 'git push upstream master' to push them to the main wesnoth repo. <br />
<br />
If you are lazy, you might even skip making a topic branch and just commit to local master, although IMO this can make things more confusing if you get a merge conflict later.<br />
<br />
Either way, afaik the vast majority of wesnoth developers prefer to push directly to wesnoth:master.<br />
<br />
An extreme option appropriate for small changes is to skip the local repo as well, and simply commit changes directly from the github web interface. This might be appropriate for example if you forgot to commit a changelog entry in an earlier patch, or are simply changing some numbers used as parameters somewhere. Obviously if you change source code this way, you should make certain that everything still compiles immediately after! (Note: Don't actually do that.)<br />
<br />
== The ultimate cleanup power tool: git rebase ==<br />
<br />
Using things in the gitref guide, you can see how to use reset to undo mistakes you made by backing up and trying again, and for small commits that is probably fine. However, if you have a large and complicated series of changes, the better way to do this is using git rebase. Using git rebase in interactive mode, you can rewrite history by<br />
<br />
* reordering your commits<br />
* discarding unwanted commits<br />
* squashing commits together<br />
* editing the content changes represented by an individual commit<br />
* editing the commit message<br />
<br />
For our purposes, we assume you are working on a topic branch, and then you will only need to use the form<br />
<br />
git rebase -i master<br />
<br />
You can see some documentation for using this command here: https://help.github.com/articles/interactive-rebase<br />
<br />
Using 'git rebase', you can make your commit history very *clean* -- instead of the history saying "I tried a bunch of things, undid some of them, tried some other things, and found something I liked", your commit history can basically be "I took the simplest and most logical route to the solution that was finally the best". When you review your commits, instead of feeling like a nasty blood-and-elbow-grease engineering project, it should feel like folding a perfect origami crane, to the extent possible ;)<br />
<br />
But to reiterate, this has a purpose. <br />
# Other devs need to be able to understand the history.<br />
# It should be possible to jump back in time by checking out one of your commits and find ourselves in a sensible state when we do so.<br />
# If something breaks or some feature become incompatible, it should be possible to roll back only a piece of the implementation of your feature without removing the whole thing.<br />
<br />
If you want to use rebase to cleanup your history, it is important to do it *before* it is pulled into wesnoth, as once that happens it is basically no longer possible. If we rewrite history in the main wesnoth repo, then afterwards whenever any dev tries to 'git pull upstream master', their git will give them strange merge errors, stemming from the incompatible history, and then they will become nervous, jump on irc and exclaim some variation of "omg wtf bbq". So except in extreme circumstances, we will never rebase the main wesnoth master, and for the same reason, we will never use "git push --force upstream master". That's why if you want to do these things, it is important to do them on your *fork* before it makes it onto master.<br />
<br />
If you feel like it, you might read this, which is a historical email between early users / developers of git, in which Linus Torvalds explains about shared history of repos and when it is appropriate to use git rebase. <br />
<br />
http://www.mail-archive.com/dri-devel@lists.sourceforge.net/msg39091.html<br />
<br />
When you become comfortable with git rebase -i, it will greatly improve your workflow, as you will know that you can easily review and revise commit messages later, and easily reorder and squash commits. Typically I will now commit every single time I compile, and even if it is a commit which e.g. fixes a compile time error, or for some other reason I know it will be squashed in somewhere else, I give it the commit message "fixup", as a note to myself to mark it thusly in the first git rebase pass. (Actually, while writing this I have just learned about the --autosquash feature of git rebase which takes this idea further, good stuff there.)<br />
<br />
Note that unlike Linus and github, in this guide we aren't thinking about your github fork repo as public -- we prefer to think of it as your personal private IDE/tool as I described earlier. If other wesnoth devs are cloning it or pulling your topic branches, we assume you will work it out with them. With that caveat the philosophies expressed on github and by Linus should generally apply to the wesnoth project as well.<br />
<br />
=== Solving merge conflicts with git rebase ===<br />
<br />
Github version: https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request<br />
<br />
Suppose that you modify a file in the same place as someone else, and their change gets merged before yours. If git can't figure out how to merge, then someone will have to fix it. This could be done by whoever is merging the new content into master, but if you don't have commit access then that person is not you. One way that *you* could fix it is to resync your master to get the new changes locally, and then rebase your topic branch so that your changes are applied *after* the most recent changes.<br />
<br />
git rebase master<br />
<br />
To understand what is happening, we should understand a bit more about how git works. Intuitively, git is all about "snapshots" of the project content. Every commit represents a snapshot, and you can look at this snapshot by checking out the commit. However git does not store each snapshot separately -- instead git defines the snapshots in terms of one another, and stores only the diffs. When you rebase your topic branch onto master, this will also update the "point of departure" where your branch was created, so that in the history, it will depart from the current head of master with the most recent changes. (Obviously, if you don't sync master until you are done working, then this subtlety to 'git rebase' is irrelevant.) <br />
<br />
If merging your branch with the current master would create a conflict, then when git rebase gets to the commit that creates the conflict, it will get confused when it tries to apply that diff, stop, tell you about the problem, and ask you to resolve it -- you can open up the offending file and go to the point where the conflict is happening, and git will leave a note for you of the content it is having trouble with. The note will look similar to what happens in the gitref guide here, under "merge conflicts".<br />
<br />
http://gitref.org/branching/#merge<br />
<br />
You just have to remove the note, make the file look like it should to make everything compatible, and type<br />
<br />
git add .<br />
git rebase --continue<br />
<br />
Then the rebasing process will continue, and at the end your branch should be compatible with master and ready to be merged in.<br />
<br />
You can read more about this aspect of git rebase here if you like, although most likely you won't actually need more than we just talked about for wesnoth development. <br />
<br />
http://git-scm.com/book/en/Git-Branching-Rebasing<br />
<br />
That's all for this guide, have fun hacking on wesnoth!<br />
<br />
== Addendum ==<br />
The following section contains commands with the -f / --force options. Those are usually used to rewrite history, which is fine for your own fork but disallowed for upstream. Do not use them on the main repository.<br />
<br />
<br />
If a command goes awry, you can go to "git reflog", find the point just before you typed it, and reset --hard to that commit, and it should be like the bad thing never happened<br />
<br />
revert every file in the repo to look like it did at the HEAD commit (last successful sync)<br />
git reset --hard HEAD<br />
<br />
get a clean slate by syncing with upstream<br />
git fetch upstream<br />
git checkout -B master upstream/master<br />
git push --force origin master<br />
if this errors, try again after<br />
git reset --hard HEAD<br />
<br />
<br />
undo n commits, split/squash and apply again<br />
git reset HEAD~n<br />
git add -p<br />
git commit<br />
git push -f<br />
<br />
You can also push from one βrefβ to a different one: <br />
$ git push <remote> <from>:<to><br />
<br />
completely overwrite branch b with a (from a to b)<br />
git push -f origin a:b<br />
<br />
<br />
<br />
<br />
before any commit:<br />
<br />
* if the diff shows an invisible change in the first line - stop! Fix the file encoding back to UTF8 without BOM.<br />
<br />
* don't forget the changelog (and, for visible changes, the players_changelog)<br />
<br />
* try to keep the summary at 50 characters or less, maximum 72<br />
<br />
== See Also ==<br />
<br />
* [[Project#Developers]]<br />
<br />
[[Category:Development]]</div>Doofus-01