Custom UI Integration

Guide

The runtime owns the truth: subscribe to events, read current state through GCSApi, and send player decisions back the same way

The snippets contain only the components that interact with GCS; place them in the project's presenter or MonoBehaviour, then add using System;, using System.Collections.Generic;, and using TinyGiants.GCS.Runtime; for the types the class uses

Integration checklist

Place and configure a GameCardManager
Start battles with GCSApi.StartBattle
Subscribe to runtime events in UI lifetime methods
Refresh UI from GCSApi after each event
Use GCSApi.CanPlayCard and GCSApi.TryPlayCard for card buttons
Use GCSApi.EndPlayerTurn for the end-turn button
Use GCSApi.ApplyReward or GCSApi.SkipReward for reward screens
Dispose every subscription
Keep demo-only view components optional

Subscription lifetime

Use a small disposable list per UI object

private readonly List<IDisposable> _subscriptions = new();

void OnEnable()
{
    _subscriptions.Add(GCSApi.OnBattleStarted(RefreshAll));
    _subscriptions.Add(GCSApi.OnEnergyChanged(_ => RefreshEnergy()));
    _subscriptions.Add(GCSApi.OnCardDrawn(_ => RefreshHand()));
    _subscriptions.Add(GCSApi.OnCardDiscarded(_ => RefreshHand()));
    _subscriptions.Add(GCSApi.OnCardExhausted(_ => RefreshHand()));
    _subscriptions.Add(GCSApi.OnUnitHpChanged(_ => RefreshUnits()));
    _subscriptions.Add(GCSApi.OnStatusChanged(_ => RefreshStatuses()));
}

void OnDisable()
{
    foreach (var subscription in _subscriptions)
    {
        subscription.Dispose();
    }
    _subscriptions.Clear();
}

Dispose each subscription when its GameObject is destroyed; stale listeners accumulate across reloads and are the most common source of doubled UI refreshes

Battle HUD

Refresh the high-level HUD fields from state:

Widget	Read
Phase label	`GCSApi.Phase`
Turn label	`GCSApi.TurnNumber`
Energy	`GCSApi.PlayerEnergy`, `GCSApi.MaxEnergy`
End turn button	`GCSApi.Phase == BattlePhase.PlayerPhase`
Battle result overlay	`OnBattleEnded` and `BattleEndedEventArgs.Won`

Read the phase from GCSApi.Phase and phase events; A graph can end the turn, grant an extra turn, open a choice, or finish the battle without a UI click

When your HUD disagrees with the game

Open Game Card Monitor:

Tools > TinyGiants > GCS > Game Card Monitor

Check the Battle tab; if the Monitor shows the correct battle state but the HUD does not, inspect the HUD event subscriptions and refresh path

Game Card Monitor on the Battle tab during a running fight, showing the same phase, turn, player, and enemy state a custom HUD should display

Hand UI

Rebuild or patch the hand from GCSApi.Hand(); it returns the live hand pile at call time, so cards drawn since the turn began are included

void RefreshHand()
{
    foreach (var card in GCSApi.Hand())
    {
        var active = GCSApi.GetActiveCard(card);
        var cost = GCSApi.GetEffectiveEnergyCost(card);
        var playable = GCSApi.CanPlayCard(card);
        RenderCard(card, active, cost, playable);
    }
}

For click handling:

void OnCardClicked(CardInstance card)
{
    var active = GCSApi.GetActiveCard(card);
    if (GCSApi.RequiresTarget(active))
    {
        OpenTargetPicker(card);
        return;
    }

    GCSApi.TryPlayCard(card);
}

When target selection completes:

void OnTargetSelected(CardInstance card, UnitState target)
{
    GCSApi.TryPlayCard(card, target);
}

Unit panels

Build unit panels from runtime units

Panel value	Read
HP	`GCSApi.Hp(unit)`, `GCSApi.MaxHp(unit)`
Armor	`GCSApi.Armor(unit)`
Alive/dead	`GCSApi.IsAlive(unit)`
HP percent	`GCSApi.HpPercent(unit)`
Statuses	`GCSApi.StatusesOn(unit)`
Enemy intents	`GCSApi.PendingIntents(enemy)`

Recommended refresh events:

