SideWML

[edit]WML Tags

A: abilities, about, achievement, achievement_group, add_ai_behavior, advanced_preference, advancefrom, advancement, advances, affect_adjacent, ai, allied_with, allow_end_turn, allow_extra_recruit, allow_recruit, allow_undo, and, animate, animate_unit, animation, aspect, attack (replay, weapon), attack_anim, attacks (special, stats), avoid;

B: base_unit, background_layer, berserk, binary_path, break, brush;

C: campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, checkbox, choice, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_palette, color_range, command (action, replay), continue, core, credits_group, criteria;

D: damage, damage_type, death, deaths, default, defend, defends, defense, delay, deprecated_message, destination, difficulty, disable, disallow_end_turn, disallow_extra_recruit, disallow_recruit, do, do_command, drains, draw_weapon_anim;

E: editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry (credits, options), era, event, experimental_filter_ability, experimental_filter_ability_active, experimental_filter_specials, extra_anim;

F: facet, facing, fake_unit, false, feedback, female, filter (concept, event), filter_adjacent, filter_adjacent_location, filter_attack, filter_attacker, filter_base_value, filter_condition, filter_defender, filter_enemy, filter_location, filter_opponent, filter_own, filter_owner, filter_radius, filter_recall, filter_second, filter_second_attack, filter_self, filter_side, filter_student, filter_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, fonts, for, foreach, found_item, frame;

G: game_config, get_global_variable, goal, gold, gold_carryover;

H: harm_unit, has_ally, has_attack, has_unit, has_achievement, have_location, have_unit, heal_on_hit, heal_unit, healed_anim, healing_anim, heals, hide_help, hide_unit, hides;

I: idle_anim, if (action, animation, intro), illuminates, image (intro, terrain), init_side, insert_tag, inspect, item, item_group;

J: jamming_costs, join;

K: kill, killed;

L: label, language, leader, leader_goal, leadership, leading_anim, levelin_anim, levelout_anim, lift_fog, limit, literal, load_resource, locale, lock_view, lua;

M: male, menu_item, message, micro_ai, missile_frame, modification, modifications, modify_ai, modify_side, modify_turns, modify_unit, modify_unit_type, move, move_unit, move_unit_fake, move_units_fake, movement_anim, movement costs, movetype, multiplayer, multiplayer_side, music;

N: not, note;

O: object, objective, objectives, on_undo, open_help, option, options, or;

P: part, petrifies, petrify, place_shroud, plague, poison, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, progress_achievement, put_to_recall_list;

R: race, random_placement, recall (action, replay), recalls, recruit, recruit_anim, recruiting_anim, recruits, redraw, regenerate, remove_event, remove_item, remove_object, remove_shroud, remove_sound_source, remove_time_area, remove_trait, remove_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resolution, resource, return, role, rule;

S: save, scenario, screen_fade, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_achievement, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, objective, set_menu_item), show_objectives, side, skirmisher, slider, slow, snapshot, sound, sound_source, source (replay, teleport), special_note, specials, split, stage, standing_anim, statistics, status, store_gold, store_items, store_locations, store_map_dimensions, store_reachable_locations, store_relative_direction, store_side, store_starting_location, store_time_of_day, store_turns, store_unit, store_unit_defense, store_unit_defense_on, store_unit_type, store_unit_type_ids, store_villages, story, swarm, sub_achievement, switch, sync_variable;

T: target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, test_do_attack_by_id, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel;

U: unhide_unit, unit (action, scenario), unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;

V: value, variable, variables, variant, variation, victory_anim, village, vision_costs, volume;

W: while, wml_message, wml_schema;

Z: zoom;

The term "side" refers to a single player in the Wesnoth turn order, which can be controlled by either a human or an AI. Every scenario must have at least one side. There is no hard limit on the number of sides a single scenario can have.

Usually the number of sides in a scenario is fixed. However, the Lua function wesnoth.sides.create can be used to dynamically add new sides if required.

Sides in a scenario are described by the [side] tag, which recognizes the following keys and tags.

Common Keys

These keys are always permitted in a [side] tag.

• side: a number. The leader of this side is placed on the tile represented by this number (see BuildingMaps). When defining sides, they must be defined in order since the side number is checked against the number of sides seen so far. Currently, the Multiplayer server rejects entering a scenario with more than 9 sides, even if those extra sides are AI sides. (Version 1.13.2 and later only) The server doesn't limit the number of sides anymore.

