目次

カスタムプロパティの定義

カスタムプロパティを使うと、Wwiseオブジェクトに追加情報を保存できます。カスタムプロパティは、プロジェクトマネジメントやゲームで使ったメタデータの保存などに利用できます。

カスタムプロパティは、以下で編集できます:

カスタムプロパティをWwise オーサリングツールのユーザーインターフェース上で直接設定することが可能で、 Project > Project Settings > Custom Properties を選択します。 なお、ユーザーインターフェースを使うと、アクセスできる機能セットは限定されます。これらのカスタムプロパティは、プロジェクトフォルダにあるPROJECTNAME.wcustompropertiesファイルに保存されます(PROJECTNAME はWPROJファイルと同名)。このファイルを直接編集しないこと。

機能セットを完全に有効にするには、以下の場所のいずれかに、XMLファイルで、カスタムプロパティを手動で設定します:

  • "Add-ons\\Properties" フォルダ下のプロジェクトフォルダにある、1つ以上の .wcustompropertiesファイル
  • "%APPDATA%\\Audiokinetic\\Wwise\\Add-ons\\Properties" フォルダにある、1つ以上の.wcustompropertiesファイル
  • Wwiseインスタレーションフォルダ下の "Authoring\\Data\\Add-ons\\Properties" フォルダにある、1つ以上の.wcustompropertiesファイル
Note.gif
Note: .wcustompropertiesファイルを変更した場合、そのプロパティを更新するには、Wwiseプロジェクトをリロードする必要があります。カスタムプロパティの名前を変更しても、プロジェクトのコンテンツは自動的に移行されないので、注意してください。
Note.gif
Note: 名前のコンフリクトがある場合、最初にロードしたプロパティだけが登録されます。プロパティは、上記の順番でロードされます。
Note.gif
Note: すべてのカスタムプロパティは、それを定義した場所に関わらず、プロジェクトのロード時にロードします。

オーディオオブジェクトタイプのカスタムプロパティをゲーム中に取得するには、 AK::SoundEngine::Query::GetCustomPropertyValue を使います。そのカスタムプロパティは、SoundBanksで、個別の32-bitデータとしてエクスポートされ、32-bit integer (AkInt32) 、または32-bit float (AkReal32) としてクエリできます。ほかのタイプ、例えばbool、int16、Real64などをXMLで指定することができ、Wwise Authoringアプリケーションがそれをネイティブでサポートします。ただし、SoundBank生成時に、サポートするタイプを32ビットにキャストします。文字列などの非数値タイプは、SoundBanksでエクスポートされません。

Note.gif
Note: Dialogue Eventオブジェクトもゲーム中にクエリできるカスタムプロパティに対応しますが、詳しくは AK::SoundEngine::DynamicDialogue::GetDialogueEventCustomPropertyValue を参照してください。

XML ファイルのコンテンツ

XML記述ファイルに、オブジェクトタイプによって追加されるカスタムプロパティに関する以下の情報が含まれます:

  • 以下を含むプロパティ定義:
    • プロパティ名(コードやpersistedファイルの中のプロパティを識別するための文字列)
    • プロパティタイプ
    • RTPCサポート
    • デフォルト値
    • サウンドエンジンのプロパティID(このプロパティをサウンドエンジンのプラグインのコードにバインドする)
    • 範囲制限や列挙制限
    • 他プロパティへの依存
    • ユーザーインターフェースの説明要素

例: wcustomproperties File

サウンドオブジェクトの追加プロパティを定義する、単純なカスタムプロパティXML記述ファイルの例を、以下に示します。

