Difference between revisions of "DescriptionWML"

From The Battle for Wesnoth Wiki
(→‎Description texts: A user was caught by a gotcha, so re-stressing a key point)
(Swap the order so the new format is documented first)
 
(8 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
{{WML Tags}}
 
{{WML Tags}}
 +
 +
== WML Format ==
 +
 +
{{DevFeature1.13|2}}
 +
 +
As of 1.13.2, the DescriptionWML format has changed to use WML tags. It goes in either a '''[difficulty]''' tag within '''[campaign]''' or an '''[option]''' tag within '''[message]''' and comprises the following attributes:
 +
 +
* '''default''': If yes, this item is the default selection (assuming no other items also have default=yes).
 +
* '''image''': Optional path to an image file to display.
 +
* '''label''': Text to display in the first text column.
 +
* '''description''': Text to display in the second text column.
 +
 
== Description texts ==
 
== Description texts ==
 +
 +
{{DevFeature1.15|1}} '''Support for the image-icon plus text format in this section has been removed. It is documented here only for the benefit of people who wish to port old add-ons to the new format, documented above.'''
  
 
A description is a part of the value of a menu attribute.
 
A description is a part of the value of a menu attribute.
−
It represents a single option in the difficulty selection menu for a campaign, which consists of an image (called the ''icon'') followed by text. When appropriate, the icon should use [[ImagePathFunctionWML]] to replace any magenta with a team color.
+
It represents a single option in the difficulty selection menu for a campaign, which consists of an image (called the ''icon'') followed by text. When appropriate, the icon should use [[ImagePathFunctions]] to replace any magenta with a team color.
  
 
The description tag uses a special format:
 
The description tag uses a special format:
Line 23: Line 37:
 
  ";" + "&" + "units/elves-wood/elvish-champion.png~TC(1,magenta)" + "=" + _"Champion" + "=" + _"(hardest)"
 
  ";" + "&" + "units/elves-wood/elvish-champion.png~TC(1,magenta)" + "=" + _"Champion" + "=" + _"(hardest)"
  
−
The utility macros (see [[UtilWML]]) '''{MENU_IMG_TXT ''icon'' ''text''}'''
+
The utility macros (see the [https://www.wesnoth.org/macro-reference.html#file:utils.cfg Macro Reference]) '''{MENU_IMG_TXT ''icon'' ''text''}'''
 
and '''{MENU_IMG_TXT2 ''icon'' ''text'' ''text-2''}'''
 
and '''{MENU_IMG_TXT2 ''icon'' ''text'' ''text-2''}'''
 
can be used to create descriptions more easily. The above example would become:
 
can be used to create descriptions more easily. The above example would become:
Line 31: Line 45:
 
  {MENU_IMG_TXT2 "units/elves-wood/elvish-champion.png~TC(1,magenta)" _"Champion" _"(hardest)"}
 
  {MENU_IMG_TXT2 "units/elves-wood/elvish-champion.png~TC(1,magenta)" _"Champion" _"(hardest)"}
  
−
----
+
====Alternative Description Implementation====
  
 
For still greater clarity, I have the following suggestion:
 
For still greater clarity, I have the following suggestion:
Line 63: Line 77:
 
  #enddef
 
  #enddef
  
−
You can then use a standard difficulty_descriptions tag that you will rarely need to alter:
+
'''Note:''' The above example assumes three difficulty levels, which gives six difficulty entries – three for the pictures and three for the text. If you have more or fewer than three difficulty levels, make sure that the last entry does ''not'' have a trailing plus sign and that all the others do. Note also that the first image description ''doesn't'' start with a semicolon, whereas the second and subsequent ones do. Finally, only the default difficulty entry is marked with a * character.
 +
 
 +
If you set up your difficulty strings in this way you can then use a standard difficulty_descriptions tag that you will rarely need to alter. Note that this string does ''not'' contain any plus signs. You have to have them in the difficulty ratings strings instead to avoid upsetting the Wesnoth preprocessor:
  
 
  difficulty_descriptions={EASY_IMAGE}{EASY_TEXT}{NORMAL_IMAGE}{NORMAL_TEXT}{HARD_IMAGE}{HARD_TEXT}
 
  difficulty_descriptions={EASY_IMAGE}{EASY_TEXT}{NORMAL_IMAGE}{NORMAL_TEXT}{HARD_IMAGE}{HARD_TEXT}
  
−
'''Note:''' The above example assumes three difficulty levels, which gives six difficulty entries - three for the pictures and three for the text. If you have more or fewer than three difficulty levels, make sure that the last entry does ''not'' have a trailing plus sign and that all the others do.
+
The only time you would need to alter this string is if you have more or fewer than three difficulty levels for your campaign.
  
 
[[User:Simons Mith|Simons Mith]] 20:16, 18 November 2011 (UTC)
 
[[User:Simons Mith|Simons Mith]] 20:16, 18 November 2011 (UTC)

Latest revision as of 00:01, 25 July 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, 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;

WML Format

(Version 1.13.2 and later only)

As of 1.13.2, the DescriptionWML format has changed to use WML tags. It goes in either a [difficulty] tag within [campaign] or an [option] tag within [message] and comprises the following attributes:

  • default: If yes, this item is the default selection (assuming no other items also have default=yes).
  • image: Optional path to an image file to display.
  • label: Text to display in the first text column.
  • description: Text to display in the second text column.

Description texts

(Version 1.15.1 and later only) Support for the image-icon plus text format in this section has been removed. It is documented here only for the benefit of people who wish to port old add-ons to the new format, documented above.

A description is a part of the value of a menu attribute. It represents a single option in the difficulty selection menu for a campaign, which consists of an image (called the icon) followed by text. When appropriate, the icon should use ImagePathFunctions to replace any magenta with a team color.

The description tag uses a special format:

  • ; if another description precedes it
  • * if it should be the default selection
  • &image=text image with one text description
  • &image=text=text2 image with two text descriptions

Single text items are always enclosed in ", and can be joined together (concatenated) with +. This allows the text to contain translatable items and span multiple lines. (Marking text with _ indicates that it is translatable.)

A sample difficulty description tag might look like this: 

difficulty_descriptions="&" + "units/elves-wood/elvish-fighter.png~TC(1,magenta)" + "=" + _"Fighter" + "=" + _"(easiest)" +
	";*" + "&" + "units/elves-wood/elvish-hero.png~TC(1,magenta)" + "=" + _"Hero" +
	";" + "&" + "units/elves-wood/elvish-champion.png~TC(1,magenta)" + "=" + _"Champion" + "=" + _"(hardest)"

The utility macros (see the Macro Reference) {MENU_IMG_TXT icon text} and {MENU_IMG_TXT2 icon text text-2} can be used to create descriptions more easily. The above example would become: 

difficulty_descriptions={MENU_IMG_TXT2 "units/elves-wood/elvish-fighter.png~TC(1,magenta)" _"Fighter" _"(easiest)"} +
	";*" + {MENU_IMG_TXT "units/elves-wood/elvish-hero.png~TC(1,magenta)" _"Hero"} + ";" +
	{MENU_IMG_TXT2 "units/elves-wood/elvish-champion.png~TC(1,magenta)" _"Champion" _"(hardest)"}

Alternative Description Implementation

For still greater clarity, I have the following suggestion: Before the start of the [campaign] tag, create a set of #define commands as follows: 

# Image definitions
# NB Don't forget the trailing + symbols for all but the last entry.
#define EASY_IMAGE
"&units/elves-wood/elvish-fighter.png~TC(1,magenta)"+
#enddef

#define NORMAL_IMAGE
";*&units/elves-wood/elvish-hero.png~TC(1,magenta)"+
#enddef

#define HARD_IMAGE
";&units/elves-wood/elvish-champion.png~TC(1,magenta)"+
#enddef

# Difficulty ratings
#po: NB be sure to retain the = signs in the translated text.
#define EASY_TEXT
_"=Fighter=(easiest)"+
#enddef

#define NORMAL_TEXT
_"=Hero"+
#enddef

#define HARD_TEXT
_"=Champion=(hardest)"
#enddef

Note: The above example assumes three difficulty levels, which gives six difficulty entries – three for the pictures and three for the text. If you have more or fewer than three difficulty levels, make sure that the last entry does not have a trailing plus sign and that all the others do. Note also that the first image description doesn't start with a semicolon, whereas the second and subsequent ones do. Finally, only the default difficulty entry is marked with a * character.

If you set up your difficulty strings in this way you can then use a standard difficulty_descriptions tag that you will rarely need to alter. Note that this string does not contain any plus signs. You have to have them in the difficulty ratings strings instead to avoid upsetting the Wesnoth preprocessor: 

difficulty_descriptions={EASY_IMAGE}{EASY_TEXT}{NORMAL_IMAGE}{NORMAL_TEXT}{HARD_IMAGE}{HARD_TEXT}

The only time you would need to alter this string is if you have more or fewer than three difficulty levels for your campaign.

Simons Mith 20:16, 18 November 2011 (UTC)

See Also

Retrieved from "https://wiki.wesnoth.org/index.php?title=DescriptionWML&oldid=71528"
This page was last edited on 25 July 2023, at 00:01.