I've posted this on the internal PoP Dev Board weeks ago, I see now it can be useful to people here. If somebody knows more arcane stuff about the music, send a pm, and I'll add it with credit.
Note: this is valid for standard MnB and Warband, there are very few changes.
header_music.py
Warband adds these:
header_operations.py
top of module_music.py
1. module_music.py explained
Each record in module_music.py describes a music track (see top of module_music.py for official description).
Example:
("ambushed_by_vaegir", "ambushed_by_vaegir.ogg", mtf_culture_2|mtf_sit_ambushed|mtf_sit_siege, mtf_sit_fight|mtf_culture_all),
"ambushed_by_vaegir"
The name of the track as known by the code; the rest of the code can reference it with track_ambushed_by_vaegir
"ambushed_by_vaegir.ogg"
The name of the physical music file; if mtf_module_track is present in the third field, the file is in (mod dir)/Music, if not, it's a Native file in (M&B dir)/Music. The first mistake you'll probably make when adding your own track is to forget to put the mtf_module_track flag.
mtf_culture_2|mtf_sit_ambushed|mtf_sit_siege
The play condition. When will the track play: in what situation and in what culture. Translation: "The track will play only if the culture is 2 (Vaegir) AND the situation is either Ambush OR Siege". Not having culture flags is the same as putting mtf_culture_all (will match all cultures) - this may be confusing, but that's what M&B does.
mtf_sit_fight|mtf_culture_all
The continue condition. Whether the track continues to play when the situation and/or culture change (otherwise it will fade out). Translation: "The track will continue to play in any culture AND if the situation is Ambush OR Siege OR Fight". Note that the start play conditions are automatically added (ORred) to continue play conditions (and it makes sense to do so - see process_music.py if you are curious). Usually you will ignore it (stick with the culture in the play condition) or put mtf_culture_all (when you want maximum chance of continuing play - if your play field has no mtf_culture_x, this is implied and can be omitted).
Examples for culture flags:
1. ("ambushed_by_neutral", "ambushed_by_neutral.ogg", mtf_sit_ambushed|mtf_sit_siege, mtf_sit_fight)
Will play/continue in all cultures (mtf_culture_all implied).
2. ("ambushed_by_neutral", "ambushed_by_neutral.ogg", mtf_culture_1|mtf_culture_2|mtf_sit_ambushed|mtf_sit_siege, mtf_culture_4|mtf_sit_fight)
Will start playing for cultures 1 and 2, will continue playing for cultures 1, 2 and 4 (i.e. will fade out in cultures 3, 5 and 6).
There are 6 defined cultures (mtf_culture_1 to mtf_culture_6) with mtf_culture_all denoting all of them. MnB: The 6th culture is used to denote a neutral faction, but is really used for various bandits in the code. Warband: The 6th culture is used for Sarranids (and various bandits, lol).
The M&B internal music system gets information about situation and culture from the module system code (i.e. from you, or your favorite coder). When the situation and/or culture change, it will look for tracks that match these. If there are more, it will choose one at random and play it. When situation/culture change again, it will check first if it can allow the current track to continue playing. If not, it will fade out the current track and find a new one to play.
Other flags:
mtf_looping - loops the track until continue conditions are not met
mtf_start_immediately - instead of fading out the previous track, it stops it before playing this one
mtf_persist_until_finished - plays the track until finished and nothing can stop it, use with care
2. What Native music code does
Most of the code in the game changes the music through the script music_set_situation_with_culture. For coders, it's a wrapper for music_set_situation and music_set_culture. For everybody else, it analyzes a "situation" (see mtf_sit_x flags) and finds one or a variety of cultures appropriate to the situation. Multiple cultures will cause more matches found among the tracks, adding to the variety of music (or confusing the player with seeming randomness, it's a thin line).
This script only implictly plays music, the M&B internal music system detects changes in situation and culture and does the actual playing.
Examples of situations and cultures (English translation of music_set_situation_with_culture):
- In town (mtf_sit_town), set the culture to the original faction of the town.
- While travelling the map (mtf_sit_travel), set the culture to the faction of the nearest town AND the player's culture (2 cultures max).
- In battle (mtf_sit_fight or mtf_sit_ambushed), set the culture to both the leading parties AND the faction of the nearest center (3 cultures max).
- If victorius in battle (mtf_sit_victorious), the culture is player's own
- If defeated in battle (mtf_sit_killed), the culture is your enemy's
- Warband: in multiplayer, set the culture to both team factions (2 cultures)
- Some situations are not culture-specific (culture=0) - make sure you don't put mtf_culture_x play conditions with these in module_music.py: mtf_sit_tavern, mtf_sit_siege, mtf_sit_arena
- Some situations are never used by the code, so don't waste your tracks with these: mtf_sit_town (Warband uses this), mtf_sit_day, mtf_sit_night (MnB: calm_night_2.ogg never plays, Warband uses this), mtf_sit_encounter_hostile (encounter_hostile_nords.ogg never plays)
Note that the player's party culture is 0, until he becomes a vassal.
Some common music situations (mtf_sit_x) as set in the code:
Town menu (travel)
Town streets (travel, Warband: town or night)
Streets night (travel)
Tavern (tavern)
Arena Master (travel)
Arena melee (arena)
Village walk (travel)
Castle menu (travel)
Castle hall (travel)
Battles are special as they use triggers to play music. The common battle trigger fires every 30 seconds and sets the situation to mtf_sit_fight or mtf_sit_ambushed (if odds against player worse than 2:1).
Siege battles start with common siege music, then play battle music as normal.
The world map has a trigger that fires every game hour and tries to play travel music (sets situation to mtf_sit_travel).
Exceptions
Some tracks are explicitely played from code, so they don't need any flags ("captured", "empty_village", "escape", "victorious_evil"; Warband uses also "wedding").
3. Tips
3.1. Tips for music designers
- you may want to have special tracks for every possible situation in the game - resist the urge, from a player point of view more varied travel and battle tracks may bring better value
- when deciding which tracks can continue where (continue condition flags), think in terms of what the average player is likely to do - if he spends only a few seconds in your taverns, maybe you could allow the travel or town or lord's hall music to continue there, so you won't change your music every few seconds; if your taverns are more interesting to hang out, don't allow anything to play there except tavern music
- try to use mtf_persist_until_finished on shorter tracks only (like Native's victory tracks)
- if you want to annoy the player, maybe because he's a cheater, a pirate or you are just plain evil, set this flags:
("punish_player", "punish_player.ogg", mtf_looping|mtf_persist_until_finished|mtf_module_track, 0)
the track will loop forever and cannot be stopped until the player quits the game.
- make sure your tracks are stereo, mono might have some problems playing properly
3.2. Tips for coders
- (music_set_situation, 0) fades out any current music, new music will start playing when the situation is set again
- use play_track when you want to play a specific track, and not allow M&B to choose randomly (watch your continue flags or your track may stop short!)
- play_cue_track plays over any already playing track - can't think of a good use for this
- the simplest way to play a track only for a specific encounter (e.g. a zombie horde):
Step 1. In game_event_party_encounter() add this:
(try_begin),
(eq, "$g_encountered_party_template","pt_zombie_horde"),
(play_track, "track_zombie_horde", 1),
(try_end),
Step 2. Add a new track in music_module.py (and put zombie_horde.ogg in (mod dir)/Music):
("zombie_horde", "zombie_horde.ogg", mtf_module_track, mtf_sit_fight|mtf_sit_ambushed|mtf_sit_travel|mtf_culture_all),
- if you want to have faction-specific music for more than 6 factions, forget about the culture flags, you'll have to code a custom solution
- adding lord's hall (castle and town castle hall) music - both easy and fun
Step 1. Add this line to header_music.py:
mtf_sit_lords_hall = 0x02000000
Step 2. Find both lines in module_mission_templates.py and uncomment them:
# (call_script, "script_music_set_situation_with_culture", mtf_sit_lords_hall),
Step 3. Add one line to music_set_situation_with_culture in module_scripts.py:
(this_or_next|eq, ":situation", mtf_sit_town_infiltrate),
(this_or_next|eq, ":situation", mtf_sit_lords_hall),
(eq, ":situation", mtf_sit_encounter_hostile),
Step 4. Add tracks to module_music.py (change the flags as you like), and add .oggs to your mod's Music folder:
("lords_hall_swadian", "lords_hall_swadian.ogg", mtf_module_track|mtf_culture_1|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
("lords_hall_vaegir", "lords_hall_vaegir.ogg", mtf_module_track|mtf_culture_2|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
("lords_hall_khergit", "lords_hall_khergit.ogg", mtf_module_track|mtf_culture_3|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
("lords_hall_nord", "lords_hall_nord.ogg", mtf_module_track|mtf_culture_4|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
("lords_hall_rhodok", "lords_hall_rhodok.ogg", mtf_module_track|mtf_culture_5|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
("lords_hall_sarranid", "lords_hall_sarranid.ogg", mtf_module_track|mtf_culture_6|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
Note: this is valid for standard MnB and Warband, there are very few changes.
header_music.py
mtf_culture_1 = 0x00000001
mtf_culture_2 = 0x00000002
mtf_culture_3 = 0x00000004
mtf_culture_4 = 0x00000008
mtf_culture_5 = 0x00000010
mtf_culture_6 = 0x00000020
mtf_culture_all = 0x0000003F
mtf_looping = 0x00000040
mtf_start_immediately = 0x00000080
mtf_persist_until_finished = 0x00000100
mtf_sit_tavern = 0x00000200
mtf_sit_fight = 0x00000400
mtf_sit_ambushed = 0x00001000
mtf_sit_town = 0x00002000
mtf_sit_town_infiltrate = 0x00004000
mtf_sit_killed = 0x00008000
mtf_sit_travel = 0x00010000
mtf_sit_arena = 0x00020000
mtf_sit_siege = 0x00040000
mtf_sit_night = 0x00080000
mtf_sit_day = 0x00100000
mtf_sit_encounter_hostile = 0x00200000
mtf_sit_main_title = 0x00400000
mtf_sit_victorious = 0x00800000
mtf_module_track = 0x10000000 ##set this flag for tracks placed under module folder
mtf_culture_2 = 0x00000002
mtf_culture_3 = 0x00000004
mtf_culture_4 = 0x00000008
mtf_culture_5 = 0x00000010
mtf_culture_6 = 0x00000020
mtf_culture_all = 0x0000003F
mtf_looping = 0x00000040
mtf_start_immediately = 0x00000080
mtf_persist_until_finished = 0x00000100
mtf_sit_tavern = 0x00000200
mtf_sit_fight = 0x00000400
mtf_sit_ambushed = 0x00001000
mtf_sit_town = 0x00002000
mtf_sit_town_infiltrate = 0x00004000
mtf_sit_killed = 0x00008000
mtf_sit_travel = 0x00010000
mtf_sit_arena = 0x00020000
mtf_sit_siege = 0x00040000
mtf_sit_night = 0x00080000
mtf_sit_day = 0x00100000
mtf_sit_encounter_hostile = 0x00200000
mtf_sit_main_title = 0x00400000
mtf_sit_victorious = 0x00800000
mtf_module_track = 0x10000000 ##set this flag for tracks placed under module folder
mtf_sit_multiplayer_fight = 0x00000800
mtf_sit_feast = 0x01000000
mtf_sit_feast = 0x01000000
header_operations.py
play_track = 601 # (play_track,<track_id>, [options]), # 0 = default, 1 = fade out current track, 2 = stop current track
play_cue_track = 602 # (play_cue_track,<track_id>), #starts immediately
music_set_situation = 603 # (music_set_situation, <situation_type>),
music_set_culture = 604 # (music_set_culture, <culture_type>),
play_cue_track = 602 # (play_cue_track,<track_id>), #starts immediately
music_set_situation = 603 # (music_set_situation, <situation_type>),
music_set_culture = 604 # (music_set_culture, <culture_type>),
top of module_music.py
####################################################################################################################
# Each track record contains the following fields:
# 1) Track id: used for referencing tracks.
# 2) Track file: filename of the track
# 3) Track flags. See header_music.py for a list of available flags
# 4) Continue Track flags: Shows in which situations or cultures the track can continue playing. See header_music.py for a list of available flags
####################################################################################################################
# WARNING: You MUST add mtf_module_track flag to the flags of the tracks located under module directory
# Each track record contains the following fields:
# 1) Track id: used for referencing tracks.
# 2) Track file: filename of the track
# 3) Track flags. See header_music.py for a list of available flags
# 4) Continue Track flags: Shows in which situations or cultures the track can continue playing. See header_music.py for a list of available flags
####################################################################################################################
# WARNING: You MUST add mtf_module_track flag to the flags of the tracks located under module directory
1. module_music.py explained
Each record in module_music.py describes a music track (see top of module_music.py for official description).
Example:
("ambushed_by_vaegir", "ambushed_by_vaegir.ogg", mtf_culture_2|mtf_sit_ambushed|mtf_sit_siege, mtf_sit_fight|mtf_culture_all),
"ambushed_by_vaegir"
The name of the track as known by the code; the rest of the code can reference it with track_ambushed_by_vaegir
"ambushed_by_vaegir.ogg"
The name of the physical music file; if mtf_module_track is present in the third field, the file is in (mod dir)/Music, if not, it's a Native file in (M&B dir)/Music. The first mistake you'll probably make when adding your own track is to forget to put the mtf_module_track flag.
mtf_culture_2|mtf_sit_ambushed|mtf_sit_siege
The play condition. When will the track play: in what situation and in what culture. Translation: "The track will play only if the culture is 2 (Vaegir) AND the situation is either Ambush OR Siege". Not having culture flags is the same as putting mtf_culture_all (will match all cultures) - this may be confusing, but that's what M&B does.
mtf_sit_fight|mtf_culture_all
The continue condition. Whether the track continues to play when the situation and/or culture change (otherwise it will fade out). Translation: "The track will continue to play in any culture AND if the situation is Ambush OR Siege OR Fight". Note that the start play conditions are automatically added (ORred) to continue play conditions (and it makes sense to do so - see process_music.py if you are curious). Usually you will ignore it (stick with the culture in the play condition) or put mtf_culture_all (when you want maximum chance of continuing play - if your play field has no mtf_culture_x, this is implied and can be omitted).
Examples for culture flags:
1. ("ambushed_by_neutral", "ambushed_by_neutral.ogg", mtf_sit_ambushed|mtf_sit_siege, mtf_sit_fight)
Will play/continue in all cultures (mtf_culture_all implied).
2. ("ambushed_by_neutral", "ambushed_by_neutral.ogg", mtf_culture_1|mtf_culture_2|mtf_sit_ambushed|mtf_sit_siege, mtf_culture_4|mtf_sit_fight)
Will start playing for cultures 1 and 2, will continue playing for cultures 1, 2 and 4 (i.e. will fade out in cultures 3, 5 and 6).
There are 6 defined cultures (mtf_culture_1 to mtf_culture_6) with mtf_culture_all denoting all of them. MnB: The 6th culture is used to denote a neutral faction, but is really used for various bandits in the code. Warband: The 6th culture is used for Sarranids (and various bandits, lol).
The M&B internal music system gets information about situation and culture from the module system code (i.e. from you, or your favorite coder). When the situation and/or culture change, it will look for tracks that match these. If there are more, it will choose one at random and play it. When situation/culture change again, it will check first if it can allow the current track to continue playing. If not, it will fade out the current track and find a new one to play.
Other flags:
mtf_looping - loops the track until continue conditions are not met
mtf_persist_until_finished - plays the track until finished and nothing can stop it, use with care
2. What Native music code does
Most of the code in the game changes the music through the script music_set_situation_with_culture. For coders, it's a wrapper for music_set_situation and music_set_culture. For everybody else, it analyzes a "situation" (see mtf_sit_x flags) and finds one or a variety of cultures appropriate to the situation. Multiple cultures will cause more matches found among the tracks, adding to the variety of music (or confusing the player with seeming randomness, it's a thin line).
This script only implictly plays music, the M&B internal music system detects changes in situation and culture and does the actual playing.
Examples of situations and cultures (English translation of music_set_situation_with_culture):
- In town (mtf_sit_town), set the culture to the original faction of the town.
- While travelling the map (mtf_sit_travel), set the culture to the faction of the nearest town AND the player's culture (2 cultures max).
- In battle (mtf_sit_fight or mtf_sit_ambushed), set the culture to both the leading parties AND the faction of the nearest center (3 cultures max).
- If victorius in battle (mtf_sit_victorious), the culture is player's own
- If defeated in battle (mtf_sit_killed), the culture is your enemy's
- Warband: in multiplayer, set the culture to both team factions (2 cultures)
- Some situations are not culture-specific (culture=0) - make sure you don't put mtf_culture_x play conditions with these in module_music.py: mtf_sit_tavern, mtf_sit_siege, mtf_sit_arena
- Some situations are never used by the code, so don't waste your tracks with these: mtf_sit_town (Warband uses this), mtf_sit_day, mtf_sit_night (MnB: calm_night_2.ogg never plays, Warband uses this), mtf_sit_encounter_hostile (encounter_hostile_nords.ogg never plays)
Note that the player's party culture is 0, until he becomes a vassal.
Some common music situations (mtf_sit_x) as set in the code:
Town menu (travel)
Town streets (travel, Warband: town or night)
Streets night (travel)
Tavern (tavern)
Arena Master (travel)
Arena melee (arena)
Village walk (travel)
Castle menu (travel)
Castle hall (travel)
Battles are special as they use triggers to play music. The common battle trigger fires every 30 seconds and sets the situation to mtf_sit_fight or mtf_sit_ambushed (if odds against player worse than 2:1).
Siege battles start with common siege music, then play battle music as normal.
The world map has a trigger that fires every game hour and tries to play travel music (sets situation to mtf_sit_travel).
Exceptions
Some tracks are explicitely played from code, so they don't need any flags ("captured", "empty_village", "escape", "victorious_evil"; Warband uses also "wedding").
3. Tips
3.1. Tips for music designers
- you may want to have special tracks for every possible situation in the game - resist the urge, from a player point of view more varied travel and battle tracks may bring better value
- when deciding which tracks can continue where (continue condition flags), think in terms of what the average player is likely to do - if he spends only a few seconds in your taverns, maybe you could allow the travel or town or lord's hall music to continue there, so you won't change your music every few seconds; if your taverns are more interesting to hang out, don't allow anything to play there except tavern music
- try to use mtf_persist_until_finished on shorter tracks only (like Native's victory tracks)
- if you want to annoy the player, maybe because he's a cheater, a pirate or you are just plain evil, set this flags:
("punish_player", "punish_player.ogg", mtf_looping|mtf_persist_until_finished|mtf_module_track, 0)
the track will loop forever and cannot be stopped until the player quits the game.
- make sure your tracks are stereo, mono might have some problems playing properly
3.2. Tips for coders
- (music_set_situation, 0) fades out any current music, new music will start playing when the situation is set again
- use play_track when you want to play a specific track, and not allow M&B to choose randomly (watch your continue flags or your track may stop short!)
- play_cue_track plays over any already playing track - can't think of a good use for this
- the simplest way to play a track only for a specific encounter (e.g. a zombie horde):
Step 1. In game_event_party_encounter() add this:
(try_begin),
(eq, "$g_encountered_party_template","pt_zombie_horde"),
(play_track, "track_zombie_horde", 1),
(try_end),
Step 2. Add a new track in music_module.py (and put zombie_horde.ogg in (mod dir)/Music):
("zombie_horde", "zombie_horde.ogg", mtf_module_track, mtf_sit_fight|mtf_sit_ambushed|mtf_sit_travel|mtf_culture_all),
- if you want to have faction-specific music for more than 6 factions, forget about the culture flags, you'll have to code a custom solution
- adding lord's hall (castle and town castle hall) music - both easy and fun
Step 1. Add this line to header_music.py:
mtf_sit_lords_hall = 0x02000000
Step 2. Find both lines in module_mission_templates.py and uncomment them:
# (call_script, "script_music_set_situation_with_culture", mtf_sit_lords_hall),
Step 3. Add one line to music_set_situation_with_culture in module_scripts.py:
(this_or_next|eq, ":situation", mtf_sit_town_infiltrate),
(this_or_next|eq, ":situation", mtf_sit_lords_hall),
(eq, ":situation", mtf_sit_encounter_hostile),
Step 4. Add tracks to module_music.py (change the flags as you like), and add .oggs to your mod's Music folder:
("lords_hall_swadian", "lords_hall_swadian.ogg", mtf_module_track|mtf_culture_1|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
("lords_hall_vaegir", "lords_hall_vaegir.ogg", mtf_module_track|mtf_culture_2|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
("lords_hall_khergit", "lords_hall_khergit.ogg", mtf_module_track|mtf_culture_3|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
("lords_hall_nord", "lords_hall_nord.ogg", mtf_module_track|mtf_culture_4|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
("lords_hall_rhodok", "lords_hall_rhodok.ogg", mtf_module_track|mtf_culture_5|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
("lords_hall_sarranid", "lords_hall_sarranid.ogg", mtf_module_track|mtf_culture_6|mtf_sit_lords_hall, mtf_sit_tavern|mtf_culture_all),
