Difference between revisions of "MusicListWML"

From The Battle for Wesnoth Wiki
(the [music] tag)
(Updated MusicListWML with engine limitations and macro references)
 
(2 intermediate revisions by 2 users not shown)
Line 2: Line 2:
 
== the [music] tag ==
 
== the [music] tag ==
  
This tag is a subtag of [scenario] and [event] which is used to describe a music track to play.  You can repeat this tag as many times as you like; if you set the ''append'' tag to ''yes'' they will form a playlist from which tracks will be selected at random.
+
This tag is a subtag of [scenario] and also part of [[ActionWML]], which is used to describe a music track to play.  You can repeat this tag as many times as you like; if you set the ''append'' tag to ''yes'' they will form a playlist from which tracks will be selected at random.
  
 
Tags describe the music track:
 
Tags describe the music track:
Line 9: Line 9:
 
* ''play_once=yes'' immediately switch to playing this track, but then return to the play list, which is unchanged.
 
* ''play_once=yes'' immediately switch to playing this track, but then return to the play list, which is unchanged.
 
* ''immediate=yes'' immediately switch to playing this track.  Without this, the song will play when the entire [event] is over or the current song ends.  This exists to force music changes '''during''' dialog exchange or other [event] which take significant time.
 
* ''immediate=yes'' immediately switch to playing this track.  Without this, the song will play when the entire [event] is over or the current song ends.  This exists to force music changes '''during''' dialog exchange or other [event] which take significant time.
* ''ms_before'' (optional) specifies how many milliseconds to delay before playing this track.  Currently this does not apply when the scenario first starts, or with ''play_once'' or ''immediate''.
+
* ''ms_before'' (optional) specifies how many milliseconds to delay before playing this track.  Currently this does not apply when the scenario first starts, or with ''play_once'' or ''immediate''.  Do not use this key for a [music] tag directly under [scenario] tag, because of the sound engine limitations it will lead to a story screen lag.
* ''ms_after'' (optional) specifies how many milliseconds to delay after playing this track.
+
* ''ms_after'' (optional) specifies how many milliseconds to delay after playing this track.  Do not use this key for a [music] tag directly under [scenario] tag, because of the sound engine limitations it will lead to a story screen lag.
 +
* ''shuffle'' {{DevFeature1.13|0}} (optional, boolean 'yes'/'no') specifies whether the music playlist as a whole should be shuffled or not. Defaults to 'yes'. The last [music] tag to include this attribute dictates the playlist's configuration.
  
 
For a list of music tracks you can use in your scenario, see [[Available Music]].
 
For a list of music tracks you can use in your scenario, see [[Available Music]].
Line 30: Line 31:
  
  
 +
== Useful Macros ==
 +
There are some predefined macros. You can find a complete list along with a detailed explanation of how they work [http://www.wesnoth.org/macro-reference.xhtml here].
 +
* '''{DEFAULT_MUSIC_PLAYLIST}''': Defines a standard playlist.
 +
* '''{FULL_MUSIC_PLAYLIST}''': Defines a playlist of all tracks.
 +
* '''{SCENARIO_MUSIC}''': Defines first track that is played when a scenario starts.
 +
* '''{EXTRA_SCENARIO_MUSIC}''': Use this immediately after the above SCENARIO_MUSIC macro to append extra tracks to the playlist.
 +
* '''{INTRO_AND_SCENARIO_MUSIC}''': Works as SCENARIO_MUSIC does, except that it allows you to specify the music used for the story screen (if any) as well.
 +
* '''{LET_INTRO_MUSIC_FINISH}''': Use immediately following INTRO_AND_SCENARIO_MUSIC, to let the intro music finish before switching to scenario music.
 +
* '''{INCIDENTAL_MUSIC}''': To be played immediately to mark an incident, but not appended to the scenario playlist.
 +
* '''{REPLACE_SCENARIO_MUSIC}''':  Use this in a mid-scenario to replace the current playlist.
 +
* '''{APPEND_MUSIC}''': Use this immediately after the above REPLACE_SCENARIO_MUSIC macro to append extra tracks to the playlist.
  
 
[[Category: WML Reference]]
 
[[Category: WML Reference]]
 
[[Category:Music]]
 
[[Category:Music]]

Latest revision as of 12:19, 18 April 2019

[edit]WML Tags

A:

abilities, about, add_ai_behavior, advance, 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, attack_anim, attacks, avoid;

B:

base_unit, berserk, binary_path, break, brush;

C:

campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_range, command (action, replay), continue, 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, era, event, 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_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, for, foreach, frame, full_heal;

G:

game_config, get_global_variable, goal, gold, gold_carryover;

H:

harm_unit, has_ally, has_attack, has_unit, 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), illuminates, image, 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, portrait, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, 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_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resource, return, role, rule;

