Wwise SDK 2021.1.14

Building your Plug-in

The build command will use the solutions previously generated (refer to Configuring Your Project With Premake if there is no solution in the project folder) to compile the plug-in and copy the binary files to the Wwise installation. This command must be called from within the project folder and needs a few arguments in order to do its job properly. Here is a typical build command:

python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" build -c Release -x x64 -t vc160 Authoring

This will build the project in release mode (-c flag), targeting the architecture x64 (-x flag) and MSVC toolset vc160 (-t flag), for the platform Authoring on the current operating system. Consult the help of the build command for more details about the possible values of its arguments.

python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" build -h

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

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

Note: Some platforms build the plug-in for multiple toolchain versions during execution of the build command, including setting up unique environment variables for each project build invocation. For each supported platform, the "%WWISEROOT%\Scripts\ToolchainSetup\<Platform>" directory, if it exists, contains two files:

ToolchainVers.txt, which specifies the list of supported toolchain versions for the platform
GetToolchainEnv.py, which determines the environment variables to be applied during the build process, given one of the values in ToolchainVers.txt as an argument

If desired, it is also possible to override either of these when executing the build command in wp.py, by specifying "--toolchain-vers {file}" or "--toolchain-env-script {file}" on the command line. This may be desired if you want to maintain your own build structure, or publish your plug-in for toolchains separate from the Wwise SDK.

The projects generated by wp.py also automatically adjust the build output folder for the toolchain version that the project is compiled against, based on the defined environment. For more information on how this is determined for each platform, refer to the corresponding Platform-Specific Information page, which describes this in further detail.

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. You will at least want to build one platform and, if you build for Authoring, you'll probably also want to build the Documentation. This will install the documentation for the plug-in properties, which is shown in the Property Help panel when a property is selected.

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

python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" premake Windows_vc160
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" premake Authoring
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" build Windows_vc160 -c Release -x x64
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" build Authoring -c Release -x x64 -t vc160
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" build Documentation

Executing Post-Build Actions Using Hooks

It is common to want to execute custom actions after building a specific target. This can be 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
    # ...

This example calls a post-build hook for the Windows_vc160 and Authoring platforms:

python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" build Windows_vc160 -c Release -x x64 --build-hooks-file=build_hooks.py
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" build Authoring -c Release -x x64 -t vc160 --build-hooks-file=build_hooks.py
python "%WWISEROOT%/Scripts/Build/Plugins/wp.py" build Documentation

The build_hooks.py file must be located at the root of the plug-in directory.

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_Windows":
        platform_files["Authoring/x64/{}/bin/plugins".format(config)] = [
            "Prebuilt/x64/{}/library.dll".format(config)
        ]
    elif platform == "Windows_vc160":
        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))

The last step to perform, when the development of the plug-in is finished, is to package the project in a format ready to install by the Audiokinetic Launcher. Refer to Packaging your Plug-in for the Audiokinetic Launcher for more details.

Next section: Packaging your Plug-in for the Audiokinetic Launcher

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