Skip to main content

GCSApi Reference

GCS · API

Every public GCSApi member, grouped the way the facade itself is: control, reads, mutation, content, events.

Keep this page open while wiring custom UI, scene flow, save systems, or debug tooling to GCS through code.

This page lists every public member of the GCSApi static facade. Each member sits in its own collapsible block with the exact signature, what it returns, and how it behaves when no battle is running. Use the surface map below to jump straight to the member you need.

Namespace

All members on this page live on TinyGiants.GCS.Runtime.GCSApi.

using TinyGiants.GCS.Runtime;

The facade contract​

GCSApi is a thin static wrapper. Every member forwards to the runtime owner that actually holds the state: the GameCardManager singleton, the read-only IBattleState, the writable IBattleController, or the core event channel. The facade stores nothing itself.

Three rules hold across the whole surface:

  • Call from the Unity main thread.
  • A battle exists only between StartBattle and DisposeBattle (or the next StartBattle). Outside that window, collection accessors return empty lists, value accessors return safe defaults (0, false, BattlePhase.None), and mutation helpers do nothing. The one exception is CurrentHand, which returns null outside battle by design.
  • Object accessors (Manager, Battle, Controller, Player(), FirstAliveEnemy()) return null when their target does not exist, so guard those with IsReady or a null check.

Surface map​

Access points: Manager, IsReady, Battle, Controller, Events

Lifecycle: StartBattle, TryPlayCard, CanPlayCard, RequiresTarget, EndPlayerTurn, ApplyReward, SkipReward, DisposeBattle

Manager and channels​

Manager
public static GameCardManager Manager { get; }

The active GameCardManager singleton, or null when no manager has been loaded into a scene yet. The manager owns run-level state (master deck, run bonuses) and the active battle.

Most facade members turn into no-ops or safe defaults while this is null, so you rarely need to read it directly. Use IsReady as the readable guard, and prefer the named helpers below over reaching into manager internals.

IsReady
public static bool IsReady { get; }

Returns: true when a GameCardManager is present and ready to receive calls.

if (!GCSApi.IsReady)
{
    return;
}
Battle
public static IBattleState Battle { get; }

Returns: The read-only view of the current battle, or null when no battle is active.

Use it for low-level reads when no convenience accessor exists on the facade. For writes, use the typed helpers under Battle mutation or Controller.

Controller
public static IBattleController Controller { get; }

Returns: The write surface of the current battle, or null when no battle is active.

This is the full mutation interface the effect executor uses internally. Mutations applied here take effect immediately on the authoritative battle state and broadcast the same events the built-in nodes do, so presentation stays in sync.

Mutation boundary

The typed helpers under Battle mutation cover the common operations with null-safety built in. Reach for Controller only when you need an operation those helpers do not expose.

Events
public static IGCSEventChannel Events { get; }

Returns: The core GCS event channel.

Prefer the strongly typed On* methods under the event shortcuts for the built-in events. Use the channel directly only for custom event names or bulk operations.

Battle control​

StartBattle
public static void StartBattle(GameEncounter encounter);

Argument: encounter defines the battle: player unit, enemy line-up, reward pool, and rules. A null encounter is ignored.

Effect: Starts a new battle, seeding the draw pile from the persistent master deck. Any battle already in progress is disposed first. The opening hand is drawn and OnBattleStarted is raised before this method returns, and enemy intents are resolved for the first turn. If the scene has no IChoicePresenter, choice nodes in card effects resolve as skipped.

public GameEncounter Encounter;

public void BeginEncounter()
{
    if (GCSApi.IsReady)
    {
        GCSApi.StartBattle(Encounter);
    }
}
TryPlayCard
public static bool TryPlayCard(CardInstance card, UnitState target = null);

Arguments:

  • card: the hand card instance to play.
  • target: the target unit for cards whose target mode is single enemy. Pass null for everything else; the engine resolves targets for self, all-enemy, and untargeted cards automatically.

Returns: true when the card was accepted and played; false when it was rejected (no active battle, card not in hand, not enough energy, the card is unplayable, or a play hook cancelled it).

if (GCSApi.CanPlayCard(card))
{
    GCSApi.TryPlayCard(card, selectedEnemy);
}
CanPlayCard
public static bool CanPlayCard(CardInstance card);

