Wwise SDK 2019.1.11

初回の設定

始める前に、開発ツールを使うにはPython 2または3をインストールする必要があります。

Property Helpのドキュメンテーションをビルドするには、以下の2つのPythonの依存性（dependency）をインストールしてください:

pip install markdown

pip install jinja2

また、ほかのターゲットプラットフォーム用のあなたのビルドツールも、あなたのPATHに入れえおきます。どのビルドツールをインストールするかについては、プラットフォーム要件を参照してください。

注意: Wwise SDKを Launcher からインストールするときに、すべてのターゲットプラットフォームを必ず選択し、 インストールパスにスペースが入らないようにします。

ツールの概要

Wwise SDKの特定のバージョンでは、開発ツールのプラグインは "%WWISEROOT%/Scripts/Build/Plugins" にあります。これらのファイルに目を通すと、以下のPythonスクリプトが提供されています:

new.py 新しいプラグインを作成するのに使います。
premake.py 特定のターゲットプラットフォーム用にソリューションを生成するために、Premakeをコールします。
build.py 特定のターゲットプラットフォームとコンフィギュレーション用のビルドツールをコールします。
package.py バイナリやその他のファイル（help、factory assetsなど）をtar.xzアーカイブにパッケージします。
generate_bundle.py Wwise Launcherで使うJSONメタデータファイルを生成します。
wp.py すべてのスクリプトに、サブコマンドとしてアクセスできます。

注意: これらのスクリプトは、カレントワーキングディレクトリをあなたのプラグインのルートとみなすので、コールする前に必ず、ディレクトリが正しいことを確認してください！

注釈: これらのスクリプトの使い方について、詳しくは -h または –help コマンドラインフラグで確認できます。

プラグインの作成

新しいプラグインを作成するには、以下のコマンドラインを実行するだけです:

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

これで、プラグインのカレントワーキングディレクトリの名前がついたディレクトリが作成されます。作成するプラグインタイプのためのスケルトンが、ディレクトリに入っています。重要なファイル:

PremakePlugin.lua -> プラグインの、特定プラットフォーム用ソリューションを生成するのに使うPremakeファイル。
ProjectNameConfig.h -> プラグインのグローバルID変数の入ったヘッダ。これを変更するのにはCompany IDやPlugin IDが必要です。
WwisePlugin Directory -> プラグインのオーサリング部分が入っているもので、オーサリングアプリケーションがダイナミックライブラリとして使います。
SoundEnginePlugin -> プラグインのサウンドエンジンの部分が入っているディレクトリ。あなたのゲームでサウンドエンジンが使うもので、静的ライブラリまたは共有ライブラリとしてビルドできます。
FactoryAssets -> プラグインと一緒にインストールするファクトリーアセトの入ったディレクトリ。このディレクトリにあるManifest.xmlファイルが、プロジェクトに含めるファクトリーアセットの、必要な依存性を指定します。

プラグインを書く準備が完了しました！オーディオプラグインの書き方については、オーディオプラグインを参照してください。

注釈: 同じ設定を使った複数のプラグインを生成するときにあるタスクを自動化したければ、プロンプトをコマンドライン引数として出せば事前入力できます。

ターゲットプラットフォームの追加

あなたのプラグインの開発中に、いつでもターゲットプラグインを追加できます。追加するには、プラットフォームをプリメイクしてビルドします。

例えば、コマンドラインで以下を実行すれば、Windows_vc140とAuthoringの2つのプラットフォームをプリメイクし、ビルドできます:

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 コマンドが、プラグインをビルドするのに build コマンドが使うソリューションを生成します。 new コマンドが生成するデフォルトのPremakeコンフィギュレーションファイルはそのまま使えますが、あなたのプラグインの作業をするには、変更が必要になります。 premake コマンドをもう1度コールすると、これらのファイルの変更をすべて上書きしてしまうので、生成されたソリューションを直接修正しないでください 。代わりにPremakeコンフィギュレーションファイルを変更してください。このコンフィギュレーションファイルは、あなたのプラグインのルートにあり、ファイル名は PremakePlugin.lua です。

PremakePlugin.lua を見ると、3つの似たセクションに分かれています。各セクションに、ソリューションの生成方法を設定できる様々な文字列リストの表があります。

表 Plugin.sdk.static は、静的SDKプラグインの設定に使います。
表 Plugin.sdk.shared は、 静的SDKプラグインにリンクしている 共有SDKプラグインのコンフィギュレーションに使います（プリメイクスクリプトの一貫として行われます）。
表 Plugin.authoring は 静的SDKプラグインにリンクしている Authoringプラグインのコンフィギュレーションに使います。

リストの中身の記入方法については、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 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" })

高度な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" コマンドで生成する最初のスケルトンには含まれていません。例えば、ビルド後のフックファイルは以下のような内容になります:

# build_hooks.py
 
# ポストビルドフックを定義し、このファンクションはプラグインにコールされる
# ターゲットのビルドが完了するたびに、開発ツール
def postbuild(**kwargs):
    WWISE_ROOT = kwargs.get("wwise_root") # Wwiseインストールのルートへの絶対パス
    PROJECT_ROOT = kwargs.get("project_root") # プラグインディレクトリのルートへの絶対パス
 
    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
    # ...

こちらは、Windows_vc140とAuthoringのプラットフォーム用に、ビルド後にフックをコールする例です:

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

プラグインをWwise Launcher用にパッケージングする

プラグインをすべてのプラットフォームやコンフィギュレーション用にビルドしたあとに、 Wwise Launcherからインストールできるようにパッケージングできます。以下の2つの手順を行います:

それぞれのターゲットプラットフォームをパッケージングし、特別な 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 フラグの動作も似ていますが、一度に受け付けるパスは1つだけです（2つ以上の追加ファイルをパッケージするには、このフラグを複数回指定します）。

最後に、プロジェクトディレクトリにあるファイルをパッケージするのに、同じ additional_artifacts.json ファイルを使えます。パスの代わりに、destination -> sources の項目を設定します。前述の通り、DestinationのパスはあなたのWwiseインストールのルートに対するものとし、Sourceのパスはプラグインディレクトリのルートに対するものとします。以下は前の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"
    ],
}

さらに、上記の追加アーティファクトファイルは、プロジェクトのルートから、あなたのWwiseインストールのルートまで、ファイルをコピーしやすくするために使えます。destination -> sources の設定は –copy-artifacts フラグを使ってコピーできます。これはパッケージ処理を完全に省略し、単純にファイルをコピーする方法です。

このページはお役に立ちましたか？

サポートは必要ですか？

ご質問や問題、ご不明点はございますか？お気軽にお問い合わせください。

サポートページをご確認ください

あなたのプロジェクトについて教えてください。ご不明な点はありませんか。

プロジェクトを登録していただくことで、ご利用開始のサポートをいたします。

Wwiseからはじめよう