目次

Wwise Project のクエリ

Wwise Authoring APIは、Wwiseプロジェクトの最も重要な要素を取得するための包括的なクエリシステムを提供します。具体的には、プロジェクト内の任意のオブジェクトを取得できます。

クエリシステムは ak.wwise.core.object.get 関数に組み込まれています。詳細については、参照ドキュメントを参照してください。

クエリは2つの部分で構成されています:

  • from: クエリの開始点を指定します。これはデータの取得元です。
  • transform: オブジェクトに適用する一連の変換を指定します。変換は順番に追加できます。

さらに、クエリには次のようなオプションがあります:

  • return: オブジェクトから何を返すかを指定します。指定しない場合、デフォルトは['id', 'name']です。
  • platform: クエリに使用するプラットフォームを指定します。指定しない場合、デフォルトは現在のプラットフォームです。

from

from 文は、クエリを開始するためのいくつかのポイントを提供します。

  • id:オブジェクトID(GUID)の配列を指定します。IDをすでに持っているとき、オブジェクトを検索するのに便利です。
  • name: タイプでqualifyしたオブジェクト名の配列を、type:nameという形式で指定します。サポートされるのは、名前がグローバルに固有なオブジェクトタイプのみです。使用可能なタイプについては、 Wwise Objects Reference を参照してください。
  • search:Wwiseオブジェクトの名前と注釈で、検索するテキストを指定します。これは、Wwise検索と同じ検索エンジンを使用します。
  • path:検索するパスの配列を指定します。パスは絶対パスでなければならず、物理フォルダ名と同じカテゴリ名で始まる必要があります。. 例: \Actor-Mixer Hierarchy\Default Work Unit\MySound。
  • ofType:Wwiseオブジェクトタイプの配列を指定します。これは、すべてのGame Parameter を取得するなど、特定オブジェクトタイプのすべてのオブジェクトを取得する場合に便利です。使用可能なタイプについては、 Wwise Objects Reference を参照してください。

transform

transform 文には、選択中のオブジェクトを変換するために使用できるいくつかの変換関数が用意されています。最初の変換は、 from 文によって選択されたオブジェクトに適用されます。他の変換は、前の変換の結果に適用されます。

複数の変換を順番に追加できます。

  • select parent: すべてのオブジェクトに対して、オブジェクトの親を選択します。
  • select children: すべてのオブジェクトに対して、オブジェクトの子のリストを選択します
  • select descendants: すべてのオブジェクトに対して、すべての子を再帰的に選択します。
  • select ancestors: すべてのオブジェクトに対して、すべての親を再帰的に選択します。
  • select referencesTo: すべてのオブジェクトに関して、そのオブジェクトを参照するすべてのオブジェクトを選択します。
  • where: 以前のイテレータの結果をフィルタリングすることができます。可能な基準は次のとおりです:
    • name:contains: オブジェクト名の大文字小文字を区別しないテキストの検索。
    • name:matches: オブジェクト名の大文字と小文字を区別しない正規表現の検索。
    • type:isIn: 特定オブジェクトタイプのオブジェクトのみを保持することで、以前のイテレータの結果をフィルタリングします。オブジェクトタイプのリストを確認するには、Wwise Objects Reference を参照してください。
    • category:isIn: 特定オブジェクトカテゴリのオブジェクトのみを保持することで、以前のイテレータの結果をフィルタリングします。
  • distinct: ユニークオブジェクトのみを保持することで、以前のイテレータの結果をフィルタリングします。

return(オプション)

return 文(式)は、すべての変換の最後に1回実行されます。変換が指定されていない場合は、 from 文から直接実行されます。 return 式は、返すWwiseオブジェクトの要素を指定します。任意の数の要素を返すことができます。

return 式には、冒頭に「@」を付けると、プロパティとレファレンスを含めることができます。例えば、'@Volume' や '@OutputBus'を含む可能性があります。冒頭に二重の'@@'を付けると、オーバーライドのソースがリターンに使われ、それは階層内のoverride parent'の様々な値によって決まります。