S:

save, scenario, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, set_menu_item), show_objectives, side, skirmisher, 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_type, store_unit_type_ids, store_villages, story, swarm, switch, sync_variable;

T:

target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel, tutorial;

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;

the [music] tag

This tag is a subtag of [scenario] and also part of ActionWML, which is used to describe a music track to play. You can repeat this tag as many times as you like; if you set the append tag to yes they will form a playlist from which tracks will be selected at random.

Tags describe the music track:

  • name specifies the music file, relative to '"music/"'. This is compulsory.
  • append=yes specifies this is to be added to the current playlist. Without this, the current playlist is replaced by this track. (Note: if the same track is appended multiple times in a row, it will only play once before moving on to the next (different) track)
  • play_once=yes immediately switch to playing this track, but then return to the play list, which is unchanged.
  • immediate=yes immediately switch to playing this track. Without this, the song will play when the entire [event] is over or the current song ends. This exists to force music changes during dialog exchange or other [event] which take significant time.
  • ms_before (optional) specifies how many milliseconds to delay before playing this track. Currently this does not apply when the scenario first starts, or with play_once or immediate. Do not use this key for a [music] tag directly under [scenario] tag, because of the sound engine limitations it will lead to a story screen lag.
  • ms_after (optional) specifies how many milliseconds to delay after playing this track. Do not use this key for a [music] tag directly under [scenario] tag, because of the sound engine limitations it will lead to a story screen lag.
  • shuffle (Version 1.13.0 and later only) (optional, boolean 'yes'/'no') specifies whether the music playlist as a whole should be shuffled or not. Defaults to 'yes'. The last [music] tag to include this attribute dictates the playlist's configuration.

For a list of music tracks you can use in your scenario, see Available Music.

Example

This creates a new playlist with three entries in it. The second track is always preceeded by 1/2 a second of silence.

 [music]
    name=background-music-1.ogg
 [/music]
 [music]
    name=background-music-2.ogg
    ms_before=500
    append=yes
 [/music]
 [music]
    name=background-music-3.ogg
    append=yes
 [/music]


Useful Macros

There are some predefined macros. You can find a complete list along with a detailed explanation of how they work here.

  • {DEFAULT_MUSIC_PLAYLIST}: Defines a standard playlist.
  • {FULL_MUSIC_PLAYLIST}: Defines a playlist of all tracks.
  • {SCENARIO_MUSIC}: Defines first track that is played when a scenario starts.
  • {EXTRA_SCENARIO_MUSIC}: Use this immediately after the above SCENARIO_MUSIC macro to append extra tracks to the playlist.
  • {INTRO_AND_SCENARIO_MUSIC}: Works as SCENARIO_MUSIC does, except that it allows you to specify the music used for the story screen (if any) as well.
  • {LET_INTRO_MUSIC_FINISH}: Use immediately following INTRO_AND_SCENARIO_MUSIC, to let the intro music finish before switching to scenario music.
  • {INCIDENTAL_MUSIC}: To be played immediately to mark an incident, but not appended to the scenario playlist.
  • {REPLACE_SCENARIO_MUSIC}: Use this in a mid-scenario to replace the current playlist.
  • {APPEND_MUSIC}: Use this immediately after the above REPLACE_SCENARIO_MUSIC macro to append extra tracks to the playlist.
This page was last edited on 18 April 2019, at 12:19.