The MMS Music Pack Creation Guide

Overview

A detailed guide to creating music packs to be used with the music modding system.

Introduction

This guide will show you how to make Xcom 2 music packs using the Music Modding System framework. While there is an existing MMS guide[docs.google.com], it contains some information which is no longer accurate and it doesn’t dive deeply into what exactly you are doing. That’s fair enough, it is described as a work in progress on the mod’s page. Given that, I felt it was worth putting together a more structured guide which goes into a bit more detail about how the system works.

Making MMS packs is fairly easy as long as you get good files to work with. On that note, I have written a companion guide on processing audio for music packs and creating loops using Audacity.

To do this you will need the XCOM 2 mod tools installed[downloads.2kgames.com] (everything on pages 2 and 3). I also recommend using the

Alternative Mod Launcher: Now a Community Project from xcom2mods

as that makes enabling and disabling music packs much easier. You will also need an icon for your pack and, of course, music files saved as WAVs .

BY THE WAY: I strongly recommend using the Vanilla mod tools tools. If you use the WotC tools then the mod will randomly crash Vanilla. There is no advantage to making music packs using the WotC tools that I am aware of.

Interacting With MMS

The music modding system has a collection of in-game situations that it understands. Examples include the main menu, the geoscape and each side’s turn in combat. Every time a new situation comes up MMS looks at its list of “cues” for it and picks one at random. Cues may contain one or more music tracks.

Some situations have extra features which can be specified. For example, if the player is in combat during a facility assault mission MMS will first look at its list of facility combat cues and only go back to the normal ones if there are no specialist files present. If the player turns on the “mix in indifferent” setting then the general files will always be included in the list.

Cues are created using the UDK (the “real” mod tools). UDK creates .upk packages which contain both the music tracks and the cues. You can create a cue for each situation, or for each track. In the former case you will be doing most of the work in UDK, the latter in Modbuddy

MMS is told about the cues through .ini files in Modbuddy. For each cue you need a line of code specifying which situation the cue is for. For example:

The above tells MMS to make a new entry with the name given by MusicID, that it refers to a sound cue stored at the address given by CuePath, neither to fade in nor fade out and that this entry applies to the situation of the player losing the game. The \ at the end of each line tell the parser that the next line is part of the same instruction (not all parsers require this, but XCom 2 does). The ) at the end indicates the end of the instruction.

If you’ve never programmed before, things like “+MusicDefs=(Stuff,OtherStuff,FurtherStuff)” are instructions. The “Stuff” portions between the commas are called arguments. If a program has an instruction “GoToTheXStoreStoreAndBuyMeY(X,Y)”, a valid calling of that instruction might be “GoToTheXStoreAndByMeY(Grocery,Milk)”. In this case, Grocery and Milk are arguments.

Choosing a Method

MMS is very chill about cues, and once you get used to working with it you will probably find your own way that you like to organize things. In fact, different projects will benefit from different structures depending on how many tracks you have and what you want them to do. You can mix and match, or start doing other odd things. However, there are two basic methods and until you get used to everything you should pick one.

The first method, and the one I tend to prefer, is to create a cue for each situation and then assign tracks to them using UDK’s tools. This has the advantage that it is very easy to make templates for and that can make the process much faster. It also allows you to do some fancy things such as having one file fade into another within one situation. The major disadvantage is that there are a couple of things you can’t do in MMS using this technique. You also need to make slightly convoluted ini files in Modbuddy in order to give your tracks equal play time with other music packs.

The second method is to create a cue for every track. If you do this you will be assigning the tracks to different situations in Modbuddy’s text editor. This has the advantage that you need to spend almost no time in UDK. There are also a few features of MMS that this gives you access to such as playing different music for Xcom and Advent combat turns. These packs are easier for end users to modify as well.

Obviously I am going to recommend the first method as that’s what I prefer to use, but I will provide instructions for both.

UDK: Cue-Per-Situation Method