• controller (required): how moves for this side should be inputted.
  • ai: the Wesnoth AI makes this side's moves.
  • human: a player controls this side's moves.
  • null: the side doesn't get a turn to move. Events that would usually occur on the side's turn will not take place. This includes healing (ability, villages and rest) and side turn events.
  • a number: gives this side's control to a side with side matching the number (multiplayer only). (Version 1.13.2 and later only) using a number is deprecated, use previous_save_id= instead.
  • Note: in multiplayer, when reading the side's data with [store_side], the value may differ between clients and using it for conditional actions may cause OOS. Discussion in https://r.wesnoth.org/p643343

• type: if present, the keys describing a unit (including type) which will begin on the side's keep will be the remainder of the [side] tag, See SingleUnitWML. Note that if the keys x, y are included, the leader will begin there regardless of keep location. If this side has a recall list from a previous level, then the recall list will be searched for a leader (using canrecruit=yes) and if one is found it will be used instead of the one described in the [side] tag. Typical keys used for defining the leader unit are id, name and unrenamable=yes, see SingleUnitWML. The unit will automatically be set to be able to recruit.

• recruit: a list of unit types. At the beginning of the scenario, the side gains recruitment of these units. Units in the side recruit list can always be recruited by a leader on this side, in addition to any units in the individual leader's extra_recruit list. (Version 1.13.? and later only) in multiplayer, unless you specify faction=Custom, this will be overwritten by the recruit list from the faction.

• gold: the starting gold for this side. Default: 100. (If gold is carried over from a previous scenario, this value is the minimum starting gold.)

• income: the base income for this side. Default: 0. This is added to base_income, [game_config] to determine the side's base income. (see GameConfigWML).

• hidden: if 'yes', side is not shown in status table.

• fog: if 'yes', this side cannot see any tiles it is not within vision of, except at the start. Please note that the AI currently ignores the fog.

• fog_data: describes the area which this team has de-fogged, using the same format as shroud_data. (This is not particularly useful when defining a side, though, as the game will recalculate fog as turns begin and end.) It is used in saved games.

• [fog_override]: With keys x= and y=, this records the hexes that have been cleared (multiturn) with [lift_fog].

• shroud: if 'yes', this side cannot see any tiles it has not moved within sight of. Please note that the AI currently ignores the shroud. NOTE: with shroud=no, this team *ignores* shroud, so it is not possible to modify it using place_shroud and remove_shroud tags. If you want to do so, use "shroud=yes" and place_shroud/remove_shroud tags.

• shroud_data: describes the area which this team has de-shrouded. An example:

|
|00011111000

This would leave the first column on the map unaltered and would change the second column for 11 tiles. A '0' means: shrouded, '1' means unshrouded. You can either call an external file using {@filename} (see PreprocessorRef) or place the data in quotes. For making an external file see ShroudDataWML.

• persistent: whether the side exists in any other scenarios. If 'yes', then save_id (see below) is used to identify the side in other scenarios. Defaults to 'yes' for sides with a human controller, and 'no' for ai controlled sides.

• save_id: defaults to the leader's id if available, 'Unknown' otherwise. The ID of the side with respect to the previous and next scenarios. Used to carry over the side's recall list (including the side's leader), recruitment list, and starting gold from scenario to scenario. Also used for the side's displayed name in the victory gold-calculation dialog.

• previous_save_id: (Version 1.13.2 and later only) defaults to save_id. Only used in mp games, specially mp campaigns. This attribute specifies which user should play this side by default. For example if a side has previous_save_id="Konrad" then the side will be assigned to that player who played the side with the save_id="Konrad" in the previous level. If used in the first scenario, multiple sides with the same previous_save_id will be assigned to the same player.

• team_name: a non translatable string representing the team's description. Sides with the same team_name are allied. Default side. team_name is now a comma-separated list of teams that the side is on.

• user_team_name: a translatable string representing the team's description. This has no effect on alliances. Default team_name.

• current_player: a translatable string representing the player's or leader's name. Defaults to the leader's id; if the side's leader is a human player in multiplayer, the default is the player's username. (Version 1.13.0 and later only) This field is now always the player name (mp server nick) it impossible to change it with wml/lua. (Version 1.13.5 and later only) You can use side_name instead to specify the name for the side (which is then used in new turn dialogs, statisitc dialogs etc.)

• side_name: (Version 1.13.5 and later only) a translatable string representing the name of the side, used for example in the new turn dialog. Defaults to name if the side was inside a [scenario] and to the player's name if the side was inside a [multiplayer].

• color: May be either a numeric color index or a color name (e.g. 'blue', 'purple', 'orange', etc.). The numeric form is deprecated. The default list of numbers and corresponding colors can be found in data/core/team_colors.cfg. Can also be an inline color range (the rgb key from GameConfigWML#Color_Palettes).

• flag: a custom flag animation to use instead of the default one to mark captured villages. An automatic side-coloring is applied.
  • Example animation that has three frames and loops every 750ms: flag=misc/myflag-[1~3].png:750

• flag_icon: a custom flag icon to indicate the side playing in the statusbar (a size of 24x16 is recommended). An automatic side-coloring is applied.

• village_gold: the amount of gold given to this side per village it controls per turn. Default specified in village_income, [game_config] (GameConfigWML).

• village_support: the number of unit levels this side is able to support (does not pay upkeep on) per village it controls. Default specified in village_support, [game_config] (GameConfigWML).

• recall_cost: the amount of gold it costs to recall a unit. Default specified in recall_cost, [game_config] (GameConfigWML). (Version 1.15.0 and later only) Units are now recalled for AI sides even if the recall_cost is larger than the unit's worth (essentially its cost, plus potentially a bonus for experience points). In 1.14 and earlier, units were not recalled by the AI in this case even if this was the only recall/recruit action possible to the AI.

• share_maps: whether sides allied with this side see all terrains that this side sees, if they are on shroud. (Version 1.13.1 and later only) This has been deprecated in favor of share_vision (see below).

• share_view: whether sides allied with this side see the units that this side sees, if they are on FoW (fog). (Version 1.13.1 and later only) This has been deprecated in favor of share_vision (see below).

• share_vision: (Version 1.13.1 and later only) all/shroud/none. If all, both shroud and fog view will be shared by this side. If shroud, only shroud view will be shared. If none, the view is not shared.

• scroll_to_leader: optional. If 'no', scroll to the leader is not performed on the start of each turn. (default: yes)

• suppress_end_turn_confirmation: If "yes", then the player will not be asked to confirm ending their turn even if they have not done anything. This is provided for some (probably few) user-made scenarios in which players often skip their turns. (default: no)

• [ai]: if controller=ai, gives parameters to the AI. See AiWML.

• [village]: describes a village the side begins in control of.
  • x, y the location of the village. If the pair of coordinates is not a village or is duplicated in another [village] tag, behaviour is undefined. Recent game engine or wmllint should warn about these.

• [unit]: describes a unit which begins on the side. See SingleUnitWML. If the side has a recall list and the unit is not given a location, it will start on the recall list. Note that the side attribute under [unit] will be ignored, as the side will come from the side attribute of [side].

• [leader]: describes the leader for the side, basically same as [unit] except that canrecruit will default to yes and current position to the side starting location if not specified. (Version 1.17.17 and later only) Furthermore, if left out, the name and save_id attributes in [side] will be set to the name and id attributes in the first [leader] tag.

• defeat_condition: Specifies when a side is considered defeated this is checked for all sides, after every player action and at the beginning of every turn.
  • no_leader_left: (default) The side is considered defeated if it has no units with canrecruit=yes
  • no_units_left: The side is defeated as soon as it has no units left.
  • never: The side is never considered defeated.
  • always: The side is always considered defeated.

For the meaning and significance of defeated, see ScenarioWML#Scenario_End_Conditions

Multiplayer Keys

These keys are only permitted in a [side] tag for a [multiplayer] scenario.

• allow_player: if false then this side will not be allowed to be modified and will be hidden during game creation. False also prevents this side from being included in shuffle sides. Defaults to yes.

• disallow_observers: prevents observers from seeing this side turn. (default: no)

• disallow_shuffle: (Version 1.13.0 and later only) do not shuffle this side if the "shuffle sides" option is used. (Usually all playable sides are shuffled.) (default: no)

• chose_random: (Version 1.13.0 and later only) indicates if a side chose a random faction during creation

• controller_lock: if true then this side's controller ("Player/Type") modification is limited. It is bound to the controller attribute in SideWML.

• team_lock: if true then this side's team is not allowed to be modified.

• color_lock: if true then this side's color is not allowed to be modified.

• gold_lock: if true then this side's gold is not allowed to be modified.

• income_lock: if true then this side's income is not allowed to be modified.

• faction_lock: if true then this side's faction is not allowed to be modified.

• no_leader: if 'yes', prevents the engine from generating a leader from the multiplayer faction, basically an alias of leader_lock

• leader_lock: if true then this side's leader (type or gender) is not allowed to be modified. Note that if type= key is missing, leader_lock=yes means the side will have no leader.

• faction: if a valid faction id is provided then this side's faction will default to it in the game setup screen. (Version 1.13.? and later only) if this key isn't included in the [side] then a random faction will be chosen, and the side's recruit list set from the faction. To use a custom recruit list, you must also specify faction=Custom.

• faction_from_recruit: if true then this side will be locked to the faction that matches the recruits better.

N.B. the lock attributes use ScenarioWML force_lock_settings as their default value. I.e. if no value to lock was set, it will take force_lock_settings value.

See Also

• EraWML
• ScenarioWML
• ReferenceWML