# 配置定义系统文档 (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**: 任务生成的关键词偏好。

**示例片段**:
```json
{
  "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**: (可选) 限制该角色只能在特定学科中使用。

**示例片段**:
```json
{
  "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`: 羁绊效果。

**示例片段**:
```json
{
  "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` 来触发特殊逻辑。

**示例片段**:
```json
{
  "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`)。

**示例片段**:
```json
{
  "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*