临时动画事件工作类 (Event_TemporaryAnimationWorkClass)

临时动画事件工作类 (`Event_TemporaryAnimationWorkClass`)

功能说明

Event_TemporaryAnimationWorkClass 是一个功能强大的事件工作类，用于在游戏世界或UI界面上播放各种临时动画效果。它支持多种动画内容类型（文本、精灵序列和DrawNode定义），并提供了灵活的配置选项，允许您精确控制动画的位置、生命周期、帧率以及是否将其附加到触发事件的实体上。这使得开发者能够通过事件系统轻松地实现诸如飘字、特效、物品拾取提示、短暂的视觉反馈等效果。

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

可用参数

Event_TemporaryAnimationWorkClass 通过解析 EventDef 中 parameter 字段里的 JSON 配置来工作。此 JSON 配置对应 TemporaryAnimationData 数据结构。

`TemporaryAnimationData` 字段列表

JSON参数名	XML参数名 (N/A)	类型	默认值	说明
`contentType`	N/A	`AnimationContentType`	无	必需。动画内容的类型。决定了使用 `textContent`、`spriteNames` 或 `drawNodeDefName` 字段。请参见下方的 `AnimationContentType` 枚举说明。
`isUIAnimation`	N/A	布尔	`false`	可选。指示动画是否作为UI元素显示在Canvas上。如果为 `true`，动画将适配屏幕坐标。
`textContent`	N/A	字符串	`null`	可选。当 `contentType` 为 `Text` 时使用。动画的文本内容。
`spriteNames`	N/A	字符串数组 (`string[]`)	`null`	可选。当 `contentType` 为 `Sprite` 时使用。组成动画的精灵资源名称数组，将按顺序播放以形成帧动画。
`drawNodeDefName`	N/A	字符串	`null`	可选。当 `contentType` 为 `DrawNode` 时使用。DrawNode定义 (`DrawNodeDef`) 的 `defName`，用于渲染复杂图像或粒子效果。
`position`	N/A	`Vector3`	`null`	可选。动画的绝对世界初始位置。如果设置，将优先使用此位置。
`relativeOffset`	N/A	`Vector3`	`null`	可选。动画相对于事件触发者 (`initiator`) 的偏移坐标。仅在 `initiator` 存在且 `position` 未设置时生效。
`parentToInitiator`	N/A	布尔	`false`	可选。指示动画是否应设置为事件触发者 (`initiator`) 的子对象。如果触发者不存在，此设置无效。
`lifeTime`	N/A	浮点数	`3.0f`	可选。动画的生命周期（秒）。动画将在此时间后自动销毁。如果省略，默认为3秒。
`fps`	N/A	浮点数	`3.0f`	可选。精灵动画或DrawNode动画的帧率（每秒更新次数）。如果省略，默认为3帧/秒。文本动画通常不使用此参数。

`AnimationContentType` (枚举)

定义临时动画的内容类型，这会影响您需要提供哪些具体内容字段。

Text: 动画内容为文本字符串。此时需要提供 textContent 字段。
Sprite: 动画内容为一系列精灵，用于播放帧动画。此时需要提供 spriteNames 字段。
DrawNode: 动画内容为DrawNodeDef定义，用于更复杂的图像或粒子效果。此时需要提供 drawNodeDefName 字段。

示例

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

<Define>
    <!-- 假设已有DrawNode_ExplosionEffect, Sprite_Coin1, Sprite_Coin2, Sprite_Coin3 等资源 -->

    <!-- 示例1: 在怪物死亡位置生成一个“命中”文本动画 (相对于触发者) -->
    <EventDef>
        <defName>SpawnHitTextOnDeath</defName>
        <label>显示命中文本</label>
        <description>在怪物死亡时显示“命中”文本。</description>
        <workClass>Event_TemporaryAnimationWorkClass</workClass>
        <parameter>
        {
            "contentType": "Text",
            "textContent": "命中！",
            "relativeOffset": {"x": 0.5, "y": 1.0, "z": 0.0},
            "lifeTime": 1.5,
            "isUIAnimation": false
        }
        </parameter>
    </EventDef>

    <!-- 示例2: 在特定坐标播放一个金币收集的UI动画 (精灵序列) -->
    <EventDef>
        <defName>SpawnCoinCollectAnimation</defName>
        <label>金币收集动画</label>
        <description>在屏幕固定位置播放金币收集UI动画。</description>
        <workClass>Event_TemporaryAnimationWorkClass</workClass>
        <parameter>
        {
            "contentType": "Sprite",
            "isUIAnimation": true,
            "spriteNames": ["Sprite_Coin1", "Sprite_Coin2", "Sprite_Coin3"],
            "position": {"x": 100.0, "y": 200.0, "z": 0.0},
            "lifeTime": 1.0,
            "fps": 10.0
        }
        </parameter>
    </EventDef>

    <!-- 示例3: 在敌人身上播放爆炸DrawNode动画，并将其设为敌人子对象 -->
    <EventDef>
        <defName>SpawnExplosionEffect</defName>
        <label>爆炸特效</label>
        <description>在敌人头上播放爆炸DrawNode动画。</description>
        <workClass>Event_TemporaryAnimationWorkClass</workClass>
        <parameter>
        {
            "contentType": "DrawNode",
            "drawNodeDefName": "DrawNode_ExplosionEffect",
            "relativeOffset": {"x": 0.0, "y": 0.5, "z": 0.0},
            "parentToInitiator": true,
            "lifeTime": 0.8,
            "fps": 15.0
        }
        </parameter>
    </EventDef>

    <!-- 示例4: 在地图随机位置显示一个“提示”文本，无触发者 -->
    <EventDef>
        <defName>ShowRandomHint</defName>
        <label>随机提示</label>
        <description>在地图随机位置显示一个提示文本。</description>
        <workClass>Event_TemporaryAnimationWorkClass</workClass>
        <parameter>
        {
            "contentType": "Text",
            "textContent": "小心前方！",
            "position": {"x": 20.0, "y": 80.0, "z": 0.0},
            "lifeTime": 2.0
        }
        </parameter>
    </EventDef>
