常见症状

🧯

GCS · Troubleshooting

症状优先的诊断法：从肉眼可见的异常（战斗没开、没有卡、敌人回合无行动）出发，沿最短检查序列走到出问题的系统。

写给此刻战斗正在出问题的人：这里给最快的定位路线，不讲架构。

大多数 GCS 问题最终都表现为十种左右的可见故障，而每种故障都有一条短而有序的检查清单。从症状入手，不要从代码入手。Game Card Monitor（Tools/TinyGiants/GCS/Game Card Monitor）是这里的主力仪器：它显示实时战斗状态，能在你打开任何资产之前先告诉你问题在哪一侧。

---

症状地图

症状	首要检查
战斗没有开始	场景 bootstrap、GameCardManager、数据库分配、encounter 引用
没有卡出现	起始卡组、卡组内容、抽牌规则、手牌 UI 引用
卡打不出去	战斗阶段、能量、target mode、目标有效性、Card Playable Hook 类状态
卡打出但没效果	卡牌图入口、节点连接、目标解析
敌人什么都不做	敌人行为图、意图 pattern、是否到达敌人阶段
状态施加不上	状态数据库、状态选择器的值、stack rule、目标
状态层数不掉	资产上的 Decay Rule、图里的触发时机
UI 不更新	先看运行时状态（Monitor），再看表现层绑定
事件收不到	事件名、订阅时机、payload 类型、释放
回合中途整个卡住	从未释放的 animation gate 持有者（Monitor Gate tab）

---

战斗没有开始

按这个顺序检查：

1. 场景里有 GameCardEncounterBootstrap（或你自己调用 GCSApi.StartBattle 的脚本）。
2. GameCardManager 存在且数据库已分配。
3. bootstrap 的 Default Encounter 指向真实存在的遭遇战；战斗要自动开打的话，Auto Start On Play 已勾选。
4. 遭遇战里有玩家单位和至少一个敌人。
5. 玩家单位有起始卡组。
6. Workbench 的校验徽标没有阻断性错误。
7. 进入 Play Mode 后，Monitor 的 Battle tab 显示有活跃战斗。

如果 Monitor 始终看不到战斗，问题在场景搭建或 bootstrap。卡牌逻辑还没有运行，不要先调整它。

---

没有卡出现

按顺序确认：玩家单位有起始卡组、卡组里真的有卡、战斗规则会在战斗或回合开始时抽牌、场景里的手牌 UI 引用已经赋值。然后打开 Monitor 的 Pile tab。

Pile tab 能一锤定音。那里手牌有卡而屏幕上没有，就是表现层问题：UI 绑定、prefab、场景引用。那里也没有卡，就是卡组、数据库或抽牌配置坏了，调 UI 毫无意义。

---

卡打不出去

以下任意一条不满足，出牌就会被拒绝：

• 战斗不在 PlayerPhase（读 GCSApi.Phase 或 Monitor 的 Phase tab）。
• 这张卡其实不在手牌里。
• 经过 cost hook 计算后能量不够。
• 卡的 target mode 要求选中目标，而目标没选或已经死了。
• 有状态通过 Card Playable Hook 否决了出牌；演示里的 Silence 对 Skill 卡做的正是这件事。

如果不是某张卡被拒，而是整场战斗都像卡死了，改看 Monitor 的 Gate tab。它列出 animation gate 的持有者和 acquire/release 日志；一个从不释放的持有者会阻塞阶段推进，表面上看起来就像"卡牌失灵了"。

---

敌人什么都不做

确认敌人还活着、战斗确实进入了 EnemyPhase、敌人的行为图有敌人回合的入口、意图 pattern 节点配置齐全。Monitor 的 Flow tab 显示敌人回合执行了哪些图，Event tab 显示触发（Raise）了什么。

敌人亮出了意图却没有任何状态变化，说明图在入口之后出了问题：在 FlowGraph 编辑器里打开它的图，沿这个意图的链路一个节点一个节点跟下去。

---

状态或 UI 不更新

动手之前先把运行时状态和表现层分开：

1. 打开 Monitor 的 Unit tab，读 HP、护甲、状态和层数。
2. 状态变了而画面没变：问题在表现层。查 UI 绑定、状态图标、prefab。
3. 状态没变：问题在逻辑。在 Flow tab 里查图的执行情况，再查状态或卡牌图里的目标解析。

没确认运行时状态就去调 UI，两个方向都在浪费时间。Monitor 几秒钟就能给出答案。