跳到主要内容

运行时错误

GCS · Troubleshooting

以 Monitor 为仪器的 Play Mode 诊断：启动失败、被阶段时机拒绝的动作、出牌异常、始终无声的事件订阅，以及落后于状态的画面。

写给内容校验通过、进入 Play Mode 后战斗仍然异常的开发者。

运行时错误只在场景进入 Play Mode 之后出现，这正是 Game Card Monitor 存在的意义。先让它回答三个问题：运行时状态是否变化、战斗此刻在哪个阶段、哪些 flow 和事件实际运行过。下面每类故障都标注了揭露它的那个 tab。

启动失败​

进了 Play Mode，战斗没出现，Monitor 的 Battle tab 也没有任何活跃战斗。沿这张单子往下走：

  1. 场景里有 GameCardManager，六个数据库全部已分配。
  2. 有 GameCardEncounterBootstrap（或你自己的 GCSApi.StartBattle 调用）引用了遭遇战；战斗要自己开打的话，Auto Start On Play 已勾选。
  3. 遭遇战的玩家单位和敌人阵容都能在活跃数据库里解析出来。

配置看着都对、战斗仍然不开时，只读 Console 的第一条错误，其余的先不管。后面的错误通常只是第一条的连锁后果。

被时机拒绝的动作​

卡打不出去、End Turn 像死了一样、某个 API 调用仿佛被无视。绝大多数情况是战斗不在这个动作要求的阶段：

  • 用 GCSApi.Phase 或 Monitor 的 Phase tab 读当前阶段。出牌和 End Turn 需要 PlayerPhase；在 PlayerTurnStart、PlayerTurnEnd、EnemyPhase 和两个结束态里被拒绝是设计使然。
  • 看 Monitor 的 Gate tab。阶段之间战斗会为动画停留；这个 tab 列出当前每个 gate 持有者和 acquire/release 日志。表现层脚本拿了 gate 不放，战斗就会冻住，看起来像输入被无视。
  • 确认选中的目标还活着，也没有状态通过 Card Playable Hook 否决出牌。

Game Card Monitor 的 Gate tab 列出每个 animation gate 持有者及其 acquire/release 记录

代码里可以用 GCSApi.CanPlayCard(card) 直接拿到可出牌判定，自定义 UI 里很好用。

出牌行为异常​

卡消失了却没有效果、打完还留在手牌、进了错误的牌堆、能量变化出乎意料。按可能性排序：

  • 打开 Monitor 的 Flow tab，确认这张卡的行为图真的执行了。出牌后毫无 flow 记录，说明图的入口节点对不上，正是"打出去没反应"那一类。
  • 查卡上的标签。Exhaust、Retain、Unplayable 各自改变卡的去向或能否打出。
  • 查遭遇战战斗规则里的弃牌和手牌上限；回合结束时"凭空消失"的卡，往往只是弃牌规则在正常工作。
  • 费用的意外来自 cost 修正和 Card Cost Hook 图，不是卡面上印的数字。

使用自定义节点时，确认每一次战斗修改都经过 ctx.Controller。绕开它修改状态会同时绕开事件、Hook 和 Monitor，导致排查范围扩大。

始终无声的订阅​

自定义 UI 不刷新、监听器触发了两次、或者完全不触发。Monitor 的 Event tab 列出战斗触发（Raise）过的每个事件及其 payload，可以把问题拆成两类：事件在列表里，说明运行时确实发了，是订阅有问题；始终不出现，说明等待的事件没有发生。

Game Card Monitor 的 Event tab 按发生顺序列出已触发的战斗事件及其 payload

常见的订阅错误：

  • 在 battle manager 存在之前就订阅，handler 挂在了空气上。
  • 从不释放。每个 GCSApi 订阅都返回 IDisposable；保存它，在监听对象销毁时释放，否则重载后会叠出重复的 handler：
IDisposable _played;

void OnEnable()  => _played = GCSApi.OnCardPlayed(args => Refresh());
void OnDisable() => _played?.Dispose();
  • 带类型的监听器用错了参数类型，或事件名和 GCSEventNames 没有完全一致。
  • 混淆了两层事件：Raise Internal Event / On Internal Event 是图与图之间的通信，C# 代码监听的是 GCSApi.Subscribe 背后的运行时事件。

走 GES 桥的事件还要确认：GES 已安装（检测到时 TG_GES_INSTALLED 宏会自动配置），节点上的 GES 事件 GUID 对应某个活跃 GES 数据库里的事件。

机制正常，画面不动​

Monitor 里伤害结算了，屏幕却不同意：HP 条不动、VFX 缺席、音效沉默、敌人没有可见的身体。既然状态已确认正确，排查范围就只剩表现层。按收益从高到低查：场景 UI 引用、单位 prefab、卡牌模板和美术、状态图标，以及图里 FX 节点上的 VFX、SFX 和动画引用。

求助之前先留一份复现记录​

运行时问题难以定位时，记下：场景路径、遭遇战名称、Monitor 显示的阶段、正在执行的动作、Console 第一条错误，以及 Battle、Pile、Unit、Flow、Event 各 tab 当时的内容。这组信息能把状态 bug、表现层 bug 和配置 bug 分开，也能把"它有时会坏"变成一个可以回答的问题。

本页总览