Wwise SDK 2021.1.11
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
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
Below is an example of a simple custom properties XML description file that defines additional properties for sound objects.
Let's look at the parts of this XML file's header and discuss them in detail.
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.
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.
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
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:
For more information about properties and references, refer to Plug-in Property and Custom Property XML Description.
|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.