Wwise SDK 2019.1.11

First-time Setup

Before getting started, Python 2 or 3 must be installed to use the development tools.

To build the property help documentation, install these two Python dependencies:

pip install markdown

pip install jinja2

Also, remember to include your build tools for other targeted platforms in your PATH. For more information on which build tools to install refer to Platform Requirements.

Caution: When installing the Wwise SDK from the Launcher, select all target platforms and ensure there are no spaces in the installation path.

Overview of the Tools

For a given version of Wwise SDK, the development tools plug-in is located in "%WWISEROOT%/Scripts/Build/Plugins". A quick look at these files provides the following Python scripts:

new.py Assists in creating new plug-ins.
premake.py Calls Premake to generate solutions for a given target platform.
build.py Calls the build tools for a given target platform and configuration.
package.py Packages binaries and other files (help, factory assets, etc.) into tar.xz archives.
generate_bundle.py Generates a JSON metadata file for use with the Wwise Launcher.
wp.py Allows access to all scripts as subcommands.

Caution: These scripts assume that the current working directory is the root of your plug-in, therefore ensure the right directory before calling them!

Note: More information about how to use these scripts is available through the -h or –help command-line flags.

Creating a Plug-in

To create a new plug-in, simply run the following in a command-line:

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

This will create a directory that is named after your plug-in's current working directory. The directory contains a skeleton for the type of plug-in to create. Important files:

PremakePlugin.lua -> Premake file used to generate platform-specific solutions for a plug-in.
ProjectNameConfig.h -> Header containing global identification variables for a plug-in. It is required to modify this with a Company ID and Plugin ID.
WwisePlugin Directory -> Contains the authoring part of the plug-in and it is used as a dynamic library by the Authoring application.
SoundEnginePlugin -> The directory containing the sound engine part of your plug-in. It is used in your game by the sound engine and can be built as a static library or a shared library.
FactoryAssets -> The directory containing any factory assets that should be installed with the plug-in. A Manifest.xml file in this directory specifies the required dependencies for any factory assets to be included in a project.

You can now successfully start writing your plug-in! Refer to Audio Plug-ins for more information on how to write audio plug-ins.

Note: If you are generating plug-ins using the same settings and want to automate a task, prompts can be pre-filled by passing them as command-line arguments.

Adding a Target Platform

Target platforms can be added at any point during the development of your plug-in. This is done by premaking and building a platform.

For example, run the following in a command-line to premake and build the Windows_vc140 and Authoring platforms:

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

The binaries will output directly to your Wwise installation and be ready for testing:

For the SoundEngine plug-in part, go to "%WWISEROOT%/SDK/<Platform>/<Config>/{bin,lib}".
For the Authoring plug-in part, go to "%WWISEROOT%/Authoring/x64/<Config>/bin/plugins".
For the Documentation plug-in part, go to "%WWISEROOT%/Authoring/Data/Plugins/<PluginName>/Html".

Configuring Your Project With Premake

The premake command generates the solutions that will be used by the build command to build your plug-in. The default Premake configuration file generated by the new command works out of the box, however further modifications will be needed to work on your plug-in. The generated solutions should not be modified directly as calling the premake command again will overwrite all changes to these files. Instead, modify the Premake configuration file. This configuration file is located at the root of your plug-in and is named PremakePlugin.lua.

Looking at the PremakePlugin.lua, notice how it is divided into three similar sections. Each section contains a table with various lists of strings that are used to configure how a solution is generated:

The Plugin.sdk.static table is used to configure the static SDK plug-in.
The Plugin.sdk.shared table is used to configure the shared SDK plug-in, which links to the static SDK plug-in (this is done under the hood by premake scripts).
The Plugin.authoring table is used to configure the Authoring plug-in, which links to the static SDK plug-in.

Further information on how to populate each list is found in the Premake documentation:

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

