Skip to main content

Common Symptoms

GCS · Troubleshooting

Symptom-first diagnosis: start from what is visibly wrong (no battle, no cards, a dead enemy turn) and follow the shortest check sequence to the owning system.

For anyone whose battle is misbehaving right now and wants the fastest route to the cause, not an architecture tour.

Most GCS problems surface as one of about ten visible failures, and each failure has a short, ordered check list. Start from the symptom, not from the code. The Game Card Monitor (Tools/TinyGiants/GCS/Game Card Monitor) is the main instrument here: it shows the live battle state, so it can tell you which side of the problem you are on before you open a single asset.

Game Card Monitor Battle tab showing a live battle: phase, turn, energy, units, and piles at a glance

Symptom map​

SymptomFirst checks
Battle does not startScene bootstrap, GameCardManager, database assignments, encounter reference
No cards appearStarting deck, deck contents, draw rules, hand UI references
Card cannot be playedBattle phase, energy, target mode, target validity, Card Playable Hook statuses
Card plays but nothing happensCard graph entry, node connections, target resolution
Enemy does nothingEnemy behavior graph, intent pattern, enemy phase reached
Status does not applyStatus database, status picker value, stack rule, target
Status never ticks downDecay Rule on the asset, trigger timing in the graph
UI does not updateRuntime state first (Monitor), presentation bindings second
Events do not arriveEvent name, subscription timing, payload type, disposal
Everything freezes mid-turnAnimation gate holder that never released (Monitor Gate tab)

Battle does not start​

Check in this order:

  1. The scene contains a GameCardEncounterBootstrap (or your own script that calls GCSApi.StartBattle).
  2. GameCardManager exists and has its databases assigned.
  3. The bootstrap's Default Encounter field points at a real encounter, and Auto Start On Play is enabled if the battle should begin immediately.
  4. The encounter has a player unit and at least one enemy unit.
  5. The player unit has a starting deck.
  6. The Workbench validation badge shows no blocking errors.
  7. After entering Play Mode, the Monitor Battle tab shows an active battle.

If the Monitor never sees a battle, the problem is scene setup or bootstrap. Card logic is not even running yet, so do not debug it.

No cards appear​

Confirm, in order: the player unit has a starting deck, the deck actually contains cards, the battle rules draw cards at battle or turn start, and the hand UI references in the scene are assigned. Then open the Monitor Pile tab.

The Pile tab answers the main question. Cards in hand there but an empty screen means a presentation problem: UI bindings, prefabs, scene references. No cards there either means the deck, database, or draw setup is broken, and no amount of UI work will help.

Game Card Monitor Pile tab showing the draw, hand, discard, and exhaust piles of the running battle

Card cannot be played​

A card play is refused when any of these fails:

  • The battle is not in PlayerPhase (read GCSApi.Phase or the Monitor Phase tab).
  • The card is not actually in hand.
  • Energy after cost hooks is insufficient.
  • The card's target mode expects a selected target and none (or a dead one) is selected.
  • A status vetoes the play through Card Playable Hook; the demo Silence status does exactly this to Skill cards.

If the whole battle feels stuck rather than one card being refused, check the Monitor Gate tab instead. It lists animation gate holders with their acquire and release log; a holder that never releases blocks phase progress and looks superficially like "cards stopped working".

Enemy does nothing​

Check that the enemy is alive, the battle actually reaches EnemyPhase, the enemy has a behavior graph with an enemy-turn entry, and its intent pattern nodes are configured. The Monitor Flow tab shows which graphs executed during the enemy turn; the Event tab shows what was raised.

An enemy that displays an intent but changes no state has a graph problem past the entry: open its graph in the FlowGraph editor and follow the intent's chain node by node.

Status or UI does not update​

Separate runtime state from presentation before touching anything:

  1. Open the Monitor Unit tab and read HP, armor, statuses, and stack counts.
  2. State changed but the screen did not: the problem is presentation. Inspect UI bindings, status icons, prefabs.
  3. State did not change: the problem is logic. Inspect the graph execution in the Flow tab and the target resolution in the status or card graph.

Debugging UI before confirming the runtime state wastes time in both directions. The Monitor answers the question in seconds.

On this page