<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright (C) Audiokinetic Inc. -->
<PluginModule>
    <WwiseObject Name="Sound" CompanyID="1" PluginID="1">
        <Properties>
            <Property Name="MyCompany:Status" Type="int16" DisplayName="Status">
                <DefaultValue>0</DefaultValue>
                <Restrictions>
                    <ValueRestriction>
                        <Enumeration Type="int16">
                            <Value DisplayName="To do">0</Value>
                            <Value DisplayName="Done">1</Value>
                            <Value DisplayName="Verified">2</Value>
                        </Enumeration>
                    </ValueRestriction>
                </Restrictions>
            </Property>
            <Property Name="MyCompany:IsReady" Type="bool" DisplayName="Is Ready">
                <DefaultValue>false</DefaultValue>
                <AudioEnginePropertyID>2</AudioEnginePropertyID>
            </Property>
            <Property Name="MyCompany:MyPriority" Type="int32" DisplayName="My Priority">
                <DefaultValue>50</DefaultValue>
                <AudioEnginePropertyID>6</AudioEnginePropertyID>
                <Restrictions>
                    <ValueRestriction>
                        <Range Type="int32">
                            <Min>1</Min>
                            <Max>100</Max>
                        </Range>
                    </ValueRestriction>
                </Restrictions>
            </Property>
            <Property Name="MyCompany:CoolDownDelay" Type="Real64" DisplayName="Cool Down Delay">
                <UserInterface  UIMax="10" Step="0.5" Fine="0.1" Decimals="3" />
                <DefaultValue>0</DefaultValue>
                <AudioEnginePropertyID>7</AudioEnginePropertyID>
                <Restrictions>
                    <ValueRestriction>
                        <Range Type="Real64">
                            <Min>0</Min>
                            <Max>600</Max>
                        </Range>
                    </ValueRestriction>
                </Restrictions>
            </Property>
            <Property Name="MyCompany:GameId" Type="string" DisplayName="Game Id">
                <DefaultValue></DefaultValue>
            </Property>
            <Property Name="MyCompany:ReadOnlyData" DocId="MyCustomProperty" DisplayName="ReadOnlyData" Type="int32">
                <UserInterface ControlClass="ReadOnlyText" />
                <DefaultValue>10</DefaultValue>
                <Restrictions>
                    <ValueRestriction>
                        <Range Type="int32">
                            <Min>0</Min>
                            <Max>100</Max>
                        </Range>
                    </ValueRestriction>
                </Restrictions>
            </Property>
            <Reference Name="MyCompany:StateGroup" DisplayName="State Group">
                <AudioEnginePropertyID>10</AudioEnginePropertyID>
                <Restrictions>
                    <TypeEnumerationRestriction>
                        <Type Name="StateGroup" />
                    </TypeEnumerationRestriction>
                </Restrictions>
            </Reference>
        </Properties>
    </WwiseObject>
</PluginModule>

XML 定義ファイルヘッダ

XML ファイルのヘッダ部分を詳しく見てみましょう。

<?xml version="1.0" encoding="UTF-8"?>

すべての XML ファイルの最初の行では、XMLバージョンとエンコーディングが定義されます。ここでは、XMLバージョンは1.0で、エンコーディングは UTF-8 です。Wwise プラグイン記述ファイルの最初の行も、これと全く同様である必要があります。

PluginModule 要素

<PluginModule>
    ...
</PluginModule>

このドキュメント内に記載されているメイン XML 要素は、 PluginModule という名前で、ファイルで定義されている様々なオブジェクトタイプのための全情報を含んでいます。

WwiseObject 要素

    <WwiseObject Name="Sound" CompanyID="1" PluginID="1">
        <Properties>
        ...
        </Properties>
    </WwiseObject>

各WwiseObject要素が、そのオブジェクトタイプのカスタムプロパティを定義します。Name 、CompanyID 、PluginID は、Wwiseで表示されないプロパティである場合を除き、Wwiseが認知しているものと全く同じでなければいけません。可能な WwiseObject 要素のリストを確認するには、 WwiseオブジェクトのID を参照してください。

Properties

カスタムプロパティには、必ずプレフィックスを付けます。これは、Audiokineticの組み込みプロパティ、サードパーティのプロパティ、そしてあなたのカスタムプロパティの間で、プロパティ名のコンフリクトを避けるために非常に重要なことです。

ユーザーインターフェース(Project > Project Settings > Custom Properties)で作成したプロパティは、名前にプレフィックスとして "Custom:" が付きます。プレフィックス"Custom:"は、カスタムプロパティを.wcustompropertiesファイル内で直接定義するときには、使わないでください。自分のプレフィックスを設定するようにします。"Custom:" プレフィックスは、 WPROJECTNAME.wcustomproperties にあるプロパティ以外に付けてはいけません。

あなたの会社名とプロダクト名を、プロパティ名のプレフィックスとして使うことを強く推奨します。例:

            <Property Name="MyCompanyMyProduct:MyProperty" Type="string" DisplayName="Game Id">
                <DefaultValue></DefaultValue>
            </Property>

プロパティやレファレンスに関する詳細は、 プラグインプロパティやカスタムプロパティのXML記述 をご覧ください。

WwiseオブジェクトのID

Note.gif
Note: カスタムプロパティ値を取得するために使えるのは、サウンドから派生するオブジェクトのみです(Music Tracks、Containersを含む)。

Wwise Authoringアプリケーション内で、カスタムプロパティを設定するために使えるすべての WwiseObject タイプを、以下に示します。

