Wwise SDK 2019.1.11

首次设置

在使用开发工具之前，必须先安装 Python 2 或 3。

若要构建属性帮助文档，请安装以下两个 Python 依赖项：

pip install markdown

pip install jinja2

另外，请记得将 PATH 中其他目标平台所需的构建工具包含在内。如需进一步了解所需安装的构建工具，请参阅平台要求章节。

注意: 在通过 Launcher 安装 Wwise SDK 时，请选中所有目标平台并确保安装路径中没有空格。

工具概述

对于给定版本的 Wwise SDK，插件开发工具存放在 "%WWISEROOT%/Scripts/Build/Plugins" 下。快速查看一下此目录中的这些文件，便会发现有以下 Python 脚本可供使用：

new.py 辅助创建新的插件。
premake.py 调用 Premake 以便为给定目标平台生成解决方案。
build.py 调用针对给定目标平台和配置提供的构建工具。
package.py 将二进制及其他文件（帮助、出厂素材等）打包到 tar.xz 存档中。
generate_bundle.py 生成 JSON 元数据文件以便用于 Wwise Launcher。
wp.py 方便以子命令形式访问所有脚本。

注意: 这些脚本假定当前工作目录即为插件的根目录，因此请在调用前确认所在目录是否正确。

备注: 您可以通过 -h 或 –help 命令行标记来查看有关如何使用这些脚本的详细信息。

创建插件

若要创建新的插件，请在命令行中直接运行以下代码：

python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" new
(answer prompts)
cd <PluginName>

这样会创建一个以插件的当前工作目录命名的目录。该目录包含所要创建的插件类型的框架。主要文件：

PremakePlugin.lua -> 该 Premake 文件用于针对插件生成平台特定解决方案。
ProjectNameConfig.h -> 该头文件包含插件的全局标识变量。需要使用 Company ID 和 Plugin ID 来对此进行修改。
WwisePlugin Directory -> 该目录包含插件的 Authoring 部分。这一部分由设计工具用作动态库。
SoundEnginePlugin -> 该目录包含插件的 Sound Engine 部分。这一部分由声音引擎用在游戏中，并可构建为静态库或共享库。
FactoryAssets -> 该目录包含插件所需安装的全部出厂素材。此目录中的 Manifest.xml 文件会指定工程内所要包含的各个出厂素材的必要依赖项。

接下来便可开始编写插件了！有关如何编写音频插件的详细信息，请参阅音频插件章节。

备注: 若要使用相同的设置生成插件或想自动完成这项任务，则可通过将前述提问作为命令行参数传递来实施预填充。

添加目标平台

在开发插件的过程中，随时都可以添加目标平台。为此，可使用 premake 和 build 来添加所需平台。

比如，通过在命令行中运行以下代码，来添加 Windows_vc140 和 Authoring 平台：

python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" premake Windows_vc140
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" premake Authoring
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" build Windows_vc140 -c Debug
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" build Authoring -c Debug -x x64_vc140
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" build Documentation

二进制文件会直接输出到 Wwise 安装目录中以供稍后测试：

对于插件的 SoundEngine 部分，会存放到 "%WWISEROOT%/SDK/<Platform>/<Config>/{bin,lib}" 下。
对于插件的 Authoring 部分，会存放到 "%WWISEROOT%/Authoring/x64/<Config>/bin/plugins" 下。
对于插件的 Documentation 部分，会存放到 "%WWISEROOT%/Authoring/Data/Plugins/<PluginName>/Html" 下。

使用 Premake 配置工程

premake 命令会生成供 build 命令用来构建插件的解决方案。new 命令生成的默认 Premake 配置文件只需稍作修改便可用于所要创建的插件。注意不可直接修改生成的解决方案，因为再次调用 premake 命令会覆盖针对这些文件所作的全部修改。正确的做法是修改 Premake 配置文件。此配置文件存放在插件的根目录下，名为 PremakePlugin.lua。

我们来看下 PremakePlugin.lua，注意它被分成了以下三个相似的部分。每个部分包含一个表格，里面设有多个字符串列表，用于配置如何生成解决方案：

Plugin.sdk.static 表格用于配置静态 SDK 插件。
Plugin.sdk.shared 表格用于配置共享 SDK 插件，并链接静态 SDK 插件（由 premake 脚本在后台完成）。
Plugin.authoring 表格用于配置 Authoring 插件，并链接静态 SDK 插件。