Returns: true when the play would be allowed to proceed: the battle is in PlayerPhase, the card is not marked Unplayable, and the player's energy covers the card's effective cost. It does not play the card.

Use it to drive enabled and disabled states on card buttons before the player clicks.

RequiresTarget
public static bool RequiresTarget(GameCard card);

Returns: true only for cards whose target mode is single enemy. Self, all-enemy, and untargeted cards return false because the engine picks their targets automatically.

var activeCard = GCSApi.GetActiveCard(cardInstance);

if (GCSApi.RequiresTarget(activeCard))
{
    OpenTargetPicker(cardInstance);
}
else
{
    GCSApi.TryPlayCard(cardInstance);
}
EndPlayerTurn
public static void EndPlayerTurn();

Effect: Ends the player's turn and advances to the enemy phase. Has no effect outside PlayerPhase.

ApplyReward
public static void ApplyReward(RewardChoice choice, GameCard pickedCard);

Arguments:

  • choice: the selected reward kind (card, energy, or cost discount).
  • pickedCard: the chosen card when choice is RewardChoice.Card; otherwise null.

Effect: Applies the player's pick for the post-battle reward currently offered via OnBattleRewardOffered, resolves the reward step, and raises OnBattleEnded. Call it from a custom reward screen.

SkipReward
public static void SkipReward();

Effect: Declines the post-battle reward currently offered, ending the battle. Wire it to the skip button on a reward UI.

DisposeBattle
public static void DisposeBattle();

Effect: Tears down the active battle state machine and clears the live battle. The persistent master deck and run bonuses are unaffected; only the in-progress battle is discarded.

Call it when leaving a battle scene without playing to completion, or when resetting a test.

Battle status​

Phase
public static BattlePhase Phase { get; }

Returns: The current battle phase, or BattlePhase.None when no battle is active.

IsBattleActive
public static bool IsBattleActive { get; }

Returns: true while a battle is in progress: started and not yet won or lost.

IsBattleOver
public static bool IsBattleOver { get; }

Returns: true when the current battle has concluded, in BattleWon or BattleLost.

IsWaitingForChoice
public static bool IsWaitingForChoice { get; }

Returns: true while the battle is paused for the player to resolve a card-effect choice (see OnEffectChoiceOffered).

IsWaitingForReward
public static bool IsWaitingForReward { get; }

Returns: true while the battle is paused for the player to resolve a post-battle reward (see OnBattleRewardOffered).

TurnNumber
public static int TurnNumber { get; }

Returns: The current battle turn number, 1-based; 0 when no battle is active.

IsPlayerTurn
public static bool IsPlayerTurn { get; }

Returns: true while it is the player's turn, as opposed to the enemy phase.

Player, units, and energy​

Player
public static UnitState Player();

Returns: The player unit in the current battle, or null when no battle is active.

PlayerEnergy
public static int PlayerEnergy { get; }

Returns: The player's current energy, or 0 when no battle is active.

MaxEnergy
public static int MaxEnergy { get; }

Returns: The player's per-turn maximum energy, including run bonuses and per-turn energy hooks; 0 when no battle is active.

AliveEnemies
public static IReadOnlyList<UnitState> AliveEnemies();

Returns: The living enemy units in the current battle. Never null.

FirstAliveEnemy
public static UnitState FirstAliveEnemy();

Returns: The first living enemy unit, or null when none remain. A convenient default target.

EnemyCount
public static int EnemyCount();

Returns: The number of living enemy units in the current battle.

AllUnits
public static IReadOnlyList<UnitState> AllUnits();

Returns: Every living unit in the current battle, the player followed by all living enemies. Never null.

Allocates a fresh list per call, so cache the result if you read it every frame.

Hp
public static int Hp(UnitState unit);

Returns: The unit's current hit points, or 0 for a null unit.

MaxHp
public static int MaxHp(UnitState unit);

Returns: The unit's maximum hit points, or 0 for a null unit.

Armor
public static int Armor(UnitState unit);

Returns: The unit's current armor (block), or 0 for a null unit.

HpPercent
public static int HpPercent(UnitState unit);

Returns: The unit's hit points as an integer percentage of its maximum, 0 to 100; 0 for a null unit.

