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).

info

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>

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Get started with Wwise

Wwise SDK 2016.2.6