播放音频事件工作类 (Event_PlayAudio)

播放音频事件工作类 (`Event_PlayAudio`)

功能说明

Event_PlayAudio 是一个事件工作类，用于在游戏中的特定时刻播放音频片段。它提供了丰富的配置选项，允许您精确控制音频的播放方式，包括音量、是否循环、空间混合（2D或3D音效）、播放延迟，以及是否将音效关联到触发事件的实体上，或在播放结束后自动销毁。这使得您可以为各种游戏事件（如用户界面交互、技能施放、环境音效、背景音乐片段等）添加动态的听觉反馈。

该事件工作类通过 EventDef 中的 workClass 字段引用，其具体的行为由 parameter 字段中提供的 JSON 配置来控制。

可用参数

Event_PlayAudio 通过解析 EventDef 中 parameter 字段里的 JSON 配置来工作。此 JSON 配置对应 AudioEventConfig。

JSON参数名	XML参数名 (N/A)	类型	默认值	说明
`audioClipName`	N/A	字符串	无	必需。要播放的音频资源或音频定义 (`AudioDef`) 的 `defName`。系统将通过此名称获取实际的音频数据。
`volume`	N/A	浮点数	`1.0`	播放音量（0.0到1.0之间）。`1.0` 为最大音量。
`loop`	N/A	布尔值	`false`	如果为 `true`，音频将循环播放直到被其他逻辑停止。
`spatialBlend`	N/A	浮点数	`0.0`	空间混合因子（0.0到1.0之间）。`0.0` 为完全2D音效（不受听者位置影响），`1.0` 为完全3D音效（受听者位置和距离影响）。
`attachToInitiator`	N/A	布尔值	`true`	如果存在触发此事件的实体（发起者），当此项为 `true` 时，音频播放器会尝试附加到该发起者上，使其成为一个3D音源（即使 `spatialBlend` 为 `0.0`，也依然会跟随发起者移动而移动）。
`delay`	N/A	浮点数	`0.0`	播放前的延迟秒数。
`destroyAfterPlay`	N/A	布尔值	`true`	如果是非循环播放的音效，并且系统临时创建了一个音频源来播放它，当此项为 `true` 时，会在播放结束后自动销毁这个临时的音频源以节省资源。

示例

以下是 EventDef 的示例，展示了 Event_PlayAudio 的不同用法：

<Define>
    <!-- 假设已有 Sound_ButtonClick 和 Sound_AmbientWind 等 [音频定义 (AudioDef)](AudioDef.md) -->

    <EventDef>
        <defName>PlayButtonClickSound</defName>
        <label>播放按钮点击音效</label>
        <description>在UI点击时播放短促的按钮点击音效。</description>
        <workClass>Event_PlayAudio</workClass>
        <parameter>
        {
            "audioClipName": "Sound_ButtonClick", // 要播放的音频定义名
            "volume": 0.8,                        // 音量为0.8
            "loop": false,                        // 不循环
            "spatialBlend": 0.0,                  // 2D音效
            "attachToInitiator": false            // UI音效通常不依附于发起者
        }
        </parameter>
    </EventDef>

    <EventDef>
        <defName>PlayAmbientWindSound</defName>
        <label>播放环境风声</label>
        <description>在地图特定区域播放循环环境风声。</description>
        <workClass>Event_PlayAudio</workClass>
        <parameter>
        {
            "audioClipName": "Sound_AmbientWind", // 播放环境风声
            "volume": 0.5,                        // 音量为0.5
            "loop": true,                         // 循环播放
            "spatialBlend": 1.0,                  // 3D音效，受位置影响
            "attachToInitiator": true             // 依附于事件发起者（例如一个风源实体）
        }
        </parameter>
    </EventDef>

    <EventDef>
        <defName>PlayDelayedWarningSound</defName>
        <label>播放延迟警告音效</label>
        <description>在5秒延迟后播放一个警告音效。</description>
        <workClass>Event_PlayAudio</workClass>
        <parameter>
        {
            "audioClipName": "Sound_Warning",
            "volume": 1.0,
            "delay": 5.0,                         // 延迟5秒播放
            "destroyAfterPlay": true              // 播放完成后自动销毁
        }
        </parameter>
    </EventDef>
</Define>

复杂参数说明

`parameter` 字段 (JSON配置)

说明：EventDef 中的 parameter 字段是一个特别说明，它不使用标准的XML元素赋值方式，而是直接作为文本内容包含一个JSON格式的字符串。这个JSON字符串包含了 AudioEventConfig 的所有配置参数，用于指导 Event_PlayAudio 的具体行为。您需要确保提供的JSON字符串是语法正确的。
JSON属性与C#映射关系：
- 所有JSON属性名（如 audioClipName, volume 等）与C#内部数据类中的对应属性名一致（JSON通常使用驼峰式命名）。
示例：请参考上方的 EventDef 示例中 parameter 标签内的内容。

`volume` 和 `spatialBlend` 字段 (浮点数范围)

说明：这两个字段都接受浮点数，但其值应限制在特定的有效范围内。
- volume：值应介于 0.0（静音）到 1.0（最大音量）之间。超出此范围的值可能会被截断或导致非预期行为。
- spatialBlend：值应介于 0.0（完全2D）到 1.0（完全3D）之间。

示例：

"volume": 0.75,         // 75%音量
"spatialBlend": 0.5     // 混合音效，2D与3D各一半

`loop`, `attachToInitiator`, `destroyAfterPlay` 字段 (布尔值开关)

说明：这些字段是布尔值开关，接受 true 或 false。
- loop：控制音频是否重复播放。
- attachToInitiator：当一个实体触发事件时，这个选项决定了音频源是否附加到该实体上。这常用于使音效跟随实体移动，或使3D音效从实体位置发出。
- destroyAfterPlay：主要用于非循环音效。如果为 true，系统在播放完毕后会自动清理临时创建的音频源。如果为 false，则需要其他逻辑手动清理，否则可能造成资源泄露。

示例：

"loop": true,
"attachToInitiator": true,
"destroyAfterPlay": false

异噬XML数据定义文档