|
Wwise SDK 2023.1.8
|
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 Description File Header
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.
PluginModule Element
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
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:
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.
Was this page helpful?
Need Support?
Questions? Problems? Need more info? Contact us, and we can help!
Visit our Support pageTell us about your project. We're here to help.
Register your project and we'll help you get started with no strings attached!
Get started with Wwise