Table of Contents
Wwise SDK 2018.1.11
The open architecture of Wwise supports three kinds of plug-ins: source plug-ins, which generate sounds; effect plug-ins, which enhance sounds; and source control plug-ins, which enable the use of source control software within Wwise. The first two kinds of plug-ins use an XML plug-in description file which allows you to quickly change some of the settings of your plug-in, including default property values, without having to recompile the code. A Wwise plug-in DLL can contain multiple plug-ins, each of which must be described in the associated XML file. The XML description file for each Wwise plug-in DLL must have the same name as the DLL, except for the XML file extension. For example, if your DLL is named "MyPlugin.dll", then the plug-in description file must be named "MyPlugin.xml".
The Wwise open architecture also allows to define custom properties for Wwise objects. In much the same way as defining plug-ins, Wwise properties are controlled through XML descriptions. Refer to Defining Custom Properties for more information.
Properties section defines the properties and references of your plug-in.
Reference elements will be ordered in the user interface as they are in the XML.
- The properties correspond to the controls, such as sliders and check boxes, that can be manipulated by the user in your plug-in's user interface, and to the values that the sound engine plug-in code can use to make its computations.
- The references correspond to fields containing a reference to a Wwise object. For example, a reference could point to a Game Parameter object defined in the project.
Property is typically defined as follows:
A Reference is typically defined as follows:
Reference elements can contain several attributes:
Name [Property, Reference](type:string, mandatory): This is the string ID used in the Wwise plug-in to identify the property. It is used in the following places:
- Binding of properties to controls: This is the name you must specify in your plug-in's dialog resources (Prop=<Property Name>) to bind the control to this property.
Persistence: This is the name that will appear in the
Propertyelement in Wwise Project files to persist data related to this property.
Caution: Never change the name of an existing property. Projects using your plug-in will lose any value, randomizer, or RTPC the user might have set on that property.
- in_szPropertyName parameter in:
Property Nameis not a name that appears in the UI, but you should still make it meaningful because a user might see it in a Project file. The name that appears in the UI is specified by the
Note: When defining custom properties, the
Nameattribute must be prefixed with "Custom:". Refer to Defining Custom Properties for more information.
DisplayName [Property, Reference](type: string, default: empty): Defines the display name of the Property, to be displayed at many places in Wwise. This attribute supersedes the function
DisplayGroup [Property, Reference](type: string, default: empty): Defines a slash separated path used to organize properties or references in a Tree. Ex: "Audio/HDR"
IsVisible [Property, Reference](type: boolean, default: true, optional): Default value is
true. If absent, the property will be visible in generic editors. Set the
falsewhen the property and its value are not meaningful for the user or you don't want the user to see or modify it in generic editors (for example, in the List View).
Type [Property](mandatory): This is the property type. Possible values are:
Real32:Single-precision float (32-bit)
Real64:Double-precision float (64-bit)
string:Wide character string
Note that the supported types for custom property queries in game are int32 and Real32. At SoundBank generation time, numerical values will be cast to 32 bits (boolean values are interpreted as 1 for true and 0 for false). If you use a 64-bit value, a loss of data may occur from int64 to int32, in which case an error will be produced. For casting from Real64 to Real32, a possible loss of precision may occur and a warning will be produced. Since strings cannot be represented numerically, they are not exported in SoundBanks.
SupportLink [Property, Reference](type: boolean, default: false, optional): Defines if the
Referencesupports the Link/Unlink functionality. Note that
SupportLinkis only supported for Source plug-ins, not for Effect plug-ins.
SupportRTPCType [Property](type: string, default: undefined, optional): If absent, the property will not support RTPCs. If present, it must be set to
Additivemode means the value computed from the RTPC curve will be added to the base property value of the object and to other RTPCs on the same property. The
Exclusivemode means the value computed from the RTPC curve has exclusive control over the property's value, completely overriding the value set in the property's control within the dialog (that control will be disabled to make it clear to the Wwise user that it does not have any effect on the property).
ForceRTPCCurveSegmentShape [Property](type: string, default: undefined, optional, used with
SupportRTPCType): Restricts the possible segment shapes used in RTPC curves on this property. If not specified, then the user has the freedom to change the shape of any segment within the curve. If specified, possible values are:
Constant:All segments in the curve will use constant interpolation (between two adjacent points, the Y value is the same as that of the left-most point of the pair). Use this when the property represents discreet values such as booleans or enumerations.
DataMeaning [Property](type: string, default: undefined, optional): If defined, specifies that the property represents some special type of data, such as decibels.
Possible values are:
Decibels:This property represents decibels. RTPC curves will use decibel scaling by default, though the user has the option to change between decibel and linear scaling. Decibel scaling affects the way values are interpolated between points. For example, if you have a point at 0 dB and one at -96.3 dB, a linear curve segment evaluated exactly between the two points will produce a value of -48.15 dB when using linear scaling, and around -6 dB when using decibel scaling (corresponding to a halving of amplitude).
Frequency:This property represents a frequency in Hz. Frequency scaling affects the way values are interpolated between points. For example, if you have a point at 1000 Hz and one at 4000 Hz (two octaves above), a linear curve segment evaluated exactly between the two points will produce a value of 2500 Hz when using linear scaling, and a value of 2000 Hz (one octave above) when using frequency scaling.
|Note: If you want the sound or effect produced by your plug-in to be set by the Wwise user, and not change during a game, do not set it to support RTPCs.|
DefaultValue element specifies the default value for a property. This default value represents the initial value when creating new instances, and value to which the property is reset when the user clicks on the property's control while holding the CTRL key. This value must match the type (as specified with the
Type attribute in the
Property element) and range (below) of the property.
|Tip: XML files can be edited with any text or XML editor. They are located in the same folder as the plug-in DLLs, in the "plugins" folder under the main Wwise installation folder. Wwise users who have custom plug-ins can edit the XML file for their plug-ins to change the default value of a plug-in property without recompiling the plug-in. Developer expertise is not required to make this change.|
AudioEnginePropertyID element identifies this property in the Sound Engine. It must be a positive integer in the range 0-32767, except for the wcustomproperties file, in which case the range must be 0-150. The value you set in the
AudioEnginePropertyID element corresponds to the
AkFXParamID parameter in
AK::IAkEffectParam::SetParam(), so make sure you keep your property IDs in sync between your implementation of
AK::IAkEffectParam::SetParam() and your plug-in description file.
UserInterface element defines attribute that relates to user interface behavior and appearance. The following attributes are all optional and can be set on the
DisplayName(type: string, default: empty): (Deprecated) Defines the display name of the Property, to be displayed at many places in Wwise. This attribute is replaced by the DisplayName attribute defined in the
Decimals(type: integer, default: 0): Defines the number of digits to display after the decimal point. This value must be a non-negative integer number. If set to 0, then no decimal digits and no point will be displayed.
Step(type: float, default: 1): Defines the amount by which the numeric value changes when moving a slider. This value can be an integer or decimal number, depending on the type of property the control is bound to.
Fine(type: float, default: 1): Defines the amount by which the numeric value changes when moving a slider while holding the SHIFT key. This value can be an integer or decimal number, depending on the type of property the control is bound to.
SliderType(type: integer, default: 0): Defines the mapping of the values across a slider range.
- 0: Linear (default)
- 1: Pseudo-Logarithmic, from -96.3 dB to 0 dB
- 2: Pseudo-Logarithmic, from -96.3 dB to 96.3 dB
- 4: Pseudo-Logarithmic, from 20 Hz to 20000 Hz
- 5: Pseudo-Logarithmic, from 20 Hz to 12000 Hz
- 6: Pseudo-Logarithmic, from -96.3 dB to 12 dB
- 11: Pseudo-Logarithmic, from 0.02 Hz to 20000 Hz
- 12: Pseudo-Logarithmic, from 0.02 Hz to 20 Hz
- 15: Pseudo-Logarithmic, from -24 dB to 24 dB
- 16: Pseudo-Logarithmic, from -96.3 dB to 24 dB
Mid(type: float, default: 0): Defines the value in the [min,max] range that is considered neutral. This value affects the drawing of a slider control.
UIMin(type: float, default: Range's Min): Defines the minimum value that can initially be set by using the slider. If this value is greater than the one specified with the
Minattribute, then the user can force it to a lower value by entering a value that is smaller than the one specified by this attribute, thus enlarging the range of the control.
UIMax(type: float, default: Range's Max): Defines the maximum value that can initially be set by using the slider. If this value is lower than the one specified with the
Maxattribute, then the user can force it to a larger value by entering a value that is larger than the one specified by this attribute, thus enlarging the range of the control.
AutoUpdate(type: boolean, default: false): Defines if the value is updated while moving a slider. Set this attribute to
falsewhen updating the value too often because of audio performance glitches.
LRMixDisplay(type: boolean, default: false): Defines if the value is shown as a special Left-Right balance range style. The value range must be between -100 and +100 and map to a Left to Right balance/mix, where 0 is the Center.
ControlClass(type: string, default: empty): Defines the user interface control that must be used for the property in views such as the List View or the Multi Editor. Possible values are:
- ColorPicker: A color picker.
- ReadOnlyText: The value of the property is read-only in the user interface.
DropDown(type: string, default: empty): When used with a numerical enumeration (for example,
Enumerationof type int16), this allows you to specify how each value of the
Enumerationwill be represented in the menu. Possible values are:
- Menu: Displays a shortcut menu for the corresponding enum values instead of a drop down. The path of the menu is defined by the
Enumeration. For example, a
DisplayNameof value "/Bus Volume/Reset Bus Volume" will display a menu with Bus Volume in which the submenu Reset Bus Volume, once clicked, will set the property to the value 14.
- CurveIn: For corresponding values 0 to 8, it displays a curve (positive slope) for the following functions: Logarithmic (Base 3), Sine, Logarithmic (Base 1.41), Inverted S-Curve, Linear, S-Curve, Exponential (Base 1.41), Reciprocal Sine, and Exponential (Base 3).
- CurveOut: For corresponding values 0 to 8, it displays a curve (negative slope) for the following functions: Logarithmic (Base 3), Sine, Logarithmic (Base 1.41), Inverted S-Curve, Linear, S-Curve, Exponential (Base 1.41), Reciprocal Sine, and Exponential (Base 3).
- Menu: Displays a shortcut menu for the corresponding enum values instead of a drop down. The path of the menu is defined by the
Tip: The purpose of the
A property can optionally have any of the two following restrictions for its data values.
Range restriction (Restrictions/ValueRestriction/Range section), you can define the range of numeric properties.
Enumeration restriction (Restrictions/ValueRestriction/Enumeration section), you can define a list of possible values and the display name for each one.
string properties do not need a range. This range is used in various places in Wwise, such as the RTPC Curve Editor, to define the range of the graph on the Y-axis.
The format of this file is described formally in the Plugin.xsd XML Schema file found in the "/Authoring/Data/Schemas" folder under the main Wwise installation folder.
A reference can optionally have a list of any of the following restrictions for referenced objects:
TypeEnumerationRestriction: Defines a list of valid Wwise object types for the reference.
Type Name can be: ActorMixer, RandomSequenceContainer, SwitchContainer, BlendContainer, Sound, Bus, Event, SwitchGroup, Switch, State, GameParameter, MidiParameter, SoundBank, Effect, MusicSegment, MusicTrack, MusicTrackSequence, MusicPlaylistContainer, MusicSwitchContainer, Trigger, Attenuation, DialogueEvent, MotionBus, MotionFX, Conversion, AuxBus, ModulatorLfo, ModulatorEnvelope.
CategoryEnumerationRestriction: Defines a list of valid Wwise object categories for the reference.
Category Name can be: Busses, AudioObjects, Events, Switches, States, SoundBanks, GameParameters, Effects, AudioDevices, Presets, SoundcasterSessions, MixingSessions, Queries, InteractiveMusic, Triggers, Attenuations, DynamicDialogue, Conversions, Modulators, ControlSurfaceSessions.
PlayableRestriction: Defines if the object must be playable.
NotNullRestriction: Defines if the object must not be null.
Properties or references can have zero or many dependencies. Dependencies allow to link properties together, so a property can be enabled or disabled based on the value of another property.
Please note the dependencies are currently only used in the following contexts:
- Property Editor - All Properties tab
- Default User Interface for Effects (but not sources)
- List View
- Multi Editor
- Query View
- Reference View
The dependencies are not being used in the Effect Editor if you implement your own user interface by providing a dialog in
AK::Wwise::IAudioPlugin::GetDialog(). Enabled or disabled States must be implemented in the user interface of the plug-in.
The following example adds a dependency from "GainBand1" to "OnOffBand1". The "GainBand1" property will be enabled when "OnOffBand1" is set to "True".
Condition element can either contain an
Enumeration element or a
Range element. The
Action attribute specified in the
PropertyDependency element must be "Enable". It specifies the property will be enabled when the condition is matching.
Context attribute can be specified on a
PropertyDependency to change the object on which the
Condition will be evaluated. The
Context attribute can be set to either "Parent" or "Self", and defaults to "Self" when it is not explicitely given.
Continuing from the previous example, adding a context to the
PropertyDependency will cause the "GainBand1" property to be enabled when "OnOffBand1" is set to "True" on the parent of the current object.