Wwise SDK 2024.1.9

自定义属性用来在Wwise对象中存储额外信息。自定义属性可以用于项目管理，或存储游戏使用的元数据。

自定义属性可以在以下位置编辑：

Multi Editor;
List View;
Reference View;
Query Editor; and
Property Editor 的所有 Properties 选项卡。

直接从 Wwise Authoring 用户界面，通过菜单 Project > Project Settings > Custom Properties 来定义自定义属性也是可以的。请注意，通过用户界面可访问受限功能集。These custom properties are saved in the PROJECTNAME.wcustomproperties file located in the project folder (where PROJECTNAME is the same name as the WPROJ file). 请不要直接编辑此文件。

若要启用整套功能集，请在 XML 文件中的如下位置手动定义自定义属性：

Add-ons\Properties 文件夹下工程文件夹中的一个或多个 .wcustomproperties 文件
APPDATA%\Audiokinetic\Wwise\Add-ons\Properties 文件夹中的一个或多个 .wcustomproperties 文件
主 Wwise 安装文件夹下 Authoring\Data\Add-ons\Properties 文件夹中的一个或多个 .wcustomproperties 文件

备注: 在每次修改 .wcustomproperties 文件后，都要重新加载 Wwise Project 才能更新相应属性。Be aware that renaming a custom property will not automatically migrate the content of the project.

备注: 在存在名称冲突时，将只注册冲突属性中先加载的属性。系统会按照上述顺序加载属性。

备注: 在加载工程时，会加载所有自定义属性，而不论其定义在什么位置。

利用 AK::SoundEngine::Query::GetCustomPropertyValue ，可在游戏中检索音频对象类型的自定义属性。这些自定义属性将以 32 位数据形式单独导出到 SoundBank（音频包）中，并可作为 32 位整数 (AkInt32) 或 32 位浮点数 (AkReal32) 来查询。Bool、Int16 和 Real64 等其他类型可在 XML 文件中指定，并由 Wwise 设计工具提供原生支持。不过，在生成 SoundBank 时会将支持的类型转换为 32 位形式。字符串 (string) 等非数字类型不会导出到 SoundBank 中。

备注: 另外，Dialogue Event（对白事件）对象也支持在游戏中查询自定义属性（详见 AK::SoundEngine::DynamicDialogue::GetDialogueEventCustomPropertyValue ）。

XML 文件的内容

XML 描述文件包含了添加到不同类型对象的自定义属性的信息：

属性定义，包括：
- 属性名（用于标识代码和持久化文件属性的字符串）
- 属性类型
- RTPC 支持
- 默认值
- 声音引擎属性ID（关联此属性和声音引擎插件中的代码）
- 值域限制或枚举限制
- 对其它属性的依赖性
- 用户界面描述元素

Example： wcustomproperties文件

以下是一个自定义属性 XML 描述文件的简单示例，该文件定义了声音对象的额外属性。

<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright (C) 2006 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 元素都定义了该对象类型的自定义属性。The Name, CompanyID and PluginID must exactly be the one known by Wwise, unless the properties won't appear in Wwise. 如需查看可用 WwiseObject 元素列表，请参阅 Wwise对象ID 。

Properties

所有自定义属性都要添加前缀。这样才能避免 Audiokinetic 内置属性、第三方属性和您本人自定义属性之间发生属性名称冲突。

对于用户界面中所创建的属性 (Project > Project Settings > Custom Properties)，其名称中会添加 Custom: 前缀。在 .wcustomproperties 文件中直接定义自定义属性时，请不要使用 Custom: 前缀。请另行设定前缀。只有 WPROJECTNAME.wcustomproperties 中的属性才要添加 Custom: 前缀。

强烈建议使用公司名称和产品名称作为属性名称的前缀。例如：

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

有关属性和引用的更多信息，请参照属性 XML 描述。

Wwise对象ID

备注: 只有基于声音的对象（包括 Music Track 和容器对象）可以用来检索自定义属性值。

以下是所有可用于在 Wwise 设计工具内定义自定义属性的 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>