I want to make an XCom 2 music pack!

Cool! You have a choice then. You can make one for the original Music Modding System (in which case check out my guide on that), or you can take the plunge and become acquainted with Wwise Mms for exceptionally baller results.

If you are only interested in porting from MMS to Wwise Mms, check out this simplified guide instead.

What’s the difference?

MMS bypasses the Wwise middleware audio engine and plays music tracks using UE3’s stock system. Wwise Mms packs, as the name implies, play through Wwise and are therefore built using the same tools that Firaxis used.

What is the advantage of using Wwise?
There are a few benefits:

1. The sound cue system is really quite bad if you want the music to do anything more than loop. Check out these screen shots. Both of them loop the same behaviour: select one of three random sections and play a transition section. The left is built using the sound cue editor, the right is built with Wwise. As you can see, Wwise has specific tools for this kind of task. On the other hand, the only reason I can tell you that's what the sound cue version does is because I remember what that track was supposed to do.
   
   
   This simple task pushes the cue system well out of its comfort zone. Elsewhere I have encountered its absolute limits and they are simply not comparable to those of Wwise.
   
   
2. Wwise Mms provides a huge amount of information to you, allowing for the creation of complex interactive music. Want to reduce the bass when the player hasn’t seen the enemy for 3 turns? Easy. Want to add another section that plays only while the player is in the research lab? Go to town. Want to change to a different track when there are more than 5 enemies in view? Yup, not a problem.
   
   
3. You can control transitions as much as you want. If you have a transitional section between your Xcom and Alien combat music you can have that play after the current musical phrase has finished. Or you can fade straight into it. Or you can add a little lead in which will play over the Xcom music before the Alien music starts. Or whatever you can think of really.
   
   
4. You can start playing music on the Skyranger and have almost complete control until the mission ends.
   
   
5. Wwise music doesn’t play over cutscenes (if you follow one simple step). You can also replace the after action music, which MMS does not support.
   
   
6. Wwise music packs can potentially be smaller than MMS ones thanks to some compression tools.

Wow! So why wouldn’t I use it?

There are a few issues.

1. If you don’t want to do anything more complex than loop single tracks then it will be more work to make a Wwise pack.
   
   
2. Wwise isn’t massively complex to use, but there is a learning curve.
   
   
3. Wwise packs require an additional installation step on the part of the end user.

I can deal with that, where do I start?

Below!

There is a lot to cover, so I am assuming for the purposes of this guide that you are already familiar with using Modbuddy and UDK. This information is available elsewhere. I am also not going to go in-depth in the use of the Wwise authoring tools, because the website has reasonably good documentation (bearing in mind that some of it only applies to newer versions). This guide is here to cover:

• How to get Xcom to see your Wwise events
  
• A collection of tips to get you started with the Wwise authoring tools
  
• The theory and usage of Wwise Mms
  
• Troubleshooting

• The XCom 2 mod tools.
  
• A free AudioKinetic account
  
• Wwise v2014.1.6[www.hallmonitor.ca] for vanilla/LW2, and Wwise v2016.1.6[www.audiokinetic.com] for WotC. For 2016, install the launcher and select the correct version. For 2014, extract and run .\Authoring\x64\Release\bin\Wwise.exe.
  
• The Wwise Mms Resources Package[hallmonitor.ca]
  
• The alternative mod uploader. (The stock uploader will throw errors when you try to patch Wwise Mms packs)
  
• .WAVs of your music

Formerly it was only possible to export sound banks for vanilla. However, the tools to export for WotC have become available, so it is now possible to support both. There are some new features in Wwise 2016.1.6 that would be nice to have, but personally I would rather support both (particularly because I like LW2 quite a lot). Once you save assets using either the WotC mod tools or Wwise 2016, those assets will never work with vanilla again. You cannot re-export to the older version.

If you want to support both, use the vanilla mod tools and the Wwise 2014. Whenever you want to publish, copy your Wwise project and open the copy in Wwise 2016. Export the banks. Done.

One version of your mod can work in both vanilla and WotC at the same time. Include both sets of sound banks, and have users copy them to the appropriate CookedPCConsole folder for each version. You don't need to duplicate your .UPKs, everything will work as-is as long as you include both sets of banks.

The UDK Bit

