Wwise SDK 2022.1.8
Motion is a feature allowing users to control the haptic feedback of a control interface. With Wwise, you can manage motion using the same feature set that you use to manage the audio in your application. Internally, motion data is no different from audio data. This means that all the features available for audio are also available for motion. Two types of haptic feedback are available using the Wwise motion feature. You can either use any audio signals in your project and transform it into motion or generate dedicated motion signals using the Motion Generator source. This feature can be tested directly in the Wwise authoring tool on Windows with a supported controller.
Motion uses the Wwise Sound Engine plug-in system in order to work in an application and can be subdivided into two modules: the audio source called Motion Generator and the Audio Device called Wwise Motion. Although the Motion Generator is optional, it remains a powerful tool to create accurate and flexible motion designs.
The Motion sink plug-in can be seen as the link between the sound engine and a motion-ready device. Just like any sink plug-in, it receives data from a set of Listeners and is in charge of "presenting" this data to a device. This plug-in is inside a separate library and needs to be included in both the authoring tool and the application. Refer to the Setting Up Motion section for more information.
The Motion source plug-in is a very useful and accurate way to design the behavior of haptic feedback effects. Just like any audio source, you can add a Motion source plug-in to a Sound SFX node in your Wwise project. Make sure that the Sound SFX nodes have an Output Bus set to a motion-ready bus. Refer to Motion for more information.
In order to use motion in your application, you need to properly set up each component. Note that all the concepts applicable to the audio workflow are also applicable to motion. It uses the same busses, Listeners, and Emitters (see Integrating Listeners).
To be able to send either sound or motion data to a device, you need to add the licensed Wwise Motion Audio Device to the Audio Device folder of your Wwise project, located in the Audio tab of the Project Explorer. The Wwise Motion Audio Device is the plug-in used by the sound engine to interface with a motion-ready device. It is also crucial to assign the Wwise Motion Audio Device to a top level Audio Bus. The term motion bus denotes, for simplicity's sake, a top-level Audio Bus with a Wwise Motion Audio Device assigned to it. It's good practice to use a single motion bus hierarchy in your project for easier troubleshooting and monitoring. You can now set the Output Bus of any Sound SFX to a motion bus to create haptic feedback. Usually the Sound SFX elements using a motion bus are also using a Motion Generator source. To simultaneously have audio and motion, a Sound SFX needs to have at least one motion bus and one Audio Bus, either as the Output Bus or as an Auxiliary Bus.
On the game side, the first thing that you will want to do is make sure to link with the separate library called
AkMotionSink. This library provides support for the standard controllers of supported platforms. You also need to include the AkMotionSinkFactory.h file located under
SDK\include\AK\plugin. Including this file is really important because it will automatically register the plug-in.
Note: In Unity and Unreal, plug-in libraries are managed automatically. You don't have to add
Refer to the following table for the list of supported controllers and additional requirements.
|Platform||Device||Device Channel Config and Layout||Additional Requirements|
|Android||Android device with vibration support||Anonymous 1-channel|
|PlayStation 4||DUALSHOCK 4
Left motor, right motor
Left vibration, right vibration
|Stadia||Stadia-compatible Gamepads||Anonymous 2-channel:
Left motor, right motor
Left low-freq vibration, left high-freq vibration,
right low-freq vibration, right high-freq vibration
|Windows||Xbox and XInput-compatible Controllers
Left motor, right motor
|UWP||UWP Gamepad||Anonymous 4-channel:
Left motor, right motor,
left trigger, right trigger
Xbox Series X
|Xbox Controllers||Anonymous 4-channel:
Left motor, right motor,
left trigger, right trigger
If your application uses motion with one or more devices, you must add a dedicated output for each device. For example, a split-screen game with four players connected needs four different outputs for the controllers to receive haptic feedback. To add an output device, use the Wwise API function
AK::SoundEngine::AddOutput and specify the ShareSet name (as defined in your Wwise project) in the
AkOutputSettings parameter. Additionally, because multiple devices can be connected, you need to provide a device ID. Refer to the following table for more information on device ID.
|Android||Android device with vibration support||Use 0.|
|PlayStation 4||DUALSHOCK 4 and PlayStation Move||Use the handle of the device returned by scePadOpen or scePadGetHandle.|
|PlayStation 5||DualSense and VR Controllers||Use the handle of the device returned by scePadOpen or scePadGetHandle. For PSVR2, only one output device should be created, using either the handle for the left or right VR controller, to have vibrations on both VR controllers. If a device ID of 0 is specified, then the system will only be initialized for the wireless controller, and not the VR controllers.|
|Stadia||Stadia-compatible Gamepads||Retrieve the DeviceID of a gamepad by calling
|Switch||Joy-Con||Use nn::hid::NpadId with the desired index.|
|Windows||Xbox and XInput-compatible Controllers||Use the player index between 0 to 3.|
|Windows||DirectInput-compatible Controllers||Use the guidProduct stored in a DIDEVICEINSTANCE. Hash the guidProduct by using an
|UWP||UWP Gamepad||Retrieve the DeviceID of a gamepad by calling
|Xbox One (XDK)||Xbox Controllers||Use the ID stored in a IGamepad object.|
|Xbox One (GDK)
Xbox Series X
|Xbox Controllers||Retrieve the DeviceID of a gamepad by calling
|Note: On all platforms except for Windows, simply specifiying a device ID of "0" will target the first available device that supports motion.|
Keep in mind that a game controller can be disconnected either physically or through communication problems. It will not have any adverse effects on the sound engine other than needlessly using resources. If you think a device has been disconnected for a long period of time, you should call
AK::SoundEngine::RemoveOutput and provide the AkOutputDeviceID returned by the corresponding
AddOutput() function call.
Motion outputs are just like any other Secondary Outputs, therefore have the same restrictions and requirements. If you are making a single-player game, meaning only one player is controlling the game locally, the Listener/Game Object setup is very simple. In normal cases, the new motion output will re-use the same default Listener as the main audio output. In short, you rarely have to manage Listeners in a single player setup.
If making a multiplayer game, you will need to create one Listener/Game Object per motion output. This is necessary so that players each have their own mix of haptic feedback, depending on the in-game situation. The Listener associated with a device must be initialized at the same time as the output is initialized by
AK::SoundEngine::AddOutput(). Specific Listeners provide an additional layer of routing for sounds or motion. You can target a specific player if you play an Event on a Game Object that is uniquely associated with that player's Listener. This association can be done by calling
AK::SoundEngine::SetListeners. See Integrating Listeners for more information about Listeners and Game Objects. Note that you can also associate multiple listeners with the same game object, resulting in a "broadcast" effect on all listeners.
|Note: A sound needs to be routed into the motion bus hierarchy even if the Emitter as a Listener set to a motion output.|
The following examples will provide information on how to set up your application to use motion. You can also refer to the Demo Motion of the Integration Demo (DemoMotion.cpp) included in the SDK samples. It provides working examples for all the supported platforms.
First, some general plug-in management: as with any other plug-in, you need to include the corresponding file and link the library. (This is for Wwise native development, only. Ignore this on Unity.)
Then add an additional output with the Motion ShareSet name you gave in the Wwise project, in this case "Wwise_Motion". We use 0 for the output ID because we want to use the first connected game controller.
Then play an Event, as per usual. In the Wwise project, the "Play_Explosion" Event would point to a Sound SFX that is routed to a bus that has the "Wwise_Motion" ShareSet assigned as its Audio Device.
To be clear, the multiplayer case means "multiple players on the same console", and not a "networked multiplayer game". In multiplayer scenarios, the mix for motion, or any player-specific output, needs to be different to represent the player's perspective in the game world. To do so, players will each need their own Listener.
Then add an output for every player. You don't need multiple ShareSets; each ShareSet can be used multiple times. You need to provide a real device ID for every controller. This example is for Xbox controllers on Windows. Refer to the table in Game Setup for information on how to retrieve device IDs for specific platforms.
Then play an Event, as per usual. In the Wwise project, the "Play_GunFire" Event would point to a Sound SFX that is routed to a bus that has the "Wwise_Motion" ShareSet assigned as its Audio Device.
To play an Event that would be affecting multiple devices, you need to set up a new Game Object that would be listened by all the player-specific Listeners.
You can also refer to the
DemoMotion class in the sample IntegrationDemo. It provides an example of a multiplayer setup.
So, in order for a specific device to receive motion with one device you must:
AkMotionSinklibrary by including AkMotionSinkFactory.h and link with the AkMotionSink library.
|Note: In Unity and Unreal, plug-in libraries are managed automatically. The previous step is not necessary.|
Ak::SoundEngine::AddOutputwith the Wwise Motion ShareSet and a device ID. If multiplayer, provide a Listener object for each.
To have Motion in the Wwise project:
To troubleshoot problems, it is recommended to profile your application. In the authoring tool you can profile your application by connecting to it and using the Profiler layout (F6). Several tools can help you understand the source of a problem. The Capture Log view will let you see error codes, which will appear in red. The Graph view displays a visual representation of the sound engine pipeline. You should be able to see the motion devices at the end of the pipeline. If not it means that the sound engine was not able to find the device you specified. Another really helpful view is the Emitter/Listener tab. It will show you all the Emitter-Listener pairs. If the Motion Effect does not work, it can be because the Emitter is not associated with the Listener you specified to your motion device.
If you trigger a Motion effect but it doesn't work, do the following:
AddOutputis called from the game.
For Android devices, don't forget to add the permission in the application AndroidManifest.xml file like so: