Plug-in 属性和自定义属性 XML 描述

Wwise 的开放架构支持三种插件，它们分别是用于生成声音的源插件、用于增强声音的效果器插件和支持在 Wwise 中使用版本控制软件的版本控制插件。前两种插件使用了 XML 插件描述文件，可以让您快速更改包括插件默认属性值在内的一些设置，而无需重新编译代码。Wwise 插件 DLL 可以包含多个插件，相关 XML 文件中必须对每个插件进行描述。每个 Wwise 插件 DLL 的 XML 描述文件具有与 DLL 相同的名称，而扩展名可以不同。例如，如果您的 DLL 命名为“MyPlugin.dll”，那么插件描述文件必须命名为“MyPlugin.xml”。

Wwise 开放性架构也可以用于定义 Wwise 对象的自定义属性。就像定义插件一样，Wwise 属性也通过 XML 描述进行控制。请参阅定义自定义属性了解更多信息。

属性要素

        <Properties>
            ...
        </Properties>

Properties 字段定义了您的插件的属性和引用。Property 和 Reference 要素在用户界面中和 XML 中的排序一样。

这些属性对应于插件用户界面中允许操纵的控件，例如滑块和复选框，以及声音引擎插件代码可用来执行运算的值。
引用对应一个字段，这个字段包含对 Wwise 对象的引用。比如，一个引用可能指向一个在工程中定义的 Game Parameter 对象。

Property（属性）通常定义如下：

<Property Name="GainBand1" Type="Real32" SupportRTPCType="Exclusive" DataMeaning="Decibels" DisplayName="Band 1 Gain">
    <UserInterface Step="0.5" Fine="0.1" Decimals="1" />
    <DefaultValue>0</DefaultValue>
    <AudioEnginePropertyID>1</AudioEnginePropertyID>
    <Restrictions>
        <ValueRestriction>
            <Range Type="Real32">
                <Min>-24</Min>
                <Max>24</Max>
            </Range>
        </ValueRestriction>
    </Restrictions>
    <Dependencies>
        <PropertyDependency Name="OnOffBand1" Action="Enable">
            <Condition>
                <Enumeration Type="bool">
                    <Value>1</Value>
                </Enumeration>
            </Condition>
        </PropertyDependency>
    </Dependencies>
</Property>

引用通常定义如下：

<Reference Name="OutputGameParameter" DisplayName="Output Game Parameter">
    <Restrictions>
        <TypeEnumerationRestriction>
            <Type Name="GameParameter" />
        </TypeEnumerationRestriction>
    </Restrictions>
</Reference>

Property 和 Reference 要素可以包含几个属性：

Name [Property, Reference] (type:string, mandatory)：这是在 Wwise 插件中用于标识属性的字符串 ID。它用在以下两个位置：

Binding of properties to controls：您必须在插件对话框资源中指定此名称（Prop=<Property Name>），来将控件绑定至此属性。
Persistence：这是出现在 Wwise Project 文件里 Property 要素中的名称，用于保存和该属性相关的数据。

warning
Caution: 切勿更改现有属性的名称。否则工程中使用您插件的用户将可能丢失对该属性设置的值、随机化器或 RTPC。
in_szPropertyName parameter in:

info

Note: Property Name（属性名）称不是显示在 UI 中的名称，但您应该取一个有意义的名称，因为用户在工程文件中可以看到它。显示在 UI 中的名称由 DisplayName 属性指定。

info

Note: 在定义自定义属性时，Name 属性必须以“Custom:”为前缀。请参阅定义自定义属性了解更多信息。