1. Download this template[www.dropbox.com]
2. Copy the template into the folder SteamsteamappscommonXCOM 2 SDKXComGameContentXCOM_2Packages
3. Rename the template to the package name you will be using i.e. BlahBlahSoundtrackMusicPack. This name should be something that nobody is every likely to use for another mod. I will be referring to it as *PackageName* from this point on. If I write *PackageName*, always replace it with the name of this package
4. Open Modbuddy
5. Tools -> XCOM 2 Editor
6. Wait for UDK to load
7. Click through the error messages
8. Find the content browser window and get it looking as below

9. In the packages list on the left, start entering *PackageName* until you see the package you copied in
10. Click it
11. Click “Import”
12. Find your music files and select them all. You may wish to store your intro clips in a seperate group. If so, repeat steps 12 and 13 for those separately
13. Under grouping write “MusicFiles” or some such thing. I will be referring to it as *MusicGroup* from this point on
14. CTRL + S to save (if you get a warning about the file being too big, ignore it. We will deal with that later)
15. Using the buttons at the top right of the content browser window, create and undock a second content browser. I will refer to these as “CueWindow” and “MusicWindow”
16. Adjust the windows so that both are open at the same time
17. Navigate to *PackageName*/*MusicGroup in MusicWindow
18. In CueWindow, right click on the cue you want to add a track to (refer to the listing at the bottom of this section for what each cue applies to)
19. Edit using sound cue editor…

At this point the creativity begins. In MusicWindow, CTRL + Click to select the files you want in this cue. Right click in the sound cue editor and click “Random:TheNameOfSomeTrack”. This will add a randomizer and your tracks to the cue BUT they don’t loop yet. If you don’t tell them to loop then they will play once before the game goes eerily silent for a while. Right click again and click looping. this creates a loop node, surprise! You can join up nodes by dragging from one connection point to another. Ultimately you want something that looks like the cue below.

But wait, what about the intros! These two tracks just loop, but if you have tracks which intro and THEN loop you will need to add your intro clip (added the same way as the other tracks except you select SoundNodeWave instead of Random), a mixer node and a delay node.

That menu at the bottom is accessed by clicking Window -> Properties. Click the intro clip and find the duration property. Write it down or remember it. Click the Delay node and fill in both settings with that length of time. The mixer will now play both inputs at the same time, but the delay node will hold off the loop until the same moment that the intro clip ends. Connect the mixer to the randomizer and the randomizer to the big speaker. Your cue is complete.

Note: There is a concatenator node which does the same thing, but it introduces a slight delay.

There are other things you can do to your music with the cue editing system. For example, I have a track which is kind of repetetive, so I set it up to fade into one of the other tracks after it plays 3 times. That is something the Cue-Per-Track method cannot do.

If you don’t want to use a cue, just ignore it. Remember which cues you didn’t use for when we get to the Modbuddy stage.

If you CTRL+ Click nodes you can copy and paste them still connected! That saves a bunch of time, especially if you aren’t changing your geoscape cues for the different chapters.

20. Do the above for each cue. Save often
21. Save again
22. If you are getting the “package exceeds 300MB” message, do steps 23 – 29. Otherwise, skip those steps.
23. Select ~250MB of music files and their intros in the content browser
24. Right click and “Move or Rename”
25. Change Package to *PackageName*Repository1 (or whatever you want that is clear). You may also wish to store these in a MusicFile group
26. Click “Ok To All”. If it keeps asking, keep clicking, but make sure that the package name is still the new one!
27. Find the package you just created and save it. Select the same location that *PackageName* is saved in.
28. Repeat steps 23 – 27 until the main package just contains cues. These files must always move together or your cues will break. If I tell you to move/copy *PackageName*, move/copy the repositories along with it
29. SAVE!
30. Close UDK. We are done with it.

UDK: Cue-Per-Track Method

31. Open Modbuddy
32. Tools -> XCOM 2 Editor
33. Wait for UDK to load
34. Click through the error messages
35. Find the content browser window and get it looking as below

36. Click “Import”
37. Find your music files and select them all. You may wish to store your intro clips in a seperate group. If so, repeat steps 37 – 44 for those seperately. In either case do NOT do steps 40 and 41 for your intro clips
38. Under “Package” enter the package name you will be using i.e. BlahBlahSoundtrackMusicPack. This name should be something that nobody is every likely to use for another mod. I will be referring to it as *PackageName* from this point on. I will be referring to it as *PackageName* from this point on. If I write *PackageName*, always replace it with the name of this package
39. Under “Grouping” write “MusicFiles” or some such thing. I will be referring to it as *MusicGroup* from this point on
40. Under options, tick “Auto Create Cue” and “Include Looping Node”
41. Set “Cue Volume” to 1
42. Click “Ok To All”. If it keeps asking, you keep clicking
43. Select all the cues, right click and go to Sound Classes -> Music. I am nearly certain that this doesn’t do anything, but I am erring on the side of caution

But wait, what about the intros! Your music tracks just loop, but if you have tracks which play an intro and THEN loop you will need to add your intro clip, a mixer node and a delay node.

For each track that needs an intro, right click the appropriate cue and “Edit using sound cue editor…”. Now select the intro track, right click in the newly opened editor and add the file by clicking “SoundNodeWave:YourIntroTrackName”. Right click again to add mixer and delay nodes. Click and drag between the connection points to get something like this:

That menu at the bottom is accessed by clicking Window -> Properties. Click the intro clip a find the duration property. Write it down or remember it. Click the Delay node and fill in both settings with that length of time. The mixer will now play both inputs at the same time, but the delay node will hold off the loop until the same moment that the intro clip ends. Connect the mixer to the big speaker. Your cue is complete.

Note: There is a concatenator node which does the same thing, but it introduces a slight delay.

44. CTRL + S to save. Select a location within the Xcom 2 modding tools content folder. If you get a warning about the file being too large, follow steps 45 – 49, otherwise skip to step 50.
45. If you got a warning Right click and “Move or Rename”
46. Change Package to *PackageName*Repository1 (or whatever you want that is clear). You may also wish to store these in a MusicFile group
47. Click “Ok To All”. If it keeps asking, keep clicking, but make sure that the package name is still the new one!
48. Find the package you just created and save it. Select the same location that *PackageName* is saved in.
49. Repeat steps 44 – 48 until the main package just contains cues. These files must always move together or your cues will break. If I tell you to move/copy *PackageName*, move/copy the repositories along with it
50. SAVE!
51. Close UDK. We are done with it.

Setting Up Your Project In Modbuddy

52. In Modbuddy, create a new mod. Use the Empty Mod template and give it a name that makes sense such as BlahBlahMusicPack. I will refer to this as *ModName* from here on out. Avoid using the same name as your package, not because it matters but because it’s a bit less confusing
53. Enter a title when asked. This is what the mod will appear as in the store. You can change this later so don’t stress about it
54.The description system doesn’t work correctly, so enter something logical there (“A music pack of Blah Blah” for example) and move on
55. Right click *ModName* in the solution explorer and Add -> New Folder. Call that folder “Content” 56. Repeat step 55 for “Config”
57. CTRL + S to save
58. Right click *ModName* in the solution explorer and “Open Folder in File Explorer”
59. Download this set of template .ini files[hallmonitor.ca]
60. Copy those files into the Config folder
61. In another file explorer window, find where you saved *PackageName*.upk . Remember to repeat these steps for all the files if you split it up.
62. Copy *PackageName*.upk into the Content folder
63. In ModBuddy, right click the Content folder and Add -> Existing Item…
64. Find the copy of *PackageName* that you just made and click Add
65. Repeat 63 and 64 for the .ini files in the config folder.
66. (Optional) File -> Export Template and leave everything at default except the name. Next time you create a new music pack, you can select that template and start from this point.
67. CTRL + S to save

Modbuddy: Cue-Per-Situation Method

There isn’t much you need to do here. The .ini files you just added are already nearly configured to see the cues in the packages. Most of the work is done by using find and replace as follows:

68. Click on a .ini file in the solution explorer
69. CTRL + F to bring up the find/replace menu
70. Where it says “Current Document”, instead select “Entire Solution”
71. Click the little arrow to bring up both text boxes
72. In the first box enter ‘TemplateTemporaryModName’, in the second box enter *ModName*
73. Click the “Replace All” Button and click through until it’s happy
74. Repeat 68 – 73 but replace ‘TemplateTemporaryPackageName’ with *PackageName*

That is nearly the whole thing done, but you might need to tweak things in the .ini files. The tweaks you may need to make are as folllows:

• Put a semicolon ; on the start of every line for a cue which you did not assign any tracks to. XCOM will then assume that these lines are comments and ignore them. You must do this to prevent MMS from adding entries that lead to nothing.
• If your cues aren’t grouped under *PackageName*.Cues like the ones in my template are, you will need to adjust the entries to reflect that by either deleting or renaming “.Cues” in the addresses.
• Copy and paste entries a few times, then stick a number on the end of the MusicID for each. If you don’t, your files will rarely play when paired with other packs. See the note on statistics on the end of this section.

Refer to the API section to find out what the different instructions do. Below I’m just listing where you need to put them. Fortunately you shouldn’t need to to much, if anything.

• XComShellsound: This is where we add music for the main menu. Put +ShellCues here.
• XComSkyrangerSound: This is where we add music for the Skyranger loading screens. Put +SkyrangerCues here.
• XComStrategySound: This is where we add music for the HQ, Geoscape and Credits. Put +MusicDefs here.
• XComTacticalSound: This is where we add music for use on missions. Put +CombatDefs and +ExploreDefs here.

Every pack I have looked at uses the Cue-Per-Track system. This means that each track gets its own entry. If you use the Cue-Per-Situation system then you will be giving several tracks only one entry. Imagine you have 2 packs installed which each have 10 tracks for the Geoscape. If one uses the Cue-Per-Track and the other uses Cue-Per-Situation then the former will be used 10 times out of 11. Ideally it should be 50/50.

The upshot: If you want your tracks to get equal play time with other packs, you need to create multiple entries leading to the same cue. It’s a kludge, but it doesn’t have any drawbacks beyond being a bit messy.

Modbuddy: Cue-Per-Track Method

This is where you decide which cues do what. Refer to the API section for a full listing of what you can do, but the gist of it is pretty straightforward and each .ini file contains an entry that you can use as an example to get started.

Open one of the sound .ini files and add the appropriate lines of code based on the list below. You need to add a line for every cue assignment. For example, if you have a cue called “*PackageName*.Music_GreatSong” and you want to use it both for the skyranger loading screens and for combat, you need to add two entries referring to the same cue.

Note that the template entries assume that the cues are stored in a group called “Cues”, hence the address *PackageName*.Cues.Cue_Name. If yours aren’t, you need to delete or rename that part of the entries as appropriate.

It doesn’t matter if your music files are spread across multiple packages, but it’s best to keep all of your cues in one place. If you have a cue stored in a package other than *PackageName* then you need to reflect that when putting that cue in an entry.

Here are the locations where each type of cue assignment should go.

• XComShellsound: This is where we add music for the main menu. Put +ShellCues here.
• XComSkyrangerSound: This is where we add music for the Skyranger loading screens. Put +SkyrangerCues here.
• XComStrategySound: This is where we add music for the HQ, Geoscape and Credits. Put +MusicDefs here.
• XComTacticalSound: This is where we add music for use on missions. Put +CombatDefs and +ExploreDefs here.

Testing & Publishing

75. In Modbuddy, go to Build -> Build Solution
76. When building has finished, open the mod manager and make sure that only your music pack is enabled
77. Play XCOM 2 for a bit to make sure it works in a variety of situations
78. Repeat steps 76 and 77 with at least one other music pack enabled to make sure that your cues still play
79. If everything worked, go back to ModBuddy
80. Create an icon for your pack (it should be square, I use 1024 x 1024)
81. Save the icon as ModPreview.jpg in the Modbuddy folder (the one which contains the folder Config and Content)
82. In Modbuddy, right click *ModName* and Add -> Existing Item
83. Select the icon you just saved
84. Build the mod again (otherwise it won’t have an icon)
85. (Optional) if you want to add tags, iuse notepad to open SteamsteamappscommonXCOM 2 SDKXComGameMods*ModName**ModName*.XComMod
86. Add the line ‘tags= music, soundtrack, whatever else you like’. Whatever tags you add, you must maintain that format exactly or it won’t work.
84. Go to Tools -> Publish Mod
85. Make sure that you are happy with the name. Ignore the broken tags and description sections
86. Upload it
87. Follow the link to your mod (or open it from your workshop)
88. Add a description
89. Add MMS as a requirement
90. Set visibility to public.
91. Done!

Modifying Your Mod

Here are some quick ways to perform simple changes to your mod. Any time the changes you are making involve UDK you need to update the Modbuddy files afterwards. When you have finished and closed the UDK, find your updated packages and copy/paste them over the old ones in the Modbuddy folder. You may wish to save a copy of the old .upks as well. No matter what changes you make, always repeat steps 84 – 91 when you are done to rebuild and publish them.

Follow the same procedure as outlined in the guide for the cue type you are using.

If you want to edit an existing file and reimport it, the best thing to do is to save the new version in the same location that you originally imported from. Then you can simply right click that track in UDK and select “reimport”. Alternatively, drag-and-drop into the package and proceed as you normally would. When it asks if you want to update the file settings click “No To All”.

If you used the cue-per-situation method you may wish to add more cues later. In UDK, click New in the packages menu and select SoundCue. Set the package and group names as needed. Set the cue’s volume to 1. After this you will need to go into Modbuddy and add entries for your new cue using the API.

Thank You!

I hope that this guide has made the music modding system clear. Making it has helped me to clear up a few misconceptions I had about the system, and I feel ready to start pushing it further. I’m sure that there are things I still don’t know about it, so if you have anything more to add please let me know.

Always feel free to criticize and/or ask questions. I welcome feedback!

API (AKA, The Listing of Instructions You Put in the Config Files)

When telling MMS about your cues, you are writing code. Each line adds an entry to the database. The following are the types of instructions you can give, what they do and what arguments they take.

Defines a cue to play at the main menu.

• CuePath: The path to the cue in the mod package.

Defines a cue to play at the main menu.

• CuePath: The path to the cue in the mod package.

Defines a cue to play somewhere in the “strategy” (HQ) portion of the game.

• MusicID=: A unique name for MMS to call the cue. Must be enclosed in quotation marks.
• CuePath=: The path to the cue in the mod package. Must be enclosed in quotation marks.
• dontFadeIn=: Whether or not to fade the track in during transitions. Defaults to false if not included. If you don’t want a fade, set this to = true.
• dontFadeOut=: Whether or not to fade the track out during transitions. Defaults to false if not included. If you don’t want a fade, set this to = true.
• IntroCue=: Enables the built-in MMS track intro system. It is better to do this in UDK cues.
• IntroLength=: The length of the IntroCue track.
• Objective=: A special name required when the group is eSSG_CustomObjective.
• MissionName=: A special name required when the group is eSSG_SquadSelectMission.
• Group=: Which situation to use this cue for, selected from the following list

• eSSG_Chapter01
• eSSG_Chapter02
• eSSG_Chapter03
• eSSG_Geoscape
• eSSG_GeoDoomClock
• eSSG_SquadSelect,
• eSSG_AfterActionFlawless,
• eSSG_AfterActionCasualties,
• eSSG_AfterActionLoss
• eSSG_Credits
• eSSG_Loss
• eSSG_SquadSelectMission
• eSSG_CustomObjective

Defines a set of cues which will be used together during combat in the “Tactical” (on a mission) portion of the game. At a minimum this requires ID and XLoopCue.

• ID=: A unique name for MMS to call the cue. Must be enclosed in quotation marks.
• MissionMusicSet=: A special name which specifies that this is only for a particular type of mission. Must be enclosed in quotation marks.
• EnvReq=(plot=””): A special name which indicates that this entry only applies to one tileset (for example and alien facility or small town).
• XLoopCue=: The path to the cue in the mod package. Must be enclosed in quotation marks. This music will play during combat on the player’s turn.
• ALoopCue=: The path to the cue in the mod package. Must be enclosed in quotation marks. This music will play during combat on the alien’s turn. If this argument is not included XLoopCue will be used instead
• XSting=: The path to the cue in the mod package. Must be enclosed in quotation marks. This music will play if all visible aliens are killed on the player’s turn. Should be short and not looped.
• XSting=: The path to the cue in the mod package. Must be enclosed in quotation marks. This music will play if all visible aliens are killed on the alien’s turn. Should be short and not looped. If XSting is defined and ASting is not, XSting will play.

Defines a cue for use outside of combat in the “Tactical” (on a mission) portion of the game. At a minimum this requires ID and Cue.

• ID=: A unique name for MMS to call the cue. Must be enclosed in quotation marks.
• EnvReq=(plot=””): A special name which indicates that this entry only applies to one tileset (for example and alien facility or small town).
• Cue=: The path to the cue in the mod package. Must be enclosed in quotation marks.
• MissionMusicSet=: A special name which specifies that this is only for a particular type of mission. Must be enclosed in quotation marks.
• IntroCue=: Enables the built-in MMS track intro system. It is better to do this in UDK cues.
• IntroLength=: The length of the IntroCue track.

Environment / Mission Labels

This may be incomplete, WIP. I am still trying to find the objective labels, but I don’t expect those to be used very often.

Environment Types

• CityCenter
• Facility
• Rooftops
• SmallTown
• Slums
• Shanty
• Wilderness

________________________________________________________________________________

Mission Types

• MissionSource_AlienFortress
• DLC
• MissionSource_BlackSite
• MissionSource_Broadcast
• MissionSource_Final (I believe that this applies to the strategy screen, fortress to the mission itself)
• MissionSource_Forge
• MissionSource_PsiGate

________________________________________________________________________________

Cue / Situation Descriptions

These are what the situation options apply to, using the names that I assigned in my template project. These names don’t mean anything to MMS, they are labels I chose because they seem clear to me. However, I do use them in the Modbuddy template so rename them at your own risk.

Shell: Plays over the main menu.

Chapter01: Non-geoscape HQ music until the player builds the Shadow Chamber.
Chapter02: Non-geoscape HQ music until the player kills an Avatar.
Chapter03: Non-geoscape HQ music until the end of the game.
Geoscape: Plays over the geoscape if the Avatar Project meter is not full.
GeoscapeDoomClock: Plays over the geoscape if the Avatar Project meter is full.

SquadSelect: Plays on the squad select screen.
Skyranger: Plays while soldier in the skyranger going to a mission. If the player has the default music turned off and no other music packs then this will revert to SquadSelect.
DropshipIntro: Plays at mission start. By default I have set this to the included “silence” file and feel free to leave it that way. This should be something short and not looped.

Explore: Plays when on a mission but not in combat.
PlayerCombatTurn: Plays when on a mission and in combat on the player’s turn.
AlienCombatTurn: Plays when on a mission and in combat on the alien’s turn. If this cue is not assigned in Modbuddy the PlayerCombatTurn cue will be played or continued. I do not advise using this cue with the Cue-Per-Situation method because the combat tracks will be changing constantly.

XcomTurnSting: Plays when all visible aliens are killed on the player’s turn. This will never play over a track from another music pack. This should be something short and not looped.
AlienTurnSting: Plays when all visible aliens are killed on the alien’s turn. If this cue is not assigned in Modbuddy the XcomTurnSting will be used instead. This will never play over a track from another music pack.This should be something short and not looped.

AfterActionFlawless: Plays after the soldiers have left the Skyranger if the mission was a success and nobody died.
AfterActionCasualties: Plays after the soldiers have left the Skyranger if the mission was a success but somebody died (or was critically wounded?).
AfterActionLoss: Plays after the soldiers have left the Skyranger if the mission was not a success.

CreditsWin: Plays over the credits if the player wins (~7 minutes + time looking at the statistics screen).
CreditsLose: Plays over the credits if the player loses (~7 minutes + time looking at the statistics screen).

There are also mission specific cue types which I have not included in the template. I need to track down the listings for possible objective, mission and environment names. In the meantime, look at the API section of this guide to find details on those cue types. I will add the listings when I have them.