# 校园行为系统文档

本文档描述校园行为系统相关代码与配置，
覆盖 `scripts/Campus`、`scripts/Core`、`scripts/Models`
以及 `resources/definitions` 下的所有相关文件。

## 1. 系统概览

- 行为系统基于“优先级决策 + 有限状态机”。
- 决策优先级：Critical(危机) -> AssignedTask(指令任务)
  -> Needs(需求) -> Trait(特质偏好) -> Idle(闲置)。
- 行为数值由 `campus_behavior.json` 驱动，
  动作效果按“每秒”变化。
- 每轮开始会预生成整轮行动计划，
  计划包含多条动作与浮动时长。
- 所有行为通过 `GD.Print` 输出到控制台。

## 2. 代码文件说明

### 2.1 `scripts/Campus`

- `scripts/Campus/CampusBehaviorConfig.cs`
  - 定义行为系统枚举与配置结构。
  - 提供 `CampusBehaviorConfig` JSON 加载。
  - 提供 `CampusLocationRegistry` 与 `CampusBehaviorWorld`。
  - 定义 `CampusTask` 与 `CampusAgentNeeds`。
- `scripts/Campus/CampusBehaviorAgent.cs`
  - 定义 `CampusAgentRuntime`、`CampusBehaviorIntent`、`CampusBehaviorContext`。
  - 实现 Planner 与多级 Provider。
  - 实现状态机：Decision/Move/Action。
  - `CampusBehaviorAgent` 负责每帧驱动与打断。
  - `CampusTraitIds` 提供行为特质 Id 常量。

### 2.2 `scripts/Core`

- `scripts/Core/ContentCollectionResource.cs`
  - 资源集合容器，可把多个定义资源打包到 `.tres`。
- `scripts/Core/ContentRegistry.cs`
  - 内容加载与合并入口，支持 Resource/JSON 源。
- `scripts/Core/ContentResources.cs`
  - 内容资源接口：`IContentResource`/`IContentResourceCollection`。
- `scripts/Core/DisciplineDefinitionResource.cs`
  - 学科定义 `.tres` 到 `DisciplineDefinition` 的映射。
- `scripts/Core/DomainEvents.cs`
  - 领域事件：任务完成/失败、回合结束。
- `scripts/Core/EventBus.cs`
  - 轻量事件总线 `DomainEventBus`。
- `scripts/Core/GameController.cs`
  - 回合阶段切换控制器。
- `scripts/Core/GameSession.cs`
  - 会话入口，聚合 State/Content/Systems/Events/Localization。
  - `CreateDefault()` 负责加载 `.tres` 与 JSON。
- `scripts/Core/GameSystems.cs`
  - 系统集合：Turn/Task/Economy/Synergy/Assignment。
- `scripts/Core/LocalizationService.cs`
  - 多语言接口与 Godot 实现。
- `scripts/Core/ModManifest.cs`
  - Mod 清单与包信息结构。
- `scripts/Core/Mvc.cs`
  - MVC 接口与 `ModelView<TModel>` 基类。
- `scripts/Core/StatResolver.cs`
  - 数值解析器（羁绊/学科/特质/装备叠加）。

### 2.3 `scripts/Models`

- `scripts/Models/CoreIds.cs`
  - 核心内容 Id 常量（学科/羁绊/角色等）。
- `scripts/Models/DefinitionSupport.cs`
  - 通用定义结构：`LocalizedText` 与 `DefinitionHeader`。
- `scripts/Models/DisciplineDefinitions.cs`
  - 学科定义 `DisciplineDefinition` 与 `DisciplineBuff`。
- `scripts/Models/DomainEnums.cs`
  - 统一枚举：`AttributeType`、`ResourceType`、`StatusType`。
- `scripts/Models/GameContentDatabase.cs`
  - 定义数据汇总库（学科/羁绊/任务/装备等）。
- `scripts/Models/GameState.cs`
  - 全局运行时状态：回合/经济/人员/任务/库存/羁绊/肉鸽。
- `scripts/Models/ItemDefinitions.cs`
  - 装备/设施/消耗品定义与分类枚举。
- `scripts/Models/MentorModel.cs`
  - 导师模型与资源组件（能量）。
- `scripts/Models/Modifiers.cs`
  - 通用数值修饰结构（属性/状态/资源 + RuleIds）。
- `scripts/Models/PaperDefinitions.cs`
  - 论文卡牌定义（等级与元数据）。
- `scripts/Models/PropertyValue.cs`
  - 通用数值类型，带范围与运算符重载。
