Difference between revisions of "IntroWML"

From The Battle for Wesnoth Wiki
(The [story] tag: add the centered key)
([image]: Add resize_with_background)
(29 intermediate revisions by 14 users not shown)
Line 1: Line 1:
 
{{WML Tags}}
 
{{WML Tags}}
== The [story] tag ==
+
== IntroWML ==
  
The '''[story]''' tag is a series of images and text to display as the first part of the intro screen.
+
The '''[story]''' tag is a series of images and text to display as the first part of the intro screen. It can appear in [[ScenarioWML]] or {{DevFeature1.13|8}} as [[InterfaceActionsWML#.5Bstory.5D|ActionWML]].
  
The only tag recognized for '''[story]''' is '''[part]'''.
+
The '''[deprecated_message]''', '''[wml_message]''', '''[image]''', and '''[insert_tag]''' tags are allowed beneath '''[story]'''.  Most other WML tags will not be recognized in this context. Note, however, that messages produced by the first two tags will not appear in the game interface until the actual game map appears.
Each '''[part]''' represents one image and text.
+
 
 +
The only other tags currently recognized within '''[story]''' and '''[part]''' are '''[if]'''/'''[then]'''/'''[else]''' ({{DevFeature1.13|0}}: also '''[elseif]''') and '''[switch]'''/'''[case]'''. These can be used to show parts conditionally on the values of variables.
 +
 
 +
See also the journey and battle macros, in the [http://www.wesnoth.org/macro-reference.xhtml#file:image-utils.cfg Macro Reference]
 +
 
 +
=== [story] ===
 +
 
 +
* '''text_layout''': specifies the area of the screen where the story text will be displayed. It allows the ''top'', ''middle'' and ''bottom'' values; the latter is used by default.
 +
* '''title_alignment''': specifies the alignment of the title box. It allows the ''left'', ''center'' and ''right'' values; the first is used by default.
 +
 
 +
=== [part] ===
 +
 
 +
'''[part]''' is a special tag recognized only beneath '''[story]'''. Each '''[part]''' represents one image and text.
 
The part is displayed until the user clicks on the "Next>>>" button.
 
The part is displayed until the user clicks on the "Next>>>" button.
  
 
The following key/tags are recognized for '''[part]''':
 
The following key/tags are recognized for '''[part]''':
* ''background'' the image to display. Story images are usually created specially for this purpose, except for the map.
+
* '''background''': the image to display. Story images are usually created specially for this purpose, except for the map.
* ''story'' (translatable) the text to display below the image.
+
* '''scale_background''': Whether to scale the background, default yes.
* ''show_title'' whether to display the title of the scenario at the top
+
* '''story''': (translatable) the text to display below the image.
* ''music'' change to this music
+
* '''show_title''': whether to display the title of the scenario at the top
* '''[image]''' an image to display.
+
* '''title''': specifies a custom title to display instead of the name of the scenario. If specified, it implies '''show_title=yes'''. If parent '''[story]''' is used through [[InterfaceActionsWML#.5Bstory.5D|ActionWML]] with '''show_title=yes''', the '''title''' key must be explicitly specified, it does not default to scenario title and leads to missing-title error if omitted.
** ''x'', ''y'' the location in pixels to draw the image. The x,y pixel location is relative to the image specified in background, but not in a normal way. The background image is scaled up or down to fill the screen resolution, but images are never scaled in size. Their coordinates, however, are scaled. It's basically a big pain in the rear. Example: I have a background image at 640x480 and an overlay at 640x480.  To horizontally center the overlay on a 1024x768 screen, I want to position it at x=192. This is because 1024-640 = 384 total extra pixel space, then 384/2 = 192.  This results in equal space on both sides of the overlay. However, now you have to account for the background scaling.  The background image at 640 is scaled up to 1024, a scaling factor of 1.6. All image locations are also scaled up, so the overlay is not drawn at x=192, rather it is drawn at x=192*1.6 or x=307!  To compensate for this, divide the desired pixel location by the scaling factor.  In the example, x_compensated=192/1.6 or x_compensated=120.
+
* '''music''': change to this music
** ''centered'' {{DevFeature}} If "yes", use the center of the image when placing at the x,y coordinates, which is useful since this image is not scaled like the background is (and by centering no need to worry about this).
+
* '''sound''': a list of sound files; the engine will choose one at random and play it once while displaying the story part.
** ''file'' the image to display.
+
 
** ''delay'' the time to delay drawing this image.
+
=== [background_layer] ===
 +
 
 +
A layer of the background of the story screen.
 +
 
 +
* '''image''': path to the image file.
 +
* '''scale_vertically''': whether the image should be scaled to fill the screen in the vertical dimension. Default yes.
 +
* '''scale_horizontally''': whether the image should be scaled to fill the screen in the horizontal dimension. Default yes.
 +
* '''scale''': a shortcut to set scale_vertically and scale_horizontally at once. If specified, the values of the former two keys will be ignored.
 +
* '''keep_aspect_ratio''': whether the aspect ratio of the image should be preserved while scaling. Default yes.
 +
* '''tile_vertically''': whether the image should be tiled in the vertical direction. Tiling happens after aligning the image to the center of the screen. Default no.
 +
* '''tile_horizontally''': whether the image should be tiled in the horizontal direction. Tiling happens after aligning the image to the center of the screen. Default no.
 +
* '''tile''': a shortcut to set tile_vertically and tile_horizontally at once. If specified, the values of the former two keys will be ignored.
 +
* '''base_layer''': whether is this the layer to align the overlay images to. Default no.
 +
 
 +
=== [image] ===
 +
 
 +
An image to display.
 +
 
 +
* '''x''', '''y''': the location to draw the image, using the pixels of the '''base_layer''' background image as the coordinate system.
 +
* '''centered''': If "yes", use the center of the image as the anchor point when placing at the x,y coordinates, if "no" then use the top-left corner.
 +
* '''file''': the image to display.
 +
* '''delay''': the time to delay drawing this image.
 +
* '''resize_with_background''': {{DevFeature1.15|7}} if "yes", apply the same scaling as applied to the '''base_layer'''
  
See also the '''DOT''' and '''CROSS''' macros, in [[UtilWML]]
+
Each image is placed using the pixels of the background_layer as the coordinate system; each image's location moves to compensate when the background image is scaled. Example: my background image is a map with a city at pixel 160,100; I put a battle marker on that city using '''x,y,centered=160,100,yes'''. When a user plays the game they will see the map enlarged to fill the window (regardless of its size), and the battle marker will still be on top of the city.
  
 
== See Also ==
 
== See Also ==

Revision as of 15:59, 4 November 2020

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

IntroWML

The [story] tag is a series of images and text to display as the first part of the intro screen. It can appear in ScenarioWML or (Version 1.13.8 and later only) as ActionWML.

The [deprecated_message], [wml_message], [image], and [insert_tag] tags are allowed beneath [story]. Most other WML tags will not be recognized in this context. Note, however, that messages produced by the first two tags will not appear in the game interface until the actual game map appears.

The only other tags currently recognized within [story] and [part] are [if]/[then]/[else] ((Version 1.13.0 and later only): also [elseif]) and [switch]/[case]. These can be used to show parts conditionally on the values of variables.

See also the journey and battle macros, in the Macro Reference

[story]

  • text_layout: specifies the area of the screen where the story text will be displayed. It allows the top, middle and bottom values; the latter is used by default.
  • title_alignment: specifies the alignment of the title box. It allows the left, center and right values; the first is used by default.

[part]

[part] is a special tag recognized only beneath [story]. Each [part] represents one image and text. The part is displayed until the user clicks on the "Next>>>" button.

The following key/tags are recognized for [part]:

  • background: the image to display. Story images are usually created specially for this purpose, except for the map.
  • scale_background: Whether to scale the background, default yes.
  • story: (translatable) the text to display below the image.
  • show_title: whether to display the title of the scenario at the top
  • title: specifies a custom title to display instead of the name of the scenario. If specified, it implies show_title=yes. If parent [story] is used through ActionWML with show_title=yes, the title key must be explicitly specified, it does not default to scenario title and leads to missing-title error if omitted.
  • music: change to this music
  • sound: a list of sound files; the engine will choose one at random and play it once while displaying the story part.

[background_layer]

A layer of the background of the story screen.

  • image: path to the image file.
  • scale_vertically: whether the image should be scaled to fill the screen in the vertical dimension. Default yes.
  • scale_horizontally: whether the image should be scaled to fill the screen in the horizontal dimension. Default yes.
  • scale: a shortcut to set scale_vertically and scale_horizontally at once. If specified, the values of the former two keys will be ignored.
  • keep_aspect_ratio: whether the aspect ratio of the image should be preserved while scaling. Default yes.
  • tile_vertically: whether the image should be tiled in the vertical direction. Tiling happens after aligning the image to the center of the screen. Default no.
  • tile_horizontally: whether the image should be tiled in the horizontal direction. Tiling happens after aligning the image to the center of the screen. Default no.
  • tile: a shortcut to set tile_vertically and tile_horizontally at once. If specified, the values of the former two keys will be ignored.
  • base_layer: whether is this the layer to align the overlay images to. Default no.

[image]

An image to display.

  • x, y: the location to draw the image, using the pixels of the base_layer background image as the coordinate system.
  • centered: If "yes", use the center of the image as the anchor point when placing at the x,y coordinates, if "no" then use the top-left corner.
  • file: the image to display.
  • delay: the time to delay drawing this image.
  • resize_with_background: (Version 1.15.7 and later only) if "yes", apply the same scaling as applied to the base_layer

Each image is placed using the pixels of the background_layer as the coordinate system; each image's location moves to compensate when the background image is scaled. Example: my background image is a map with a city at pixel 160,100; I put a battle marker on that city using x,y,centered=160,100,yes. When a user plays the game they will see the map enlarged to fill the window (regardless of its size), and the battle marker will still be on top of the city.

See Also