目录

Wwise SDK 2021.1.1
测试您的插件

本文档用于帮助您制作与 Wwise 平台各方面相兼容的插件。我们提供一套指导准则和一系列专用测试，确保您获得软件所有领域的信息。在面向大众用户部署插件时，必须满足此处所列测试和指导准则的要求。

通过这一系列测试后，您的插件将会变得更加稳定，兼容 Wwise 整套功能的可能性更大。

指导准则

用户界面

  • 最大大小：插件 UI 的内容应能适应 1000x650 像素大小，适合小型台式机屏幕。
  • 可调整大小：建议处理 WindowProc 功能中的 WM_SIZE 消息。这可以让用户根据对插件的关注程度来设置较小或较大的工作界面空间。它还可以帮助插件更好地适配 Wwise 布局系统。
  • 使用默认控件：虽然使用默认控件不是强制要求，但是这样做具有多个优势：
    • 将自动为支持 RTPC 的属性显示 RTPC 图标。
    • 在 Wwise 中，控件交互是标准配置（滑块行为、键盘修改键、上下文菜单等）。
    • 支持平台链接/取消链接（仅限于源插件）。
    • 滑块范围会根据属性定义自动调整。
  • 大写：对于文本（标签、复选框、单选按钮、按钮、工具提示等），采用第一个单词首字母大写。
  • 无模式对话框：勿从插件窗口创建无模式对话框（无子代）。这与 Wwise 布局系统相冲突，可能制造潜在漏洞。应使用模子对话框，但将使用量降到最小（打开/保存文件对话框、用户/系统设置、消息框等）。
  • 避免闪烁：当调整插件窗口大小时，不应发生闪烁。

功能性

  • 支持 RTPC：只要可能并且合理，您都应该尽量让属性支持 RTPC。这可以将游戏输入绑定到插件属性，带来更高的灵活性。
  • 非线性滑块：对于值域呈非线性分布的滑块，例如以分贝为单位的音量滑块，使请用像素值相对于属性值域的非线性分布。

  • 使用属性限制：在 XML 插件的定义文件中定义属性时，只要可能，都应为您的属性定义限制范围或枚举。这些限制用于：

    • 自动调整滑块范围
    • 在 RTPC 坐标图中定义 RTPC 范围
    • 在工程加载时验证并调整属性值，以确保工程的完好性。

编码（第 3 方）

第 3 方插件供应商必须遵守以下要求。建议内部游戏程序员也遵守这些要求。

  • 稳定性：您的插件不得使内存受损、断言、死机或泄漏。
  • 内存分配：请勿在插件的声音引擎部分中调用 new() 或 malloc()。总是通过 Wwise 声音引擎传递给插件的 AK::IAkPluginMemAlloc 分配器来分配内存，方法是使用 IAkPlugin.h 中定义的宏 AK_PLUGIN_NEW、AK_PLUGIN_DELETE、AK_PLUGIN_ALLOC 和 AK_PLUGIN_FREE。
  • 验证分配的内存：在插件的声音引擎部分中，请总是先验证确保内存分配成功，然后再使用它。如果内存分配失败，您的插件应正常地返回 AK_Fail（如适用）。
  • 声明支持的声道配置：插件的声音引擎部分应为不支持的声道配置返回 AK_UnsupportedChannelConfig。
  • 插件性能：在插件生命周期中的所有 AK::IAkInPlaceEffectPlugin::Execute()（或等效函数）调用期间，其运行时性能应保持合理和稳定。
    • 声音引擎插件 API 的初始、终止和所有其他函数的用时也不应过分长于 Execute()。
    • 在 Wwise 创作工具中编辑非 RTPC 参数并实时应用于插件时，此限制不适用。在最坏的情况下，更改此类参数的用时不应超过终止和重新初始化插件的声音引擎部件的用时。
  • 断言：使用 AKASSERT 宏而不使用自带的断言函数。
    • 在插件 Wwise 部分的主要 cpp 文件中添加以下代码行；DEFINEDUMMYASSERTHOOK；
    • 此宏定义于 AudioPlugin.h，将确保在 Wwise 创作工具使用的 DLL 中创建插件的声音引擎部分时，能够正确地链接。
  • 可用性：作为创作工具中的插入效果时，您的插件应该能够正常工作。我们说能够正常工作是指它应该能够播放，在生成 SoundBank 时不会导致错误，无需依赖用户来执行任何操作，例如打开 Effect Editor。
  • 并行执行：所用插件应允许单独针对各个实例并发执行 Execute() 方法（见 eventmgrthread_taskscheduling）。确保实例之间共享的数据不会影响线程的安全执行。