XCom 2 doesn’t learn about Wwise events directly; instead it looks in unreal’s .upk files. These files contain a listing of events and the “sound bank” that contains them. When Xcom is told to play an event from a .UPK it then goes to the /CookedPCConsole folder to find the bank and only then does it see the actual audio. The upshot is that you need to create a .upk in the mod tools which mirrors your Wwise project. The following paragraphs will explain how this all works while helping you to play some music over the main menu.

Before even opening Wwise, go into UDK and create a new AkEvent with a unique name in a new package with a unique name. You will note that it automatically creates an AkBank called “WwiseDefaultBank_ThePackageName”. If you browse the game’s asset files you will also note that many of the bank names follow that format. There is no technical reason that you need to use that name, but it’s easier than fighting with UDK. All of the events you create in that package will automatically refer to the default bank.

You only need one event to play some menu music, so remember what you called it and save the package. Close UDK and open Wwise.

The Wwise Bit

Go to the audio tab of the project explorer. Drop a music track into the default work unit of the interactive music hierarchy and click through. Next, go to the events tab and create an event in the default work unit. Give it the same name as the one you used in UDK. Add the event action “Play” and click browse to find your music track. Click the play button to make sure that this has worked.

Now we need to create a sound bank.

1. Go to the sound banks tab and create a new one.
   
2. Give it the same name as the one in your package, “WwiseDefaultBank_BlahBlah”.
   
3. Open the sound bank editor by going to Views -> SoundBank Editor.
   
4. Drag the work units for both your event and music track into the “Add” section.
   
5. Right click your sound bank and click “Generate Sound Bank(s) for current platform”.
   
6. Wwise will do some stuff and then warn you that you aren’t allowed to make any money on your mod.
   
7. Click through, then right click the bank again and select the bottom “open containing folder” option.

There will be a bunch of files in the folder that opens. Copy the .bnk and its associated .txt files. Do not copy over anything else; overriding the stock init file is very, very bad. Paste these files into \Documents\My Games\XCOM2\XComGame\CookedPCConsole or the \CookedPCConsole folder in your XCom 2 installation (if you are using WotC, note that it has its own CookedPCConsole folder which you must use instead of the base game folder). This is the install step that users will need to do, but later I will show you a better way of doing it for release.

The ModBuddy Bit

If you have never used ModBuddy before, check out my MMS guide for more in-depth instructions on that. ModBuddy is weird, it doesn’t work quite like you think.

Create a new ModBuddy project. Do the usual config stuff for new mods. Put your .upk in the content folder and create "XComWiseSound.ini” in the config folder. Paste this into it:

If you aren’t familiar with config editing, you are going to need to become so. Here’s how it breaks down:

The top line indicates that we are going to add stuff to the Wwise Mms UIShell defaults.

• “+” indicates that we are adding an item to an array (colloquially a list), in this case the array “WiserShellCues”.
  