有关如何填充每个列表的详细信息，请参阅 Premake 文档：

includedirs -> https://github.com/premake/premake-core/wiki/includedirs
files -> https://github.com/premake/premake-core/wiki/files
excludes -> https://github.com/premake/premake-core/wiki/removefiles
links -> https://github.com/premake/premake-core/wiki/links
libdirs -> https://github.com/premake/premake-core/wiki/libdirs
defines -> https://github.com/premake/premake-core/wiki/defines

即便没有包含在生成的 PremakePlugin.lua 文件中，也会提供一个可选的 Plugin.sdk.authoringstatic 表格。该表格专门用于特定的用例，可为链接 Authoring 插件的静态 SDK 插件提供不同的配置。这里的示例展示了如何重复使用相同的 SDK 插件代码，并通过 FOR_AUTHORING 编译器进行如下定义：

Plugin.sdk.staticauthoring = {}
 
-- SDK STATIC AUTHORING PLUGIN SECTION
Plugin.sdk.staticauthoring.includedirs = Plugin.sdk.static.includedirs
Plugin.sdk.staticauthoring.files = Plugin.sdk.static.files
Plugin.sdk.staticauthoring.excludes = Plugin.sdk.static.excludes
Plugin.sdk.staticauthoring.links = Plugin.sdk.static.links
Plugin.sdk.staticauthoring.libdirs = Plugin.sdk.static.libdirs
Plugin.sdk.staticauthoring.defines = table.join(Plugin.sdk.static.defines, { "FOR_AUTHORING" })

高级 Premake 配置

从以下示例可以看出工程的配置非常简单，因为大部分 Premake 代码都隐藏在了配置表中。若要实施更为高级的配置，请将 custom 字段添加到以下相应配置部分：

Plugin.sdk.static = function()
    -- 在此插入 Premake 代码
end
Plugin.sdk.shared = function()
    -- 在此插入 Premake 代码
end
Plugin.authoring = function()
    -- 在此插入 Premake 代码
end

使用挂钩执行构建后操作

在构建特定目标后，经常要执行各种自定义操作。要想进一步实现这一点，可将 –build-hooks-file 标记添加到 build 命令并指定相应的 Python 文件。此文件必须由 User 自行创建，它并不包含在 new 命令生成的初始框架中。这里的示例展示了 post-build 挂钩文件所含的内容：

# build_hooks.py
 
# 定义 postbuild 挂钩
# 此函数由插件开发工具在每次成功构建目标后调用
def postbuild(**kwargs):
    WWISE_ROOT = kwargs.get("wwise_root") # Wwise 安装根目录的绝对路径
    PROJECT_ROOT = kwargs.get("project_root") # 插件根目录的绝对路径
 
    platform = kwargs.get("platform") # # 所构建的平台的名称（Authoring、Windows_vc140 等）
    arch = kwargs.get("arch") # 所构建的基础架构（Win32_vc140、x64_vc140 等）
    config = kwargs.get("config") # 所构建的配置（Debug、Profile、Release）
 
    # 在此处插入代码
    # ...

这里的示例会针对 Windows_vc140 和 Authoring 平台调用 post-build 挂钩：

python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" build Windows_vc140 -c Debug --build-hooks-file=build_hooks.py
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" build Authoring -c Debug --build-hooks-file=build_hooks.py
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" build Documentation

build_hooks.py 文件将被存放在插件根目录并包含与此相似的内容。

这里的示例会将 DLL 文件 (library.dll) 从插件目录复制到 Wwise 安装目录：

import os

import shutil

import sys
 
def postbuild(**kwargs):
    WWISE_ROOT = kwargs.get("wwise_root")
    PROJECT_ROOT = kwargs.get("project_root")
 
    platform = kwargs.get("platform")
    arch = kwargs.get("arch")
    config = kwargs.get("config")
 
    # 为目标文件夹构建多重映射 => 所要复制的文件
    platform_files = {}
    if platform == "Authoring":
        platform_files["Authoring/x64/{}/bin/plugins".format(config)] = [
            "Prebuilt/x64/{}/library.dll".format(config)
        ]
    elif platform == "Windows_vc140":
        platform_files["SDK/{}/{}/bin".format(arch, config)] = [
            "Prebuilt/{}/{}/library.dll".format(arch, config)
        ]
 
    # Copy all of the file to their destination
    for dest, files in platform_files.items():
        dest = os.path.join(WWISE_ROOT, dest)
        for file in files:
            file = os.path.join(PROJECT_ROOT, file)
            try:
                shutil.copy(file, dest)
                print("POSTBUILD HOOK: Copied {} to {}".format(file, dest))
            except IOError:
                sys.stderr.write("POSTBUILD HOOK: Failed to copy {} to {}\n".format(file, dest))