Unity 3D 和 Unreal4

这两个游戏引擎的官方 Wwise 集成对效果器都采用了动态库。如果您打算向大众发布插件，则应为支持的所有平台提供动态库。请阅读 创建动态库 中有关插件动态库的更多信息。

测试

新建实例（源插件）

  1. 在 Project Explorer 中，创建新声音
  2. 在 Contents Editor 中，创建源插件
  3. 双击新创建的源
  4. 验证是否设置了默认值
  5. 播放源
  6. 验证源是否播放正常

新建实例（效果器插件）

  1. 在 Project Explorer 中，双击现有的声音
  2. 在 Property Editor 中，切换到 Effects 选项卡
  3. 在 ID=0 的效果器上，单击“>>”按钮。
  4. 在效果器子菜单中，选择“New...”
  5. 选择工作单元
  6. 单击 Edit
  7. 验证是否设置了默认值
  8. 播放声音
  9. 验证声音播放时是否应用了效果
  1. 在 Project Explorer 中，双击现有的声音
  2. 在 Property Editor 中，切换到 Effects 选项卡
  3. 在 ID=0 的效果器上，单击“>>”按钮。
  4. 在效果器子菜单中，选择“Default (Custom)”
  5. 单击 Edit
  6. 验证是否设置了默认值
  7. 播放声音
  8. 验证声音播放时是否应用了效果

效果器模式更改（效果器插件）

  1. 在 Project Explorer 中，双击现有的声音
  2. 在 Property Editor 中，切换到 Effects 选项卡
  3. 在 ID=0 的效果器上，单击“>>”按钮。
  4. 在效果器子菜单中，选择“New...”
  5. 选择工作单元
  6. 单击 Edit
  7. 修改属性值
  8. 在 Property Editor 的 Effect 选项卡上，将效果器模式更改为“Define custom”
  9. 单击 Edit
  10. 验证效果器具属性值是否已修改

复制父级（效果器插件）

  1. 使用一个效果器创建一个声音
  2. 修改效果器的属性值
  3. 在 Project Explorer 中，复制声音（CTRL+C）
  4. 在 Project Explorer 中，将它粘贴到其他位置（CTRL+V）
  5. 验证复制的声音是否同样应用了效果器，并且属性值正确

复制父级（源插件）

  1. 使用源插件创建一个声音
  2. 修改该源的属性值
  3. 在 Project Explorer 中，复制声音（CTRL+C）
  4. 在 Project Explorer 中，将它粘贴到其他位置（CTRL+V）
  5. 验证被复制的声音包是否含属性值正确的源

删除效果器（效果器插件）

  1. 使用效果器创建一个声音
  2. 修改效果器的属性值
  3. 在 Property Editor 的 Effects 选项卡上，移除效果器
  4. 撤消（CTRL+Z）
  5. 验证效果器是否还原，且属性值正确
  6. 恢复（CTRL+Y）

删除声音（效果器插件）

  1. 使用效果器创建一个声音
  2. 修改效果器的属性值
  3. 在 Project Explorer 中，删除声音
  4. 撤消（CTRL+Z）
  5. 验证效果器是否还原，且属性值正确
  6. 恢复（CTRL+Y）

删除声音（源插件）

  1. 使用源插件创建一个声音
  2. 修改源的属性值
  3. 在 Contents Editor 中，删除源
  4. 撤消（CTRL+Z）
  5. 验证源插件是否还原，且属性值正确
  6. 恢复（CTRL+Y）

删除声音（源插件）

  1. 使用源插件创建一个声音
  2. 修改源的属性值
  3. 在 Project Explorer 中，删除声音
  4. 撤消（CTRL+Z）
  5. 验证源插件是否还原，且属性值正确
  6. 恢复（CTRL+Y）

撤消属性

  1. 对于每个属性或可修改的元素：
    1. 修改值
    2. 打开 Edit 菜单——验证撤消事件的名称是否正确
    3. 撤消
    4. 恢复

一致性

  1. 使用经过修改的属性创建效果器或源插件
  2. 保存工程
  3. 关闭工程
  4. 重新打开工程
  5. 验证源或效果器的属性值是否正确

RTPC 属性名称

  1. 使用源/效果器创建声音
  2. 在插件 RTPC 选项卡中，单击“>>”
  3. 确保支持 RTPC 的所有属性均列出
  4. 确保所有属性名称的第一个单词首字母均为大写

