Difference between revisions of "OptionWML"

From The Battle for Wesnoth Wiki
(The [options] tag: Add anchors that can be linked to)
(The [options] tag: Remove outdated note)
Line 2: Line 2:
 
== The [options] tag ==
 
== The [options] tag ==
  
This tag might be a child of an [era], [multiplayer] or [modification] tag. {{DevFeature1.13|1}} [options] are now also recognised in a [campaign] tag. Its subtags describe a set of configuration options which are displayed to the user as widgets on the game creation screen, and the entered values are translated into WML variables in the game. Please note that the option variables are initialized in a prestart event, therefore they can't be used before the first prestart event. The created variables' name is identical to the option's id they're attached to, so option ids must be unique across all kinds of options.
+
This tag might be a child of an [[EraWML|[era]]], [[ScenarioWML#The_.5Bmultiplayer.5D_tag|[multiplayer]]] or [[ModificationWML|[modification]]] tag. {{DevFeature1.13|1}} [options] are now also recognised in a [[CampaignWML|[campaign]]] tag. Its subtags describe a set of configuration options which are displayed to the user as widgets on the game creation screen, and the entered values are translated into WML variables in the game. The created variables' name is identical to the option's id they're attached to, so option IDs must be valid variable names and unique across all kinds of options. A good idea might be to prefix the addon ID.
  
 
The following subtags are recognized for '''[options]''':
 
The following subtags are recognized for '''[options]''':

Revision as of 11:53, 13 August 2024

[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 [options] tag

This tag might be a child of an [era], [multiplayer] or [modification] tag. (Version 1.13.1 and later only) [options] are now also recognised in a [campaign] tag. Its subtags describe a set of configuration options which are displayed to the user as widgets on the game creation screen, and the entered values are translated into WML variables in the game. The created variables' name is identical to the option's id they're attached to, so option IDs must be valid variable names and unique across all kinds of options. A good idea might be to prefix the addon ID.

The following subtags are recognized for [options]:

  • [checkbox]: registers a checkbox.
    • id: the id for this option. Must be unique.
    • default: boolean value, determines if the box should be checked initially. Default no.
    • name: a string to be displayed next to the widget.
    • description: the tooltip text to be displayed when the user hovers the mouse over the widget.
  • [combo]: registers a combo box. (Version 1.13.6 and later only) This was renamed to [choice].
    • id: the id for this option. Must be unique.
    • default: the default value of the widget.
    • name: a string to be displayed next to the widget.
    • description: the tooltip text to be displayed when the user hovers the mouse over the widget.
    • [item]: adds an item to the combo box.
      • name: the displayed name of this item.
      • value: the value the widget will take when this item is selected.
  • [entry]: registers a text entry.
    • id: the id for this option. Must be unique.
    • default: the string initially displayed by the widget.
    • name: a string to be displayed next to the widget.
    • description: the tooltip text to be displayed when the user hovers the mouse over the widget.
  • [slider]: registers an integer slider.
    • id: the id for this option. Must be unique.
    • default: an integer value. The slider will be positioned at this value by default.
    • min: the minimal value the slider can take.
    • max: the maximal value the slider can take.
    • step: the difference between adjacent values the slider can take. Default 1.
    • name: a string to be displayed next to the widget.
    • description: the tooltip text to be displayed when the user hovers the mouse over the widget.

in 1.12 those variables are inserted as preload event that set these variables. (Version 1.13.0 and later only) These variables are now inserted directly in the scenario without events, this means you can also use those variables in scenariolevel [lua] tags and prestart events.

For [campaign] use in 1.12, options need to be inserted in the first [scenario]. Options for campaigns no longer work inside the first [scenario] and must now be placed directly inside [campaign].