运行时数据类型

Guide

创作资产描述什么可以存在，运行时类型保存某一场战斗此刻正在发生什么

战斗状态与 Controller

类型	职责	项目代码如何使用
`IBattleState`	只读查看阶段、回合、单位、能量、牌堆、计数器、Encounter、等待状态与变量	通过 `GCSApi.Battle` 或更高层 `GCSApi` Helper 读取
`IBattleController`	修改 HP、护甲、能量、状态、卡牌、变量、延迟触发与单位的受支持入口	自定义 FlowGraph 节点通过 `ctx.Controller` 使用，外部代码通常使用 `GCSApi`
`BattleStateView`	同时实现 State 与 Controller Contract 的内部具体对象	集成代码不要依赖它的私有实现表面

这种拆分是有意设计的：读取可以广泛，写入必须经过 Controller 路径，Hook、事件、阶段检查、Monitor 记录与表现同步才不会被绕过

类型	实时数据
`UnitState`	定义引用、当前/最大 HP、护甲、队伍、存活状态、状态、跳过回合标记与活动 Hook
`EnemyUnitState`	`UnitState` 的全部内容，以及当前 Intent 与敌人 Pattern 执行状态

GamePlayerUnit 或 GameEnemyUnit 是创作定义，运行时状态会为当前战斗创建一次；敌人的起始 HP 在战斗开始时从定义的闭区间范围中抽取，之后修改定义不会重写已经存在的单位

状态实例以层数形式保存在单位上，并由 GameStatus 作为 Key；GameStatus 继续定义叠层与衰减规则，UnitState 则回答这个单位此刻拥有多少层

概念	运行时表示	含义
卡牌定义	`GameCard`	创作的名称、文本、基础费用、分类、Target、美术与 Behavior
战斗副本	`CardInstance`	一张带实例 ID、升级状态与实例专属费用变化的副本
当前生效定义	`CardInstance.GetActiveCard()`	实例已升级时返回升级卡，否则返回基础卡

浏览数据库与构建卡组时使用定义，执行战斗操作时使用实例；两张 Strike 共享同一个 GameCard 定义，但在牌堆中是两个不同的 CardInstance

类型或表面	生命周期
手牌、抽牌、弃牌、消耗牌堆	一场活动战斗
`CardPile` 内容	有顺序的 `CardInstance` 列表
Run Master Deck	在当前 Run 的多场战斗之间保留，并为后续战斗生成牌堆
`CardCostRule`	作用于一个卡牌实例，按设置时长或战斗结束到期

卡牌区域与牌堆说明移动、洗牌、手牌上限、出牌、生成卡牌，以及 Run Deck 与战斗牌堆的区别

要修改的内容	正确对象
以后所有 Strike 卡面的基础费用	`GameCard` 定义
当前战斗中某一张 Strike 的费用	通过受支持费用规则修改该 `CardInstance`
敌人创作时的 HP 范围	`GameEnemyUnit` 定义
这一个敌人此刻的 HP	通过 Controller 修改它的 `EnemyUnitState`
状态的叠层策略	`GameStatus` 定义
一个单位此刻的 Poison	通过 Controller 修改该单位的状态层数
起始卡组配方	`GameDeck` 定义
当前战斗可用的卡牌	实时牌堆

在 Play Mode 中修改定义，不会可靠迁移已经实例化的状态；实时数值应在 Game Card Monitor 中检查，不要假设 Inspector 仍然代表正在运行的战斗

只使用以下三种受支持入口：

直接赋值 HP、修改牌堆列表或编辑状态字典，会绕过以下一个或多个行为：

项目需求没有对应的公开 GCSApi 修改方法时，应通过文档化的 Controller Contract 实现一个职责明确的自定义节点或集成，不要把可以访问的内部字段误当成受支持 API

以下是受支持的集成表面：

没有通过这些表面公开的类型，即使 C# 可见性允许访问，也属于实现细节；运行时层级见运行时架构，项目代码工作流见 GCSApi 指南