将插件打包以便用在 Wwise Launcher 中

在针对所有目标平台和配置构建插件后，需要将其打包以便通过 Wwise Launcher 安装。为此，请执行以下两个步骤：

打包各个目标平台以及专用的 Common 平台。打包脚本会从 Wwise 安装目录自动检索全部所需文件。
生成 bundle.json 文件。捆绑包生成脚本会从插件目录自动检索之前打包的存档。

比如，通过在命令行中运行以下代码，来打包 Common、Documentation、Windows_vc140 和 Authoring 平台：

python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" package Common --version=XXXX.X.X.X
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" package Documentation --version=XXXX.X.X.X
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" package Windows_vc140 --version=XXXX.X.X.X
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" package Authoring --version=XXXX.X.X.X
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" generate-bundle --version=XXXX.X.X.X

备注: 在生成捆绑包之前，可能还要编辑 bundle_template.json 文件。如需进一步了解插件打包格式及其与 Wwise Launcher 的关系，请参阅为 Wwise Launcher 打包插件。

备注: 插件的 Documentation 部分为可选部分。

使用插件打包附加文件

您可以使用 –additional-artifacts 或 –additional-artifacts-file 标记来针对任何平台打包附加文件。

在使用 –additional-artifacts-file 标记时，必须提供相应的 JSON 文件以列出所要打包的附加文件。路径必须是相对于 Wwise 安装根目录的，并且同样可以包含 glob 模式。

这里我们以前面章节中的命令行为例稍作更新，以便针对 Windows_vc140 和 Authoring 平台打包附加 DLL 文件：

python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" package Common --version=XXXX.X.X.X
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" package Documentation --version=XXXX.X.X.X
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" package Windows_vc140 --version=XXXX.X.X.X --additional-artifacts-file=additional_artifacts.json
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" package Authoring --version=XXXX.X.X.X --additional-artifacts-file=additional_artifacts.json
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" generate-bundle --version=XXXX.X.X.X

前面例子中所用的 additional_artifacts.json 文件将被存放在插件根目录并包含以下内容：

{
    "Authoring": [
        "Authoring/x64/*/bin/plugins/library.dll"
    ],
    "Windows_vc140": [
        "SDK/Win32_vc140/*/bin/library.dll",
        "SDK/x64_vc140/*/bin/library.dll"
    ],
    "Windows_vc150": [
        "SDK/Win32_vc150/*/bin/library.dll",
        "SDK/x64_vc150/*/bin/library.dll"
    ],
}

–additional-artifacts 标记的作用与此类似，只不过其每次只接收一个路径（若要打包多个附加文件，则须多次指定该标记）。

最后，可使用同一 additional_artifacts.json 文件来打包存放在工程目录下的文件。为此，请指定 destination -> sources 条目而非路径。如前所述，目标路径必须是相对于 Wwise 安装根目录的，而源路径则须是相对于插件根目录的。这里我们对前面的 Authoring 平台示例稍作更新，以便同时打包 Factory Assets 和 Help 文件：

{
    "Authoring": [
        "Authoring/x64/*/bin/plugins/library.dll",
        {
            "Authoring/Help/<PluginName>": [
                "Help/*.pdf"
            ],
            "Authoring/Data/Factory Assets/<PluginName>": [
                "FactoryAssets/*.wproj",
                "FactoryAssets/*.xml"
            ]
        }
    ],
    "Windows_vc140": [
        "SDK/Win32_vc140/*/bin/library.dll",
        "SDK/x64_vc140/*/bin/library.dll"
    ],
    "Windows_vc150": [
        "SDK/Win32_vc150/*/bin/library.dll",
        "SDK/x64_vc150/*/bin/library.dll"
    ],
}

前面所述的 additional_artifacts 文件可进一步用来将文件从工程根目录复制到 Wwise 安装根目录。destination -> sources 条目可使用 –copy-artifacts 标记来复制。此选项会跳过打包流程，而直接复制相应的文件。

此页面对您是否有帮助？

需要技术支持？

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

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

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

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

开始 Wwise 之旅