- `scripts/Models/RogueliteDefinitions.cs`
  - 肉鸽继承定义（校友录/传承/职称保留）。
- `scripts/Models/StaffModel.cs`
  - 雇员/合作者模型（博后/小老师）与动机组件。
- `scripts/Models/StatusValue.cs`
  - 带阈值的状态值（压力/理智/忠诚等）。
- `scripts/Models/StudentModel.cs`
  - 学生模型（类型、进度、贡献记录）。
- `scripts/Models/SynergyDefinitions.cs`
  - 羁绊/职业/特质定义与叠层结构 `SynergyTier`。
- `scripts/Models/Task.cs`
  - 运行时任务模型 `TaskModel` 与进度数据结构。
- `scripts/Models/TaskDefinitions.cs`
  - 任务定义与枚举（类型/难度/奖励/需求）。
- `scripts/Models/UnitComponents.cs`
  - Unit 组件结构（身份/属性/状态/标签/分配/位置/装备）。
- `scripts/Models/UnitModel.cs`
  - Unit 组合容器，聚合上述组件。

## 3. 配置文件说明（`resources/definitions`）

### 3.1 `resources/definitions/campus_behavior.json`

行为系统核心数值配置，动作数值按秒生效。

全局阈值与衰减：

- `CriticalSanityThreshold`：理智过低触发人工湖。
- `CriticalStaminaThreshold`：体力过低触发强制休息。
- `CriticalStressThreshold`：压力过高触发人工湖。
- `HungerThreshold`：饥饿过低触发食堂。
- `EnergyThreshold`：精力过低触发睡觉/咖啡。
- `SocialThreshold`：社交过低触发社交行为。
- `LowMoodThreshold`：心情过低触发宿舍休息。
- `HungerDecayPerSecond`：基础饥饿衰减。
- `EnergyDecayPerSecond`：基础精力衰减。
- `StaminaDecayPerSecond`：基础体力衰减。
- `StressGrowthPerSecond`：基础压力增长。
- `SocialDecayPerSecond`：基础社交衰减。
- `DecisionIntervalSeconds`：打断/重评估间隔。
- `ActionDurationVariance`：动作时长浮动比例（±百分比）。
- `MinPlannedActionSeconds`：单次规划动作的最短时长。

ActionConfigs：

- `ActionId`：动作枚举名。
- `LocationId`：地点枚举名。
- `DurationSeconds`：动作持续时间。
- `HungerDelta`/`EnergyDelta`/`StaminaDelta`。
- `StressDelta`/`MoodDelta`/`SocialDelta`。
- `SanityDelta`/`HealthDelta`。

### 3.2 `resources/definitions/archetypes.json`

- 数组形式的 `ArchetypeDefinition`。
- `Header`：`Id`、`Name`、`Description`、`Tags`。
- `Tiers`：叠层配置列表。
  - `RequiredCount`：触发层数。
  - `Modifiers`：数值修饰与 `RuleIds`。

### 3.3 `resources/definitions/roles.json`

- 数组形式的 `RoleDefinition`。
- `Header`、`Tiers` 与 archetypes 一致。
- `AllowedDisciplineIds`：学科限制列表。

### 3.4 `resources/definitions/traits.json`

- 数组形式的 `TraitDefinition`。
- `Header`：Id 与名称说明。
- `Modifiers`：数值修饰与 `RuleIds`。

### 3.5 `resources/definitions/disciplines.json`

- 数组形式的 `DisciplineDefinition`。
- `Header`：学科 Id、名称、描述、Tags。
- `Buff`：学科被动（Name/Description/Modifiers）。
- `RolePoolIds`：角色池 Id 列表。
- `ItemPoolIds`：装备池 Id 列表。
- `TaskKeywordIds`：任务关键词 Id 列表。

### 3.6 `resources/definitions/discipline_biology.tres`

- Godot 资源版学科定义（`DisciplineDefinitionResource`）。
- 主要字段：
  - `Id`/`NameKey`/`NameFallback`/`DescriptionKey`/`DescriptionFallback`。
  - `IconPath`/`Tags`。
  - `BuffNameKey`/`BuffNameFallback`。
  - `BuffDescriptionKey`/`BuffDescriptionFallback`/`BuffRuleIds`。
  - `RolePoolIds`/`ItemPoolIds`/`TaskKeywordIds`。

## 4. 规则扩展建议

- 新增地点：扩展 `CampusLocationId`，并添加 `Locations` 标记。
- 新增动作：扩展 `CampusActionId`，并添加 ActionConfig。
- 新增 AI 规则：新增 Provider 并加入 `BuildProviders()`。