运行时概览
理解项目操作如何进入 GCSApi、转成战斗状态变化，再通过事件回到 UI 与表现系统
从项目操作到战斗反馈
上图展示了 GCS 的完整运行链路：项目通过 GCSApi 提交启动战斗、出牌、结束回合或奖励选择等操作，GameCardManager 将请求交给当前战斗，状态机负责推进流程，FlowGraph 执行器负责结算规则，状态改变后，事件和表现请求再把结果交给 UI、动画、VFX 与音频系统
这条链路只规定玩法状态和对外接口，不限制项目怎样设计战斗界面，你可以继续使用随包表现组件，也可以替换手牌、HUD、单位视图和奖励界面，而无需重写卡牌与状态规则
运行时组件的职责
| 组件 | 主要职责 | 项目代码是否需要直接依赖 |
|---|---|---|
GCSApi | 启动和控制战斗、读取状态、安全修改数据、订阅事件、查找内容 | 是，它是项目代码的首选入口 |
GameCardManager | 保存当前启用的数据库、Run 数据与活动战斗 | 场景必须存在；通常不直接调用 |
BattleStateMachine | 推进阶段、回合、敌人行动、等待、奖励与胜负流程 | 否，通过 GCSApi 控制 |
BattleStateView | 保存当前战斗的单位、卡牌、牌堆、能量、状态和变量 | 否，通过 GCSApi.Battle 或查询方法读取 |
GameCardFlowExecutor | 按连接关系执行 Card、Status 与 Enemy Behavior | 否，通过 FlowGraph 和执行上下文使用 |
GCSEvents | 将已经发生的运行时变化通知外部系统 | 通过 GCSApi 的订阅方法使用 |
GameCardManager 是场景入口，场景中没有可用的 Manager 时，GCSApi.IsReady 为 false；查询方法会返回空集合、0、false 或 null，修改方法不会执行，初始化场景和配置数据库的操作见安装与初始化与数据库管理
读取和修改同一份战斗状态
GCSApi.Battle 与 GCSApi.Controller 访问的是同一场战斗，但权限不同
| 入口 | 适用场景 |
|---|---|
GCSApi 查询方法 | 读取阶段、回合、能量、单位、牌堆、状态、Intent 与等待状态 |
GCSApi.Battle | 读取 GCSApi 尚未提供具名方法的只读战斗信息 |
GCSApi 修改方法 | 造成伤害、治疗、获得护甲、修改能量、操作状态或牌堆 |
GCSApi.Controller | 自定义节点或高级集成需要调用更完整的运行时修改能力 |
GCSApi.Battle 返回的集合和其中的 UnitState、CardInstance 仍然指向实时对象，并不是不可变快照，项目代码可以读取它们，但不应直接修改字段或集合
不要直接赋值 UnitState.CurrentHp，也不要修改 CardPile.Cards 或 UnitState.Statuses，这些写法会绕过 Hook、阶段检查、事件、Monitor 记录与 UI 刷新，运行时修改必须通过 GCSApi、受支持的 IBattleController 方法或内置 FlowGraph 节点完成
创作定义与运行实例的区别见定义与运行实例
FlowGraph 如何参与结算
Card、Status 和 Enemy Behavior 共用同一套 FlowGraph 执行规则，每次图开始执行时，运行时都会提供当前行为的来源、持有者、目标、卡牌、状态和战斗数据，因此同一个节点可以在不同内容中复用
| 节点职责 | 可用能力 |
|---|---|
| 读取与计算 | 通过 IEvaluationContext 读取上下文、端口输入、变量和前序节点结果 |
| 修改状态 | 通过 IExecutionContext.Controller 调用受支持的战斗修改方法 |
| 控制流程 | 使用分支、循环、Choice、Wait 与 Group 组织后续执行 |
| 发布结果 | 把实际结算值写入输出端口，供后续逻辑和表现节点读取 |
普通用户只需要在 FlowGraph Editor 中连接节点，编写自定义节点时，再查阅执行上下文与自定义节点
等待不会转移状态所有权
Choice、Wait 和 Animation Gate 可以推迟后续执行或阶段转换，但战斗状态仍由运行时维护
| 机制 | 等待内容 | 恢复条件 |
|---|---|---|
| Choice | 当前 Flow 分支及待处理的阶段转换 | 玩家选择、跳过，或系统因缺少 Presenter/候选项而走 Skipped 分支 |
| 秒数 Wait | 当前 Flow 的后续分支 | 指定的实时秒数结束 |
| Animation Wait | 当前 Flow 的后续分支 | 同名 Gate holder 释放，或等待超时 |
| Animation Gate | 状态机的阶段转换或敌人步骤 | 表现组件成对调用 Acquire 与 Release |
| Reward Wait | 胜利后的最终结束通知 | 玩家应用或跳过奖励 |
FX 节点不会自动等待动画、粒子或音频播放完成，需要严格控制顺序时，应在图中连接 Wait，或由表现协程持有 Animation Gate，节点参数见流程节点，对阶段推进的影响见战斗生命周期
事件和表现请求交付结果
运行时事件用于通知外部系统“某项变化已经发生”，UI 收到事件后，应重新读取 GCSApi 的当前状态，而不是把事件参数长期保存为自己的战斗副本
表现请求负责播放浮动文本、单位动画、VFX、SFX 或镜头效果，它们反映已经结算的玩法结果，不拥有 HP、状态、牌堆或阶段数据，缺少可选表现资源时，玩法仍会继续结算
事件订阅和 UI 刷新方式见事件使用指南与自定义 UI 接入
按任务选择文档入口
| 任务 | 继续阅读 |
|---|---|
| 理解定义、实例与安全修改边界 | 定义与运行实例 |
| 查找阶段、回合和奖励的精确顺序 | 战斗生命周期 |
| 理解手牌、抽牌堆、弃牌堆和消耗堆 | 卡牌与牌堆生命周期 |
| 理解状态施加、Hook、衰减与过期 | 状态生命周期 |
| 接入 UI、动画、VFX、音频和 Gate | 自定义 UI 接入、FX 节点与流程节点 |
| 编写战斗控制代码 | API 使用指南 |
| 查找完整成员和事件参数 | API 参考与事件参考 |