Wwise SDK 2024.1.0

Custom properties allow to store additional information in Wwise objects. The custom properties could be used for project management or to store game-used meta data.

The custom properties can be edited in the:

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

It is possible to define custom properties directly from the Wwise Authoring user interface, via the menu Project > Project Settings > Custom Properties.
Please note that using the user interface provides access to a limited feature set. 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). Do not edit this file directly.

To enable the complete feature set, define custom properties manually in an XML file in one of the following locations:

One or multiple .wcustomproperties files located in the project folder under "Add-ons\\Properties" folder
One or multiple .wcustomproperties files located in the "%APPDATA%\\Audiokinetic\\Wwise\\Add-ons\\Properties" folder
One or multiple .wcustomproperties files located in the "Authoring\\Data\\Add-ons\\Properties" folder under the main Wwise installation folder

Note: Every time a .wcustomproperties file 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.

Note: In case of name conflict, only the first property loaded will be registered. The properties are loaded in the order specified above.

Note: All custom properties are loaded at project load time, independently from where they are defined.

Custom properties of audio object types can be retrieved in the game using AK::SoundEngine::Query::GetCustomPropertyValue. Their custom properties are exported in SoundBanks as individual 32-bit data and can be queried either as a 32-bit integer (AkInt32) or a 32-bit float (AkReal32). Other types such as bool, int16, or Real64 can be specified in the XML and are supported natively by the Wwise Authoring application. However, at SoundBank generation time, supported types are casted to 32 bits. Non-numeral types such as strings are not exported in SoundBanks.

Note: Dialogue Event objects also support custom properties that can be queried in the game, refer to AK::SoundEngine::DynamicDialogue::GetDialogueEventCustomPropertyValue.

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="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 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. Refer to Wwise Object IDs for the list of possible WwiseObject elements.

Properties

All custom properties should have a prefix. This is very important to avoid property name conflicts across Audiokinetic built-in properties, 3rd party properties and your own custom properties.

Properties created in the user interface (Project > Project Settings > Custom Properties) are prefixed with "Custom:" in their name. Do not use the "Custom:" prefix when defining custom properties in .wcustomproperties files directly. Use your own prefix. Only properties found in WPROJECTNAME.wcustomproperties should have the "Custom:" prefix.

We highly recommend using your company and product name as prefix in the property name. For example:

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

For more information about properties and references, refer to Properties XML Description.

Wwise Object IDs

Note: Only objects derived from sounds (including Music Tracks and Containers) can be used to retrieve a custom property value.

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

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