目录

定义命令扩展

命令扩展概述

命令扩展方便为 Wwise 设计工具定义新的命令。每个命令都与 Wwise 触发的外部程序关联。所执行的程序可接收来自当前所选对象的各种预定义参数。

可通过不同方式触发扩展命令:

可在多个级别定义扩展命令:

  • 用户数据目录中:APPDATA%\Audiokinetic\Wwise\Add-ons\Commands 下
  • 安装文件夹中:Authoring\Data\Add-ons\Commands 下
  • 工程文件夹中:Add-ons\Commands 下
  • 使用 ak.wwise.ui.commands.register
Note.gif
Note: 在存在 id 冲突时,只注册所加载的第一个命令。系统会按照上述顺序加载命令。
Note.gif
Note: 在启动 Wwise 时,加载安装文件夹或用户数据目录中指定的命令扩展。在加载工程时,加载工程文件夹中指定的命令扩展。

另外,每次在 Wwise 中执行命令时,WAAPI 都会使用 ak.wwise.ui.commands.executed 通知订阅服务器传递所选对象并遵守 WAAPI 返回选项。 在定义扩展命令时,可设为不执行任何程序。因此,您可以使用发布事件在 WAAPI 客户端中执行自编代码。

命令扩展的定义

定义字段

使用以下字段描述命令:

  • id: 为命令定义用户可读的唯一 ID。为了降低 ID 冲突风险,请结合使用作者姓名、产品名称和命令名称。
  • displayName: 定义用户界面中显示的名称。
  • program: 定义执行命令时要运行的程序或脚本。在 args 中定义参数。
  • args: 定义参数。如需了解支持的内置变量,请参阅相关文档。注意,在执行多选时,将根据 startMode 字段扩展变量。
  • cwd: 定义用于执行程序的当前工作目录。
  • defaultShortcut: 定义此命令默认使用的快捷方式。若快捷方式存在冲突,则不使用。可在 Keyboard Shortcut Manager 中更改此快捷方式。
  • startMode: 指定在 Wwise 用户界面中执行多选时如何扩展参数字段中的变量。
  • SingleSelectionSingleProcess: 仅支持单选,启动程序一次。
  • MultipleSelectionSingleProcessSpaceSeparated: 启动程序一次,并将变量扩展为空格分隔的参数(每个变量都加上双引号)。
  • MultipleSelectionMultipleProcesses: 每选中一项启动程序一次(并行执行)。每次运行实例接收一个选定项。
  • contextMenu
    • basePath: 为父级子菜单定义正斜杠分隔的路径。若为空,则在第一个级别插入菜单。
  • enabledFor: 为已启用项定义逗号分隔的对象类型名列表。如需了解支持的类型名称列表,请参阅 Wwise Objects Reference 。若为空,则允许任意类型。
  • visibleFor: 为可见项对应的对象类型名称定义逗号分隔的列表。如需了解支持的类型名称列表,请参阅 Wwise Objects Reference 。若为空,则允许任意类型。
  • mainMenu
    • basePath: 为父级子菜单定义正斜杠分隔的路径。该字段至少要定义一层路径,并与顶层菜单关联。

参数变量

args 字段(程序参数)可使用以下预定义变量。在执行多选时,请参阅 startMode 以便了解这些变量如何解析。

变量 类型 说明
${id} string 对象 ID (GUID)。
${name} string 对象名称。
${notes} string 对象备注。
${type} string 对象类型。有关可用类型的详细信息,请参阅 Wwise Objects Reference
${path} string 工程根目录下的对象路径。例如:'\\Actor-Mixer Hierarchy\\Default Work Unit\\Sound1'
${isPlayable} boolean 若对象可在 Transport 中播放,则返回 True。
${shortId} integer 对象短 ID。
${classId} integer 对象类 ID。
${category} string 对象类别。例如:Actor-Mixer Hierarchy
${filePath} string 对象所在文件的路径。该路径可为 Work Unit 文件或工程文件。
${childrenCount} number 对象的子对象数量。
${sound:originalWavFilePath} string 原始 WAV 文件的绝对路径。仅适用于 Sound 和 Audio Source 对象。
${sound:convertedWemFilePath} string 转码后 WEM 文件的绝对路径。指定选项中的平台。仅适用于 Sound 和 Audio Source 对象。
${soundbank:bnkFilePath} string 所生成的 SoundBank 文件的绝对路径,该文件与 SoundBank 对象关联。仅适用于 SoundBank 对象。
${workunit:isDefault} boolean 若 Work Unit 为默认工作单元,则返回 True。
${workunit:type} string Work Unit 的类型。请注意,物理文件夹与 Work Unit 一样,类型都是 WorkUnit。物理文件夹的 workunit:type 为 folder。
可能的值:folder、rootFile、nestedFile
${workunit:isDirty} boolean 若 Work Unit 或工程(wproj 文件)未清理(即修改了而没保存),则返回 True。

命令扩展示例

定义字段

若要创建新的命令,请在“ 定义命令扩展 ”中列出的其中一个目录下创建 JSON 文件。 请注意,很多第三方都可能会在这些目录下创建文件。 为了降低文件名冲突风险,建议使用以下命名规范:companyname_productname.json

示例: mycompany_myproduct.json

{
    "commands":[
        {
            "id":"ak.edit_in_vscode",
            "displayName":"Edit in Visual Studio Code",
            "defaultShortcut":"C",
            "program":"code",
            "startMode":"MultipleSelectionSingleProcessSpaceSeparated",
            "args":"${filePath}",
            "cwd":"",
            "contextMenu":{
                    "basePath":"Editors",
                    "enabledFor":"Sound,ActorMixer,SwitchContainer,RandomSequenceContainer"
                },          
            "mainMenu":{
                    "basePath":"Extra"
                }
        },
        {
            "id":"ak.open_in_wavosaur",
            "displayName":"Edit in My Wav Editor",
            "defaultShortcut":"W",
            "program":"c:\\MyWavEditor\\WavEditor.exe",
            "args":"${sound:originalWavFilePath}",
            "cwd":"",
            "contextMenu":{}
        }          
    ]
}

示例 – 使用 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 上,使用以下格式执行扩展命令:

 /bin/sh -c

. 可直接在 program 中指定可执行程序或脚本。若要打开应用程序,则必须使用 open 命令。若路径包含空格,则必须在其前后加上单引号。

示例: mycompany_myproduct_forMac.json

{
    "commands":[
        {
            "id":"ak.edit_in_audacity",
            "displayName":"Open wav in Audacity",
            "defaultShortcut":"A",
            "program":"open -n -a /Applications/Audacity.app",
            "startMode":"SingleSelectionSingleProcess",
            "args":"${sound:originalWavFilePath}",
            "cwd":"",
            "contextMenu": {
                "basePath":"Editors",
                "enabledFor":"Sound"
            }
        },
        {
            "id":"ak.edit_in_script",
            "displayName":"Open in script",
            "defaultShortcut":"A",
            "program":"'/path/to/folder with spaces/myScript.sh'",
            "startMode":"SingleSelectionSingleProcess",
            "args":"${sound:originalWavFilePath}",
            "cwd":"",
            "contextMenu": {
                "basePath":"Editors",
                "enabledFor":"Sound"
            }
        }
    ]
}