Runtime issues

🧯

Guide

Start from current state and execution records in the Monitor to locate a failure in startup, phase, Behavior, waits, events, or presentation

Battle does not start

When no battle appears after entering Play Mode, check the four startup requirements:

• The scene contains an enabled GameCardManager

• A fixed-scene Bootstrap has a Default Encounter and Auto Start On Play enabled, or project code actually calls GCSApi.StartBattle

• The Encounter contains a valid Player and at least one Enemy

• The Manager registers every database the battle must resolve actively

When Monitor Battle shows No active battle, it confirms only that no battle can currently be read. Continue with the first GCS error in Console and its complete stack trace; later errors may be consequences of the same failure

tip

After the fix, enter Play Mode again and confirm that Battle shows the Encounter, player, enemies, and current Phase, with an OnBattleStarted record

Operation is not accepted

When a card cannot be played or End Turn does not respond, check the state required for the operation:

• Is Phase equal to PlayerPhase?

• Is the card still in Hand, and is its effective cost no greater than player energy?

• For Single Enemy, is the selected target alive and valid?

• Did Card Playable Hook cancel the play?

• Is the battle waiting for a Choice or Reward?

tip

• Project UI should use GCSApi.CanPlayCard(card) to update button state and inspect the return value of TryPlayCard. Do not decide playability from the displayed cost alone
• After the fix, repeat the same operation, confirm that the API succeeds, and verify the matching hand, energy, phase, or wait-state change in the Monitor

Card resolution is incorrect

When a card has left the hand but its damage, status, or pile result is wrong:

1. In Flow, confirm that the correct Card Owner and Entry executed
2. In Unit, inspect HP, Armor, and status stacks
3. In Pile, confirm whether the card entered Discard or Exhaust
4. Inspect Exhaust, Retain, Ethereal, Unplayable, and the Encounter's Hand Discard rule
5. Check whether cost, damage, Armor, or status Hooks changed or cancelled the result

warning

• Custom nodes must modify battle state through ctx.Controller. Direct field writes bypass events, Hooks, and Monitor records, leaving UI and runtime state out of sync

• After the fix, replay the same card. Its execution path in Flow should agree with the final Unit and Pile state

Flow stops progressing

First identify the last phase transition in Phase, then inspect the active wait type:

Wait type	Evidence	Fix
Gate	Gate contains a Reason with Acquire but no Release	Release the same Holder from success, failure, and cancellation paths in the presentation flow
Choice	Battle or Phase shows Choice Pending	Keep one usable IChoicePresenter in the scene and submit a selection or Skip
Reward	GCSApi.IsWaitingForReward is true	Submit one ApplyReward or SkipReward from the reward UI
Wait	Flow entered an explicit Wait path	Check the duration and object lifecycle

tip

Regular VFX, SFX, and animation do not block a phase automatically. GCS remains waiting only when a Behavior explicitly uses Wait, Gate, or Choice, or when the reward flow awaits submission

After releasing the wait, confirm that Gate no longer retains the Holder, Choice or Reward is no longer Pending, and the next Phase record appears

Event listener does not respond

Open the Monitor's Event tab before reproducing the issue, then diagnose it from the record:

• No event record: confirm that the gameplay timing occurred and retry after clearing Filter

• The event is recorded with subs 0: no subscriber existed at broadcast time; inspect subscription timing

• Subscribers are present but the target UI does not respond: inspect the event name, Payload type, callback object, and callback logic

• The callback runs more than once: inspect duplicate subscriptions and undisposed IDisposable handles

An object that needs OnBattleStarted or opening-hand draw events must subscribe before StartBattle is called. See the event guide for the complete pattern

After the fix, clear Event history and trigger the timing once more. The expected event, subscriber count, and callback count should agree

Runtime state is correct but the screen does not update

1. When the Monitor records the correct HP, Armor, status, pile, or Phase change but the health bar, card face, unit, VFX, or audio does not respond, the gameplay state has been written and the fault is in presentation binding

2. Continue with UI subscriptions, Prefab references, Card Template, Status Icon, FlowGraph FX nodes, and scene Presentation components. If the presentation flow holds a Gate, confirm that both completion and cancellation paths release it. See custom UI integration for UI binding and FX nodes for node behavior

3. After the fix, use the same state change in the Monitor as the baseline and confirm that the screen updates once with no Gate left behind