Defining Custom Properties

Custom properties allow to store additional information in Wwise objects. The custom properties could be use for project management or to store game-used meta data. To retrieve the custom property values in the game, refer to AK::SoundEngine::Query::GetCustomPropertyValue.

The custom properties can be edited in the:

Multi Editor;
List View;
Reference View;
Query View; and
All Properties tab of the Property Editor.

It's possible to define custom properties directly from the Wwise Authoring user interface, via the menu Project > Project Settings > Custom Properties. However, to enable more features, it is also possible to define custom properties directly from a PROJECTNAME.wcustomproperties file located in the project folder (where PROJECTNAME is the same name as the WPROJ file).

Note: Every time the file PROJECTNAME.wcustomproperties is modified, the Wwise Project needs to be reloaded for the properties to be updated. Be aware that renaming a custom property will not automatically migrate the content of the project.

Contents of the XML file

The XML description file contains information about custom properties to be added to different types of objects:

Property definitions, including:
- Property name (string used to identify the property in the code and persisted files)
- Property type
- RTPC support
- Default value
- Sound engine property ID (binding this property to the code in the sound engine plug-in)
- Range restrictions or enumeration restrictions
- Dependencies on other properties
- User interface description elements

Example: wcustomproperties File

Below is an example of a simple custom properties XML description file that defines additional properties for sound objects.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright (C) Audiokinetic Inc. -->
<PluginModule>
    <WwiseObject Name="Sound" CompanyID="1" PluginID="1">
        <Properties>
            <Property Name="Custom:Status" DisplayGroup="Production" 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="Custom:IsReady" DisplayGroup="Production" Type="bool" DisplayName="Is Ready">
                <DefaultValue>false</DefaultValue>
                <AudioEnginePropertyID>2</AudioEnginePropertyID>
            </Property>
            <Property Name="Custom:Priority" DisplayGroup="Production" Type="int32" DisplayName="Priority">
                <DefaultValue>50</DefaultValue>
                <AudioEnginePropertyID>6</AudioEnginePropertyID>
                <Restrictions>
                    <ValueRestriction>
                        <Range Type="int32">
                            <Min>1</Min>
                            <Max>100</Max>
                        </Range>
                    </ValueRestriction>
                </Restrictions>
            </Property>
            <Property Name="Custom: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="Custom:GameId" Type="string" DisplayName="Game Id">
                <DefaultValue></DefaultValue>
            </Property>
            <Reference Name="Custom:StateGroup" DisplayName="State Group">
                <AudioEnginePropertyID>10</AudioEnginePropertyID>
                <Restrictions>
                    <TypeEnumerationRestriction>
                        <Type Name="StateGroup" />
                    </TypeEnumerationRestriction>
                </Restrictions>
            </Reference>
        </Properties>
    </WwiseObject>
</PluginModule>

XML Description File Header

Let's look at the parts of this XML file's header and discuss them in detail.

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

The first line of any XML file defines the XML version and encoding. In this case, the XML version is 1.0, and the encoding is UTF-8. The first line of any Wwise plug-in description file should always be exactly like the one above.

PluginModule Element

<PluginModule>
    ...
</PluginModule>

The main XML element in this document is named PluginModule, and encloses all of the information for the various object types defined in the file.

WwiseObject Elements

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

Each WwiseObject element defines the custom properties for that object type. The Name, CompanyID and PluginID must exactly be the one known by Wwise, unless the properties won't appear in Wwise.

For more information about properties and references, refer to Plug-in Property and Custom Property XML Description. Please note that each property ID must have the prefix "Custom:".

Wwise Object IDs

