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. If a Behavior is waiting on a Wait, Gate, or Choice, or a reward still needs to be submitted, resolve that wait first. Then confirm that the Holder is gone from Gate or that Choice or Reward is no longer Pending, and check for the next Phase record.

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

Subscribe before calling StartBattle if the object needs OnBattleStarted or opening-hand draw events. Follow the pattern in the event guide, then clear Event history and reproduce the action to verify the expected event, subscriber count, and callback count.

Runtime state is correct but the screen does not update

1. Confirm the change in Monitor, then find the view or effect that should respond to it.

2. Check the matching UI subscription, Prefab reference, card template, status icon, or FX node. If the presentation holds a Gate, release it on completion and cancellation. See Custom UI integration and FX nodes.

3. Repeat the state change and confirm the view updates once. Check the Gate tab for any remaining holder.

If a legacy scene shows health bars, statuses, or Intents in the wrong order after an upgrade, follow Repair legacy UI sorting.