Difference between revisions of "MusicListWML"

From The Battle for Wesnoth Wiki
(Clarify the use of "immediate" (ie. it's exceptional).)
(Updated MusicListWML with engine limitations and macro references)
 
(7 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 +
{{WML Tags}}
 
== the [music] tag ==
 
== the [music] tag ==
{{DevFeature}}
 
  
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:
 
* ''name'' specifies the music file, relative to '"music/"'.  This is compulsory.
 
* ''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.
+
* ''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.
 
* ''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]].
 +
 +
=== 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 [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]]

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, checkbox, choice, 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 (credits, options), 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;

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, intro), illuminates, image (gui2, 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, 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, [[OptionWML|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, 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.