Wwise Unity Integration Documentation

自 2018.1 版本起，我们将对 Wwise Authoring API (WAAPI) 的支持嵌入到了 Unity Integration 中（有关详细信息，请参阅使用 Wwise Authoring API (WAAPI)）。在 2021.1 版本中，为了更好地整合 Wwise Picker 并提高整体的易用性，我们对 Wwise Authoring API (WAAPI) 进行了重新设计。有关如何结合 Wwise Picker 使用 WAAPI 的详细信息，请参阅 Wwise Picker 文档页面。

WAAPI 设置

WAAPI 设置可在 Project Settings > Wwise Editor > Wwise Authoring API 中找到。

若未选中 Connect to Wwise 复选框，则将禁用 WAAPI 功能。在默认情况下，WAAPI 客户端会连接到本地主机 (127.0.0.1) 上的 8080 端口。若在连接 WAAPI 时更改这些设置，则将关闭当前连接并尝试连接到新的目标地址。

故障排除

下面列出了无法正常连接到工程时的一些解决方案。

检查是否在 Wwise 设计工具中打开了正确的工程。
检查 Project Settings > Wwise Editor > Wwise Project 中的 Wwise Project Path 是否正确。
若打开了多个 Wwise 设计工具实例，则其中一个可能会阻断另一个的 WAAPI 端口。
检查是否在 Wwise 设计工具中启用了 WAAPI，以及允许的连接和端口有无错误。
- WAAPI 设置可在 User Preferences 中找到。

在 Unity 中使用 WAAPI

AKWaapiClient 类通过 WebSocket 连接与 Wwise 设计工具进行通信。WAAPI 消息为 JSON 对象。 WAAPI 调用为异步操作。因为对 WAAPI 的调用可能来自 GUI 之类的线程，而我们不能无限期地等待其作出响应。 WebSocket 实现也只能等待一次作出一个响应。为此，我们使用 AkWaapiUtilities 类对 WAAPI 客户端进行了封装。此类提供一系列函数来创建 WAAPI 请求并予以排序，然后在更新循环过程中按次序加以调用。 WAAPI 请求封装在 WaapiCommand 中，其仅包含异步函数指针负载。在接收命令时，将执行其负载。

AkWaapiUtilities 中内置的函数应可满足大部分需求。若想按其他方式使用 WAAPI，则不妨自行加以实现。有关详细信息，请参阅其他 WAAPI 命令章节。

注意： 大部分内置 WAAPI 调用使用 Wwise Authoring Query Language (WAQL)。有关 WAQL 的详细信息，请参阅 WAQL 简介和 WAQL 参考页面。

使用 WAAPI 获取 Wwise 对象

AkWaapiUtilities 已经包含用来获取 Wwise 对象的内置 WAAPI 调用：

这些调用会返回一系列包含返回选项中所指定属性的对象。如需查看返回选项的完整列表，请参阅 WAAPI 文档。

Wwise Picker 使用 WwiseObjectInfoJsonObject 作为这些函数的模板类型。这些对象随后会由 AkWaapiUtilities.ParseObjectInfo 转换为 WwiseObjectInfo。

若要获取未包含在 WwiseObjectInfo 中的对象属性，则需为所要访问的属性创建一个自定义类。比如，若只想获取 Notes 字段，则可按照以下方式创建类：

public class WwiseObjectNotes 
{
    public string notes;
}

随后便可调用 AkWaapiUtilities.GetWwiseObject<T>（或前面列出的任何其他函数），来使用 ReturnOptions 对象仅列出 Notes 字段，同时通过回调来接收一系列 WwiseObjectNotes。

{
    var callback = ( List<WwiseObjectNotes> notes ) => { 
        // do something 
        };
    var options = new ReturnOptions(new string[] { "notes" });
    var objectGuid =  System.Guid.Empty(); //Put an actual guid from your project here
    AkWaapiUtilities.GetWwiseObject<WwiseObjectNotes>( objectGuid, options, callback);
}

AkWwiseTreeWAAPIDataSource 类包含多个有关如何使用 WAAPI 获取 Wwise 对象以填充 Wwise Picker 的示例。

订阅主题

您可以使用 AkWaapiUtilities.Subscribe 订阅 WAAPI 主题。 URI 会识别所要订阅的主题。回调参数将以函数形式接收 JSON 字符串参数以供发布主题时调用。在成功注册订阅时会调用 handshakeCallback。它将接收包含订阅标识符的 AkWaapiUtilities.SubscriptionInfo 对象。请求订阅的类应当存储此信息。

注意： 调用 AkWaapiUtilities.Subscribe 的类负责在其生命周期结束时清理订阅。此操作通过调用 AkWaapiUtilities.Unsubscribe 来实现。

有关 Integration 中所用订阅的示例，请参阅 AkWwiseTreeWAAPIDataSource 类。

AkWwiseTreeWAAPIDataSource.SubscribeTopics
AkWwiseTreeWAAPIDataSource.UnsubscribeTopics

有关可用对象的详细信息，请参阅 >Wwise Authoring API 参考。

大部分主题 URI 可在 Uri.cs 中找到。

断开连接

在将要或突然关闭 WAAPI 连接时，将调用 AkWaapiUtilities.Disconnection 委托。该委托的布尔参数会指示连接是否仍处于激活状态。

备注：

应将订阅 WAAPI 主题的类与此委托绑定，以确保其能够在连接中断前取消订阅。

其他 WAAPI 命令

AkWaapiUtilities 类包含以下附加函数。您可以利用其在 Unity 内与 WAAPI 工程进行交互。

您可以在 AkWwisePicker 和 AkWwiseTreeView 中找到这些命令的使用示例。

若所要执行的 WAAPI 命令尚未整合到 AkWaapiUtilities 中，则不妨根据需要自行创建相应的命令。为了开始进行 WAAPI 调用并接收响应，必须构建并解析 JSON 参数。

对于无需通过响应解析数值的命令，使用 AkWaapiUtilities.QueueCommand

对于需要通过响应解析数值的命令，使用 AkWaapiUtilities.QueueCommandWithReturnType<T>

利用 Unity JsonUtility 类，可以轻松地在 C# 类和 JSON 字符串之间进行转换。对于必须转换成 JSON 字符串的参数和选项，使用 JsonSerializable 作为基类。

public class JsonSerializable
{
    public static implicit operator string(JsonSerializable o) => UnityEngine.JsonUtility.ToJson(o);
}

然后，可对此类进行扩展，以便提供用于特定 WAAPI 模式的 C# 封装器。如需查看相关使用示例，可参阅我们如何使用 WAAPI 创建所需架构类来播放 Event 并订阅 Transport：

参数和选项架构

返回的对象架构

您可以在 AkWaapiUtilities.TogglePlayWwiseEventAsync 和 AkWaapiUtilities.CreateTransport 中查看相关使用示例。

JsonSerializable

Base class for Json serializable objects. Implements implicit cast to string using UnityEngine....

Definition: AkWaapiHelper.cs:27

ReturnOptions

WAAPI options to specify the names of fields to return in a WAAPI request returning WwiseObjects.

Definition: AkWaapiHelper.cs:150

AkWaapiUtilities

This class wraps the client that communicates with the Wwise Authoring application via WAAPI....

Definition: AkWaapiUtilities.cs:34

此页面对您是否有帮助？

需要技术支持？

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

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

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

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

开始 Wwise 之旅

Wwise Unity 集成

WAAPI 实用工具