XML 使用说明 - 定义通用事件

在游戏配置文件中，您可以使用 <EventDef> 元素来定义各种可触发的游戏事件。每个 <EventDef> 元素都必须包含在顶层的 <Define> 元素之内，并遵循其通用的属性定义规则。

功能介绍

<EventDef> 提供了一种灵活的机制来定义游戏中各种可执行的事件，从生成实体到触发故事情节。它通过指定一个事件处理类 (workClass) 及其配套的参数 (parameter) 来实现事件的定制化行为。

参数说明

所有参数都必须通过嵌套元素的方式进行赋值。

  • <defName> (必需，字符串)

    • 该事件定义的唯一标识符。在整个游戏配置中，此名称必须是全局唯一的，除非您有意覆盖现有定义。
    • 作为匿名定义时，此字段可以省略。

  • <label> (可选，字符串)

    • 提供一个人类可读的标签，用于更好地理解该事件定义的用途。

  • <description> (可选，字符串)

    • 提供更详细的文本描述，解释该事件的具体内容或特殊用途。

  • <workClass> (必需，字符串)

    • 指定处理此事件逻辑的后端类名。此字符串必须精确匹配到游戏中对应的事件处理类。
    • 关于 workClass 类的详细讲解，请参阅稍后发布的第三章：核心工作类定义。

  • <parameter> (必需，JSON 字符串)

    • 包含传递给 workClass 指定事件处理类的所有必要参数。这些参数必须以JSON (JavaScript Object Notation) 格式提供，并且其结构和内容完全取决于 workClass 所需的数据。

parameter 参数：JSON 格式详解

parameter 参数是一个 JSON 格式的字符串，其内部结构和字段名必须与 workClass 所期望的参数类型严格匹配。游戏引擎会负责解析这个 JSON 字符串，并将其映射到 workClass 内部对应的参数对象上。

JSON 格式的特点：

  • 键值对： 由键（字符串）和值组成，键和值之间用冒号 : 分隔。
  • 对象： 用大括号 {} 包裹，包含零个或多个键值对，键值对之间用逗号 , 分隔。
  • 数组： 用方括号 [] 包裹，包含零个或多个值，值之间用逗号 , 分隔。
  • 数据类型： 支持字符串、数字、布尔值（true/false）、JSON 对象、JSON 数组和 null。

编写规则：

  • 整个 JSON 结构必须是合法的。
  • 所有键（字段名）必须用双引号 "" 包裹。
  • 所有字符串值也必须用双引号 "" 包裹。数字、布尔值不需要。
  • JSON 内部可以包含换行符和缩进，以提高可读性，这些空白字符在解析时会被忽略。

示例

示例 1：生成多个怪物事件

此事件定义使用 Event_EntityGenerater 作为工作类，负责在地图外生成指定数量的怪物。parameter JSON 结构清晰地定义了要生成的实体类型、位置类型和数量。

<Define>
    <EventDef>
        <defName>Event_SpawnMonsterA1_3</defName>
        <label>生成3个A1型怪物</label>
        <description>在地图外生成3个编号为MonsterA1的怪物。</description>
        <workClass>Event_EntityGenerater</workClass>
        <parameter>
        {
            "DefinitionsToChooseFrom":[ 
                { "DefName":"MonsterA1", "DefTypeName":"MonsterDef" } 
            ],
            "LocationType":"OffMap",
            "Count":3
        }
        </parameter>
    </EventDef>
</Define>

parameter JSON 结构分析：

  • 这是一个 JSON 对象。
  • "DefinitionsToChooseFrom"：一个 JSON 数组，其中每个元素都是一个 JSON 对象，包含要生成的实体的 DefName（定义名称）和 DefTypeName（定义类型名称）。
  • "LocationType"：一个字符串，指定实体生成的位置类型。
  • "Count"：一个数字，指定要生成的实体数量。

示例 2：触发特定故事情节事件

此示例展示了一个触发故事情节的事件，parameter 可能包含故事ID、参与者等信息。

<Define>
    <EventDef>
        <defName>Event_TriggerStory_LostChild</defName>
        <label>触发失踪儿童故事</label>
        <description>在一个随机地点触发一个关于失踪儿童的故事事件。</description>
        <workClass>Event_StoryManager</workClass>
        <parameter>
        {
            "StoryID": "LostChildScenario",
            "TriggerLocation": "Random",
            "Participants": [
                { "Role": "QuestGiver", "Faction": "PlayerAffiliation" },
                { "Role": "MissingChild", "DefName": "ChildPawnDef", "DefTypeName": "PawnDef" }
            ]
        }
        </parameter>
    </EventDef>
</Define>

注意事项

  • parameter 的严格性： parameter 中的 JSON 结构必须与 workClass 内部定义的参数类结构完全匹配，包括字段名的大小写和数据类型。任何不匹配都可能导致事件无法正确执行。
  • workClass 定义： workClass 对应的类必须在游戏中存在且可加载。错误的类名会导致事件无法实例化。
  • 可读性： 尽管 JSON 允许在一行中定义，但为了配置文件的可读性和易维护性，强烈建议使用多行和缩进来格式化 parameter 的内容。