版本
Wwise SDK 2023.1.3
|
You can use Motion plug-ins to control the haptic feedback of a control interface. With Wwise, you can use the same set of tools to manage motion and audio in your application. Internally, motion data is no different than audio data, and all the features available for audio are also available for motion. Two types of haptic feedback are available through the motion feature: you can transform any audio signals in your project and into motion, or generate dedicated motion signals with the Motion source. You can test motion directly in Wwise Authoring on Windows with a supported controller.
Motion uses the Wwise Sound Engine plug-in system to work in an application, and can be subdivided into two modules: the audio source called Motion and the Audio Device called Wwise Motion. Although the Motion audio source is optional, it remains a powerful tool to create accurate and flexible motion designs.
The Wwise Motion audio device plug-in links the sound engine to motion-ready devices. Just like any audio device plug-in, it receives data from a set of Listeners and "presents" this data to a device. This plug-in is inside a separate library and needs to be included in both Wwise Authoring and the application. 请参阅 Setting Up Motion 一节了解更多信息。
You can use the Motion source plug-in to design the behavior of haptic feedback effects. 正如其他音频源一样,您可以将 Motion 添加至 Wwise 工程中的 Sound SFX 节点。Make sure that the Sound SFX nodes have Output Busses set to motion-ready busses. See Motion for more information.
To use motion in your application, you need to properly set up each component. All the concepts applicable to the audio workflow are also applicable to motion. 它使用相同的总线、听者和发声体(参阅“ 集成 Listener ”)。
为了能向设备发送声音或振动数据,必须将经授权的 Wwise Motion Audio Device 添加至 Wwise 工程的 Audio Device 文件夹(位于 Project Explorer 的 Audio 选项卡中)。Wwise Motion Audio Device 是声音引擎用来与振动设备进行交互的插件。同时,必须将 Wwise Motion Audio Device 指派给顶层 Audio Bus。The term motion bus denotes a top-level Audio Bus with a Wwise Motion Audio Device assigned to it. It is good practice to use a single motion bus hierarchy in your project for easier troubleshooting and monitoring. You can then set the Output Bus of any Sound SFX to a motion bus to create haptic feedback. Usually the Sound SFX elements that use a motion bus also use a Motion source. 为了模拟音频和振动,Sound SFX 须至少拥有一条振动总线和一条音频总线(作为 Output Bus 或 Auxiliary Bus)。
On the game side, link with the separate library called AkMotionSink
. 此库为所支持平台的标准控制器提供支持。You also need to include the AkMotionSinkFactory.h file, located under SDK\include\AK\plugin
. It is important to include this file because it automatically registers the plug-in.
备注: 在 Unity 和 Unreal 中,会自动管理插件库。无需手动添加 AkMotionSink 。 |
有关支持的控制器及其他要求,请参阅下表。
Platform | Device | Device Channel Config and Layout | Additional Requirements |
Android | Android device with vibration support | Anonymous 1-channel | |
iOS | iOS device with vibration support iOS-compatible Controllers | Anonymous 1-channel | CoreHaptics.framework GameController.framework |
Linux | Not supported. | ||
Mac | Mac-compatible Controllers | Anonymous 1-channel | CoreHaptics.framework GameController.framework |
PlayStation 4 | DUALSHOCK 4 PlayStation Move | 匿名 2 声道: 左侧电机、右侧电机 | |
PlayStation 5 | DualSense VR 控制器 | 立体声 2 声道: Left vibration, right vibration | |
Switch | Joy-Con | Anonymous 4-channel: 左侧低频振动、左侧高频振动、 右侧低频振动、右侧高频振动 | |
Windows | Xbox 和 XInput 兼容控制器 DirectInput 兼容控制器 | 匿名 2 声道: 左侧电机、右侧电机 | XInput.lib Dinput8.lib Winmm.lib |
Xbox One Xbox Series X | Xbox 控制器 | 匿名 4 声道: 左侧电机、右侧电机、 左侧触发器、右侧触发器 |
若应用程序要在一些设备上使用振动效果,则必须为每个设备添加专用输出。比如,对于连有四个玩家的分屏游戏,需要添加四个不同的输出以便各个控制器分别接收触觉反馈。To add an output device, use the Wwise API's AK::SoundEngine::AddOutput
function and specify the ShareSet name (as defined in your Wwise project) in the AkOutputSettings
parameter. 另外,因为可能连接多个设备,所以还必须提供设备 ID。The following table contains more information about device IDs.
Platform | Device | Information |
Android | Android device with vibration support | Use 0. |
iOS | iOS device with vibration support and iOS-compatible Controllers | To vibrate the device, use 0. To vibrate a connected controller, first assign a player index to the desired GCController instance using the GameController.framework API. Then, retrieve the DeviceID of that player index by calling AK::SoundEngine::GetDeviceIDFromPlayerIndex. |
Linux | Not supported. | - |
Mac | Mac-compatible Controllers | First, assign a player index to the desired GCController instance using the GameController.framework API. Then, retrieve the DeviceID of that player index by calling AK::SoundEngine::GetDeviceIDFromPlayerIndex. |
PlayStation 4 | DUALSHOCK 4 and PlayStation Move | Use the handle of the device returned by scePadOpen or scePadGetHandle. |
PlayStation 5 | DualSense 和 VR 控制器 | 使用 scePadOpen 或 scePadGetHandle 返回的设备句柄。For PSVR2, create only one output device, using the handle of either the left or right VR controller, to have vibrations on both VR controllers. If you specify a device ID of 0, the system is only initialized for the wireless controller, not the VR controllers. The Advanced vibration control mode, which is required for haptic feedback, is enabled in the System Software by default for DualSense and VR Controllers on PlayStation 5. If your code calls scePadSetVibrationMode, ensure that you do not use any behavior that disables Advanced vibration control mode, such as setting a vibration mode of SCE_PAD_VIBRATION_MODE_COMPATIBLE. |
Switch | Joy-Con | Use nn::hid::NpadId with the desired index. |
Windows | Xbox 和 XInput 兼容控制器 | 使用玩家索引 (0 ~ 3)。 |
Windows | DirectInput 兼容控制器 | 使用 DIDEVICEINSTANCE 中存储的 guidProduct。使用 AK::FNVHash32 生成 guidProduct 哈希值。 |
Xbox One (XDK) | Xbox Controllers | Use the ID stored in a IGamepad object. |
Xbox One (GDK) Xbox Series X | Xbox 控制器 | 通过调用 AK::SoundEngine::GetGameInputDeviceID 来检索手柄的 DeviceID。 |
备注: On all platforms except Windows, a device ID of "0" targets the first available device that supports motion. |
Remember that game controllers can be disconnected either physically or due to communication problems. Disconnection does 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 time, call AK::SoundEngine::RemoveOutput
and provide the AkOutputDeviceID
returned by the corresponding AddOutput()
function call.
Motion outputs are like any other Secondary Outputs and therefore have the same restrictions and requirements. If you are making a single-player game, in which only one player controls the game locally, the Listener/Game Object setup is very simple. In normal cases, the new motion output re-uses the same default Listener as the main audio output. In other words, you rarely have to manage Listeners in a single-player setup.
For multiplayer games, you must create one Listener/Game Object for each motion output. This is necessary so that each player has their own mix of haptic feedback, depending on the situation in the game. 在 AK::SoundEngine::AddOutput()
初始化输出的同时,必须初始化与设备关联的 Listener。各个 Listener 会为声音或振动提供附加通路层。在针对只与某个玩家的 Listener 关联的 Game Object 上播放 Event 时,可让声音只被该玩家听到。To establish this association, you can call AK::SoundEngine::SetListeners
. You can also associate multiple listeners with the same game object, which has a "broadcast" effect on all listeners. 请参阅 集成 Listener 了解有关Listeners和Game Objects的更多信息。
备注: A sound needs to be routed into the motion bus hierarchy even if the Emitter has a Listener set to a motion output. |
The following examples demonstrate how to set up your application to use motion. You can also refer to the Demo Motion example in the Integration Demo (DemoMotion.cpp) included in the SDK samples. 其中提供有所有支持平台的工作示例。
First, as with any other plug-in, you need to include the corresponding file and link the library (for Wwise native development only, not required for Unity).
Next, add another output with the Wwise Motion Audio Device ShareSet name from the Wwise project, in this case "Wwise_Motion". The output ID is 0 to ensure that the first connected game controller is used.
Next, play an Event. In the Wwise project, the "Play_Explosion" Event is linked to a Sound SFX that is routed to a bus that has "Wwise_Motion" ShareSet assigned as its Audio Device.
This section describes how to set up motion for multiple players on the same console, not a networked multiplayer game. In multiplayer scenarios, the mix for motion, or any player-specific output, must be different to represent the player's perspective in the game world. Players therefore need their own Listeners.
Add an output for every player. You can use an Audio Device ShareSet multiple times, so you don't have to create multiple Audio Device ShareSets. You must provide a real device ID for every controller. 本例适用于 Windows 上的 Xbox 控制器。有关如何针对特定平台检索设备 ID 的信息,请参阅“ Game Setup ”中的表格。
Next, play an Event. In the Wwise project, the "Play_GunFire" Event is linked to a Sound SFX that is routed to a bus that has "Wwise_Motion" assigned as its Audio Device ShareSet.
To play an Event that affects multiple devices, set up a new Game Object, and ensure that all player-specific Listeners listen to it.
For an example of multiplayer setup, refer to the DemoMotion
class in the IntegrationDemo sample.
For a specific device to receive motion with one device, you must:
AkMotionSink
library. Include AkMotionSinkFactory.h
and link with the AkMotionSink
library. 备注: 在 Unity 和 Unreal 中,会自动管理插件库。This step is unnecessary. |
AK::SoundEngine::RegisterGameObj
.Ak::SoundEngine::AddOutput
with the Wwise Motion ShareSet and a device ID. For multiplayer, provide a Listener object for each.To add Motion to the Wwise project:
To troubleshoot problems, we recommend that you profile your application. In Wwise Authoring, you can profile your application as described in Profiling. 您可以利用各项工具来了解问题的根源。The Capture Log view lists error codes in red. 在 Graph 视图中,可查看声音引擎管线的图示。The motion devices appear at the end of the pipeline. If no motion devices are displayed, the sound engine could not find the device you specified. Finally, the Emitter/Listener tab displays all Emitter-Listener pairs. If the Motion Effect does not work, the Emitter might not be associated with the Listener you specified for your motion device.
若触发 Motion Effect 时出现问题,请执行以下操作:
AkMotionSinkFactory.h
and linked to the AkMotionSink
library.AddOutput
is called from the game.RegisterGameObj
, SetListeners
, and AddOutput
.For Android devices, add the permission in the application's AndroidManifest.xml file: