feat: Wwise documentation

modules/ROOT/pages/Development/Satisfactory/Audio.adoc

@@ -7,14 +7,219 @@ This page is a work in progress.
 
 == Wwise
 
-TODO
-
 Coffee Stain uses the Wwise audio system to play sounds in Satisfactory.
 
-At the time of writing it is very difficult for modders to interface with Wwise systems,
-so you should use Unreal's built in sound system instead.
+To create new audio events to play in your mod, you will need the Wwise project set up and integrated into the SML project.
+
+=== Setting Up Audio Buses
+
+By default when using Wwise audio only the `Master` volume slider will work.
+
+You will need to manually create the different Audio Buses that link to the other sliders.
+
+TODO: Waiting for CSS to provide the correct audio bus names.
+
+=== Importing Media Files to Wwise
+
+Open the Wwise project file, typically in `SMLProject/SMLProject_WwiseProject/SMLProject_WwiseProject.wproj`. Double-clicking this file will open Wwise.
+
+To make sure you are in the correct layout at the top, go to `Layout -> Designer`
+
+On the left-hand side, you will see the project explorer; select the Audio Tab.
+
+image:Satisfactory/Wwise/Wwise_Import_PorjectExplorer.png[Wwise_Import_PorjectExplorer, 350]
+
+Under `Actor-Mixer Hierarchy`, there will be `Default Work Unit`
+
+To keep everything organized, create a new Virtual Folder and name it the same as your mod:
+
+image:Satisfactory/Wwise/Wwise_Import_VirtualFolderCreate.png[Wwise_Import_VirtualFolderCreate, 600]
+
+Now, to import audio files!
+
+Drag your `.wav` files into this newly created Virtual Folder. The `Audio File Importer` window will show.
+
+image:Satisfactory/Wwise/Wwise_Import_ImportWindow.png[Wwise_Import_ImportWindow, 600]
+
+Ensure that you have `Create New Objects` selected under import mode. Verify it is going to the correct folder and then click `Import`
+
+That's It. Your audio files are now imported to Wwise!
+
+=== Creating Audiokinetic Events
+
+Audiokinetic Events trigger audio events like Play, Pause, Stop, etc.
+These are typically referred to as `AKEvents`
+
+To play the audio in your mod, you will need to create an event in Wwise. First, make sure that you have followed the above steps to import your `.wav` files to Wwise.
+
+In Project Explorer, go to the Audio tab and locate the audio for which you want to create an event.
+
+Right-click the audio and select `New Event -> Play`. This will create a new Play event.
+
+image:Satisfactory/Wwise/Wwise_AkEvent_Create.png[Wwise_AkEvent_Create, 600]
+
+In the Project Explorer, go to the Events tab, and you should see the event `Play_<AudioName>`.
+
+Double-clicking the event will show the Event's details in the main center section.
+
+There are a few things to take note and verify:
+
+* Take a note of the Event ID (Marked in Red)
+* Make sure that Inclusion is checked (Marked In Green)
+* Verify that the target is for the correct audio (Marked In Blue)
+
+image:Satisfactory/Wwise/Wwise_AkEvent_Info.png[Wwise_AkEvent_Info, 600]
+
+Repeat the process for all other audio you want to play in your mod.
+
+[NOTE]
+====
+Create a new Virtual Folder to store the Events for ease and organization.
+====
+
+=== Creating Audiokinetic Soundbanks
+
+You will need to create a new Soundbank for all your Events to be stored.
+
+In Wwise, change the layout to Soundbanks. This can be found at the top under `Layouts -> Soundbanks`.
+
+Select the `Soundbanks` tab in the Project Explorer on the left.
+
+
+By default, you will have the following tree structure:
+
+image:Satisfactory/Wwise/Wwise_Soundbank_ProjectExplorer.png[Wwise_Soundbank_ProjectExplorer, 600]
+
+Create a new Soundbank by Right-clicking the `Default Work Unit` then `New Child -> Soundbank`
+
+image:Satisfactory/Wwise/Wwise_Soundbank_Create.png[Wwise_Soundbank_Create, 600]
+
+Name the Soundbank `ModName_Soundbank`. This is optional and can be named however you want.
+
+Double-click the newly created Soundbank, which will open in a new window.
+
+In the main Wwise window, navigate to the Events tab in the Project Explorer.
+
+With the Soundbank window still open, drag the `Default Work Unit` or, if you created a Virtual Folder for your event, drag this to the Soundbank window.
+
+image:Satisfactory/Wwise/Wwise_Soundbank_Window.png[Wwise_Soundbank_Window, 700]
+
+Go to the `Edit` tab to verify that all the events are included in the Soundbank.
+
+image:Satisfactory/Wwise/Wwise_Soundbank_EditTab.png[Wwise_Soundbank_EditTab, 600]
+
+Now, it's finally time to generate the Soundbank for Unreal Engine.
+
+In the Project Explorer, on the Soundbanks tab, right-click on the soundbank and click `Generate Soundbank(s) for all platforms`.
+
+image:Satisfactory/Wwise/Wwise_Soundbank_Generate.png[Wwise_Soundbank_Generate, 500]
+
+=== Creating AKEvents In Unreal Engine
+
+Open the Unreal Engine project settings and Navigate to the Wwise integration settings.
+
+Change the `Root Output Path` setting to `<WwiseProjectPath>/GeneratedSoundBanks`.
+
+Then Change the `Unreal Audio Routing` to `Both Wwise and Unreal audio`
+
+You may need to restart Unreal after these changes.
+
+Once your audio, event, and soundbanks are created, it's time to utilize them in the Unreal Engine.
+
+Create a new Audiokinetic Event by right-clicking on an empty area in the Content Browser.
+
+Go To `Audiokinetic -> Audiokinetic Event`
+
+image:Satisfactory/Wwise/Wwise_UEAkEvent_Create.png[Wwise_UEAkEvent_Create, 500]
+
+Name the new asset **Exactly** the same name as the event in Wwise.
+
+[NOTE]
+====
+If the asset name is exactly the same as the Wwise event, Unreal Engine will automatically populate the correct event information to the variables below.
+====
+
+Verify that the event has the correct information by opening the event in Unreal.
+
+* Verify that the `Wwise Short ID` matches the event ID in Wwise.
+* Verify the `Wwise Name` matches the event name.
+
+image:Satisfactory/Wwise/Wwise_UEAkEvent_Verify.png[Wwise_UEAkEvent_Verify, 500]
+
+If everything has worked correctly, you can now test the event by right-clicking the event in Unreal and clicking `Play Event`
+
+=== Playing AKEvents In Blueprints
+
+==== Fire & Forget Events
+
+If you would like to play a one-off AK event, such as a spark sound, you will need to use the following method in your blueprint.
+
+image:Satisfactory/Wwise/Wwise_UEAkEvent_FireAndForget.png[Wwise_UEAkEvent_FireAndForget, 100%]
+
+This will first create a new `AK Component` at the blueprint's root component and then play the AK Event specified.
+
+Once the AK event has ended, you must clean up the `AK Component` using the callback event.
+
+==== Looping Events
+
+If you would like to play a sound effect that might loop, for example, a humming/buzzing sound for a building.
+
+The best method is to add an `AK Component` to your blueprint and set the `AK Audio Event` variable on the component.
+
+You must ensure that you stop the event when the actor is destroyed.
+
+image:Satisfactory/Wwise/Wwise_UEAkEvent_EndPlay.png[Wwise_UEAkEvent_EndPlay, 100%]
+
+
+=== Setting Up Attenuation
+
+If you plan to use Wwise audio for buildings, you will need to set up attenuation. By default, the audio will play even if you are on the other side of the map.
+
+Wwise has a great tutorial on how to set this up here: https://youtu.be/lOP0seni1DY[Wwise & Unreal | Adding 3D Audio With Attenuation]
+
+=== Updating Wwise Values From Your Mod
+
+Wwise uses a feature called Real-Time Parameter Control (RTPC) that allows game engines like Unreal or Unity to change values on the Wwise software in real-time.
+
+An example of this would be if, for example, you have a building and want the sound volume to fluctuate based on the recipe's progress.
+
+You can set up an RTPC in Wwise and Unreal and update the value in your building's blueprint.
+
+To set these up, in your Wwise project, go to Project Explorer and the `Game Syncs` tab.
+
+Under `Game Parameters -> Default Work Unit` create a new game parameter by right-clicking the `Default Work Unit` and then `New Child -> Game Parameter`
+
+image:Satisfactory/Wwise/Wwise_RTPC_Create.png[Wwise_RTPC_Create, 100%]
+
+Name this whatever you want.
+
+Open the newly created Game Parameter, and you should see the following in the main section.
+
+image:Satisfactory/Wwise/Wwise_RTPC_Range.png[Wwise_RTPC_Range, 100%]
+
+You will need to set the range. I recommend using 0 to 1.
+
+Now, assign the RTPC Game Parameter to your audio.
+
+Open your Audio and go to the `RTPC` tab. Click the `>>` in the main section to set what you want to update. In this case, I want to update the `Voice Volume`.
+
+Then click the `>>` to the right of the first one and select your game parameter.
+
+image:Satisfactory/Wwise/Wwise_RTPC_Configure.png[Wwise_RTPC_Configure, 500]
+
+Once that is done, you should see something similar to the following:
+
+image:Satisfactory/Wwise/Wwise_RTPC_Overview.png[Wwise_RTPC_Overview, 100%]
+
+Now, to create the link between unreal engine and Wwise you will need to create the Game Parameter in Unreal Engine.
+
+image:Satisfactory/Wwise/Wwise_UERTPC_Create.png[Wwise_UERTPC_Create, 600]
+
+Name it the same as you have in Wwise.
+
+You can now update the RTPC Game Parameter value using blueprints:
 
-The SML team is working on enabling modders to interface with Wwise.
+image:Satisfactory/Wwise/Wwise_UERTPC_Usage.png[Wwise_UERTPC_Usage, 700]
 
 == ADA