<WwiseObject Name="AcousticTexture" CompanyID="1" PluginID="72"></WwiseObject>
<WwiseObject Name="Action" CompanyID="1" PluginID="5"></WwiseObject>
<WwiseObject Name="ActorMixer" CompanyID="1" PluginID="8"></WwiseObject>
<WwiseObject Name="Attenuation" CompanyID="1" PluginID="41"></WwiseObject>
<WwiseObject Name="AudioDevice" CompanyID="1" PluginID="71"></WwiseObject>
<WwiseObject Name="AudioSource" CompanyID="1" PluginID="0"></WwiseObject>
<WwiseObject Name="AuxBus" CompanyID="1" PluginID="61"></WwiseObject>
<WwiseObject Name="BlendContainer" CompanyID="1" PluginID="29"></WwiseObject>
<WwiseObject Name="BlendTrack" CompanyID="1" PluginID="30"></WwiseObject>
<WwiseObject Name="Bus" CompanyID="1" PluginID="21"></WwiseObject>
<WwiseObject Name="ControlSurfaceBinding" CompanyID="1" PluginID="67"></WwiseObject>
<WwiseObject Name="ControlSurfaceBindingGroup" CompanyID="1" PluginID="68"></WwiseObject>
<WwiseObject Name="ControlSurfaceSession" CompanyID="1" PluginID="66"></WwiseObject>
<WwiseObject Name="Conversion" CompanyID="1" PluginID="55"></WwiseObject>
<WwiseObject Name="DialogueEvent" CompanyID="1" PluginID="46"></WwiseObject>
<WwiseObject Name="Effect" CompanyID="1" PluginID="17"></WwiseObject>
<WwiseObject Name="Event" CompanyID="1" PluginID="4"></WwiseObject>
<WwiseObject Name="ExternalSource" CompanyID="1" PluginID="57"></WwiseObject>
<WwiseObject Name="Folder" CompanyID="1" PluginID="2"></WwiseObject>
<WwiseObject Name="GameParameter" CompanyID="1" PluginID="23"></WwiseObject>
<WwiseObject Name="Language" CompanyID="1" PluginID="75"></WwiseObject>
<WwiseObject Name="MixingSession" CompanyID="1" PluginID="53"></WwiseObject>
<WwiseObject Name="Modifier" CompanyID="1" PluginID="15"></WwiseObject>
<WwiseObject Name="ModulatorEnvelope" CompanyID="1" PluginID="65"></WwiseObject>
<WwiseObject Name="ModulatorLfo" CompanyID="1" PluginID="64"></WwiseObject>
<WwiseObject Name="ModulatorTime" CompanyID="1" PluginID="78"></WwiseObject>
<WwiseObject Name="MultiSwitchEntry" CompanyID="1" PluginID="10000"></WwiseObject>
<WwiseObject Name="MusicClip" CompanyID="1" PluginID="60"></WwiseObject>
<WwiseObject Name="MusicClipMidi" CompanyID="1" PluginID="62"></WwiseObject>
<WwiseObject Name="MusicCue" CompanyID="1" PluginID="59"></WwiseObject>
<WwiseObject Name="MusicPlaylistContainer" CompanyID="1" PluginID="34"></WwiseObject>
<WwiseObject Name="MusicPlaylistItem" CompanyID="1" PluginID="36"></WwiseObject>
<WwiseObject Name="MusicSegment" CompanyID="1" PluginID="27"></WwiseObject>
<WwiseObject Name="MusicStinger" CompanyID="1" PluginID="38"></WwiseObject>
<WwiseObject Name="MusicSwitchContainer" CompanyID="1" PluginID="35"></WwiseObject>
<WwiseObject Name="MusicTrack" CompanyID="1" PluginID="28"></WwiseObject>
<WwiseObject Name="MusicTrackSequence" CompanyID="1" PluginID="58"></WwiseObject>
<WwiseObject Name="MusicTransition" CompanyID="1" PluginID="37"></WwiseObject>
<WwiseObject Name="Panner" CompanyID="1" PluginID="42"></WwiseObject>
<WwiseObject Name="Path" CompanyID="1" PluginID="11"></WwiseObject>
<WwiseObject Name="Platform" CompanyID="1" PluginID="69"></WwiseObject>
<WwiseObject Name="Position" CompanyID="1" PluginID="12"></WwiseObject>
<WwiseObject Name="Project" CompanyID="1" PluginID="3"></WwiseObject>
<WwiseObject Name="Query" CompanyID="1" PluginID="32"></WwiseObject>
<WwiseObject Name="RandomSequenceContainer" CompanyID="1" PluginID="9"></WwiseObject>
<WwiseObject Name="SearchCriteria" CompanyID="1" PluginID="33"></WwiseObject>
<WwiseObject Name="Sound" CompanyID="1" PluginID="1"></WwiseObject>
<WwiseObject Name="SoundBank" CompanyID="1" PluginID="18"></WwiseObject>
<WwiseObject Name="SoundcasterSession" CompanyID="1" PluginID="26"></WwiseObject>
<WwiseObject Name="State" CompanyID="1" PluginID="6"></WwiseObject>
<WwiseObject Name="StateGroup" CompanyID="1" PluginID="7"></WwiseObject>
<WwiseObject Name="Switch" CompanyID="1" PluginID="20"></WwiseObject>
<WwiseObject Name="SwitchContainer" CompanyID="1" PluginID="10"></WwiseObject>
<WwiseObject Name="SwitchGroup" CompanyID="1" PluginID="19"></WwiseObject>
<WwiseObject Name="Trigger" CompanyID="1" PluginID="40"></WwiseObject>
<WwiseObject Name="UserProjectSettings" CompanyID="1" PluginID="51"></WwiseObject>
<WwiseObject Name="WorkUnit" CompanyID="1" PluginID="25"></WwiseObject>