|
Wwise SDK 2023.1.8
|
命令扩展概述
命令扩展方便为 Wwise 设计工具定义新的命令。每个命令都与 Wwise 触发的外部程序关联。所执行的程序可接收来自当前所选对象的各种预定义参数。
可通过不同方式触发扩展命令：
- 键盘快捷方式
- 上下文菜单
- 主菜单
- 控制器
- WAAPI（使用 ak.wwise.ui.commands.execute ）
可在多个级别定义扩展命令：
- 用户数据目录中：
- Windows："%APPDATA%\\Audiokinetic\\Wwise\\Add-ons\\Commands"
- macOS："$HOME/Library/Application Support/Audiokinetic/Wwise/Add-ons/Commands"
- 安装文件夹中：
- Windows："%WWISEROOT%\\Authoring\\Data\\Add-ons\\Commands"
- macOS："/Library/Application Support/Audiokinetic/Wwise <version>/Authoring/Data/Add-ons/Commands"
- 工程文件夹中：Add-ons\Commands 下
- 使用 ak.wwise.ui.commands.register
 | 备注: 在存在 id 冲突时，只注册所加载的第一个命令。系统会按照上述顺序加载命令。 |
| 备注: 在启动 Wwise 时，加载安装文件夹或用户数据目录中指定的命令扩展。在加载工程时，加载工程文件夹中指定的命令扩展。 |
另外，每次在 Wwise 中执行命令时，WAAPI 都会使用 ak.wwise.ui.commands.executed 通知订阅服务器传递所选对象并遵守 WAAPI 返回选项。 在定义扩展命令时，可设为不执行任何程序。因此，您可以使用发布事件在 WAAPI 客户端中执行自编代码。
命令扩展的定义
定义字段
使用以下字段描述命令：
- id： 为命令定义用户可读的唯一 ID。为了降低 ID 冲突风险，请结合使用作者姓名、产品名称和命令名称。
- displayName： 定义用户界面中显示的名称。
- program： 定义执行命令时要运行的程序或脚本。在 args 中定义参数。
- args： 定义参数。如需了解支持的内置变量，请参阅相关文档。注意，在执行多选时，将根据 startMode 字段扩展变量。
- cwd： 定义用于执行程序的当前工作目录。
- defaultShortcut： 定义此命令默认使用的快捷方式。若快捷方式存在冲突，则不使用。可在 Keyboard Shortcut Manager 中更改此快捷方式。
- redirectOutputs ：（仅限 Windows）定义程序的标准输出流 (stdout + stderr) 是否要在终止时转为在 Wwise 中记录。 This also prevents the window from displaying. Note that this feature should only be used for programs that will run briefly. 该值为布尔类型，默认值为 false。
- startMode： 指定在 Wwise 用户界面中执行多选时如何扩展参数字段中的变量。可能值是：
- SingleSelectionSingleProcess： 仅支持单选，启动程序一次。
- MultipleSelectionSingleProcessSpaceSeparated： 启动程序一次，并将变量扩展为空格分隔的参数（每个变量都加上双引号）。
- MultipleSelectionMultipleProcesses： 每选中一项启动程序一次（并行执行）。每次运行实例接收一个选定项。
- contextMenu： 指定要将命令显示在上下文菜单中的哪个位置以及可用于哪些对象类型。此字段可包含以下条目：
- basePath： 为父级子菜单定义正斜杠分隔的路径。若为空，则在第一个级别插入菜单。
- enabledFor： 为已启用项定义逗号分隔的对象类型名列表。如需了解支持的类型名称列表，请参阅 Wwise 对象参考 。若为空，则允许任意类型。
- visibleFor： 为可见项对应的对象类型名称定义逗号分隔的列表。如需了解支持的类型名称列表，请参阅 Wwise 对象参考 。若为空，则允许任意类型。
- mainMenu： 指定要将命令显示在 Wwise 菜单中的哪个位置。
- basePath： 为父级子菜单定义正斜杠分隔的路径。该字段至少要定义一层路径，并与顶层菜单关联。
通用目录
为了避开电脑专用绝对路径，请将以下预定义目录用在 program 字段中。另外，您也可以将其用在 args 字段中来把路径作为参数传给程序，或者用在 cwd 字段中来定义当前工作目录。
| 变量 | 引用位置 |
|---|---|
| ${CurrentCommandDirectory} | 当前命令所在目录。如上所述，其应为 "Add-ons\\Commands"。 |
| ${WwiseInstallRoot} | Wwise 安装目录。 |
| ${WwiseInstallBin} | Wwise.exe 目录。 |
| ${WwiseInstallAddons} | Windows："${WwiseInstallRoot}\\Authoring\\Data\\Add-ons" macOS："/Library/Application Support/Audiokinetic/Wwise <version>/Authoring/Data/Add-ons/Commands" |
| ${WwiseUserAddons} | Windows："%APPDATA%\\Audiokinetic\\Wwise\\Add-ons" macOS："$HOME/Library/Application Support/Audiokinetic/Wwise/Add-ons/Commands" |
| ${WwiseProjectRoot} | Wwise 工程目录。 |
| ${WwiseProjectAddons} | "${WwiseProjectRoot}\\Add-ons" |
| ${WwiseProjectOriginals} | "${WwiseProjectRoot}\\Originals" |
| ${WwiseProjectSoundbanks} | 平台特定 Generated SoundBanks 目录。 |
参数变量
args 字段（程序参数）中可使用零到多个变量。您可以利用变量来从选定对象获取信息。比如，您可以检索对象 ID 并将其作为参数来传递。另外，还可利用变量从选定对象获取属性值，包括 Custom Properties 值。如需进一步了解 Custom Properties，请参阅 定义自定义属性 章节。
如需查看变量中可用的表达式的完整列表，请参阅 Wwise Authoring Query Language (WAQL) 参考 中的对象表达式和数值表达式章节。
在执行多选时，请参阅 startMode 以便了解这些变量如何解析。
例如：
| 变量 | 类型 | 说明 |
|---|---|---|
| ${id} | string | 对象 ID (GUID)。 |
| ${name} | string | 对象名称。 |
| ${notes} | string | 对象备注。 |
| ${type} | string | 对象类型。有关可用类型的详细信息，请参阅 Wwise 对象参考 。 |
| ${path} | string | 工程根目录下的对象路径。例如：'\\Actor-Mixer Hierarchy\\Default Work Unit\\Sound1' |
| ${filePath} | string | 对象所在文件的路径。该路径可为 Work Unit 文件或工程文件。 |
| ${originalWavFilePath} | string | 原始 WAV 文件的绝对路径。仅适用于 Sound 和 Audio Source 对象。 |
| ${convertedWemFilePath} | string | 转码后 WEM 文件的绝对路径。指定选项中的平台。仅适用于 Sound 和 Audio Source 对象。 |
| ${soundbankBnkFilePath} | string | 所生成的 SoundBank 文件的绝对路径，该文件与 SoundBank 对象关联。仅适用于 SoundBank 对象。 |
| ${workunitIsDirty} | boolean | 若 Work Unit 或工程（wproj 文件）未清理（即修改了而没保存），则返回 True。 |
| ${Volume} | string | Voice Volume。 |
| ${OutputBus.name} | string | Output Bus 名称。 |
命令扩展示例
示例 – 使用命令定义文件
若要创建新的命令，请在 定义命令扩展 中列出的某个目录下创建 JSON 文件，并将版本指定为 2。 请注意，很多第三方都可能会在这些目录下创建文件。 为了降低文件名冲突风险，建议使用以下命名规范：companyname_productname.json
示例： mycompany_myproduct.json
示例 – 使用 WAAPI
在向当前 Wwise 进程添加新命令时，可将上述相同的 JSON 命令代码传给 WAAPI ak.wwise.ui.commands.register 。
请注意，系统不会保留通过 ak.wwise.ui.commands.register 添加的命令。一旦 Wwise 进程终止，这些命令马上就会被删除。 所以，下次需要重新注册。
结合 WAAPI 使用扩展命令
扩展命令可用于执行 WAAPI 脚本或程序。这样方便用户访问 Wwise 功能和工程数据。有关如何使用 WAAPI 的信息，请参阅“ 使用 Wwise Authoring API（WAAPI） ”。
在 Mac 上使用扩展命令
在 Mac 上，使用以下格式执行扩展命令：
. 可直接在 program 中指定应用程序、可执行文件或脚本。
示例： mycompany_myproduct_forMac.json