跳到主要内容

运行时问题

Guide

从 Monitor 中的当前状态和执行记录出发，定位故障发生在启动、阶段、Behavior、等待、事件还是表现层

战斗没有启动​

进入 Play Mode 后没有出现战斗，先检查四项启动条件：

  • 场景中存在一个启用的 GameCardManager

  • 固定场景的 Bootstrap 已指定 Default Encounter 并开启 Auto Start On Play，或项目代码确实调用了 GCSApi.StartBattle

  • Encounter 包含有效 Player 与至少一个 Enemy

  • Manager 注册了本场需要主动解析的数据库

Monitor 的 Battle 显示 No active battle 时，只能确认当前没有可读取的战斗，继续检查 Console 中第一条 GCS 错误和完整调用栈；后续错误可能只是同一问题的连锁结果

提示

修复后请重新进入 Play Mode，确认 Battle 显示 Encounter、玩家、敌人和当前 Phase，并出现 OnBattleStarted 记录

操作没有被接受​

卡牌无法打出或 End Turn 没有响应时，请核对操作成立所需的状态：

  • Phase 是否为 PlayerPhase

  • 卡牌是否仍位于 Hand，当前有效费用是否不高于玩家能量

  • Single Enemy 的已选目标是否存活且合法

  • Card Playable Hook 是否取消出牌

  • 当前是否正在等待 Choice 或 Reward

提示
  • 项目 UI 应使用 GCSApi.CanPlayCard(card) 更新按钮状态，并检查 TryPlayCard 的返回结果，不要只根据卡面费用决定是否可出牌
  • 修复后重新执行同一操作，确认 API 返回成功，并在 Monitor 中看到手牌、能量、阶段或等待状态发生对应变化

卡牌结算异常​

卡牌已经离开手牌，但伤害、状态或牌堆结果不符合预期时：

  1. 在 Flow 中确认正确的 Card Owner 与 Entry 已执行
  2. 在 Unit 中核对 HP、护甲与状态层数
  3. 在 Pile 中确认卡牌进入 Discard 还是 Exhaust
  4. 检查 Exhaust、Retain、Ethereal、Unplayable 等关键词与 Encounter 的 Hand Discard 规则
  5. 检查费用、伤害、护甲与状态相关 Hook 是否修改或取消结果
注意

  • 自定义节点必须通过 ctx.Controller 修改战斗状态，直接改写对象字段会绕开事件、Hook 和 Monitor 记录，将导致 UI 与运行状态不同步

  • 修复后重放同一张卡牌，Flow 中的执行路径应与 Unit、Pile 中的最终状态一致

流程停止推进​

先在 Phase 中确认最后一次阶段转换，再检查当前等待类型：

等待类型证据修复方向
GateGate 中存在只有 Acquire、没有 Release 的 Reason确保表现流程在成功、失败和中止分支都释放同一 Holder
ChoiceBattle 或 Phase 显示 Choice Pending场景保留一个可用的 IChoicePresenter，并提交选择或 Skip
RewardGCSApi.IsWaitingForReward 为 true奖励 UI 提交一次 ApplyReward 或 SkipReward
WaitFlow 已进入显式 Wait 路径核对等待时长与对象生命周期
提示

普通 VFX、SFX 和动画不会自动阻塞阶段，只有 Behavior 显式使用 Wait、Gate 或 Choice，或奖励流程等待提交时，GCS 才会保持等待状态

释放等待后，请确认 Gate 不再保留对应 Holder，Choice 或 Reward 的 Pending 状态，并出现下一次 Phase 记录

事件监听没有响应​

复现前打开 Monitor 的 Event 标签页，并按记录状态定位订阅问题：

  • 事件没有记录：确认对应玩法时机确实发生，并清除 Filter 后重试

  • 事件已有记录但 subs 0：广播时没有订阅者，检查订阅时机

  • 存在订阅者但目标 UI 无响应：检查事件名、Payload 类型、回调对象和回调逻辑

  • 回调重复执行：检查是否重复订阅，或旧 IDisposable 没有释放

需要接收 OnBattleStarted 或起手抽牌事件的对象必须在调用 StartBattle 前完成订阅，完整模式见事件使用指南

修复后清除 Event 历史并重新触发一次时机，预期事件、订阅者数量和回调次数应当一致

运行状态正确但画面没有更新​

  1. Monitor 已记录正确的 HP、护甲、状态、牌堆或 Phase 变化，但血条、卡面、单位、VFX 或音频没有对应反馈，说明机制已经写入，问题位于表现绑定

  2. 继续检查 UI 订阅、Prefab 引用、Card Template、状态 Icon、FlowGraph FX 节点与场景 Presentation 组件，若表现流程持有 Gate，还要确认完成和中止路径都会释放，UI 绑定见自定义 UI 接入，节点行为见FX 节点

  3. 修复后以 Monitor 中同一条状态变化为基准，确认画面只更新一次，且没有遗留 Gate

本页总览