DisplayName [Property, Reference] (type: string, default: empty)：定义在 Wwise 中多处出现的 Property 的显示名称。此属性将取代 AK::Wwise::IAudioPlugin::DisplayNameForProp 函数。
DisplayGroup [Property, Reference] (type: string, default: empty)：定义 Tree 中用于组织属性或引用的斜杠分隔路径。例：“Audio/HDR”
IsVisible [Property, Reference] (type: boolean, default: true, optional)：默认值是true。如果使用默认设置，在普通编辑器中可以查看此属性。当属性和它的数值对用户无意义时，或者您不想让用户看见它或在普通编辑器（比如在 List View中）中改动它时，则要将 IsVisible 设置为 false。
Type [Property] (mandatory)：这是属性类型。可能值是：
- bool ：布尔型
- int16 ：16 位整数
- int32 ：32 位整数
- Real32 ：单精度浮点（32 位）
- Real64 ：双精度浮点（64 位）
- string ：宽字符字符串
SupportLink [Property, Reference] (type: boolean, default: false, optional)：定义 Property 或 Reference 是否支持 Link/Unlink 功能。请注意 SupportLink 仅支持 Source 插件，而不支持 Effect 插件。
SupportRTPCType [Property] (type: string, default: undefined, optional)：如果不存在，则属性不支持 RTPCs。如果存在，则必须设置为Exclusive 。这意味着从 RTPC 曲线计算得到的值对属性值拥有专属控制权，将完全覆盖对话框属性控件中设置的值（该控件将被禁用以使 Wwise 用户明白，它对属性没有任何影响）。
ForceRTPCCurveSegmentShape [Property] (type: string, default: undefined, optional, used with SupportRTPCType)：限制在该属性上的 RTPC 曲线中可能使用的线段形状。如果不指定，那么用户可以自由地更改曲线中任何段落的形状。如果指定，可能值是：
- Constant ：曲线中的所有片段将使用恒定的插值（两个相邻点之间，Y 值与最左边点的 Y 值相同）。当属性表示离散值（例如布尔型或枚举）时使用此值。
DataMeaning [Property] (type: string, default: undefined, optional)：如果已定义，则指定该属性代表一些特殊种类的数据，比如分贝。

可能值是：
- Decibels ：此属性以分贝表示。在默认情况下，RTPC 曲线将使用分贝刻度，但用户可以在分贝刻度和线性刻度之间切换。分贝度量将影响点与点之间的插值方式。例如，假设您有 0 dB 和 -96.3 dB 两个点，当使用线性度量时，在两点连线的中点值将为 -48.15 dB，当使用分贝刻度时中点值将约为 -6 dB（相当于振幅的一半）。
- Frequency ：此属性代表频率，单位：Hz。频率度量影响点与点之间的插值方式。例如，假设有 1000 Hz 和 4000 Hz 两个点（两个八度音阶以上），当使用线性刻度时，在两点连线的中点値将为 2500 Hz，而使用频率度量时中点值为 2000 Hz（高一个八度）。

info

Note: 如果您希望 Wwise 用户来设置插件产生的声音或效果，并且在游戏期间不发生改变，则不要让其支持 RTPC。

DefaultValue 要素为属性指定默认值。此默认值即为创建新实例时的初始值，也是用户按住 CTRL 键的同时单击属性控件时属性的复位值。此值必须匹配属性类型（由Property 要素中的 Type 属性指定）和属性的范围（见下文）。

check_circle

Tip: XML 文件可以通过文本或 XML 编辑器进行编辑。它们位于插件 DLL 所在的路径，该文件夹位于主 Wwise 安装路径下的“plugins”文件夹中。Wwise 用户可以编辑插件的 XML 文件来更改自定义插件属性的默认值，而无需重新编译插件。因而无需研发，就可以执行此更改。

AudioEnginePropertyID 要素在 Sound Engine 中标识了该属性。它必须是介于 0 到 32767 之间的正整数。您在 AudioEnginePropertyID 要素中设置的值对应于 AK::IAkEffectParam::SetParam() 中的 AkFXParamID 参数，因此请确保属性 ID 在 AK::IAkEffectParam::SetParam() 中的实现和插件描述文件之间保持同步。

UserInterface

UserInterface 元素定义与用户界面行为和外观相关的属性。以下属性均为可选，在 UserInterface 元素上设置它们：