式の解が有効な参照先であれば、さらにクエリをかけ、参照オブジェクトのプロパティを求めることができます。例えば、Soundオブジェクトの '@UserAuxSend0' の参照先が、既存のAuxiliary Busであれば、このAuxiliary Busのプロパティをクエリするには、ピリオド('.')を付け、続いてプロパティディスクリプタを付けます。例えば、参照先のAuxiliary Busの、Attenuationのクエリは、単純に '@UserAuxSend0.@Attenuation'となります。オーバーライドのソースを使い、ダブルの '@@' を使うという方法は、ここでも適用できます。

オブジェクトによっては、ランダム化(randomization)などの特定機能が設定されたプロパティがあります。これらの機能に関連する値を取得するには、そのプロパティに紐づけられた特別なオブジェクトを、数式のようなアクセサー(accessors)を通してクエリできます。例えば、ランダム化機能は、オブジェクトの特定の機能にリンクしたModifierオブジェクトによって記述されています。このオブジェクトは 'randomizer("PropertyName")' でクエリすることができ、ここでPropertyNameには、プロパティの名前、例えば 'Volume'などを入れます。 アクセサーが有効な参照先を提供すれば、前述の方法で、返されたオブジェクトをさらにクエリできます。例えば、Volumeランダマイザーの 'Max' プロパティを取得するには、'randomizer("Volume").@Max' とします。

可能なアクセサーのリストを以下に示します:

  • ランダマイザー(randomizer)

return 式の項目が互換性がないか、返されたオブジェクトに存在しない場合、結果の一部にはなりません。

  • 可能なアクセサーのすべてのリストについては、 ak.wwise.core.object.get を参照してください。
  • 使用可能なプロパティと参照の詳細については、 Wwise Objects Reference を参照してください。

その他のオプション

ak.wwise.core.object.get ファンクションやその他のファンクションは、オプションオブジェクトを使いますが、以下が定義されます:

  • return式(上記セクションを参照)
  • プラットフォーム: プラットフォームのID (guid) または名前。
  • ランゲージ: ランゲージのID (guid) または名前。

一部のアクセサーはオプションに左右されます。例えば、プロパティ値やレファレンス値を取得するときに、アンリンクされた値を入手するためにプラットフォームを指定できます。プラットフォームが指定されない場合は、現在のプラットフォームが使われます。 ランゲージ特有の情報、例えばサウンドオブジェクトのオーディオソースデータを取得するために、ランゲージを指定することもできます。 指定されない場合は、現在のランゲージが使われます。

初期化については プロジェクトコード を参照してください。

ak.wwise.core.object.get にほかの例があります。

オブジェクトのリストのID、名前、音声ボリュームをリターンします。

var query = {
    from: { id: [
        '{A076AA65-B71A-45BB-8841-5A20C52CE727}',
        '{2028C899-8300-4667-ADD0-ED10467BD91E}',
        '{24979032-B170-43E3-A2E4-469E0193E2C3}'
    ] }
};
var options = {
    return: ['id', 'name', '@Volume']
};

session.call('ak.wwise.core.object.get', [], query, options).then(
    function (res) {
        // Print the name and volume
        var objects = res.kwargs.return;
        for(let i = 0; i < objects.length;++i ){
            console.log(`${objects[i].name}: ${objects[i]['@Volume']}`);
        }
    },
    function (error) {
        console.log(`error: ${error}`);
    }        
);

'My' で始まるActor-Mixer Hierarchy のすべてのオブジェクトのIDと名前を正規表現で返します。

var query = {
    from:{path:['\\Actor-Mixer Hierarchy']},
    transform:[
        {select:['descendants']},
        {where:['name:matches','^My']}
    ]
};

var options = {
    return: ['id', 'name']
};

session.call('ak.wwise.core.object.get', [], query, options).then(
    function (res) {
        // Print the name
        var objects = res.kwargs.return;
        for(let i = 0; i < objects.length;++i ){
            console.log(`${objects[i].name}`);
        }
    },
    function (error) {
        console.log(`error: ${error}`);
    }        
);