カスタムプロパティを使うと、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ファイル
![](/images/2023.1.3_8471/?source=SDK&id=images/Note.gif) | 注釈: .wcustompropertiesファイルを変更した場合、そのプロパティを更新するには、Wwiseプロジェクトをリロードする必要があります。カスタムプロパティの名前を変更しても、プロジェクトのコンテンツは自動的に移行されないので、注意してください。 |
![](/images/2023.1.3_8471/?source=SDK&id=images/Note.gif) | 注釈: 名前のコンフリクトがある場合、最初にロードしたプロパティだけが登録されます。プロパティは、上記の順番でロードされます。 |
![](/images/2023.1.3_8471/?source=SDK&id=images/Note.gif) | 注釈: すべてのカスタムプロパティは、それを定義した場所に関わらず、プロジェクトのロード時にロードします。 |
オーディオオブジェクトタイプのカスタムプロパティをゲーム中に取得するには、 AK::SoundEngine::Query::GetCustomPropertyValue
を使います。そのカスタムプロパティは、SoundBanksで、個別の32-bitデータとしてエクスポートされ、32-bit integer (AkInt32) 、または32-bit float (AkReal32) としてクエリできます。ほかのタイプ、例えばbool、int16、Real64などをXMLで指定することができ、Wwise Authoringアプリケーションがそれをネイティブでサポートします。ただし、SoundBank生成時に、サポートするタイプを32ビットにキャストします。文字列などの非数値タイプは、SoundBanksでエクスポートされません。
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>
</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>
</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>
</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>
プロパティやレファレンスに関する詳細は、 Properties XML Description をご覧ください。
WwiseオブジェクトのID
![](/images/2023.1.3_8471/?source=SDK&id=images/Note.gif) | 注釈: カスタムプロパティ値を取得するために使えるのは、サウンドから派生するオブジェクトのみです(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>