版本
menu_open
Wwise Unreal Integration Documentation
Unreal Engine C++ 工程

链接模块

Wwise Unreal Integration 被分成了多个模块。为了在 C++ 工程内使用 Wwise 的功能,必须在工程的构建文件 (.Build.cs) 内链接这些模块。您可以通过从构建文件中移除模块来将其禁用。

在以下示例中,工程包含以下 public 模块:Core、CoreUOBject、Engine、InputCore、AkAudio 和 WwiseSoundEngine。其中,AkAudioWwiseSoundEngine 为 Wwise 模块。

public class MyModule : ModuleRules
{
public MyModule(ReadOnlyTargetRules Target) : base(Target)
{
PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "AkAudio", "WwiseSoundEngine" });
// 其他设置
}
}

在本例中,可使用 WwiseSoundEngineAkAudio 模块的功能。模块可包含在 PublicDependencyModulesNamesPrivateDependencyModulesNames 中。有关模块的详细信息,请参阅 Unreal Engine 文档

模块概述

Integration 被分成了以下模块:

  • AkAudio:该根模块适用于大部分面向用户的 Integration 功能。
  • AkAudioMixer:该模块允许工程将音频输出及音频下混从 Unreal 音频组件传输到 Wwise 工程的混音器。
  • AudiokineticTools: Implements editor-specific tools and utilities like the Wwise Browser.
  • WwiseFileHandler:该模块为 Wwise 声音引擎提供所需的媒体、SoundBank 和外部源,包括处理来自 Wwise Location Resolver 和 I/O Hook 的请求。
  • WwiseProjectDatabase:该模块提供基于内存的数据库视图,方便查看 Wwise 工程所生成 SoundBank 的当前状态。
  • WwiseResourceCooker:该模块将 WwiseObjectInfo 结构 转换为 Cooked 结构,并将所需资源复制到 Staging 目录。
  • WwiseResourceLoader:该模块负责加载和卸载各种 Wwise 素材类型所需的资源。
  • WwiseSoundEngine:该模块提供 Wwise 声音引擎 API 和 Unreal 工程之间的桥接。

下图展示了 Integration 的模块依赖关系:

覆盖 Wwise Unreal Integration

Integration 中的模块(除了 WwiseSoundEngineAudiokineticToolsAkAudio)可通过继承来进行扩展。这些模块的大部分功能都可由开发者根据工程自身需要进行覆盖并修改相应行为。若要覆盖模块,请创建一个新的模块并确保其继承所要覆盖的模块。然后,覆盖所需函数。为了使用新建的模块,请确保将其包含在游戏的 Build.cs 中,并添加到 DefaultEngine.ini(如下所示):

[Audio]
WwiseFileHandlerModuleName=WwiseSimpleExternalSource

上面举例展示了 <tt>WwiseSimpleExternalSource</tt> 模块对另一模块的覆盖。确切来说,它覆盖了 WwiseFileHandler 模块以便通过 Data Table 来处理外部源。

利用 C++ 创建 AkComponent

在利用 C++ 创建新的 AkComponent 时,必须将其关联到父组件。有了 AkComponent,API 才能正常运行。以下章节举例展示了如何添加 AkComponent

在 Unreal 工程中使用 Wwise API

现在可以通过 Wwise Unreal Integration 来使用 Wwise API。您可以通过 WwiseSoundEngineAkAudio 模块调用大部分函数。

WwiseSoundEngine 模块

WwiseSoundEngine 模块提供对大部分 SoundEngine API 操作的底层访问。借助 WwiseSoundEngine 模块,可直接、安全地访问 API 函数(如以下示例所示):

#include "AkAudioEvent.h"
#include "AkComponent.h"
#include "Wwise/LowLevel/WwiseLowLevelSoundEngine.h"
void PostEventSoundEngine(UAkAudioEvent* Event, AActor* GameObject)
{
if (auto* SoundEngine = IWwiseSoundEngineAPI::Get())
{
if(Event && GameObject)
{
TArray<UAkComponent*> Array;
GameObject->GetComponents<UAkComponent>(Array);
//The Actor doesn't have an AkComponent attached. 若要通过此 Actor 来发出声音,就需要此组件。
if (Array.Num() == 0)
{
//PostEvent doesn't load the event. The Event needs to be loaded beforehand.
if (!Event->IsLoaded())
{
Event->LoadData();
}
auto* AkAudioComponent = NewObject<UAkComponent>(GameObject);
AkAudioComponent->SetupAttachment(GameObject->GetDefaultAttachComponent());
Array.Add(AkAudioComponent);
AkAudioComponent->RegisterComponent();
}
SoundEngine->PostEvent(Event->GetWwiseShortID(), Array[0]->GetAkGameObjectID());
}
}
}

此代码会在给定 Actor 上发送 Event。您必须在 Actor 上添加 UAkComponent 以通过 Wwise 予以注册。同时还要加载 Event,因为 WwiseSoundEngine 模块中不会自动加载 Event。

注記: 在 Integration 2022.1 之前,无法在 AkAudio 之外访问代码,因为需要在同一动态库中访问 API。

