Runtime overview
Understand how project actions enter GCSApi, become battle-state changes, and return to UI and presentation through events
From project action to battle feedback
The diagram above shows the complete GCS runtime path. The project uses GCSApi to start battles, play cards, end turns, or submit rewards. GameCardManager passes each request to the active battle, the state machine advances the flow, and the FlowGraph executor resolves rules. Once state changes, events and presentation requests deliver the result to UI, animation, VFX, and audio systems
This path defines gameplay state and the public interface without dictating the battle screen. A project can keep the bundled presentation components or replace the hand, HUD, unit views, and reward UI without rewriting card or status rules
Runtime component responsibilities
| Component | Main responsibility | Should project code depend on it directly? |
|---|---|---|
GCSApi | Start and control battles, read state, modify data safely, subscribe to events, and discover content | Yes. It is the preferred entry for project code |
GameCardManager | Store enabled databases, Run data, and the active battle | The scene requires one; direct calls are rarely needed |
BattleStateMachine | Advance phases, turns, enemy actions, waits, rewards, and win or loss flow | No. Control it through GCSApi |
BattleStateView | Store the current battle's units, cards, piles, energy, statuses, and variables | No. Read it through GCSApi.Battle or query methods |
GameCardFlowExecutor | Execute Card, Status, and Enemy Behaviors along their connections | No. Use it through FlowGraphs and execution context |
GCSEvents | Notify external systems about runtime changes that have already occurred | Use the subscription methods on GCSApi |
GameCardManager is the scene entry. When the scene has no usable Manager, GCSApi.IsReady is false; query methods return empty collections, 0, false, or null, and mutation methods do nothing. See installation and initialization and database management for scene and database setup
Read and modify the same battle state
GCSApi.Battle and GCSApi.Controller access the same battle with different permissions
| Entry | Use case |
|---|---|
GCSApi query methods | Read phase, turn, energy, units, piles, statuses, Intents, and wait state |
GCSApi.Battle | Read battle information that does not yet have a named GCSApi method |
GCSApi mutation methods | Deal damage, heal, gain Armor, change energy, or modify statuses and piles |
GCSApi.Controller | Access the broader runtime mutation surface from custom nodes or advanced integrations |
The collections returned by GCSApi.Battle, along with their UnitState and CardInstance objects, still point to live data rather than immutable snapshots. Project code may read them but should not modify fields or collections directly
Do not assign UnitState.CurrentHp or edit CardPile.Cards and UnitState.Statuses directly. These changes bypass Hooks, phase checks, events, Monitor records, and UI refreshes. Runtime mutations must go through GCSApi, supported IBattleController methods, or built-in FlowGraph nodes
See definitions and runtime instances for the boundary between authored data and live state
How FlowGraph participates in resolution
Card, Status, and Enemy Behaviors share the same FlowGraph execution rules. Each graph run receives the current behavior's source, holder, target, card, status, and battle data, allowing the same node to be reused across different content
| Node responsibility | Available capability |
|---|---|
| Read and calculate | Use IEvaluationContext to read context, port inputs, variables, and results from earlier nodes |
| Modify state | Call supported battle mutation methods through IExecutionContext.Controller |
| Control flow | Organize continuation with branches, loops, Choice, Wait, and Group |
| Publish results | Store resolved values on output ports for subsequent logic and presentation nodes |
Most users only need to connect nodes in the FlowGraph Editor. When authoring a custom node, use execution context and custom nodes
Waiting does not transfer state ownership
Choice, Wait, and Animation Gate can delay subsequent execution or a phase transition, but runtime continues to own the battle state
| Mechanism | What waits | Resume condition |
|---|---|---|
| Choice | Current Flow branch and pending phase transition | The player selects or skips, or the system takes the Skipped branch because no Presenter or candidates are available |
| Timed Wait | Remaining branch of the current Flow | The specified real-time duration elapses |
| Animation Wait | Remaining branch of the current Flow | The holder for the matching Gate is released, or the wait times out |
| Animation Gate | State-machine phase transition or enemy step | Presentation components call Acquire and Release as a pair |
| Reward Wait | Final battle-end notification after victory | The player applies or skips a reward |
FX nodes do not wait automatically for animation, particle, or audio playback. When order must be controlled, connect a Wait in the graph or hold an Animation Gate from a presentation coroutine. See Flow nodes for node parameters and battle lifecycle for their effect on phase advancement
Events and presentation requests deliver results
Runtime events tell external systems that a change has already happened. After receiving one, UI should read the current state again through GCSApi instead of retaining event arguments as a separate battle copy
Presentation requests play floating text, unit animation, VFX, SFX, or camera feedback. They reflect gameplay results that have already resolved and do not own HP, statuses, piles, or phase data. Gameplay continues when optional presentation assets are missing
See the event guide and custom UI integration for subscriptions and UI refresh patterns
Choose the next page by task
| Task | Continue with |
|---|---|
| Understand definitions, instances, and safe mutation boundaries | Definitions and runtime instances |
| Find the exact phase, turn, and reward sequence | Battle lifecycle |
| Understand the hand, draw pile, discard pile, and exhaust pile | Card and pile lifecycle |
| Understand status application, Hooks, decay, and expiration | Status lifecycle |
| Integrate UI, animation, VFX, audio, and Gates | Custom UI integration, FX nodes, and Flow nodes |
| Write battle-control code | API guide |
| Find the complete member and event argument reference | API reference and event reference |