AddonsWML

[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;

Creating add-ons in WML

An add-on is defined by a directory structure, there is no tag called [addon]. The directory must contain a _main.cfg, and the name of the directory is treated as its id. There are different rules for add-ons that define a custom core, which are described in CoreWML and ignored for the purposes of this page.

The description of a downloaded add-on is found in _info.cfg, the data for a locally authored add-on is in _server.pbl (see PblWML).

An add-on typically contains other files, see for example AddonStructure or BuildingCampaignsTheCampaignFile.

Which add-ons are active during gameplay

To help prevent clashes between add-ons, when starting a scenario the engine only loads the active add-ons. An add-on is active if one or more "add-on modules" is used by the game. If a game does not use any add-on module from your add-on, then your add-on won't be parsed at all. On the other hand, if the game uses any add-on module from your add-on, then your entire add-on will be parsed, relying on preprocessor defines to exclude parts that aren't relevant to the add-on module that is to be loaded.

Several toplevel tags are used to define an "add-on module":

• [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 add-on module

Notably, that list doesn't contain the [units] tag. For example, a multiplayer scenario which allows the player to choose any era but has scripted events that spawn Ageless Era units needs to activate those units' add-on by loading a resource from it.

Common Tags and Keys

The following tags and keys are supported in most types of addon modules:

• id: The addon module's unique ID. It must be unique across all addon module types, so for example there cannot be a [scenario] and a [multiplayer] with the same 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: (translatable) The visible name for the addon module, shown in the campaign selection or multiplayer game creation menu. (Not supported for [resource] since it is never visible anywhere.)
• description: (translatable) The detailed description for the addon module, shown in the campaign selection or multiplayer game creation menu. (Also not supported for [resource], nor for [scenario] or [test].)
• define=SYMBOL When this addon module 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 addon modules. Besides the addon module 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 addon modules), you can use binary-path-independent paths for the textdomain and any assets that are used in the addon module 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 module is active. See EventWML.
• [lua] - Lua code that will be run when the addon module 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].
  • Note: This tag may not be supported in [resource], [scenario], or [test].
• [options]: Custom options. See OptionWML for details. Note: This may not be supported in [resource], [scenario], or [test].
• [load_resource]: Indicates a resource to load when this addon module 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.
  • [advancement] : (Version 1.19.5 and later only) If a list of [advancement] is here, replace all [advancement] in unit type(s).
  • [male] : (Version 1.19.5 and later only) If exist and unit type use this tag, key and tags previously listed contained in this tag will apply to male unit type(s) only.
  • [female] : (Version 1.19.5 and later only) Same what [male] but for [female] sub_tags in unit type(s).
  • [variation] : (Version 1.19.5 and later only) If variation_id matches with variation_id of a [variation] in unit type(s), same what [male] or [female] tags.

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.