AkAudio 模块

AkAudio 根模块适用于大部分面向用户的 Integration 功能。它可以完成 WwiseSoundEngine 模块可使用 Unreal 组件执行的大部分操作。它包含用于 Integration 所用素材类型和组件的类。作为直接调用 SoundEngine 的替代方法,AkAudioDevice 提供了很多辅助函数来封装常用的 WwiseSoundEngine API。这些辅助函数还会检查是否已加载使用 API 所需的资源并提供更多日志信息。

就像前面的例子一样,以下代码也会在给定 Actor 上发送 Event。同时,还会绑定 AkComponent 并加载 Event:

#include "AkAudio.h"
void PostEvent(UAkAudioEvent* Event, AActor* GameObject)
{
if (FAkAudioDevice::Get())
{
FAkAudioDevice::Get()->PostAkAudioEventOnActor(Event, GameObject);
}
}

您可以在 WwiseDemoGame/WwiseCodeExample 下的 WwiseDemoGame 中找到更多代码示例,并在 WwiseDemoCodeExampleMap 中做各种尝试。

调试功能

日志记录

Integration 中的每个模块都有独立的详细级别。这样可以提高调试的效率。在出现错误时,可找到产生错误的模块,然后将该模块的日志详细级别设为 VerboseVeryVerbose 以更好地理解出错的原因。您可以在 DefaultEngine.ini 文件的 Core.Log 部分更改各个模块的详细级别。另外,所有模块中都会默认启用一个名为 LogWwiseHints 的特殊日志类别,其会在使用被弃用的函数和存在其他不良习惯时发出警告。

以下为可能的详细级别:

  • Fatal:在无法或不应继续执行程序时导致发生崩溃。比如,没有加载必要的插件模块。
  • Error:在音频无法正常运行时阻止对游戏进行打包。
  • Warning:指示非关键功能可能具有无法预测的行为。在必要时,还可阻止打包。
  • Display:记录有关模块初始化的信息并提供 Commandlet 信息。
  • Log:记录各种重要操作。
  • Verbose:记录模块执行的所有操作。
  • VeryVerbose:记录模块执行的每一步操作。

在以下示例中,可看到与各个模块关联的详细级别:

[Core.Log]
LogAkAudio=Verbose
LogAkAudioMixer=Verbose
LogAudiokineticTools=Log
LogWwiseAudioLink=Verbose
LogWwiseConcurrency=Verbose
LogWwiseFileHandler=Verbose
LogWwiseHints=Warning
LogWwiseResourceLoader=Warning
LogWwiseResourceCooker=Log
LogWwiseProjectDatabase=Log
LogWwiseSimpleExtSrc=Error

有关详细级别的详细信息,请参阅 Unreal Engine 文档

Stats

Integration 包含以下可为调试提供帮助的 Stats:

  • AkAudioDevice:记录有关 Post Event Async 调用的信息。
  • AkSoundBankGenerationSource:记录与 SoundBank 生成相关的 WAAPI 调用。
  • WwiseConcurrency: Logs information about memory used to manage multi-threading.
  • WwiseFileHandler:记录有关所加载媒体、SoundBank 和外部源的信息。
  • WwiseFileHandlerLowLevelIO:记录有关流播放声音的信息。
  • WwiseMemory: Logs information about memory usage.
  • WwiseObstructionOcclusion: Logs information about obstruction and occlusion calculations.
  • WwiseProjectDatabase: Logs information about memory used by the WwiseProjectDatabase module.
  • WwiseResourceLoader:记录有关被引用 AkType 的信息。
  • WwiseSoundEngine:记录有关 API 调用的信息。

若要访问这些信息,请在 Unreal 的 Viewport Options 中选择感兴趣的 Stats。

有关 Stats 的详细信息,请参阅 Unreal Engine 文档

Packaging Requirements

When you package your Unreal project, the assets are "tree-shaken." In other words, Unreal assets that represent Wwise objects are automatically included if they are referenced either by another packaged asset or by a packaged map. If they are, any associated SoundBanks and media files are copied into the built package. Any Wwise Unreal assets that do not satisfy one of these conditions are not included.

This packaging approach is efficient, but in certain cases some Wwise Unreal assets might be improperly excluded, which can cause errors. The following scenarios can cause this type of problem:

  • The project uses Wwise Unreal assets that are not directly referenced by packaged maps.
  • The project uses Events that are posted by string or from code.

If one of these scenarios applies to your project, you must therefore ensure that either the asset is directly referenced by a map, or ensure that the required assets are manually loaded. To manually add assets, add the containing directory to the project's Additional Asset Directories to Cook in the Project Settings. Refer to Project Section of the Unreal Project Settings for more information.


此页面对您是否有帮助?

需要技术支持?

仍有疑问?或者问题?需要更多信息?欢迎联系我们,我们可以提供帮助!

查看我们的“技术支持”页面

介绍一下自己的项目。我们会竭力为您提供帮助。

来注册自己的项目,我们帮您快速入门,不带任何附加条件!

开始 Wwise 之旅