RTPC 属性值域

  1. 使用源/效果器创建一个声音
  2. 将所有属性添加到 RTPC 列表中
  3. 对于每个属性：
    1. 验证值域正确
    2. 验证默认值正确

播放时更改 RTPC

  1. 使用源/效果器创建声音
  2. 对于支持 RTPC 的每个属性：
    1. 向 RTPC 列表中添加属性
    2. 播放父级声音
    3. 在播放时，更改绑定到属性的游戏参数

在播放时更改属性

  1. 使用源/效果器创建一个声音
  2. 播放包含效果器/源的声音（如果声音太短，请将声音设置为循环播放）
  3. 在播放时，针对每个属性：
    1. 更改此值

循环播放声音

  1. 使用源/效果器创建一个声音
  2. 对声音启用循环播放（设置为无限）
  3. 播放声音
  4. 确保没有听到故障杂音
  5. 使用不同的插件属性值重新测试

循环播放容器

  1. 使用源/效果器创建一个声音
  2. 更改随机容器中的父级声音
  3. 将随机容器设置为：PlayMode=Continuous, Loop=Infinite
  4. 播放随机容器
  5. 确保没有听到故障杂音
  6. 使用不同的插件属性值重新测试

循环播放精确到采样的容器

  1. 使用源/效果器创建一个声音
  2. 将父级声音置于随机容器中
  3. 将随机容器设置为：PlayMode=Continuous, Loop=Infinite
  4. 将随机容器设置为：Transition=Sample Accurate
  5. 播放随机容器
  6. 确保没有听到故障杂音
  7. 使用不同的插件属性值重新测试

虚声部（源插件）

  1. 在 Project Settings 对话框中，将 Volume Threshold 设置为 -5 db
  2. 使用源创建声音
  3. 在 Property Editor 的 Advanced Settings 选项卡上，设置 WhenBelowVolumeThreshold=SendToVirtualVoice
  4. 播放声音
  5. 设置声音音量 =-6 db
  6. 确保没有听到故障杂音
  7. 设置声音音量 =0 db
  8. 确保没有听到故障杂音
  9. 使用不同的插件属性值重新测试

对声音使用多声道效果器（效果器插件）

  1. 对于具有以下声道配置的声音：0.1、1.0、1.1、2.0、2.1、4.0、4.1、5.0、5.1
  2. 在声音上使用效果器
  3. 播放声音

在总线上使用多声道效果器（效果器插件）

  1. 创建总线并使用效果器
  2. 对于具有以下声道配置的声音：0.1、1.0、1.1、2.0、2.1、4.0、4.1、5.0、5.1
  3. 将声音的通路指定到此总线
  4. 播放声音

将使用效果器的声音播放多次（效果器插件）

  1. 创建声音并使用效果器
  2. 使用 SoundCaster 同时播放声音多次

在使用效果器的总线上播放多个声音（效果器插件）

  1. 创建总线并使用效果器
  2. 为多个声音指定通路到此总线
  3. 使用 SoundCaster 同时播放多个声音（此总线下）

游戏内测试

需要在游戏内测试插件，以涵盖在 Wwise 中无法测试的方面，例如：

  • 在其他平台上运行代码：PS4、Xbox One 等
  • SoundBank 生成/加载插件参数
  • 启用 Render（预渲染）效果
  • 环境效果器

为了方便在游戏内测试，可以使用 Game Simulator 创建测试脚本。以下是在 Game Simulator 中制作和运行脚本所需的步骤。

  1. 在您的工程中：
    1. 创建 SoundBank
    2. 创建播放声音的事件
    3. 将事件添加到 SoundBank
    4. 生成 SoundBank
  2. 安装 Game Simulator（必须与您正在使用的 Wwise 版本相同）
  3. 从 Scripts 文件夹中复制 AkSampleNoCoroutines.lua 或 AkSampleWithCoroutines.lua 到 Game Simulator 安装目录。
  4. 修改 lua 脚本，以便加载您自己的 SoundBank 并播放事件。
  5. 在选定的平台上使用适当的 Game Simulator 运行 lua 脚本。

Render（预渲染）效果器（效果器插件）

  1. 创建声音并使用效果器
  2. 在 Property Editor 的 Effects 选项卡上，为该效果器启用“Render”。
  3. 在游戏中播放该声音

故障排除

如果遇到任何问题，请参见 Wwise 源插件和效果器插件故障排除指南 中的帮助。