Overview
GameCardSystem (GCS) is TinyGiants' visual card roguelike battle framework for Unity, covering the full workflow from content authoring to runtime. Its ScriptableObject-based Workbench modes let you build cards and battle content visually, while the built-in FlowGraph system can express classic card mechanics without requiring code. A complete low-level API remains available when your project needs deeper runtime integration or custom behavior.
The image above shows the complete visual authoring system behind the GCS card roguelike framework. Game Card Editor defines cards and battle content, FlowGraph Editor turns gameplay rules into executable Behaviors, Play Mode runs the battle, and Game Card Monitor verifies the result and traces problems. All four stages operate on the same content and runtime. A mechanic can be followed from its asset definition to its live presentation, then revised at the source with the runtime record in hand.
One workflow across authoring, runtime, and integration
A project enters this workflow at scene initialization. Once the runtime objects and content databases are ready, Battle Runtime executes the definitions from Game Card Editor and the rules from FlowGraph. Game Card Monitor brings state and execution records back to the relevant content and Behavior, while GCSApi and Events connect the same battle to the HUD, map, quests, save data, and other project systems.
The diagram connects content authoring, behavior design, battle execution, diagnosis, and project integration in one repeatable workflow. The editors establish content and rules, the runtime produces the result, Monitor traces that result back to its source, and the API and events carry it into the rest of the project. The table below shows the scope already covered by this workflow.
| Area | Included scale | Direct value to your project |
|---|---|---|
| Visual content authoring | 6 Game Card Editor modes | Create cards, decks, players, enemies, statuses, and encounters in one window |
| Visual gameplay authoring | 147 nodes and 103 classic mechanic recipes | Build card, status, and enemy behavior without a separate script for every asset |
| Runtime and project integration | 147 public GCSApi members and 43 built-in events | Read, control, and extend battles from custom UI and project code |
| Play Mode diagnosis | 7 Game Card Monitor tabs | Inspect live state, wait sources, Flow summaries, and event history in Play Mode |
| Included finished content | 12 playable battles, 80 cards, 16 enemies, and 30 statuses | Play the finished result, then open its source assets to study the implementation |
Build battle content from the scene foundation
Open Game Card System and click Initialize System. GCS creates or reuses the central GameCardManager, attaches GameCardEncounterBootstrap, adds the runtime objects and UI hierarchy for the battlefield, hand, and Canvas HUD, and registers the six bundled preset database types. The panel state below is the point at which content authoring can begin.
Once the Manager, six database types, and Bootstrap are ready, System Information also displays the Unity version, Editor platform, scripting backend, and render-pipeline support. Battle Scene Setup and Starting a Battle explain the responsibilities and startup relationship of these objects. After confirming the scene foundation, open Game Card Editor from Editor & Monitor to switch between its six Workbench modes.
All six Workbench modes use the same three-column interface. List manages databases and entries on the left, Inspector edits the selected definition in the center, and Preview shows the player-facing result and tracks references through Used By on the right. Drag sorting, cross-database copy and paste, inline renaming, Undo/Redo, smart dropdowns, reference pickers, and Validation apply across every mode, so one content type can lead directly into the next type that references it.
| Content | What you define in Game Card Editor | What it controls in battle |
|---|---|---|
| Cards | Name, description, cost, type, rarity, Target, tags, keywords, Upgrade, art, and Behavior | The actions a player can take, plus draw, retain, exhaust, upgrade, and cost rules |
| Decks | Card entries and copy counts | Starting builds, the Master Deck during a Run, and encounter reward pools |
| Player units | HP, energy, starting deck, Prefab, icon, and class tags | Player-side unit state, starting resources, and battle presentation |
| Enemies | HP range, tier, Prefab, Intent, and Behavior | Preview and execute actions for Normal, Elite, Boss, or summoned enemies |
| Statuses | Buff or Debuff identity, stacking, cap, decay, icon, and Behavior | Persistent effects, counters, rule changes, triggers, and turn timing |
| Encounters | Player, enemy lineup, reward deck, Intent display, and Battle Rules | Assemble existing content into a battle that can start, resolve victory or defeat, and grant rewards |
These six content types store names, values, art, and references as ScriptableObject sub-assets in their databases, while each asset's FlowGraph expresses its dynamic gameplay rules. When a battle starts, GCS uses those definitions to create isolated runtime data such as CardInstance, UnitState, and battle piles without changing the definition assets. Database Management explains how content is organized and activated, while Runtime Data Model covers definition assets, runtime instances, and safe mutation paths.
Content becomes a battle by following its real reference chain. Cards first define the face the player sees and the Behavior that runs during resolution. Decks then use card references and copy counts to assemble starting builds, the Master Deck for a Run, and encounter reward pools. The included Demo uses Basic, Support, Skill, Burst, and Curse templates to cover different kinds of battle actions.
The five cards shown here come from the 80 finished cards included with the Demo: 6 Basic, 20 Support, 40 Skill, 12 Burst, and 2 Curse cards. Strike and Defend each include a three-level upgrade chain. Card Authoring explains how face fields, cost, targeting, and Behavior define one card, while Deck Authoring assembles those cards into 12 class starting decks and 4 reward decks. The same card definition can be reused across multiple decks.
Once the cards and decks exist, a player unit brings its starting deck, HP, energy, class tags, Prefab, and preview art into battle. The Demo provides Novice, Veteran, and Master ranks for the Warrior, Mage, Hunter, and Priest class lines.
Each class line has its own card build, character presentation, and three battles of increasing difficulty, for 12 reusable player units in total. Once the player side is defined, enemies use Intent to preview their next action on the other side of the battlefield, then execute its rules through Behavior.
The Demo's 16 enemies are organized across four class themes, each with a Normal, Elite, Boss, and Summon enemy. Together they cover attacks, defense, buffs, debuffs, healing, special abilities, multi-step actions, weighted behavior, phase changes, and summoning. Target Selection resolves Self, Opponent, All, set filtering, sorting, random selection, and player choice into concrete units for both player cards and enemy behavior, so both sides use the same targeting semantics.
Once players and enemies are on the battlefield, statuses continue to change damage, armor, energy, costs, card draw, turns, and unit behavior as the battle advances. A status can store stacks that the player can see and use its Behavior to respond to Hooks, lifecycle changes, and other battle timing.
The 30 bundled statuses consist of 15 Buffs and 15 Debuffs covering damage over time, stat modifiers, vulnerability, weakness, shields, retaliation, lifesteal, control, loss-of-life prevention, decay, and global rule changes. Open any status through Status Authoring to inspect its stacking rules, FlowGraph, and references. Encounter Authoring then combines a player, enemy lineup, reward deck, and Battle Rules into a battle that can start, resolve victory or defeat, and grant rewards.
Turn content definitions into gameplay with FlowGraph
With the battle objects and their references defined in Game Card Editor, FlowGraph Editor carries those definitions into behavior authoring, organizing card resolution, status responses, and enemy actions into executable Behaviors.
The image above places Card, Status, and Enemy Behaviors beside a collapsible Group subgraph. Cards resolve from card-play or other lifecycle entries, statuses modify rules through Hooks and battle timing, enemies select and execute actions through intent patterns, and Group contains an already connected mechanism as a collapsible subgraph.
These graphs share the same nodes, ports, and execution context. Control connections define order, branches, loops, choices, waits, and Gates, while data connections carry units, cards, sets, event arguments, and calculated values to the next node. A field can keep a fixed value or become a port that accepts runtime input. FlowGraph Model explains the relationship between graphs, nodes, ports, context, and execution order.
The core assembly provides 145 nodes. Loading the Demo assembly registers 2 more FX nodes, bringing the complete node library to 147.
| Node family | Count | What it can do |
|---|---|---|
| Entry | 33 | Start behavior from battle, turn, card, unit, status, energy, or event timing |
| Hook | 18 | Modify or cancel damage, armor, healing, energy, draw, cost, and playability results before commit |
| Action | 27 | Modify HP, armor, energy, cards, piles, statuses, variables, turns, and units |
| Operator | 22 | Compare, calculate, filter, sort, select, combine, and convert data |
| Get | 19 | Read units, cards, piles, statuses, battle values, variables, and event arguments |
| Flow | 10 | Organize branches, loops, sequences, player choices, Switches, waits, and Gates |
| FX | 7 + 2 Demo | Play VFX, SFX, animations, floating text, unit movement, flashes, and camera feedback |
| Intent | 6 | Build enemy intent leaves, sequences, random patterns, and HP-threshold patterns |
| Event | 2 | Raise internal GCS events or optional GES events |
| Group | 1 | Organize a complex graph as a collapsible visual group |
Group only organizes the canvas and contains an already connected subgraph. Its child nodes retain their real connections and execution order, so grouping does not change runtime behavior. The remaining nodes cover multi-hit attacks, X-cost cards, discover, replay, pile search and sorting, equipment durability, multi-phase bosses, summoning and revival, cross-graph events, delayed resolution, player choice, and presentation waits. Node Library provides the complete lookup entry point, while three recipe libraries document 103 mechanics you can build directly.
| Mechanic you want to build | Open this reference |
|---|---|
| Damage, armor, X-cost, draw and discard, discover, replay, transform, stance, cost, and card lifecycle | 52 card recipes |
| Poison, burn, strength, vulnerable, thorns, barricade, silence, revival, equipment, and global rules | 30 status recipes |
| Intent sequences, weighted random behavior, boss phases, summoning, splitting, escape, deck disruption, and cross-system events | 21 enemy recipes |
Once the nodes and recipes express the rules, Battle Runtime executes the same Behaviors in Play Mode and turns them into battle results that can be observed and verified directly.
Battle Runtime turns rules into verifiable results
When the player attempts to play a card from hand, the runtime checks the current phase, hand ownership, cost, play Hooks, Unplayable, and playability Hooks before resolving the target and executing the card FlowGraph. Damage, armor, and status application pass through their corresponding Hooks, and the card moves to Discard or Exhaust according to its keywords. If VFX, SFX, animation, or floating text issued by presentation nodes must block execution, a Wait node or a coroutine registered with Animation Gate holds the flow until that work finishes. The battle state machine then continues through enemy turns, dynamic summons, player choices, reward waits, and victory or defeat. The Hunter battle below shows the result maintained by these systems together.
The player and three enemy HP values, current hand and costs, remaining energy, draw and discard counts, enemy intents, and current turn each come from a different runtime system working on the same battle. The table below follows these visible results back to the responsible system and its detailed documentation.
| Runtime system | What it handles | Read next |
|---|---|---|
| Battle lifecycle | Battle Start, player turns, enemy phases, victory, defeat, selection waits, and reward waits | Battle Loop, Battle State Machine |
| Cards and piles | Draw, Hand, Discard, Exhaust, and the Master Deck retained between battles | Cards, Hand, and Deck |
| Target selection | Self, opponents, all units, set filtering, sorting, random targets, player choice, and no-valid-target handling | Target Selection |
| Statuses and Hooks | Stacking, caps, decay, source attribution, active Behavior, and 18 Hook nodes | Status System, Hook Nodes |
| Enemy battlefield | Intent preview, skipped turns, dynamic summoning, removal, death, revival, and multi-phase bosses | Enemy Authoring, Enemy Recipes |
| Presentation and waits | CardView pooling, drag-to-play, targeting arrows, status UI, choice and reward panels, VFX, SFX, animation, and Animation Gate | Presentation Layer, Custom UI |
| Scene and startup | Manager, Encounter Bootstrap, Battle Board, Hand, Canvas, HUD, and Presentation roots | Battle Scenes, Starting a Battle |
When these visible results do not match the authored rules, an HP discrepancy or an animation that has not finished cannot identify the failing step by itself. Game Card Monitor separates the current state and execution process into records you can inspect one by one.
Game Card Monitor connects live state to execution records
If a card deals 2 less damage than expected, an enemy does not advance to its next intent, or the battle is still waiting after an animation ends, you can reconstruct the sequence through the phase, piles, unit state, Animation Gate, FlowGraph execution summary, and event timeline. Seven live tabs keep that evidence in one window.
During diagnosis, start with Battle, Pile, and Unit to confirm the current result, then use Phase to reconstruct state transitions. Finally, follow Gate wait sources, the Flow execution summary, and Event ordering until the problem resolves to specific data or a specific Behavior. Each tab covers the following scope.
| Tab | What you can inspect |
|---|---|
| Battle | Current encounter, turn, faction, player, and enemy summary |
| Pile | Cards in Hand, Draw, Discard, Exhaust, and the Master Deck |
| Unit | HP, armor, energy, statuses, intent pattern, and live unit data |
| Phase | Current phase, turn, selection wait state, and phase transition history |
| Gate | Animation Gate Holder count, Timeout, hold reasons, and recent Acquire/Release records |
| Flow | FlowGraph Host, trigger timing, visited node count, and synchronous execution time |
| Event | GCS event timeline, payload summaries, and Dispatcher subscriber counts |
Game Card Monitor documents every field and the symptom-based inspection order. For failed startup, rejected card plays, missing events, or mechanics that resolve without updating the screen, continue with Common Symptoms, Authoring Errors, or Runtime Errors. Once the runtime can be traced from end to end, project code can join the battle through the same state, mutation, and event paths.
Integrate your project and extend GCS through GCSApi
When the HUD, map, quests, save data, or other project systems need to read or drive the same battle, GCSApi is the single code-facing entry point. Battle queries read the authoritative BattleState, while content queries read the databases currently enabled on GameCardManager. Project code applies changes through Controller, and built-in or custom Mutator nodes use the same state mutation path. Each operation then raises the corresponding Hooks and events and refreshes presentation where required.
| API area | Members | What it can do |
|---|---|---|
| Manager and battle lifecycle | 13 | Check readiness, start or release a battle, play cards, end turns, and handle rewards |
| Live battle state and queries | 38 | Read phase, units, HP, armor, intents, piles, costs, statuses, and formatted descriptions |
| Battle mutation | 24 | Deal damage, change HP, armor, and energy, draw and move cards, apply statuses, summon enemies, and read or write variables |
| Content discovery and runtime deck | 24 | Enumerate active databases and content, find assets by GUID, and manage the Master Deck retained between battles |
| Event subscription | 44 | Use generic subscriptions or strongly typed entry points for turns, cards, damage, armor, energy, statuses, piles, rewards, choices, and phases |
| Extension registries | 4 | Discover FlowGraph nodes, card types, card tags, and description Tokens |
The smallest integration only needs this one entry point to start a battle, attempt to play a card, and end the player's turn.
using TinyGiants.GCS.Runtime;
GCSApi.StartBattle(encounter);
bool played = GCSApi.TryPlayCard(card, target);
GCSApi.EndPlayerTurn();
- These three calls enter the same runtime path as visually authored content. GCSApi Guide follows the real integration order through startup, turn control, UI queries, safe mutation, event subscription, and the Master Deck
- API Reference lists the signatures, return values, null contracts, and runtime conditions for all 147 public members
- The 43 built-in events cover battle and turn flow, card lifecycle, HP, armor, damage, energy, statuses, enemies, delayed triggers, rewards, and player choices. Of those events, 42 have strongly typed
On*shortcuts, and every event also supports name-based subscription - Event Guide explains subscription and lifecycle, while Event Reference gives the payload and exact trigger timing for every event
When a project needs a mechanic beyond the built-in set, extensions continue to use the same node discovery, port inference, execution context, content classification, and event paths.
| Extension point | Use it when | Documentation |
|---|---|---|
| Custom FlowGraph node | Add a new gameplay action, data source, selector, rule operation, or presentation request | Custom Nodes |
| Automatic and explicit ports | Promote fields to inputs or declare data outputs, dropdown choices, and dynamic control branches | Custom Ports |
| Execution context | Read connected inputs, resolve units and cards, mutate state through Controller, store results, and access variables | Execution Context |
| Card types, tags, and description Tokens | Add project-specific classifications, filtering dimensions, and dynamic card text | Types, Tags, and Tokens |
| Copyable samples | Start from the template, conditional-heal node, and two-input operator node | Extension Samples |
- Four reflection registries automatically discover attributed FlowGraph nodes, card types, card tags, and description Tokens, so you do not maintain a manual registration list
- Custom nodes appear in the existing Add Node menu. Automatically inferred and explicitly declared ports both read from the same execution context, while state mutation continues through
Controller - Description Tokens format node results and project data as card text. The core assembly includes 21 Tokens and the Demo adds 4, for 25 total, so card text can use runtime values without duplicating their calculations
These extensions still run inside the GCS battle path. When events must cross plugin boundaries, install GameEventSystem and use Raise GES Event and On GES Event from Optional GES Integration to create a two-way channel. If the GES runtime is not present, the bridge code remains disabled while GCS battles and internal events continue to run independently. The included Demo is a finished, inspectable project built with this same production toolchain and runtime.
The included Demo is a finished project you can inspect
Warrior, Mage, Hunter, and Priest each have Normal, Elite, and Boss battles, for 12 scenes you can enter directly in Play Mode. Every scene already connects the hand, energy, target selection, enemy intents, status HUD, rewards, result screens, and their presentation. All of this content uses the same Game Card Editor, FlowGraph, runtime API, and extension system as a production project. The complete scale is listed below.
| Demo content | Count | Composition |
|---|---|---|
| Playable scenes | 12 | Four classes × Normal, Elite, and Boss |
| Encounter definitions | 12 | Four classes × Normal, Elite, and Boss |
| Player units | 12 | Four classes × Novice, Veteran, and Master |
| Enemies | 16 | Four classes × Normal, Elite, Boss, and Summon |
| Cards | 80 | 6 Basic, 20 Support, 40 Skill, 12 Burst, and 2 Curse |
| Decks | 16 | 12 class starting decks and 4 reward decks |
| Statuses | 30 | 15 Buffs and 15 Debuffs |
Open any card, status, or enemy in Game Card Editor to inspect its fields, FlowGraph, and references. You can also inspect each encounter's player, enemy lineup, reward deck, and Battle Rules in the same window, then enter the matching scene to verify the result in Play Mode.
Demo Overview lists every count and the six preset database types, while Battle Scenes shows the lineups and live results for all 12 battles. Use Content Reference and Asset Layout when you need to locate an individual asset or confirm its ownership. This content can be run directly and also demonstrates the engineering foundation provided for production projects.
Engineering foundations for production projects
Whether the complete workflow can move into a production project also depends on version and dependency boundaries, data references, authoring safeguards, runtime consistency, and diagnosis. The table below shows the foundation GCS already provides in each area.
| Engineering area | Foundation provided by GCS |
|---|---|
| Unity and render pipelines | Supports Unity 2021.3 LTS and newer, including Unity 6. The Demo uses pipeline-independent Shaders and Materials and supports both the Built-in Render Pipeline and URP |
| Runtime dependencies | The GCS runtime has zero third-party dependencies. TinyGiants' own TGTween drives built-in transitions and procedural animation, and presentation nodes can also trigger Unity Animator |
| Content stability | ScriptableObject sub-assets store content definitions, Unity object references connect content, Active Database controls runtime availability explicitly, and GUIDs support content lookup |
| Authoring safeguards | Game Card Editor provides Undo/Redo, Validation, Used By, and cross-database copying. Validation in Game Card Editor and FlowGraph Editor checks entries, connections, and Host constraints |
| Runtime consistency | Controller owns state mutation, Hooks can modify or cancel results before commit, events broadcast changes to subscribers, and Animation Gate waits for registered presentation work |
| Diagnosis | Game Card Monitor shows live Battle, Pile, and Unit snapshots and records Phase, Gate, Flow, and Event history in Play Mode |
Installation and Requirements covers supported versions, render pipelines, and the first-scene checklist. Runtime Data Model explains definitions, instances, and safe mutation paths. Presentation Layer defines the boundary between UI, VFX, audio, animation, and gameplay state. From here, continue directly to the documentation that matches the current task.
Choose your next step
Start by running a finished battle to see the complete result, or move directly into authoring content, integrating project code, or extending GCS.
| What you want to do | Start here |
|---|---|
| Play a finished battle first | Run Your First Demo Battle |
| Build your own cards, enemies, and encounter from scratch | Build the Second Battle |
| Understand how content, behavior, and runtime work together | Database Management, FlowGraph Model, Battle Loop, Runtime Data Model |
| Start authoring content | Cards, Decks, Players, Enemies, Statuses, Encounters |
| Find a node or finished mechanic | Node Library, Card Recipes, Status Recipes, Enemy Recipes |
| Integrate custom UI and project code | GCSApi Guide, Custom UI, Event Guide |
| Extend nodes, ports, or content types | Custom Nodes, Custom Ports, Execution Context |
| Diagnose authoring or runtime problems | Common Symptoms, Authoring Errors, Runtime Errors |