• “=(” indicates that we are starting the definition of the thing we are adding to the array here.
  
• “\\” indicates that we will be continuing this definition on the next line.

From there we add parts to the definition being put into the array. The comma indicates that there is another part coming. It may seem odd that I put the comma at the beginning of a line instead of at the end of the previous one, but trust me it is better. You could also put the whole thing on one line if you wanted, but you will quickly find that this would be a poor decision.

Replace the MusicID with something unique. This is the name that Wwise Mms will use to identify your definition so it has to be “safe”. That's why I put my name in it. What are the odds that another Adrian will make a System Shock music pack?

Replace the "Start_EventPath" with the package.event address which matches your .upk event.

The XCom 2 Bit

Save the project and build it, you are ready to go! To recap, you should have:

• MMS and Wwise Mms enabled
  
• No other MMS or Wwise Mms music packs enabled
  
• Your ModBuddy project set up properly
  
• A .upk containing a listing of your event
  
• An XcomWiseSound.ini containing your music definition
  
• A Wwise sound bank matching the .upk, placed in one of the CookedPCConsole folders

When you get to the main menu you should hear your music play...

...once...

...if you want it to loop, you must enter the wide world of Wwise.

Back in Wwise, press F10. This will put you in the interactive music design view. All of the views are fully configurable, but this contains what you need for now. In the project explorer, create a playlist item and drop your music track into it. Now open the playlist and drop your music track into that. Set the number of repeats on the container from 1 to infinite (click the down arrow as though you were going to set it to 0). Now you have an infinite loop, but your event is still connected to the audio track which just plays once. Go to your event and set it to play your looping playlist instead of your audio track. Regenerate the sound bank, paste it over the old one and start the game again. You should now have looping music.

This is the core of how you will work with Wwise, creating tracks, playlists and switch containers which are activated and modified by events that will be called by the game. From this point on I am not going to direct you on specific tasks. Instead I am going to introduce some concepts and provide some advice.

Setting Up Your Workspace

Before you move on, I suggest starting to modify the interactive music layout to your liking. I use this, but I am fortunate enough to have a triple monitor set up:



The big panel on the right is the “soundcaster” view, which is hugely useful because it allows you to simulate actually playing your events in-game. Outside of it you can only call one event at a time and set some values manually.

You will want to turn off the “Original” toggle next to the play button. Wwise maintains both copies of your original .wav files and the converted ones which are added to your soundbank. Monitoring the converted ones will tell you if there is a problem with your conversion settings. With this toggle off, you will need to convert your music after importing it (either through “Project -> Convert All Audio files” or by adding them to a sound bank and generating it).

You don’t need to use the default work units. Just remember that if you create a new one you will need to add it to the sound bank. What you DO need is a naming system. As I will explain more thoroughly in the troubleshooting section, events with the same name (even in different projects) can lead to problems. You must therefore use event names which are unlikely to be used by anybody else. You will also need to enter all of these into your .upk, so something with an easy-to-modify pattern is preferable. Using a spreadsheet to keep track of what does what is not a bad idea.

The audio busses are essentially virtual mixing boards. The game manipulates them to make certain parts quieter or louder depending on what is happening. In order to stop your music from playing through cutscenes, you need to put it on the correct bus. Create a structure like this:



I’m not sure what the difference is between the normal and no_filter busses, but I just put everything on the appropriate no_filter. You can set the default bus in “Project - > Default User Settings”. The playlist you already created will need to have its bus set in the property editor. For a full list of busses built into the game (and many interesting things besides), find the “Xcom 2 Init.txt” file.


These are basically your information units. Some of them are set by the game, others are entirely controlled by your events.

Switches
These are used to switch between different parts of a single switch statement or switch track. For example, you might have a “CombatTurn” switch which alternates between XCom, Civilian and Alien turns during combat.

States
These are like switches but they can control more stuff. They are also global, where switches only apply to the object that ran them (for your purposes this means that states can affect the whole audio system while switches only apply to the music system).
In order to use states, you must do some additional setup as described in the relevant section below.

RTPCs
These are variables, mainly used to make a particular part of your music louder or quieter. There is a list of RTPCs that Wwise Mms sets in the resources package. All you need to do to access one of these RTPCs is add one with that name to your project.

Trigger
These are used to fire one-off sounds in your music. I don’t use them. Like RTPCs there is a listing of these in the resources package.


There is a great deal that Wwise can do and I can’t cover all of it, but here are some things that you will probably want:

• In the music segment editor, right click the time bar and select “bars and beats”. Go to the parent object and set the BPM. You can now use musical terminology to do stuff!
  
• In the music segment editor, right click a track and observe the existence of the switch and step types.
  
• The Property Editor’s “Transitions” tab is hugely important.
  
• Selecting multiple items and pressing CTRL + M opens the Multi-Edit menu. This doesn’t do everything, but it’s a start. Unfortunately batch renaming wasn't added until a later version. A macro editor like Mouse Recorder Premium[mouserecorder.com] can sometimes help to overcome the limitations of multi-edit.
  
• Switches can derive their definitions from RTPC values which could save you from having to create many events.

Your Wwise sounds won’t play if you don’t put them in a config properly. Just like MMS, there are points in the game when Wwise Mms will look at its list of definitions and select a new piece of music to play. However, the way it looks can be very different. The logic is as follows:

1. The player has opened the Geoscape! I need to do something.
   
2. Has the current music definition been playing longer than its “lifespan” setting?
   
3. No, so I’ll look to see if it has a Geoscape_TransitionEventPath.
   
4. I haven’t found a transition, so I’ll pick randomly from a list of music definitions which are either MMS definitions for the Geoscape or Wwise Mms definitions with a Geoscape_StartEventPath.
   
5. Stop the old music definition.
   
6. Start the new music definition.

This means that while MMS definitions can be thought of as single tracks that are randomly selected , Wwise Mms definitions are more like programs with multiple entry points. Your definition may be asked to start during the "XCom Concealed section", but with the right transitions it might play all the way to the end of an "Alien Combat" section.


Xcom 2 is divided between the Strategy and Tactical portions, with a Skyranger loading screen in between. Wwise follows a similar divide, but it is shifted slightly. The colours of the circle in the image below illustrates the scope of Wwise Mms definitions.


The Tactical logic of Wwise Mms starts in the Skyranger on the way to a mission, and the Strategy logic starts when the mission ends in the Tactical screen. Because of the way configs are read in, a separate definition entry is required for each of those transitional sections, hence the four colours used. Because of the way loading works, the music stops and has to be restarted on the changeover from Tactical to Strategy. If you listen carefully with the stock music on you will hear that the After Action track restarts as the skyranger lands.

At present the music may stop when the screen goes blank during transitions. I'm working on this issue but I'm not sure if it can realistically be solved. This will be worse if your skyranger media files are from a different soundbank than the ones they are transitioning into.


Your start event path needs to actually start your track. If the transitions do that you will get two tracks playing at once. Any time a config variable ends “_StartEventPath” it requires a track start, any time it ends with “_TransitionEventPath” you do not need a track start...unless you are doing something weird, in which case all the power to you!

Stopping is handled automatically unless you specify a path for your own track ending. Custom endings should be quick because Wwise Mms will start playing the next track immediately even if your ending is still playing.


Note that the examples below do not contain full path names. The reason will become clear soon.

If a variable ends in “_EventPath” then it is an optional parameter which will fire when certain conditions are met. If you leave these blank Wwise Mms will just ignore them. These come in 3 flavours:

string
You assign one path for the event in your definition.

Автор сообщения: Example

, ScanningCompleted_EventPath = “SSC_FinishedScanning” \\

<string>
This is an array of strings. When an RTPC changes, Wwise Mms will look at this array for an event to call for that number. If it doesn’t find one it will check the next lowest number and so on. If it finds an event it will call it. If you want it to stop at a number without doing anything, set that path to “IGNORE”.

These entries are put in one at a time as seen below

Автор сообщения: Example

TurnsRemainingCount_EventPaths[1] = “SSC_OnlyOneTurnLeft” \\
, TurnsRemainingCount_EventPaths[2] = “SSC_OnlyTwoTurnsLeft” \\
, TurnsRemainingCount_EventPaths[3] = “IGNORE” \\
, TurnsRemainingCount_EventPaths[5] = “SSC_StillTimeToGo” \\

<NAP>
NAP stands for Name and Path. This is an array used for events which you may want to fire when a particular thing is true, such as a mission family name. “theName” should be the thing’s name, “thePath” should be the path to call. Where appropriate these will be called immediately after your definition's start event.

These are not hard coded, so (for example) if a mod adds new mission family names Wwise Mms will support them automatically.

Автор сообщения: Example

Mission_EventPaths[0] = ( \\
theName= “ProtectDevice” \\
, thePath = “SSC_ProtectDeviceMission” \\
)

Variables Common To All Definitions

MusicID
The name of this definition. This is more important in Wwise Mms than it is in MMS. It is critical that these be unique.

Lifespan
Because it is possible for a single definition to play for an entire mission, this variable places a limit on how long your definition can play. If the lifespan timer expires, Wwise Mms will ignore any transitions you have entered for this definition and instead find a new one (which is guaranteed not to be the current one). The default is 480.

Append:
Whatever you put in here will be put at the beginning of all your paths for this definition. Usually you will want to put your .upk name in here. This saves you from having to write out the same text 4 billion times. This is why my examples do not include full package addresses.

End_EventPath
Exactly as it sounds, this will be called instead of a generic stop when your definition ends. The transition and and shell definitions do not have this variable.

Other Variables
See the resources package for a listing of the other variables for each mission. They have usage descriptions where their use is not deeply obvious.

You’ve finished your sweet music pack and you want to share it with the world. You can post it on Steam Workshop, but nobody will be able to hear the music except you because those sound banks need to be moved to the correct folder on the user's computer. The best solution I have come up with is to put your banks in the Content folder and provide the user with a .BAT file that creates hard links to your files.

A hard link is like a shortcut, except that programs can’t tell the difference between it and the real file. This means that your sound banks can stay in the Workshop folder and you can push updates for them. I also include a few empty banks so I can add more if I need to.

After you have published your mod, but before you have made it public, open the .BAT file provided in the resources package using a text editor. It will contain two lines which make links, one of which is:
The first address is where we will be putting the link, the second is what it points to. All mods for XCom 2 go in the folder 268500\ModIDNumber, so you will need to get your number before you can create the file.

Go to the steam page for your mod and get the id number from the URL (in the case above that would be https://gtm.steamproxy.vip/sharedfiles/filedetails/?id=1232201493). Replace the number in the .bat file with your id number and replace “SomeBank” with the path to one of your banks within your mod. Copy this line, paste it and modify as needed for each bank you are using.

The second link does the same for WotC. Follow the same process as above, just with the different folders.

Provide this .bat in the mod description. Users must put it in their steam folder and run it to create the links.

Linux and Mac don't support .bat files and may require you to export the banks differently. If I sort this out the guide will, of course, be updated.

In Wwise, states allow some behaviour that cannot be achieved any other way. However, they are not included in your sound banks. In fact, if you generate a sound bank that uses states anywhere, nothing in the sound bank will play. There is another bank you must include to enable your custom states.

When you generate your sound banks, an additional sound bank called "Init" is created. This contains the information about what states your bank uses. Because the base game already has an Init bank, you must change the name of your Init bank to something else. It will still be read and you will be able to use custom states. When you distribute your music pack, include this file in the .BAT file that you distribute.

Wwise, as shipped with any commercial game, is a black box. Usually the only sign you will get that something is broken is a total lack of music. Fortunately Wwise Mms prints a great deal to the log, so you can quickly identify if the issue is with your sound bank or your config. I leave notepad++ permanently open to \Documents\My Games\XCOM2\XComGame\Logs\Launch.Log. All Wwise Mms logs start with the words “wwise mms”, so CTRL+F is your friend.

If nothing is happening but Wwise Mms believes that it is playing your file, then something is probably wonky with your bank. Aside from perhaps finding a message that an AkEventPlayer tried to play an event that doesn’t exist, trial and error is your only tool. Having gone through quite a lot of that, here are my tips for starting out:

• Make sure that the event plays properly in the Wwise authoring tools
  Durr.
  
  
• Ensure everything is actually in your sound bank
  Again, durr. Just drop the whole work unit in unless something in it is broken.
  
  
• Try to just play the sound on the main menu
  Durrrrrrrrrrr.
  
  
• Don’t convert to Ogg Vorbis
  If you want to play a long track on the main menu it might be ok, but in general it does not work very well. I rewrote the whole StrategySoundManager event playing system hunting down a bug that turned out to be normal Vorbis behaviour. Use PCM or ADPCM instead.
  
  
• States are weird
  In order to use a bank that uses states anywhere, you must load in the init bank. Check the relevant section for instructions about doing this.
  
  
• I think there is a bank size limit
  Not 100% sure, but if you are pushing 90 MB try removing something or compressing more heavily.
  
  
• Events, playlists and source files with the same name are bad news
  I have had issues when two banks are loaded containing stuff with the same name. Wwise is not prepared for this possibility because it expects all banks to come from the same project. It seems to always play the first thing that was loaded. I use a unique prefix for the events in each of my packs.
  
  
• The event that doesn’t play may not be the issue
  Something broken in one part of a package can cause the whole thing not to work. I think that Wwise loads in the whole bank when you play one event. If something that really should be working is not playing, take everything else out of the sound bank and see if it works then. If it plays, start adding one thing at a time until you find the problem.

If you are unable to update the sound banks for your mod after publishing, ensure that you are using the alternative mod uploader. Modbuddy can post the sound banks when first publishing, but I haven't been able to update existing soundbanks with it.

Because it is config driven I can add new event, trigger and RTPC types to Wwise Mms without breaking old packs. If there is something you want that isn’t available, let me know and we can see about adding it. That said, if you are handy with Unrealscript you can add such things yourself without overriding my classes. The active event player and music definition are available to be accessed from anywhere.

Oh yeah, please don’t try to override the Wwise Mms sound managers. I am already overriding the MMS ones, which isn’t even something you are supposed to be able to do. Trying to make an override train is going to start leading to questionable stability since you will need to do your override somewhere after OnTemplatesCreated() which means that Wwise Mms will already have started doing stuff.

I hope you have fun playing with Wwise. If you have any questions or find anything cool, please don’t hesitate to contact me! Wwise Mms took a huge amount of time and effort and I am hugely excited to help people make use of it to create awesome stuff.