DisplayName (type:string, default:empty)：（已弃用）规定属性的显示名称，此名称将在 Wwise 中的多个位置显示。该属性会被 Property 或 Reference 要素中定义的 DisplayName 属性替代。
Decimals (type: integer, default: 0)：定义小数点后显示的位数。此值必须是非负整数。如果设为 0，则不会显示小数和小数点。
Step ( type: $1 default :1)：定义移动滑块时数值的变化量。此值可以是整数或小数，具体取决于控件所绑定的属性类型。
Fine (type: float, default: 1) ：定义在按住 SHIFT 键并移动滑块时数值的变化量。此值可以是整数或小数，具体取决于控件所绑定的属性类型。
SliderType (type: integer, default: 0)：定义滑块范围内的数值的映射。
- 0：线性（默认）
- 1：伪对数，介于 -96.3 dB 到 0 dB 之间
- 2：伪对数，介于 -96.3 dB 到 96.3 dB 之间
- 4：伪对数，介于 20 Hz 到 20000 Hz 之间
- 5：伪对数，介于 20 Hz 到 12000 Hz 之间
- 6：伪对数，介于 -96.3 dB 到 12 dB 之间
- 11：伪对数，介于 0.02 Hz 到 20000 Hz 之间
- 12：伪对数，介于 0.02 Hz 到 20 Hz 之间
- 15：伪对数，介于 -24 dB 到 24 dB 之间
- 16：伪对数，介于 -96.3 dB 到 24 dB 之间
Mid (type: float, default: 0)：被视为中间值，介于 [最小值，最大值]范围内。此值将影响滑块控件的绘制。
UIMin (type: float, default: Range's Min)：定义使用滑块可以设置的最小值。如果此值大于使用Min 属性设置的值，则用户可通过输入一个小于此属性指定值的值来强制将它设为更小值，从而扩大控制范围。
UIMax ( type: float, default: Range's)：定义使用滑块可以设置的最大值。如果此值小于使用Max 属性指定的值，则用户可通过输入一个比此属性指定值更大的值来强制将它设为更大值，从而扩大控制范围。
AutoUpdate (type: boolean, default: false)：定义在移动滑块时是否可以更新此值。如果频繁更新此值会导致音频性能出现故障问题，请将此属性设为 false。
LRMixDisplay (type:boolean, default:false)：定义此值是否以左右范围平衡的特殊样式显示。此值必须介于 -100 和 +100 之间，并映射到左到右平衡/混合，其中 0 代表中心。

check_circle

Tip: 属性范围很大的情况下，UIMin 和 UIMax 旨在让控件滑块的初始范围变得更加便于使用。如果某个属性具有较大的理论范围，但用户一般使用较小的范围，则使用 Min/Max 属性设置 实际范围，并使用 UIMin/UIMax 属性设置滑块的初始范围。

限制

Wwise XML 描述可以指定属性限制和引用限制。

属性限制

也可以为属性的数据值设置以下 2 个限制中的一个。

在Range 限制（Restrictions/ValueRestriction/Range 部分）中，您可以定义数值属性的范围。

<Restrictions>
    <ValueRestriction>
        <Range Type="Real64">
            <Min>0</Min>
            <Max>100</Max>
        </Range>
    </ValueRestriction>
</Restrictions>

在 Enumeration 限制（Restrictions/ValueRestriction/Enumeration 部分）中，您可以定义可能值列表和每个值的显示名称。

<Restrictions>
    <ValueRestriction>
        <Enumeration Type="int32">
            <Value DisplayName="Low Pass">0</Value>
            <Value DisplayName="High Pass">1</Value>
            <Value DisplayName="Band Pass">2</Value>
            <Value DisplayName="Notch">3</Value>
            <Value DisplayName="Low Shelf">4</Value>
            <Value DisplayName="High Shelf">5</Value>
            <Value DisplayName="Peaking">6</Value>
        </Enumeration>
    </ValueRestriction>
</Restrictions>

bool 和 string 属性不需要范围。Wwise 中的多个位置（例如 RTPC Curve Editor）都将使用此值域来定义坐标图 Y 轴的范围。

Plugin.xsd XML Schema 文件正式描述了此文件的格式，该 XML Schema 文件位于主 Wwise 安装路径下的“/Authoring/Data/Schemas”文件夹中。

引用限制

引用可以任意选择由以下被引用对象的限制所组成的清单：

TypeEnumerationRestriction：为引用定义有效的 Wwise 对象类型清单。

<Restrictions>
    <TypeEnumerationRestriction>
        <Type Name="GameParameter" />
        ...
    </TypeEnumerationRestriction>
</Restrictions>

Type Name 可以是：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：为引用定义有效的 Wwise 对象类别清单。

<Restrictions>
    <CategoryEnumerationRestriction>
        <Category Name="AudioObjects" />
        ...
    </CategoryEnumerationRestriction>
</Restrictions>

Category Name 可以是：Busses、AudioObjects、Events、Switches、States、SoundBanks、GameParameters、Effects、AudioDevices、Presets、SoundcasterSessions、MixingSessions、Queries、InteractiveMusic、Triggers、Attenuations、DynamicDialogue、Conversions、Modulators、ControlSurfaceSessions。

PlayableRestriction：定义对象是否必须可播放。

<Restrictions>
    <PlayableRestriction />
</Restrictions>

NotNullRestriction：定义对象是否不能为 null。

<Restrictions>
    <NotNullRestriction />
</Restrictions>

Wwise SDK 2017.1.9