版本
menu_open
Wwise SDK 2023.1.2
监控错误

大多数 SDK 函数在出现问题时都会返回错误代码。然而声音引擎运行的是它自己的线程,因此有可能有在发生错误时未收到直接通知的情况。 在输出给用户之前,错误代码会由转换器进行解析,进而将代码转换为有意义的消息,并将数字标识符解析为对象名称。在默认情况下,这些消息仅通过 DefaultErrorMessageTranslator 进行转换。有关更多详细信息,请参阅 错误消息转换器 章节。

有多种方法可以检测声音引擎中的错误。您可以执行以下任意操作:

  • 检查由 SDK 中的函数返回的错误代码。
  • 验证在同步调用时指定的回调中发送的错误代码。这只适用于使用异步功能的情形。
  • 调用 AK::Monitor::SetLocalOutput() 函数来启用/禁用监控消息和错误的本地输出。对于此用例,请确保启动监控线程。 否则,AkMonitor 将无法分派通知,也不会向本地输出发送任何内容。 若要启动监控,直接调用 AkMonitor::Instance()->StartMonitoring() 即可。 若不想运行单独的线程,请确保已经调用 AkMonitor::Instance()->InitMonitoring() 并手动调用 AkMonitor::Instance()->DispatchNotification()
  • 使用 DEBUG 或 PROFILE 设置将 Wwise Authoring 应用程序连接到游戏。在此之前,请确保将通信正确初始化。有关详细信息,请参阅 通信初始化 章节。
  • 使用函数 AK::Monitor::PostString()AK::Monitor::PostCode() 监控游戏所发布的消息。

错误消息转换器

在将错误消息发给用户之前,声音引擎会向错误消息转换器发送错误代码。错误消息转换器会尝试对错误代码中的标记进行解析以生成更为详细的错误消息。此页面将阐释如何在工程中运用转换器。

运用转换器

以下章节阐述了使用错误消息转换器时所需的两个组件。

回调函数

首先,必须将回调函数设为接收监控消息。该函数须采用 AK::Monitor::LocalOutputFunc 的签名,并且会在转换之后接收错误消息。 您需要在此函数中定义要针对错误消息执行怎样的操作。比如,在 IntegrationDemo 中,以 LocalErrorCallback 为回调函数。在该 Demo 中,在收到错误消息时,会对当前页面内容进行修改并将错误消息显示为红色。 若要设置回调函数,请调用 AK::Monitor::SetLocalOutput() 并传递所要使用的回调函数指针。

错误消息转换器

声音引擎带有默认的转换器,其会将错误代码转换为用户可读的消息。不过,该转换器只会直接在错误消息中输出其收到的信息(如 ID),而不会尝试将其转换为有用的信息(如对象名称)。强烈建议向工程添加其他转换器来接收更为详细的错误消息。 这些转换器存放在 SDK/tools/AkWwiseErrorHandler 文件夹中。

备注: 对于有些转换器,可能需要向工程添加其他的库。有关详细信息,请参阅各个转换器的文档。

在将想要使用的转换器添加到工程中之后,为其创建相应的实例并通过调用 AK::Monitor::AddTranslator() 将其安装到监控器中。用户需要追踪新建的实例以确保可将其删除。

转换器类型

转换器类型有四种:

  • Default:将错误代码转换为消息,但只输出 Game Object、Event、Audio Node 等的数字标识符。
  • XML:将错误代码转换为消息,并使用 SoundBanks.xml 中的信息将 Event、Audio Node 和 Media 的标识符解析为有意义的名称。Game Object 和其他一些实体保留为数字值格式。
  • WAAPI(须在 linker->input project 选项中添加 AkAutobahn.lib):将错误代码转换为消息并连接到 Wwise 工程(通过活跃的 Wwise 实例)来将所有标识符解析为有意义的名称。
  • Unity:跟 WAAPI 一样,但会同时使用来自 Unity 的信息。仅可用在 Unity 工程中。

只有 Default 转换器能处理标准的 printf 样式的标记(即以 % 为开头的标记)。每个转换器类型都可重新定义应当如何处理 Wwise 标记 ($)。没必要处理给定转换器中的每个标记。可以定义后备转换器,并在转换尝试失败后调用。在此之后,可创建转换器模组以将多个转换器联用直到转换成功。模组末端的转换器始终为 Default 转换器。

支持的标记

转换器使用与 printf() 函数相似的标记系统。支持的标记包括:

  • 标准标记:
    • %i:整数
    • %f:浮点数
    • %u:无符号整数(32 位)
    • %llu:无符号整数(64 位)
    • %s:字符串
  • Wwise 标记:
    • $b:Bank Id
    • $g:GameObject Id
    • $m:Media Id
    • $p:Plugin Id 和 ShareSet Id
    • $s:Switch/State Id
    • $w:WwiseObject Id(如 Event Id)
    • $$:转义符

创建新的错误消息转换器

在必要时,可创建新的错误消息转换器。直接创建从 AssistedErrorMessageTranslator 接口继承的新类。

此类具有两个抽象方法:

  • InitConnection():确保成功连接到外部源(即确保转换器已准备就绪)
  • GetInfoFromExternalSource():决定要针对给定标记执行怎样的操作

新建的转换器无需处理所有标记。它可以依赖模组中的下一转换器。

备注: 若新建的转换器采用某种方式处理 $p 标记,请确保其同时处理两个参数:Plugin Id 和 ShareSet Id。参见 AkDefaultErrorMessageTranslator.cpp 中的 ParseWwiseTag 示例。

此页面对您是否有帮助?

需要技术支持?

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

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

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

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

开始 Wwise 之旅