Even though it is not included in the generated PremakePlugin.lua file, there is also an optional Plugin.sdk.authoringstatic table. This is used for unique use-cases and provides a different configuration for the static SDK plug-in that is linked to the Authoring plug-in. For example, this demonstrates how to re-use the same SDK plug-in code with a FOR_AUTHORING compiler define:

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" })

Advanced Premake Configuration

Notice how configuring a project is fairly straightforward since most of the Premake code is hidden in the configuration table. For a more advanced configuration, add a custom field to any of the following configuration sections:

Plugin.sdk.static = function()
    -- put your Premake code here
end
Plugin.sdk.shared = function()
    -- put your Premake code here
end
Plugin.authoring = function()
    -- put your Premake code here
end

Executing Post-Build Actions Using Hooks

It is common to want to execute custom actions after building a specific target. This can be further achieved by adding the –build-hooks-file flag to the "build" command and specifying a Python file. This file must be created by the User and is not part of the initial skeleton generated by the "new" command. For example, this illustrates the content of a post-build hook file:

# build_hooks.py
 
# Defines a postbuild hook, this is the function that gets called by the plug-in
# development tools every time a target is successfully built
def postbuild(**kwargs):
    WWISE_ROOT = kwargs.get("wwise_root") # Absolute path to the root of the Wwise installation
    PROJECT_ROOT = kwargs.get("project_root") # Absolute path to the root of the plug-in directory
 
    platform = kwargs.get("platform") # Name of the platform that was built (Authoring, Windows_vc140, etc.)
    arch = kwargs.get("arch") # The architecture that was built (Win32_vc140, x64_vc140, etc.)
    config = kwargs.get("config") # The configuration that was built (Debug, Profile, Release)
 
    # Put your code here
    # ...

And this example calls a post-build hook for the Windows_vc140 and Authoring platforms:

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

The build_hooks.py file is located at the root of the plug-in directory and would have similar content.

Another example copies a DLL file "library.dll" from the plug-in directory to the Wwise installation:

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")
 
    # Build a multimap of destination folders => files to copy
    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))

Packaging your Plug-in for the Wwise Launcher

After your plug-in is built for all target platforms and configurations, you may want to package it for installation through the Wwise Launcher. This is a two-step process:

Package each of your target platforms, as well as the special Common platform. The packaging script will automatically retrieve all of the required files from your Wwise installation.
Generate the bundle.json file. The bundle generation script will automatically retrieve the previously packaged archives from your plug-in directory.

For example, run the following in the command-line to package the Common, Documentation, Windows_vc140, and Authoring platforms:

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

Note: Also, you may want to edit the bundle_template.json file before bundle generation. Refer to Packaging Plug-ins for the Wwise Launcher for more information on the plug-in packaging format and how it relates to the Wwise Launcher.

Note: The Documentation part of the plug-in is optional.

Packaging Additional Files With Your Plug-in

Additional files can be packaged with any platform using either the –additional-artifacts flag or the –additional-artifacts-file flag.

When using the –additional-artifacts-file flag, a JSON file listing the paths of additional files to package must be provided. The paths must be relative to the root of your Wwise installation and may also contain glob patterns.

For example, this is the command-line from the previous section: it is updated to package an additional DLL file with the Windows_vc140 and Authoring platforms:

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

The additional_artifacts.json file used in the previous example is located at the root of the plug-in directory and has the following content:

{
    "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"
    ],
}

The –additional-artifacts flag behaves similarly, but only accepts a single path at a time (the flag must be specified multiple times to package more than one additional file).

Finally, the same additional_artifacts.json file can be used to package files that are located in the project directory. Specify a destination -> sources entry, instead of a path. As stated previously, the destination path must be relative to the root of your Wwise installation and source paths must be relative to the root of the plug-in directory. Here is a new version of the previous Authoring platform example, which now extends to package Factory Assets and Help files:

{
    "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"
    ],
}

The additional artifacts file presented above can further be used to facilitate the copy of files from the project root to the root of your Wwise installation. The destination -> sources entries can be copied using the –copy-artifacts flag. This option will skip packaging altogether and simply copy the files.

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Get started with Wwise