supervisor-simulator/docs/配置定义系统文档.md

配置定义系统文档 (Definition System)

本文档详细说明了《最强导师》游戏中的数据定义系统。该系统采用数据驱动（Data-Driven）的设计理念，将核心游戏内容（如学科、角色、特质等）与代码逻辑分离，存储为 JSON 格式的配置文件。这不仅便于开发过程中的数值调整，也为未来的 Mod 支持打下了基础。

1. 系统概述

游戏的核心数据存储在 resources/definitions/ 目录下。游戏启动时，ContentRegistry（位于 scripts/Core/ContentRegistry.cs）负责加载这些文件，并将它们反序列化为 C# 对象，最终汇聚在 GameContentDatabase 中供游戏逻辑查询。

主要特点：

• 格式统一：主要使用 JSON 格式。
• 支持热加载/Mod：设计上支持从多个源（res:// 或 user://）加载并合并数据。
• 国际化支持：所有名称和描述都包含 Key (本地化键) 和 Fallback (默认文本)。

2. 核心数据结构

几乎所有的定义文件都复用了以下核心数据结构。

2.1 DefinitionHeader (通用头部)

所有定义对象都包含一个 Header 字段，用于标识身份。

字段名	类型	说明
Id	string	唯一标识符，建议格式 namespace:type_name (如 core:archetype_grinder)。
Name	LocalizedText	显示名称。
Description	LocalizedText	详细描述。
IconPath	string	图标资源路径 (可选)。
Tags	List<string>	标签列表，用于分类或过滤。

2.2 LocalizedText (本地化文本)

用于支持多语言。

字段名	类型	说明
Key	string	翻译文件中的 Key (如 archetype.grinder.name)。
Fallback	string	当找不到翻译时的默认显示文本。

2.3 ModifierBundle (数值修正包)

用于描述 Buff、Debuff 或被动效果。它不直接修改数值，而是提供加成或规则 ID。

• AttributeModifiers: 属性修正 (如 Academic, Engineering)。
  • Type: 属性枚举。
  • Add: 固定加值。
  • Multiplier: 乘法倍率 (默认为 1.0)。
• StatusModifiers: 状态修正 (如 Mood, Stress)。
• ResourceModifiers: 资源修正 (如 Money)。
• RuleIds: List<string>，特殊规则的 ID (如 rule:no_sleep)，由代码逻辑解析具体效果。

---

3. 定义类型详解

以下是各类定义文件的详细说明。

3.1 学科 (Disciplines)

文件: resources/definitions/disciplines.json 对应类: DisciplineDefinition

定义了游戏中的学术流派（如“经济学”、“计算机科学”）。学科决定了核心的资源循环机制和允许使用的角色。

• Buff: 学科全局 Buff，通常提供特定资源产出或属性加成。
• RolePoolIds: 该学科允许使用的角色 ID 列表。
• ItemPoolIds: 该学科关联的特殊物品池。
• TaskKeywordIds: 任务生成的关键词偏好。

示例片段:

{
  "Header": { "Id": "core:discipline_computer", ... },
  "Buff": {
    "Name": { "Fallback": "Overclock" },
    "Modifiers": {
      "AttributeModifiers": [{ "Type": "Engineering", "Add": 5, "Multiplier": 1.05 }]
    }
  },
  "RolePoolIds": [ "core:role_geek", "core:role_coder" ]
}

3.2 角色身份 (Roles)

文件: resources/definitions/roles.json 对应类: RoleDefinition (推测)

定义了学生在实验室中的具体分工（如“码农”、“实验员”）。

• Tiers: 角色等级列表。通常随人数或投入增加解锁更高级别的修正。
  • RequiredCount: 激活该层级所需数量。
  • Modifiers: 该层级提供的修正包。
• AllowedDisciplineIds: (可选) 限制该角色只能在特定学科中使用。

示例片段:

{
  "Header": { "Id": "core:role_coder", ... },
  "Tiers": [
    {
      "RequiredCount": 2,
      "Modifiers": { "AttributeModifiers": [{ "Type": "Engineering", "Multiplier": 1.20 }] }
    }
  ]
}

3.3 原型 (Archetypes)

文件: resources/definitions/archetypes.json 对应类: ArchetypeDefinition (推测)

定义了学生的性格原型（如“卷王”、“摸鱼怪”）。类似于种族天赋，随同类学生数量增加而增强。

• Tiers: 羁绊等级列表。
  • RequiredCount: 激活羁绊所需人数。
  • Modifiers: 羁绊效果。

示例片段:

{
  "Header": { "Id": "core:archetype_grinder", ... },
  "Tiers": [
    {
      "RequiredCount": 2,
      "Modifiers": { "AttributeModifiers": [{ "Type": "Activation", "Multiplier": 1.15 }] }
    }
  ]
}

3.4 特质 (Traits)

文件: resources/definitions/traits.json 对应类: TraitDefinition (推测)

定义了学生个体的具体特征（如“咖啡依赖”、“夜猫子”）。

• Modifiers: 特质带来的修正效果，通常直接包含 RuleIds 来触发特殊逻辑。

示例片段:

{
  "Header": { "Id": "core:trait_night_owl", ... },
  "Modifiers": { "RuleIds": [ "rule:trait_night_owl" ] }
}

3.5 校园行为与模拟参数 (Campus Behavior)

文件: resources/definitions/campus_behavior.json 对应结构: 模拟配置对象 (非标准 Definition)

定义了模拟系统的全局常数和行为交互规则。

• Thresholds: 各种状态的阈值（如 CriticalStressThreshold: 90）。
• Decay/Growth Rates: 状态随时间变化的速率（如 HungerDecayPerSecond）。
• ActionConfigs: 定义学生可执行的具体动作。
  • ActionId: 动作 ID (如 Eating)。
  • LocationId: 执行地点 (如 Canteen)。
  • DurationSeconds: 持续时间。
  • *Delta: 执行该动作对各项数值的影响 (如 HungerDelta, StressDelta)。

示例片段:

{
  "CriticalStressThreshold": 90,
  "ActionConfigs": [
    {
      "ActionId": "Eating",
      "LocationId": "Canteen",
      "HungerDelta": 3.00,
      "StressDelta": -0.50
    }
  ]
}

4. 如何添加新内容

1. 找到对应文件: 在 resources/definitions/ 下找到对应类型的 JSON 文件。
2. 复制模板: 复制现有的一个对象块。
3. 修改 ID: 确保 Header.Id 是全局唯一的。
4. 配置参数: 修改名称、描述和修正数值。
5. 重启游戏: 数据将在游戏启动时重新加载。

5. 关联代码文件

• 加载逻辑: scripts/Core/ContentRegistry.cs
• 数据仓库: scripts/Models/GameContentDatabase.cs
• 学科定义: scripts/Models/DisciplineDefinitions.cs
• 修正结构: scripts/Models/Modifiers.cs
• 通用结构: scripts/Models/DefinitionSupport.cs

---

文档生成日期: 2026-01-17