</Define>

复杂参数说明

`parameter` 字段 (JSON配置)

说明：EventDef 中的 parameter 字段是一个特别说明，它不使用标准的XML元素赋值方式，而是直接作为文本内容包含一个JSON格式的字符串。这个JSON字符串包含了 TemporaryAnimationData 的所有配置参数，用于指导 Event_TemporaryAnimationWorkClass 的具体行为。您需要确保提供的JSON字符串是语法正确的，并且其内容符合 TemporaryAnimationData 的结构。
JSON属性与C#映射关系：
- 所有JSON属性名（如 contentType, isUIAnimation 等）与C#内部数据类 TemporaryAnimationData 中的对应属性名一致（JSON通常使用驼峰式命名）。
Vector3 的JSON表示：在JSON中，Vector3 类型的字段需要以一个包含 x, y, z 三个浮点数字段的JSON对象形式表示。
- 例如："position": { "x": 50.0, "y": 30.0, "z": 0.0 }
字符串数组的JSON表示： spriteNames 字段是一个字符串数组，应以JSON数组的形式表示。
- 例如："spriteNames": ["Sprite_Frame1", "Sprite_Frame2", "Sprite_Frame3"]
枚举值的JSON表示：在JSON中，所有枚举类型（如 contentType）都应以其字符串名称来表示。
- 例如："contentType": "Sprite"

`contentType` 字段及其相关内容字段

contentType 字段是动画的核心配置，它决定了动画将显示何种内容。根据您选择的 contentType，以下字段中的且仅其中的一个是必需的，其余字段将被忽略：

当 contentType 为 Text 时：
- textContent (字符串)：必须提供动画要显示的文本内容。
- 例如："contentType": "Text", "textContent": "伤害！"
当 contentType 为 Sprite 时：
- spriteNames (字符串数组) ：必须提供组成帧动画的单个精灵名称列表。这些名称必须是游戏资源管理系统可识别的有效精灵名称。动画将按列表顺序循环播放这些精灵。
- 例如："contentType": "Sprite", "spriteNames": ["FX_Dust1", "FX_Dust2"]
当 contentType 为 DrawNode 时：
- drawNodeDefName (字符串)：必须提供 DrawNodeDef 的 defName。DrawNodeDef 是一种更复杂的图形定义，可以用于创建包含多个图层、动态效果或粒子系统的动画。
- 例如："contentType": "DrawNode", "drawNodeDefName": "DrawNode_HealEffect"

位置 (`position`, `relativeOffset`) 与父级 (`parentToInitiator`) 逻辑

动画的生成位置和父级关系遵循以下优先级和逻辑：

绝对位置 (position)：如果 position 字段被设定，则动画将精确地生成在该世界坐标。这是定位的最高优先级。
相对偏移 (relativeOffset)：如果 position 未设置，但 relativeOffset 字段被设定，并且事件有一个 initiator (触发者实体)，则动画将生成在 initiator 的位置加上 relativeOffset。
触发者位置：如果 position 和 relativeOffset 都未设置，但事件有一个 initiator，则动画将生成在 initiator 的当前位置。
默认位置：如果上述所有条件均不满足（即未提供 position，没有 relativeOffset 或没有 initiator），动画将默认生成在世界坐标 (0,0,0) 处，并会输出警告日志。
父级设置 (parentToInitiator)：如果 parentToInitiator 设置为 true 并且事件有一个 initiator，则生成的动画对象将会被设置为 initiator 的子对象，这意味着动画会随 initiator 移动。如果 initiator 不存在，即使设置为 true，动画也不会有父级，并会输出警告。

异噬XML数据定义文档