IsDead
public static bool IsDead(UnitState unit);

Returns: true when the unit is dead. A null unit is treated as dead.

IsAlive
public static bool IsAlive(UnitState unit);

Returns: true for a non-null unit with hit points remaining.

Enemy intents​

CurrentIntentTag
public static IntentTag CurrentIntentTag(UnitState enemy);

Returns: The category of the enemy's planned action for its next turn (attack, defend, buff, debuff, and so on). Returns IntentTag.Unknown for null or non-enemy units.

CurrentIntentValue
public static int CurrentIntentValue(UnitState enemy);

Returns: The number the enemy's planned action displays, such as incoming damage or block. Returns -1 when there is no number to show: non-value intents, hidden intents, or non-enemy units.

PendingIntents
public static IReadOnlyList<IntentEntry> PendingIntents(UnitState enemy);

Returns: The full list of intent entries the enemy plans for its next turn (an enemy may telegraph several actions), as raw resolved intents. Never null.

The encounter's intent display mode is not applied here; that shaping only affects the OnEnemyUnitIntentChanged event payload. Read this method when you need the true plan, and the event payload when you need what the player is meant to see.

Card piles and card queries​

CurrentHand
public static IReadOnlyList<CardInstance> CurrentHand { get; }

Returns: The cards currently in the player's hand, or null when no battle is active.

Equivalent to Hand() except for the out-of-battle value: this property returns null where Hand() returns an empty list, matching GameCardManager.CurrentHand.

Hand
public static IReadOnlyList<CardInstance> Hand();

Returns: The player's current hand pile. Never null.

DrawPile
public static IReadOnlyList<CardInstance> DrawPile();

Returns: The player's current draw pile. Never null. The top of the pile is the last element, so the next card to draw is DrawPile()[DrawPile().Count - 1].

DiscardPile
public static IReadOnlyList<CardInstance> DiscardPile();

Returns: The player's current discard pile. Never null.

ExhaustPile
public static IReadOnlyList<CardInstance> ExhaustPile();

Returns: The player's current exhaust pile. Never null.

PlayedThisTurn
public static IReadOnlyList<CardInstance> PlayedThisTurn();

Returns: The card instances played during the current turn, in play order. Never null.

DrawnThisTurn
public static IReadOnlyList<CardInstance> DrawnThisTurn();

Returns: The card instances drawn during the current turn, in draw order. Never null.

GetEffectiveEnergyCost
public static int GetEffectiveEnergyCost(CardInstance card);

Returns: The card instance's battle-adjusted energy cost, accounting for per-card modifiers, run-level cost deltas, and play-cost hooks. Returns 0 for a null card or when no battle is active.

This is the number your cost badge should display, not the base cost on the card asset.

GetActiveCard
public static GameCard GetActiveCard(CardInstance card);

Returns: The effective card definition behind an instance: the upgraded form when the instance is upgraded, otherwise the base card. Returns null for a null instance.

IsUpgraded
public static bool IsUpgraded(CardInstance card);

Returns: true when the card instance is currently in its upgraded form.

FormatDescription
public static string FormatDescription(GameCard card, CardInstance instance = null);

Arguments:

  • card: the card whose description text to format.
  • instance: the optional live instance, so instance-specific values (upgrade state, cost delta) resolve. Pass null to format the base definition.

Returns: The description with tokens such as {Damage} or {Stacks:Poison} resolved into final display text; an empty string for a null card.

Tokens resolve through the DescriptionTokenRegistry, so any custom IDescriptionToken you register participates automatically. Use this when custom card views need the same resolved text as GCS-powered UI.

Status queries​

GetStatusStacks
public static int GetStatusStacks(UnitState unit, GameStatus status);

Returns: The stack count of the status on the unit; 0 when the unit lacks the status or is null.

HasStatus
public static bool HasStatus(UnitState unit, GameStatus status, int minStacks = 1);

Returns: true when the unit holds at least minStacks of the status. minStacks defaults to 1.

GetStatusApplier
public static UnitState GetStatusApplier(UnitState unit, GameStatus status);

Returns: The unit that originally applied the status, or null when unknown. Useful for retaliation effects that hit the source.

StatusesOn
public static IReadOnlyDictionary<GameStatus, int> StatusesOn(UnitState unit);