Here are all the possible WwiseObject types that can be used to define custom properties.

    <WwiseObject Name="Action" DisplayGroup="Events" CompanyID="1" PluginID="5"></WwiseObject>
    <WwiseObject Name="ActorMixer" CompanyID="1" PluginID="8"></WwiseObject>
    <WwiseObject Name="Attenuation" DisplayGroup="ShareSets/Attenuation" CompanyID="1" PluginID="41"></WwiseObject>
    <WwiseObject Name="AudioDevice" CompanyID="1" PluginID="71"></WwiseObject>
    <WwiseObject Name="AuxBus" CompanyID="1" PluginID="61"></WwiseObject>
    <WwiseObject Name="BlendContainer" CompanyID="1" PluginID="29"></WwiseObject>
    <WwiseObject Name="Bus" CompanyID="1" PluginID="21"></WwiseObject>
    <WwiseObject Name="ControlSurfaceSession" CompanyID="1" PluginID="66"></WwiseObject>
    <WwiseObject Name="Conversion" DisplayGroup="ShareSets/Conversion Setting" CompanyID="1" PluginID="55"></WwiseObject>
    <WwiseObject Name="DialogueEvent" DisplayGroup="Events" CompanyID="1" PluginID="46"></WwiseObject>
    <WwiseObject Name="Effect" CompanyID="1" PluginID="17"></WwiseObject>
    <WwiseObject Name="Event" DisplayGroup="Events" CompanyID="1" PluginID="4"></WwiseObject>
    <WwiseObject Name="ExternalSource" CompanyID="1" PluginID="57"></WwiseObject>
    <WwiseObject Name="GameParameter" DisplayGroup="Game Syncs/Game Parameter" CompanyID="1" PluginID="23"></WwiseObject>
    <WwiseObject Name="MixingSession" CompanyID="1" PluginID="53"></WwiseObject>
    <WwiseObject Name="ModulatorEnvelope" DisplayGroup="ShareSets/Modulators/Envelope" CompanyID="1" PluginID="65"></WwiseObject>
    <WwiseObject Name="ModulatorLfo" DisplayGroup="ShareSets/Modulators/LFO" CompanyID="1" PluginID="64"></WwiseObject>
    <WwiseObject Name="MotionBus" CompanyID="1" PluginID="47"></WwiseObject>
    <WwiseObject Name="MotionFX" CompanyID="1" PluginID="48"></WwiseObject>
    <WwiseObject Name="MusicRndSeqContainer" CompanyID="1" PluginID="34"></WwiseObject>
    <WwiseObject Name="MusicSegment" CompanyID="1" PluginID="27"></WwiseObject>
    <WwiseObject Name="MusicSwitchContainer" CompanyID="1" PluginID="35"></WwiseObject>
    <WwiseObject Name="MusicTrack" CompanyID="1" PluginID="28"></WwiseObject>
    <WwiseObject Name="Query" DisplayGroup="Queries" CompanyID="1" PluginID="32"></WwiseObject>
    <WwiseObject Name="RndSeqContainer" CompanyID="1" PluginID="9"></WwiseObject>
    <WwiseObject Name="Sound" CompanyID="1" PluginID="1"></WwiseObject>
    <WwiseObject Name="SoundBank" DisplayGroup="SoundBanks" CompanyID="1" PluginID="18"></WwiseObject>
    <WwiseObject Name="State" CompanyID="1" PluginID="6"></WwiseObject>
    <WwiseObject Name="StateGroup" DisplayGroup="Game Syncs/States" CompanyID="1" PluginID="7"></WwiseObject>
    <WwiseObject Name="SwitchContainer" CompanyID="1" PluginID="10"></WwiseObject>
    <WwiseObject Name="SwitchGroup" DisplayGroup="Game Syncs/Switch Group" CompanyID="1" PluginID="19"></WwiseObject>
    <WwiseObject Name="Trigger" CompanyID="1" PluginID="40"></WwiseObject>
    <WwiseObject Name="VirtualFolder" CompanyID="1" PluginID="2"></WwiseObject>
    <WwiseObject Name="WorkUnit" CompanyID="1" PluginID="25"></WwiseObject>
    <WwiseObject Name="AudioSource" CompanyID="1" PluginID="0"></WwiseObject>

此页面对您是否有帮助？

需要技术支持？

仍有疑问？或者问题？需要更多信息？欢迎联系我们，我们可以提供帮助！

查看我们的“技术支持”页面

介绍一下自己的项目。我们会竭力为您提供帮助。

来注册自己的项目，我们帮您快速入门，不带任何附加条件！

开始 Wwise 之旅

Wwise SDK 2016.2.6