Integrating Wwise Motion

Using Wwise, you can manage motion using the same feature set that you use to manage the audio in your game. This means that everything that you used to do to audio data can now be done to motion data using the same API. Currently, only the console game controllers are supported in the motion engine.

Note: Motion is not available on the Mac® and iOS, tvOS platforms.

Registering a Device for Use in a Game

The motion devices are not available by default in the sound engine. The game must link to the separate library for each of the devices. See the following table:

The game must register the device in the Motion engine by calling AK::MotionEngine::RegisterMotionDevice. You need to make this call once for each device type used in your game. If your game supports multiple devices but the particular hardware setup it runs on doesn’t have them installed, you should avoid registering the device uselessly. This is not the way to test if the device is installed or not.

Player Initialization

The Motion engine supports multiple players and multiple devices per player as well. For example, an Xbox360 game with a split-screen can have up to 4 players on the same console. The game must register each player so that they can receive feedback through each of their devices. This is done with: AK::MotionEngine::AddPlayerMotionDevice.

This must be repeated for each player and device currently connected. If the device driver is not installed on the computer this will return an error. It won’t check if the devices are actually powered. For Rumble, checking if the controller is connected should be done by the game, when the input device is initialized.

On the game consoles, the game controllers can be disconnected either physically or through communication problems. It won’t have any adverse effects on the Motion engine other than using some resources uselessly. If you think a device is disconnected for a long period of time you can call AK::MotionEngine::RemovePlayerMotionDevice to free up resources.

If a player disconnects his controller and reconnects it in a different port of the console you must call RemovePlayerMotionDevice and then AddPlayerMotionDevice with the new player port.

Player Management

Since each of the players, in a multi-player game, won’t be doing the same thing at the same time, the feedback received shouldn’t be the same either. To control which player receives which motion effect, the same concepts used in audio have been reused: the listener and the game object. For motion, the game object “emits” vibrations and the listener “receives” them.

In a game with motion support, each player must have its own Listener (see Integrating Listeners). The game must assign a listener to a player explicitly. This is done with AK::MotionEngine::SetPlayerListener.

Note that by default all players use listener 0. The Listeners have been modified to act as receivers for both audio and motion data. However, the listeners are only enabled to receive audio by default. To specify what kind of data the listener will receive, call AK::SoundEngine::SetListenerPipeline.

After this is setup, the game only has to activate the proper listeners' bits on each game object, depending on the situation. This is done the same way it is for audio, using AK::SoundEngine::SetActiveListeners.

However, there is one major difference with audio. In audio, the listeners come into play only when a sound is set with 3D positioning. This is not the case with motion. For Motion, the listener and game object setup is mandatory for any feedback to be felt in the motion devices.

Using Motion Source Plugins

Wwise currently ships with the following motion source plug-ins:

To use a motion source plugin, just register it as you would any other source plugin, with AK::SoundEngine::RegisterSource.

Writing Motion Source Plugins

Writing source plugins for motion devices is very similar to writing plugins for audio. Refer to the section for audio plugins for more details (Audio Plug-ins).

There are two differences between audio and motion source plugins. First, the interface AK::Wwise::IMotionSourcePlugin must be supported by the plugin. It derives from AK::Wwise::IAudioPlugin, therefore all services and restrictions related to audio plugins apply (see Writing the Wwise Part of an Audio Plug-in). The second difference is in the xml file needed to define the plugin properties. Although most of the file is identical to what is needed for regular audio sources (see Wwise Plug-in XML Description Files), the motion plugin must be declared as follows:

<FeedbackSourcePlugin Name="Wwise Motion Generator" CompanyID="0" PluginID="405" DataType="TypeSpeedSamples">

• Name is the visible name in the Wwise application, in the “Add Source” menu.
• CompanyID is your company ID. 0 is reserved for Audiokinetic.
• PluginID is your plugin ID. You can use anything here.
• DataType must be one of the following : TypePositionSamples, TypeSpeedSamples, TypeAccelSamples. This specifies what kind of samples are output by your plugin and ensures that an incompatible device won’t receive data it doesn’t support. Rumble pads support speed samples.

Checklist and Troubleshooting

So, in order for a specific player to receive motion with one device you must:

• Call AK::MotionEngine::RegisterMotionDevice once to tell the engine that this device will be used.
• Call AK::SoundEngine::RegisterPlugin once for each source plugin (Motion Generator, Tone Generator and so on) that will be used.
• Call AK::MotionEngine::AddPlayerMotionDevice once for the player/device combination to tell the engine that this player uses a specific device type.
• Call AK::MotionEngine::SetPlayerListener once to tell the engine which listener represents the player.
• Call AK::SoundEngine::SetListenerPipeline once to enable reception of motion data on the chosen listener.
• Call AK::SoundEngine::SetActiveListeners on each game object emitting motion signals that the player must receive.

In your Wwise project:

• You must have the device selected in the Project Settings / Motion Devices tab
• You must have one source routed to the Master Motion Bus
• The source must be part of a bank that is loaded.

If the motion created in Wwise is not playing on a particular motion device, you can troubleshoot the problem using the Profiler. To capture motion data in the Advanced Profiler, do the following:

• Press F6 to switch to the Profiler layout.
• From the menu bar, click Project > Profiler Settings.
• Select the Motion Data option and click OK. The Motion Devices tab is added to the Advanced Profiler.

Now you can connect to your game and profile the motion to identify the potential problem. The "Motion Devices" tab contains two separate lists: one for Devices and one for Game Objects. The Devices list indicates which motion devices have been properly registered and initialized in the sound engine, for each player.

To troubleshoot the problem, first check to see if the motion devices have been properly initialized, by doing the following:

• Verify that each motion device is displayed in the Device list. IF the device doesn't show up in this list, then the call to AK::MotionEngine::RegisterMotionDevice failed.

If the motion device appears in the list, then check to see if the motion device has been associated with a particular player, by verifying that there is a check mark matching up the device to the appropriate player. If there is no check mark, then either of the following may be true:

• The call to AK::MotionEngine::AddPlayerMotionDevice failed.
• AK::MotionEngine::RemovePlayerMotionDevice was called.

If the motion devices have been properly initialized and they are associated to the appropriate player, then you can check the Game Objects list to verify if the game objects are setup properly to send motion data to a specific player. If there is no check mark for a particular combination of game object/player, you can switch to the Listeners tab of the Advanced Profiler to check the following:

• In the Listener list, find the player number that is not receiving motion data in the Players column and then check to see which Listener the player is using to receive the motion data. If the player is not using the correct listener, verify your calls to AK::MotionEngine::SetPlayerListener.
• If the player is using the right listener, then make sure that the listener to which the player is attached has a check in the Motion column. If not, verify that you are calling AK::SoundEngine::SetListenerPipeline properly.
• If a check mark is displayed, check the Game Object list to verify that the listener used by the player is enabled for the game object on which the Motion FX is playing. If the listener is not enabled for the game object, verify your calls to AK::SoundEngine::SetActiveListeners.