Returns: Every status currently on the unit mapped to its stack count. Never null.

The returned view is a live read of the unit's status table; treat it as read-only and do not cache it across mutations.

Battle mutation​

Controller-backed operations

Every helper below forwards to the active battle controller and does nothing when no battle is running. They run the same rules and raise the same events as the built-in FlowGraph nodes, so use them instead of editing runtime state fields directly.

DealDamage
public static void DealDamage(UnitState target, int amount, UnitState attacker = null, bool bypassArmor = false);

Arguments:

  • target: the unit to damage.
  • amount: the raw damage before mitigation.
  • attacker: the unit credited as the attacker, enabling on-deal-damage hooks and kill credit. Pass null for unattributed damage.
  • bypassArmor: when true, the damage ignores armor and reduces hit points directly.

Effect: Deals damage through the full pipeline: armor absorption, damage-modifying hooks (Vulnerable, Weak, Strength), death checks, and reactive triggers such as Thorns. Mirrors what a Deal Damage node performs.

GCSApi.DealDamage(GCSApi.FirstAliveEnemy(), 8, GCSApi.Player());
LoseHp
public static void LoseHp(UnitState target, int amount);

Effect: Reduces the unit's hit points directly, ignoring armor, while still running loss hooks and death checks.

Heal
public static void Heal(UnitState target, int amount);

Effect: Heals the unit, clamped to its maximum hit points.

SetHp
public static void SetHp(UnitState target, int value);

Effect: Sets the unit's current hit points to an exact value, clamped to its valid range.

GainArmor
public static void GainArmor(UnitState target, int amount);

Effect: Grants armor (block) to the unit through the armor-gain rules.

LoseArmor
public static void LoseArmor(UnitState target, int amount);

Effect: Removes armor from the unit, clamped at zero.

SetArmor
public static void SetArmor(UnitState target, int value);

Effect: Sets the unit's armor to an exact value.

KillUnit
public static void KillUnit(UnitState target, UnitState source = null);

Effect: Reduces the unit to zero hit points immediately. The optional source is credited for kill triggers.

ReviveUnit
public static void ReviveUnit(UnitState target, float hpPercent);

Effect: Revives a dead unit to a percentage of its maximum hit points. hpPercent runs from 0 to 1, so 0.5f means half HP.

GainEnergy
public static void GainEnergy(int amount);

Effect: Grants energy to the player. Uncapped: energy may exceed the per-turn maximum.

LoseEnergy
public static void LoseEnergy(int amount);

Effect: Removes energy from the player, clamped at zero.

SetEnergy
public static void SetEnergy(int value);

Effect: Sets the player's energy to an exact value, clamped to the per-turn maximum.

DrawCards
public static void DrawCards(int count);

Effect: Draws cards from the draw pile into the player's hand. The discard pile reshuffles in when the draw pile empties, and drawing stops at the hand-size limit.

ApplyStatus
public static void ApplyStatus(UnitState target, GameStatus status, int stacks, UnitState source = null);

Arguments:

  • target: the unit to receive the status.
  • status: the status asset to apply.
  • stacks: the number of stacks; must be positive to have any effect.
  • source: the unit credited as the applier, recorded for retaliation effects. Optional.

Effect: Applies stacks honoring the status's stack rule (additive, max, or replace) and max-stack cap, and runs inflict and receive hooks.

var vulnerable = GCSApi.FindStatus(vulnerableGuid);
GCSApi.ApplyStatus(GCSApi.FirstAliveEnemy(), vulnerable, 2, GCSApi.Player());
RemoveStatus
public static void RemoveStatus(UnitState target, GameStatus status, int stacks);

Effect: Removes stacks of a status from the unit. Pass a negative count to remove the status entirely.

ModifyStatusStacks
public static void ModifyStatusStacks(UnitState target, GameStatus status, int delta);

Effect: Adjusts the stack count by a signed delta, bypassing the apply pipeline: no inflict or receive hooks, no stack-rule recombination. Use ApplyStatus when you want normal application semantics.

AddCardToHand
public static CardInstance AddCardToHand(GameCard card);

Effect: Instantiates the card definition into the player's hand, or into the discard pile when the hand is full.

Returns: The created card instance, or null when no battle is active.

MoveCardToPile
public static void MoveCardToPile(CardInstance card, PileScope pile);

Effect: Moves an existing card instance to a different pile.

ShuffleDrawPile
public static void ShuffleDrawPile();

Effect: Randomly shuffles the player's draw pile.

GrantExtraTurn
public static void GrantExtraTurn();

Effect: Grants the player an extra turn after the current one resolves.

SummonEnemy
public static EnemyUnitState SummonEnemy(GameEnemyUnit enemy, UnitState summoner = null);

Effect: Summons a new enemy unit into the current battle. The optional summoner is credited for the summon.

Returns: The spawned enemy state, or null when no battle is active.

RaiseGameEvent
public static void RaiseGameEvent(string eventName, IReadOnlyDictionary<string, object> args = null);

Effect: Raises a custom internal battle event by name. It reaches both code subscribers and any card or status graph listening for it through an On Internal Event entry node, which makes it the bridge from your game systems into authored card behavior.

GetBattleVariable
public static object GetBattleVariable(string name);

Returns: The battle-scoped variable previously stored by SetBattleVariable or a Set Variable node; null when unset or no battle is active.

SetBattleVariable
public static void SetBattleVariable(string name, object value);

Effect: Stores a battle-scoped variable readable by graphs and by GetBattleVariable. Variables live and die with the battle.

Content discovery​

Active*Databases
public static IReadOnlyList<GameEncounterDatabase> ActiveEncounterDatabases();
public static IReadOnlyList<GamePlayerUnitDatabase> ActivePlayerUnitDatabases();
public static IReadOnlyList<GameEnemyUnitDatabase> ActiveEnemyUnitDatabases();
public static IReadOnlyList<GameCardDatabase> ActiveCardDatabases();
public static IReadOnlyList<GameDeckDatabase> ActiveDeckDatabases();
public static IReadOnlyList<GameStatusDatabase> ActiveStatusDatabases();

Returns: The active databases of each content type configured on the manager. Each method returns an empty list when no manager is active, never null.

Cards, Decks, PlayerUnits, EnemyUnits, Statuses, Encounters
public static IReadOnlyList<GameCard> Cards();
public static IReadOnlyList<GameDeck> Decks();
public static IReadOnlyList<GamePlayerUnit> PlayerUnits();
public static IReadOnlyList<GameEnemyUnit> EnemyUnits();
public static IReadOnlyList<GameStatus> Statuses();
public static IReadOnlyList<GameEncounter> Encounters();

Returns: Every entity of that type across the active databases. Never null.

Cache browser data

Each call enumerates the active databases and allocates a fresh list. Cache the result in menus, collection browsers, and any panel that refreshes frequently.

FindCard
public static GameCard FindCard(string guid);

Returns: The card with the given stable GUID across the active card databases, or null when none matches. GUIDs survive renames, so they are the correct identifier for save data and external tools.

FindDeck
public static GameDeck FindDeck(string guid);

Returns: The matching GameDeck, or null.

FindPlayerUnit
public static GamePlayerUnit FindPlayerUnit(string guid);

Returns: The matching player unit asset, or null.

FindEnemyUnit
public static GameEnemyUnit FindEnemyUnit(string guid);

Returns: The matching enemy unit asset, or null.

FindStatus
public static GameStatus FindStatus(string guid);

Returns: The matching status asset, or null.

FindEncounter
public static GameEncounter FindEncounter(string guid);

Returns: The matching encounter asset, or null.

Run deck​

The master deck is the run-level card list that seeds the draw pile at the start of each battle. It persists across battles for the life of a run and is independent of any encounter's authored starting deck, which makes it the canonical place to record roguelike card acquisition, upgrades, and removal.

GetMasterDeck
public static IReadOnlyList<MasterDeckEntry> GetMasterDeck();

Returns: The current run deck entries. Never null.

SetMasterDeck
public static void SetMasterDeck(IList<MasterDeckEntry> entries);

Effect: Replaces the entire persistent master deck. Passing null clears it.

AddCardToMasterDeck
public static void AddCardToMasterDeck(GameCard card, bool isUpgraded = false);

Effect: Adds one card entry to the run deck. isUpgraded controls whether the entry starts in its upgraded form.

RemoveCardFromMasterDeck
public static bool RemoveCardFromMasterDeck(string cardGuid, bool removeFirstOnly = true);

Effect: Removes matching card entries by GUID. With removeFirstOnly at its default true, a single match is removed; pass false to remove every match.

Returns: true when at least one entry was removed.

UpgradeCardInMasterDeck
public static bool UpgradeCardInMasterDeck(string cardGuid);

Effect: Upgrades the first matching entry that is not yet upgraded.

Returns: true when an entry was upgraded.

ClearMasterDeck
public static void ClearMasterDeck();

Effect: Clears the run deck and resets run-level bonuses. Typically called when starting a new run.

Events​

Every subscription method returns IDisposable. Dispose the handle in OnDisable, OnDestroy, or your UI teardown path; a leaked subscription survives scene reloads and fires into dead objects.

Subscribe<TArgs>
public static IDisposable Subscribe<TArgs>(string eventName, Action<TArgs> handler);

Arguments:

  • eventName: an event-name constant from GCSEventNames, or a custom name.
  • handler: the callback invoked when the event is raised.

Returns: A disposable subscription handle.

The generic argument must match the event's published payload type. Subscribing to a name already in use with a different TArgs is rejected with an error log, and raising with a mismatched type does not fire the handler. For custom events raised via RaiseGameEvent, the payload arrives as IReadOnlyDictionary<string, object>.

private IDisposable _sub;

void OnEnable()
{
    _sub = GCSApi.Subscribe<DamageEventArgs>(
        GCSEventNames.OnDamageDealt,
        args => Debug.Log(args.Amount));
}

void OnDisable()
{
    _sub?.Dispose();
}
Subscribe
public static IDisposable Subscribe(string eventName, Action handler);

Returns: A disposable subscription handle for a parameterless event.

OnBattleStarted
public static IDisposable OnBattleStarted(Action handler);

Fires when: Battle startup completes, once per battle.

The natural place to rebuild every visible battle panel in custom UI.

OnCardPlayed
public static IDisposable OnCardPlayed(Action<CardPlayedEventArgs> handler);

Fires when: A card is played. The payload carries the card, its instance id, and the optional target unit id.

Drives hand views, discard and exhaust counters, combat log entries, and card-play VFX.

OnUnitHpChanged
public static IDisposable OnUnitHpChanged(Action<UnitHpChangedEventArgs> handler);

Fires when: A unit's hit points or armor change. The payload carries both the new and previous values.

Drives custom health bars, floating damage numbers, and unit frames.

All built-in event shortcuts

Each shortcut wraps Subscribe with the matching GCSEventNames constant and payload type, and returns IDisposable.

  • OnBattleStarted(Action) fires once when a battle begins.
  • OnBattleEnded(Action<BattleEndedEventArgs>) fires once when the battle is won or lost.
  • OnTurnStarted(Action<TurnEventArgs>) fires at the start of each player turn.
  • OnEnemyTurnStarted(Action<TurnEventArgs>) fires once at the start of each enemy phase.
  • OnTurnEnded(Action<TurnEventArgs>) fires at the end of each player turn.
  • OnDrawPhase(Action<TurnEventArgs>) fires at the draw step of each player turn.
  • OnDiscardPhase(Action<TurnEventArgs>) fires at the discard step of each player turn.
  • OnDrawPileShuffled(Action) fires when the draw pile is shuffled.

See the Event Reference for event-name constants and payload fields.

Extension registries​

NodeTypes
public static IReadOnlyList<FlowNodeRegistry.Entry> NodeTypes();

Returns: Every registered flow-graph node type, built-in plus any custom [FlowNode] classes discovered in user assemblies. The registry scans loaded assemblies once.

CardTypes
public static IReadOnlyCollection<CardType> CardTypes();

Returns: Every registered card type, including custom [CardType] classifications.

CardTags
public static IReadOnlyCollection<CardTag> CardTags();

Returns: Every registered card tag, including custom [CardTag] classifications.

DescriptionTokens
public static IReadOnlyCollection<DescriptionTokenRegistry.Entry> DescriptionTokens();

Returns: Every registered description token, including custom [DescriptionToken] resolvers used by FormatDescription.

On this page