Difference between revisions of "AddonsWML"

From The Battle for Wesnoth Wiki
(Update addon_min_version documentation from EraWML)
(See Also: New section linking to other toplevel tags that may be relevant to an addon)
Line 37: Line 37:
 
** '''add_advancement''' : adds a (list of comma separated) unit type(s) to the possible advancements of this unit type.
 
** '''add_advancement''' : adds a (list of comma separated) unit type(s) to the possible advancements of this unit type.
 
** '''remove_advancement''' : removes a (list of comma separated) unit type(s) from the possible advancements of this unit type.
 
** '''remove_advancement''' : removes a (list of comma separated) unit type(s) from the possible advancements of this unit type.
 +
 +
== See Also ==
 +
 +
* [[BinaryPathWML]] - Toplevel tag to define search paths for assets.
 +
* [[UnitsWML]] - Toplevel tag to define units and unit-related data.
 +
* [[TerrainWML]] - Toplevel tag to define terrain types.
 +
* [[TerrainGraphicsWML]] - Toplevel tag to define how terrain is drawn.

Revision as of 17:42, 26 March 2023

[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, credits_group, criteria;

D:

damage, 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, found_item, for, foreach, 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, 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, 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;

Several toplevel tags are used to define an "addon", which is something like a module that the game loads as needed. There are several different types of addons, but they all share some common keys.

Note: The concept of "addon" described on this page is slightly different from an add-on downloaded through the Add-ons Manager – such an add-on can define multiple addons.

All of the following toplevel tags define an addon:

  • [era] - A multiplayer era
  • [campaign] - A campaign, either single-player or multiplayer
  • [scenario] - A campaign scenario
  • [multiplayer] - A multiplayer scenario
  • [test] - A test or demo scenario
  • [modification] - A modification that can be selected in the campaign or multiplayer menu
  • [resource] - A resource that can be requested by any other type of addon

Common Tags and Keys

The following tags and keys are supported in all types of addons:

  • id: The addon's unique ID.
  • addon_min_version: The minimum version of your add-on with which this content is backwards compatible. Compared with the version string given in PblWML. If addon_min_version is not explicitly specified, it means compatible only with the same version. Clients in multiplayer must have add-on versions agreeing with the addon_min_versions of each others' content in order to play, and will be prompted to update otherwise.
  • name: The visible name for the addon. (Not supported for [resource] since it is never visible anywhere.)
  • description: The detailed description for the addon. (Also not supported for [resource].)
  • define=SYMBOL When this addon is active, the preprocessor symbol SYMBOL will be defined. See ifdef for how this can be used to isolate parts of the file from other addons. Besides the addon tag, only the tags [textdomain] and [binary_path] (see BinaryPathWML) should go outside of #ifdef SYMBOL. This symbol will be defined before any .cfg is preprocessed. Note: If for some reason you don't want to place your [binary_path] outside your #ifdef SYMBOL (perhaps it's causing conflicts with other addons), you can use binary-path-independent paths for the textdomain and any assets that are used in the addon tag. This looks like icon=data/add-ons/whatever/something.png – essentially, any path beginning with data/.
  • [event] - An event handler that will be registered when the addon is active. See EventWML.
  • [lua] - Lua code that will be run when the addon is loaded, before the preload event is fired. See LuaWML.
  • [ai]: Defines an AI algorithm that can be selected by players at the join game screen. See here for details. This is not used in single-player. (Note: This is not the place to define faction-specific AI parameters in an era. For that, place the [ai] tag in [multiplayer_side].)
  • [options]: Custom options. See OptionWML for details. Note: This may not be supported in [resource].
  • [load_resource]: Indicates a resource to load when this addon is loaded.
    • id: The ID of the resource.
  • [modify_unit_type] (Version 1.15.2 and later only): Changes a unit type while this modification is active. The supported attributes are:
    • type : the id of the unit type to change.
    • set_experience : changes the unit type's max experience.
    • set_cost : changes the unit type's recruit cost.
    • set_advances_to : changes the unit type's advancements.
    • add_advancement : adds a (list of comma separated) unit type(s) to the possible advancements of this unit type.
    • remove_advancement : removes a (list of comma separated) unit type(s) from the possible advancements of this unit type.

See Also