BinaryPathWML

[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 toplevel [binary_path] tag

This tag is used to recognize more than one directory as containing images, music, and sound. It only has one key:

• path: a directory. When an image is not found it the normal images directory, it will be looked for in path/images. Similarly,
  • music will be looked for in path/music, and
  • sound in path/sound.
  • (Version 1.15.3 and later only) For [scenario]map_file and [replace_map]map_file, the file will be looked for in path/maps.

Notice that path is still relative to the main Wesnoth directory.

[binary_path] should only be used where necessary. For example a multiplayer era should have its [binary_path] inside an #ifdef MULTIPLAYER instead of outside it in order to avoid possible clashes with single-player content.

Resolving paths against the binary path

When resolving an asset path to locate the actual file on disk, the game goes through all defined [binary_path] tags in reverse order of definition. For each binary path, it checks in the following directories, in order:

• <user data dir>/<binary path>/<type>/<asset path>
• <game data dir>/<binary path>/<type>/<asset path>
• <user data dir>/<binary path>/<asset path>
• <game data dir>/<binary path>/<asset path>

The <user data dir> is the directory containing the add-ons folder, while the <game data dir> is the directory containing the game data itself – it contains folders sounds, images, and data, at minimum. The <binary path> is the path defined in [binary_path] while the <asset path> is the path being resolved. Finally, <type> is the type of asset being resolved, usually one of images, sounds, music, or maps. Lua can define additional types as well.

Assuming you have loaded the default core, the penultimate binary path to be checked in this process is data/core, meaning that built-in assets can be overridden by an add-on simply by creating a file with the same asset path in the add-on's binary path. This binary path is defined by a [binary_path] tag in <game data dir>/data/_main.cfg. It is expected that alternate cores would define a similar path.

The final binary path to be checked is the empty string, which means that if an asset is not found in any of the paths defined by [binary_path], then the game checks in the following four directories as a last resort:

• <user data dir>/<type>/<asset path>
• <game data dir>/<type>/<asset path>
• <user data dir>/<asset path>
• <game data dir>/<asset path>

This behaviour means that you can build what is called a "binary path independent path" by specifying the path relative to either the <user data dir> or the <game data dir>. These paths are used in contexts where there is no guarantee what the active binary path stack will be, such as AchievementsWML or the saved game cache.

Example

To enable the game to find images, sounds and music in the add-on MyAddOn:

[binary_path]
    path=data/add-ons/MyAddOn
[/binary_path]

When the game looks for an image units/humans/footman.png, it'll now be able to find and use the file MyAddOn/images/units/humans/footman.png.

See Also

• ReferenceWML