supervisor-simulator/docs/校园行为系统文档.md

校园行为系统文档

本文档描述校园行为系统相关代码与配置， 覆盖 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()。