OnUnitHpChanged
OnUnitDied
OnArmorGained
OnArmorLost
OnStatusChanged
OnStatusTicked
OnEnemyUnitIntentChanged
OnEnemyPhaseChanged

Status widgets

Status UI should read the full current map, not only the values in the event payload; use StatusChangedEventArgs.UnitId to locate which unit changed, then re-read everything on it

void RefreshStatusList(UnitState unit)
{
    foreach (var pair in GCSApi.StatusesOn(unit))
    {
        var status = pair.Key;
        var stacks = pair.Value;
        RenderStatus(status.Icon, status.DisplayName, stacks, status.ShowStackCount, status.IsDebuff);
    }
}

Enemy intents

Intent UI can show the current top intent or the full pending list

void RenderIntent(UnitState enemy)
{
    var tag = GCSApi.CurrentIntentTag(enemy);
    var value = GCSApi.CurrentIntentValue(enemy);
    var pending = GCSApi.PendingIntents(enemy);
    RenderIntentIcons(tag, value, pending);
}

Refresh when OnEnemyUnitIntentChanged fires and after enemy phase changes

Choice UI

When a Choice node asks the player to pick cards, units, or statuses, GCS raises OnEffectChoiceOffered

Payload field	Use
`PromptText`	Label for the choice panel
`Candidates`	Options to render
`AllowSkip`	Whether to show a skip button

The selection itself flows back through IChoicePresenter; your choice panel implements that interface, and the runtime hands it the prompt text, the candidates, minPicks and maxPicks so the panel can enforce how many options must be selected, and the onPicked and onSkipped callbacks; if no IChoicePresenter exists in the scene, choice nodes resolve as skipped; after the player picks, GCS raises OnEffectChoiceSelected; if the player skips, it raises OnEffectChoiceSkipped instead; disable normal card buttons while GCSApi.IsWaitingForChoice is true

Reward UI

After a won battle, GCS may raise OnBattleRewardOffered

private void ShowReward(BattleRewardOfferedEventArgs args)
{
    foreach (var card in args.CardCandidates)
    {
        RenderRewardCard(card);
    }
}

public void PickReward(GameCard card)
{
    GCSApi.ApplyReward(RewardChoice.Card, card);
}

public void SkipReward()
{
    GCSApi.SkipReward();
}

RewardChoice also offers Energy and Cost; pass null as the card for those; applying or skipping resolves the reward step and raises OnBattleEnded; use GCSApi.IsWaitingForReward to decide whether the reward controls should be visible

Floating text and presentation

For custom floating text, subscribe to FloatingTextSystem.Requested; the handler receives a FloatingTextRequest

void OnEnable()
{
    FloatingTextSystem.Requested += ShowFloatingText;
}

void OnDisable()
{
    FloatingTextSystem.Requested -= ShowFloatingText;
}

For unit visuals, either use the built-in UnitView or bind your own view model to the unit ids in event payloads; the demo HandController, CardView, and reward UI classes serve the sample scenes; production integrations should bind to runtime events and ids unless the project is intentionally modifying the demo

Refresh strategy

Strategy	Use when
Full rebuild	Hand, reward choices, and small status lists
Patch by id	Unit panels, intent widgets, floating text targets
Debounced refresh	Large custom combat logs or analytics panels
Immediate animation plus refresh	Damage, heal, armor, and card movement

A full refresh from GCSApi is usually cheap enough for the visible battle UI; optimize only after a real profile shows a problem

Common mistakes

Mistake	Better approach
Keeping a local copy of hand cards and mutating it manually	Rebuild from `GCSApi.Hand()` after card events
Enabling card buttons based only on energy	Use `GCSApi.CanPlayCard(card)`
Forgetting to unsubscribe	Store and dispose `IDisposable` handles
Treating an event payload as complete state	Use the payload to locate what changed, then read current state
Depending on demo UI classes in production UI	Depend on `GCSApi`, events, and your own view classes
Blocking gameplay because a VFX or SFX asset is missing	Let gameplay resolve and degrade presentation gracefully

Integration checklist​

Subscription lifetime​

Battle HUD​

Hand UI​

Unit panels​

Status widgets​

Enemy intents​

Choice UI​

Reward UI​

Floating text and presentation​

Refresh strategy​

Common mistakes​