189 lines
6.7 KiB
Markdown
189 lines
6.7 KiB
Markdown
# 配置定义系统文档 (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*
|