API reference

API

Guide

Find every public GCSApi member by battle control, state reads, battle mutations, content discovery, and events

Namespace

All members are defined on TinyGiants.GCS.Runtime.GCSApi

using TinyGiants.GCS.Runtime;

Usage contract

GCSApi is the unified project-code entry to the current GCS battle. UI, scene flow, and external systems can use it to start battle, read state, submit operations, and subscribe to events without locating the Manager, Battle, Controller, and event channel separately

The four entries above act on the same active battle, keeping API reads, FlowGraph resolution, and Monitor records consistent. Calls follow these boundaries:

• 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

Battle control

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

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

Battle status

Phase, IsBattleActive, IsBattleOver, IsWaitingForChoice, IsWaitingForReward, TurnNumber, IsPlayerTurn

Units and intents

Units and energy: Player, PlayerEnergy, MaxEnergy, AliveEnemies, FirstAliveEnemy, EnemyCount, AllUnits, Hp, MaxHp, Armor, HpPercent, IsDead, IsAlive

Intents: CurrentIntentTag, CurrentIntentValue, PendingIntents

Cards and statuses

Piles: CurrentHand, Hand, DrawPile, DiscardPile, ExhaustPile, PlayedThisTurn, DrawnThisTurn

Card queries: GetEffectiveEnergyCost, GetActiveCard, IsUpgraded, FormatDescription

Status queries: GetStatusStacks, HasStatus, GetStatusApplier, StatusesOn

Mutation

HP and armor: DealDamage, LoseHp, Heal, SetHp, GainArmor, LoseArmor, SetArmor, KillUnit, ReviveUnit

Energy and cards: GainEnergy, LoseEnergy, SetEnergy, DrawCards, AddCardToHand, MoveCardToPile, ShuffleDrawPile

Statuses and units: ApplyStatus, RemoveStatus, ModifyStatusStacks, SummonEnemy, GrantExtraTurn

Events and variables: RaiseGameEvent, GetBattleVariable, SetBattleVariable

Content and events

Databases: Active*Databases, Cards and friends, FindCard, FindDeck, FindPlayerUnit, FindEnemyUnit, FindStatus, FindEncounter

Run deck: GetMasterDeck, SetMasterDeck, AddCardToMasterDeck, RemoveCardFromMasterDeck, UpgradeCardInMasterDeck, ClearMasterDeck

Events: Subscribe<TArgs>, Subscribe, built-in shortcuts

Registries: NodeTypes, CardTypes, CardTags, DescriptionTokens

Manager and channels

Manager

public static GameCardManager Manager { get; }

Returns: The active GameCardManager, or null before a manager is loaded

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

When it is null, most GCSApi members do nothing or return safe defaults. Use IsReady to check Manager availability and prefer the matching named method to preserve the public API's null and event semantics

Example:

GameCardManager manager = GCSApi.Manager;

IsReady

public static bool IsReady { get; }

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

Example:

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 this to read battle state when GCSApi has no matching convenience accessor. Write through the typed methods under Battle mutation or through Controller

Example:

IBattleState battle = GCSApi.Battle;

Controller

public static IBattleController Controller { get; }

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

This is the complete battle mutation interface. Operations submitted through it update battle state immediately and broadcast the same events as built-in nodes, keeping presentation synchronized

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

Example:

IBattleController controller = GCSApi.Controller;

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

Example:

IGCSEventChannel channel = GCSApi.Events;

Battle control

StartBattle

public static void StartBattle(GameEncounter encounter);

Parameters:

Name	Type	Description
encounter	GameEncounter	defines the battle: player unit, enemy lineup, reward pool, and rules; a null encounter is ignored

Returns: Nothing (void). The operation runs when its runtime preconditions are met

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

Example:

public GameEncounter Encounter;

public void BeginEncounter()
{
    if (GCSApi.IsReady)
    {
        GCSApi.StartBattle(Encounter);
    }
}

TryPlayCard

public static bool TryPlayCard(CardInstance card, UnitState target = null);

Parameters:

Name	Type	Description
card	CardInstance	the hand card instance to play
target	UnitState	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 because the battle is outside an unlocked PlayerPhase, the card is absent from Hand, energy is insufficient, a required enemy target is invalid, the card is Unplayable, or a play Hook cancelled it

Example:

if (GCSApi.CanPlayCard(card))
{
    GCSApi.TryPlayCard(card, selectedEnemy);
}

CanPlayCard

public static bool CanPlayCard(CardInstance card);

Parameters:

Name	Type	Description
card	CardInstance	The card instance

Returns: true when the play would be allowed to proceed: the battle is in an unlocked PlayerPhase, the card remains in Hand, the card is not marked Unplayable, energy covers its effective cost, and playability Hooks permit it; a pending Wait or Choice returns false; the method does not play the card

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

Example:

bool result = GCSApi.CanPlayCard(cardInstance);

RequiresTarget

public static bool RequiresTarget(GameCard card);

Parameters:

Name	Type	Description
card	GameCard	The card definition

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

Example:

var activeCard = GCSApi.GetActiveCard(cardInstance);

if (GCSApi.RequiresTarget(activeCard))
{
    OpenTargetPicker(cardInstance);
}
else
{
    GCSApi.TryPlayCard(cardInstance);
}

EndPlayerTurn

public static void EndPlayerTurn();

Returns: Nothing (void). The operation runs when its runtime preconditions are met

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

Example:

GCSApi.EndPlayerTurn();

ApplyReward

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

Parameters:

Name	Type	Description
choice	RewardChoice	the selected reward kind (card, energy, or cost discount)
pickedCard	GameCard	the chosen card when choice is RewardChoice.Card; otherwise null

Choice	Run-level effect
RewardChoice.Card	Adds pickedCard to the current master deck as an unupgraded card; a null card adds nothing
RewardChoice.Energy	Adds 1 to the run's per-turn energy bonus for later battles

| RewardChoice.Cost | Reduces the cost delta of every card currently in the master deck by 1; cards added later do not inherit this discount |

Returns: Nothing (void). The operation runs when its runtime preconditions are met

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

Example:

GCSApi.ApplyReward(RewardChoice.Card, rewardCard);

SkipReward

public static void SkipReward();

Returns: Nothing (void). The operation runs when its runtime preconditions are met

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

Example:

GCSApi.SkipReward();

DisposeBattle

public static void DisposeBattle();

Returns: Nothing (void). The operation runs when its runtime preconditions are met

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

Example:

GCSApi.DisposeBattle();

Battle status

Phase

public static BattlePhase Phase { get; }

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

Example:

BattlePhase value = GCSApi.Phase;

IsBattleActive

public static bool IsBattleActive { get; }

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

Example:

bool value = GCSApi.IsBattleActive;

IsBattleOver

public static bool IsBattleOver { get; }

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

Example:

bool value = GCSApi.IsBattleOver;

IsWaitingForChoice

public static bool IsWaitingForChoice { get; }

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

Example:

bool value = GCSApi.IsWaitingForChoice;

IsWaitingForReward

public static bool IsWaitingForReward { get; }

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

Example:

bool value = GCSApi.IsWaitingForReward;

TurnNumber

public static int TurnNumber { get; }

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

Example:

int value = GCSApi.TurnNumber;

IsPlayerTurn

public static bool IsPlayerTurn { get; }

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

Example:

bool value = GCSApi.IsPlayerTurn;

Player, units, and energy

Player

public static UnitState Player();

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

Example:

UnitState result = GCSApi.Player();

PlayerEnergy

public static int PlayerEnergy { get; }

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

Example:

int value = GCSApi.PlayerEnergy;

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

Example:

int value = GCSApi.MaxEnergy;

AliveEnemies

public static IReadOnlyList<UnitState> AliveEnemies();

Returns: The living enemy units in the current battle; never null

Example:

var result = GCSApi.AliveEnemies();

FirstAliveEnemy

public static UnitState FirstAliveEnemy();

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

Example:

UnitState result = GCSApi.FirstAliveEnemy();

EnemyCount

public static int EnemyCount();

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

Example:

int result = GCSApi.EnemyCount();

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

Example:

var result = GCSApi.AllUnits();

Hp

public static int Hp(UnitState unit);

Parameters:

Name	Type	Description
unit	UnitState	The unit to inspect or modify

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

Example:

int result = GCSApi.Hp(unit);

MaxHp

public static int MaxHp(UnitState unit);

Parameters:

Name	Type	Description
unit	UnitState	The unit to inspect or modify

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

Example:

int result = GCSApi.MaxHp(unit);

Armor

public static int Armor(UnitState unit);

Parameters:

Name	Type	Description
unit	UnitState	The unit to inspect or modify

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

Example:

int result = GCSApi.Armor(unit);

HpPercent

public static int HpPercent(UnitState unit);

Parameters:

Name	Type	Description
unit	UnitState	The unit to inspect or modify

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

Example:

int result = GCSApi.HpPercent(unit);

IsDead

public static bool IsDead(UnitState unit);

Parameters:

Name	Type	Description
unit	UnitState	The unit to inspect or modify

Returns: true when the unit is dead; a null unit is treated as dead

Example:

bool result = GCSApi.IsDead(unit);

IsAlive

public static bool IsAlive(UnitState unit);

Parameters:

Name	Type	Description
unit	UnitState	The unit to inspect or modify

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

Example:

bool result = GCSApi.IsAlive(unit);

Enemy intents

CurrentIntentTag

public static IntentTag CurrentIntentTag(UnitState enemy);

Parameters:

Name	Type	Description
enemy	UnitState	The enemy unit to inspect

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; an authored IntentKind.Hidden also reports as IntentTag.Unknown, so this API does not reveal a hidden plan

Example:

IntentTag result = GCSApi.CurrentIntentTag(enemy);

CurrentIntentValue

public static int CurrentIntentValue(UnitState enemy);

Parameters:

Name	Type	Description
enemy	UnitState	The enemy unit to inspect

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

Example:

int result = GCSApi.CurrentIntentValue(enemy);

PendingIntents

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

Parameters:

Name	Type	Description
enemy	UnitState	The enemy unit to inspect

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; status and active Hook changes that affect preview values refresh these entries without waiting for phase end

The encounter's intent display mode is not applied here; that shaping only affects the OnEnemyUnitIntentChanged event payload; use this method for the true plan and the event payload for the intents exposed to the player

Example:

var result = GCSApi.PendingIntents(enemy);

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

Example:

var value = GCSApi.CurrentHand;

Hand

public static IReadOnlyList<CardInstance> Hand();

Returns: The player's current hand pile; never null

Example:

var result = GCSApi.Hand();

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]

Example:

var result = GCSApi.DrawPile();

DiscardPile

public static IReadOnlyList<CardInstance> DiscardPile();

Returns: The player's current discard pile; never null

Example:

var result = GCSApi.DiscardPile();

ExhaustPile

public static IReadOnlyList<CardInstance> ExhaustPile();

Returns: The player's current exhaust pile; never null

Example:

var result = GCSApi.ExhaustPile();

PlayedThisTurn

public static IReadOnlyList<CardInstance> PlayedThisTurn();

Returns: The card instances played during the current turn, in play order; never null

Example:

var result = GCSApi.PlayedThisTurn();

DrawnThisTurn

public static IReadOnlyList<CardInstance> DrawnThisTurn();

Returns: The card instances drawn during the current turn, in draw order; never null

Example:

var result = GCSApi.DrawnThisTurn();

GetEffectiveEnergyCost

public static int GetEffectiveEnergyCost(CardInstance card);

Parameters:

Name	Type	Description
card	CardInstance	The card instance

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

Example:

int result = GCSApi.GetEffectiveEnergyCost(cardInstance);

GetActiveCard

public static GameCard GetActiveCard(CardInstance card);

Parameters:

Name	Type	Description
card	CardInstance	The card instance

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

Example:

GameCard result = GCSApi.GetActiveCard(cardInstance);

IsUpgraded

public static bool IsUpgraded(CardInstance card);

Parameters:

Name	Type	Description
card	CardInstance	The card instance

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

Example:

bool result = GCSApi.IsUpgraded(cardInstance);

FormatDescription

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

Parameters:

Name	Type	Description
card	GameCard	the card whose description text to format
instance	CardInstance	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

Example:

string result = GCSApi.FormatDescription(card);

Status queries

GetStatusStacks

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

Parameters:

Name	Type	Description
unit	UnitState	The unit to inspect or modify
status	GameStatus	The status definition

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

Example:

int result = GCSApi.GetStatusStacks(unit, status);

HasStatus

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

Parameters:

Name	Type	Description
unit	UnitState	The unit to inspect or modify
status	GameStatus	The status definition
minStacks	int	The minimum required stacks; defaults to 1

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

Example:

bool result = GCSApi.HasStatus(unit, status);

GetStatusApplier

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

Parameters:

Name	Type	Description
unit	UnitState	The unit to inspect or modify
status	GameStatus	The status definition

Returns: The source of the latest successful application that changed the stored stack count, or null when unknown; a capped no-op and direct stack mutation do not replace it

Example:

UnitState result = GCSApi.GetStatusApplier(unit, status);

StatusesOn

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

Parameters:

Name	Type	Description
unit	UnitState	The unit to inspect or modify

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, so treat it as read-only and request it again after a mutation instead of caching it across changes

Example:

var result = GCSApi.StatusesOn(unit);

Battle mutation

Controller-backed operations

The methods below modify the active battle and do nothing when no battle exists. They follow the same rules and raise the same events as built-in FlowGraph nodes. Project code should use these methods for battle-state changes; direct field writes bypass Hooks, events, and presentation refreshes

DealDamage

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

Parameters:

Name	Type	Description
target	UnitState	the unit to damage
amount	int	the raw damage before mitigation
attacker	UnitState	the unit credited as the attacker, enabling on-deal-damage hooks and kill credit; pass null for unattributed damage
bypassArmor	bool	when true, the damage ignores armor and reduces hit points directly

Returns: Nothing (void). The operation runs when its runtime preconditions are met

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

Example:

GCSApi.DealDamage(GCSApi.FirstAliveEnemy(), 8, GCSApi.Player());

LoseHp

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

Parameters:

Name	Type	Description
target	UnitState	The target unit
amount	int	The amount to apply

Returns: Nothing (void). The operation runs when its runtime preconditions are met

Effect: Reduces a living unit's hit points directly, ignoring armor, while still running loss Hooks and death checks; non-positive amounts, dead targets, and fully prevented loss produce no false event or Entry

Example:

GCSApi.LoseHp(target, 10);

Heal

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

Parameters:

Name	Type	Description
target	UnitState	The target unit
amount	int	The amount to apply

Returns: Nothing (void). The operation runs when its runtime preconditions are met

Effect: Heals a living unit, clamped to its maximum hit points; dead or full-health targets and non-positive amounts produce no false event or Entry

Example:

GCSApi.Heal(target, 10);

SetHp

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

Parameters:

Name	Type	Description
target	UnitState	The target unit
value	int	The new absolute value

Returns: Nothing (void). The operation runs when its runtime preconditions are met

Effect: Sets a unit's current hit points to an exact value, clamped to its valid range; an actual increase or decrease enters the matching status On HP Gained or On HP Lost branch, reaching 0 runs death checks, and a positive value cannot revive an already-dead unit

Example:

GCSApi.SetHp(target, 10);

GainArmor

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

Parameters:

Name	Type	Description
target	UnitState	The target unit
amount	int	The amount to apply

Returns: Nothing (void). The operation runs when its runtime preconditions are met

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

Example:

GCSApi.GainArmor(target, 10);

LoseArmor

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

Parameters:

Name	Type	Description
target	UnitState	The target unit
amount	int	The amount to apply

Returns: Nothing (void). The operation runs when its runtime preconditions are met

Effect: Removes armor from the unit, clamped at 0, and reports the actual armor removed; only this explicit path enters the status On Armor Lost Entry, while damage absorption still publishes the public OnArmorLost event

Example:

GCSApi.LoseArmor(target, 10);

SetArmor

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

Parameters:

Name	Type	Description
target	UnitState	The target unit
value	int	The new absolute value

Returns: Nothing (void). The operation runs when its runtime preconditions are met

Effect: Sets the unit's armor to an exact value clamped at 0; this direct assignment refreshes state without entering status On Armor Gained or On Armor Lost branches and without publishing their transition events

Example:

GCSApi.SetArmor(target, 10);

KillUnit

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

Parameters:

Name	Type	Description
target	UnitState	The target unit
source	UnitState	The optional source unit

Returns: Nothing (void). The operation runs when its runtime preconditions are met

Effect: Reduces the unit to 0 hit points immediately; the optional source is credited for kill triggers

Example:

GCSApi.KillUnit(target);

ReviveUnit

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

Parameters:

Name	Type	Description
target	UnitState	The target unit
hpPercent	float	The fraction of maximum HP restored, from 0 to 1

Returns: Nothing (void). The operation runs when its runtime preconditions are met

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

Example:

GCSApi.ReviveUnit(target, 0.5f);

GainEnergy

public static void GainEnergy(int amount);

Parameters:

Name	Type	Description
amount	int	The amount to apply

Returns: Nothing (void). The operation runs when its runtime preconditions are met

Effect: Grants energy to the player; uncapped: energy may exceed the per-turn maximum

Example:

GCSApi.GainEnergy(10);

LoseEnergy

public static void LoseEnergy(int amount);

Parameters:

Name	Type	Description
amount	int	The amount to apply

Returns: Nothing (void). The operation runs when its runtime preconditions are met

Effect: Removes energy from the player, clamped at 0

Example:

GCSApi.LoseEnergy(10);

SetEnergy

public static void SetEnergy(int value);

Parameters:

Name	Type	Description
value	int	The new absolute value

Returns: Nothing (void). The operation runs when its runtime preconditions are met

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

Example:

GCSApi.SetEnergy(10);

DrawCards

public static void DrawCards(int count);

Parameters:

Name	Type	Description
count	int	The number of cards

Returns: Nothing (void). The operation runs when its runtime preconditions are met

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; for each actual card, runtime publishes OnCardDrawn, completes the player's status branches in snapshot order, then completes the card's own On Drawn branch before the next card proceeds

Example:

GCSApi.DrawCards(2);

ApplyStatus

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

Parameters:

Name	Type	Description
target	UnitState	the unit to receive the status
status	GameStatus	the status asset to apply
stacks	int	the number of stacks; must be positive to have any effect
source	UnitState	the unit credited as the applier, recorded for retaliation effects; optional

Returns: Nothing (void). The operation runs when its runtime preconditions are met

Effect: Applies stacks honoring inflict and receive Hooks, the status stack rule (additive, max, or replace), and the max-stack cap; public transition events and application Entries run only when the stored count actually changes, so a capped or Max no-op is silent

Example:

var vulnerable = GCSApi.FindStatus(vulnerableGuid);
GCSApi.ApplyStatus(GCSApi.FirstAliveEnemy(), vulnerable, 2, GCSApi.Player());

RemoveStatus

public static void RemoveStatus(UnitState target, GameStatus status, int stacks);

Parameters:

Name	Type	Description
target	UnitState	The target unit
status	GameStatus	The status definition
stacks	int	The number of stacks

Returns: Nothing (void). The operation runs when its runtime preconditions are met

Effect: Removes stacks of a status from the unit; pass a negative count to remove the status entirely

Example:

GCSApi.RemoveStatus(target, status, 2);

ModifyStatusStacks

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

Parameters:

Name	Type	Description
target	UnitState	The target unit
status	GameStatus	The status definition
delta	int	The signed stack change: positive to add, negative to remove

Returns: Nothing (void). The operation runs when its runtime preconditions are met

Effect: Adjusts the stack count by a signed delta, bypassing the apply pipeline: no inflict or receive Hooks, no stack-rule recombination; an actual positive resulting count still runs On Status Stacks Changed, while reaching 0 runs removal; use ApplyStatus when you want normal application semantics

Example:

GCSApi.ModifyStatusStacks(target, status, -1);

AddCardToHand

public static CardInstance AddCardToHand(GameCard card);

Parameters:

Name	Type	Description
card	GameCard	The card definition

Effect: Instantiates the card definition into the player's hand and runs the added-to-hand event and Behaviors; when the hand is full, the instance enters Discard through the discard event and Behaviors instead

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

Example:

CardInstance result = GCSApi.AddCardToHand(card);

MoveCardToPile

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

Parameters:

Name	Type	Description
card	CardInstance	The card instance
pile	PileScope	The destination pile

Returns: Nothing (void). The operation runs when its runtime preconditions are met

Effect: Moves an existing card instance to a different pile; entering Discard or Exhaust publishes the matching event and executes status plus card lifecycle Behaviors, while a request for the pile already containing the card is a no-op and does not dispatch that lifecycle again

Example:

GCSApi.MoveCardToPile(cardInstance, PileScope.Discard);

ShuffleDrawPile

public static void ShuffleDrawPile();

Returns: Nothing (void). The operation runs when its runtime preconditions are met

Effect: Randomly shuffles the player's draw pile

Example:

GCSApi.ShuffleDrawPile();

GrantExtraTurn

public static void GrantExtraTurn();

Returns: Nothing (void). The operation runs when its runtime preconditions are met

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

Example:

GCSApi.GrantExtraTurn();

SummonEnemy

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

Parameters:

Name	Type	Description
enemy	GameEnemyUnit	The enemy unit to inspect
summoner	UnitState	The optional summoning unit

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

Example:

EnemyUnitState result = GCSApi.SummonEnemy(enemy);

RaiseGameEvent

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

Parameters:

Name	Type	Description
eventName	string	The event name
args	IReadOnlyDictionary<string, object>	The optional event payload

Returns: Nothing (void). The operation runs when its runtime preconditions are met

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

Example:

GCSApi.RaiseGameEvent("MyCustomEvent");

GetBattleVariable

public static object GetBattleVariable(string name);

Parameters:

Name	Type	Description
name	string	The variable name

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

Example:

object result = GCSApi.GetBattleVariable("ComboCount");

SetBattleVariable

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

Parameters:

Name	Type	Description
name	string	The variable name
value	object	The new absolute value

Returns: Nothing (void). The operation runs when its runtime preconditions are met

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

Example:

GCSApi.SetBattleVariable("ComboCount", 10);

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

Example:

var databases = GCSApi.ActiveCardDatabases();

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

Example:

IReadOnlyList<GameCard> cards = GCSApi.Cards();

FindCard

public static GameCard FindCard(string guid);

Parameters:

Name	Type	Description
guid	string	The asset's stable 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

Example:

GameCard result = GCSApi.FindCard(guid);

FindDeck

public static GameDeck FindDeck(string guid);

Parameters:

Name	Type	Description
guid	string	The asset's stable GUID

Returns: The matching GameDeck, or null

Example:

GameDeck result = GCSApi.FindDeck(guid);

FindPlayerUnit

public static GamePlayerUnit FindPlayerUnit(string guid);

Parameters:

Name	Type	Description
guid	string	The asset's stable GUID

Returns: The matching player unit asset, or null

Example:

GamePlayerUnit result = GCSApi.FindPlayerUnit(guid);

FindEnemyUnit

public static GameEnemyUnit FindEnemyUnit(string guid);

Parameters:

Name	Type	Description
guid	string	The asset's stable GUID

Returns: The matching enemy unit asset, or null

Example:

GameEnemyUnit result = GCSApi.FindEnemyUnit(guid);

FindStatus

public static GameStatus FindStatus(string guid);

Parameters:

Name	Type	Description
guid	string	The asset's stable GUID

Returns: The matching status asset, or null

Example:

GameStatus result = GCSApi.FindStatus(guid);

FindEncounter

public static GameEncounter FindEncounter(string guid);

Parameters:

Name	Type	Description
guid	string	The asset's stable GUID

Returns: The matching encounter asset, or null

Example:

GameEncounter result = GCSApi.FindEncounter(guid);

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

Example:

var result = GCSApi.GetMasterDeck();

SetMasterDeck

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

Parameters:

Name	Type	Description
entries	IList<MasterDeckEntry>	The run-deck entries

Returns: Nothing (void). The operation runs when its runtime preconditions are met

Effect: Replaces the entire persistent master deck; passing null clears it

Example:

GCSApi.SetMasterDeck(entries);

AddCardToMasterDeck

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

Parameters:

Name	Type	Description
card	GameCard	The card definition
isUpgraded	bool	Whether the card starts upgraded

Returns: Nothing (void). The operation runs when its runtime preconditions are met

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

Example:

GCSApi.AddCardToMasterDeck(card);

RemoveCardFromMasterDeck

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

Parameters:

Name	Type	Description
cardGuid	string	The card's stable GUID
removeFirstOnly	bool	true removes one match; false removes every match

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

Example:

bool result = GCSApi.RemoveCardFromMasterDeck(cardGuid);

UpgradeCardInMasterDeck

public static bool UpgradeCardInMasterDeck(string cardGuid);

Parameters:

Name	Type	Description
cardGuid	string	The card's stable GUID

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

Returns: true when an entry was upgraded

Example:

bool result = GCSApi.UpgradeCardInMasterDeck(cardGuid);

ClearMasterDeck

public static void ClearMasterDeck();

Returns: Nothing (void). The operation runs when its runtime preconditions are met

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

Example:

GCSApi.ClearMasterDeck();

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);

Parameters:

Name	Type	Description
eventName	string	an event-name constant from GCSEventNames, or a custom name
handler	Action<TArgs>	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>

Example:

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);

Parameters:

Name	Type	Description
eventName	string	A built-in constant or custom parameterless event name
handler	Action	The parameterless callback invoked when the event is raised

Returns: A disposable subscription handle for a parameterless event

Example:

IDisposable subscription = GCSApi.Subscribe(
    GCSEventNames.OnBattleStarted,
    () => Debug.Log("Battle started")
);

OnBattleStarted

public static IDisposable OnBattleStarted(Action handler);

Parameters:

Name	Type	Description
handler	Action	The callback to invoke

Returns: An IDisposable subscription handle; call Dispose() to unsubscribe

Fires when: Battle startup completes, once per battle

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

Example:

IDisposable subscription = GCSApi.OnBattleStarted(
    () => Debug.Log("Battle started")
);

OnCardPlayed

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

Parameters:

Name	Type	Description
handler	Action<CardPlayedEventArgs>	The typed payload callback

Returns: An IDisposable subscription handle; call Dispose() to unsubscribe

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

Example:

IDisposable subscription = GCSApi.OnCardPlayed(
    args => Debug.Log(args.Card)
);

OnUnitHpChanged

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

Parameters:

Name	Type	Description
handler	Action<UnitHpChangedEventArgs>	The typed payload callback

Returns: An IDisposable subscription handle; call Dispose() to unsubscribe

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

Example:

IDisposable subscription = GCSApi.OnUnitHpChanged(
    args => Debug.Log(args.CurrentHp)
);

All built-in event shortcuts

Each shortcut subscription method corresponds to one GCSEventNames constant and Payload type and returns an IDisposable

Battle and turns

• 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

Cards

• OnCardPlayed(Action<CardPlayedEventArgs>) fires whenever a card is played
• OnCardModified(Action<CardModifiedEventArgs>) fires when a card's runtime cost or state changes
• OnCardDrawn(Action<CardLifecycleEventArgs>) fires for each card drawn into the hand
• OnCardDiscarded(Action<CardLifecycleEventArgs>) fires when overflow, end-of-turn cleanup, or an explicit move sends an existing card into Discard; default post-play placement and direct creation are silent
• OnCardExhausted(Action<CardLifecycleEventArgs>) fires when play cleanup, end-of-turn cleanup, or an explicit move sends an existing card into Exhaust; direct creation is silent
• OnCardRetained(Action<CardLifecycleEventArgs>) fires when a card is retained in hand at end of turn
• OnCardAddedToHand(Action<CardLifecycleEventArgs>) fires when a card is created directly into the hand
• OnCardAddedToDeck(Action<CardLifecycleEventArgs>) fires when a card is added to the draw pile

Units and damage

• OnUnitHpChanged(Action<UnitHpChangedEventArgs>) fires when a unit's hit points or armor change
• OnUnitDied(Action<UnitDiedEventArgs>) fires when a unit dies or is removed
• OnDamageDealt(Action<DamageEventArgs>) fires when an attacker deals damage; the payload includes whether it was lethal
• OnDamageTaken(Action<DamageEventArgs>) fires when a unit takes damage, from an attack or a status
• OnArmorGained(Action<ArmorChangedEventArgs>) fires when a unit gains armor
• OnArmorLost(Action<ArmorChangedEventArgs>) fires when a unit loses armor
• OnEnemyUnitIntentChanged(Action<EnemyUnitIntentChangedEventArgs>) fires when an enemy re-plans its intent
• OnEnemyUnitActing(Action<EnemyUnitActingEventArgs>) fires immediately before an enemy executes its current intent
• OnEnemyUnitSummoned(Action<EnemyUnitSummonedEventArgs>) fires when an enemy is summoned mid-battle
• OnEnemyPhaseChanged(Action<EnemyPhaseChangedEventArgs>) fires when a sequence pattern advances to another child phase

Statuses and energy

• OnStatusChanged(Action<StatusChangedEventArgs>) fires when a unit's status stacks change
• OnStatusTicked(Action<StatusTickedEventArgs>) fires when a status resolves at a turn boundary
• OnStatusInflicted(Action<StatusTransitionEventArgs>) fires when a status application changes the unit's stored stack count
• OnStatusExpired(Action<StatusTransitionEventArgs>) fires when a status decays to 0 stacks naturally
• OnStatusRemoved(Action<StatusTransitionEventArgs>) fires when a status is explicitly removed
• OnEnergyChanged(Action<EnergyChangedEventArgs>) fires when the player's energy or maximum changes
• OnEnergyGained(Action<EnergyDeltaEventArgs>) fires when the player gains energy
• OnEnergySpent(Action<EnergyDeltaEventArgs>) fires when the player spends energy

Choices and triggers

• OnDelayedTriggerScheduled(Action<DelayedTriggerScheduledEventArgs>) fires when a cross-turn effect is queued and whenever its matching phase advances the countdown without firing it; the payload includes TriggerId, SourceUnitId, TargetUnitId, RemainingTurns, TickPhase, Card, and ActionTypeName
• OnDelayedTriggerFired(Action<DelayedTriggerFiredEventArgs>) fires after the queued Body and every nested Wait or Choice continuation finish; the payload keeps the same TriggerId, SourceUnitId, TargetUnitId, TickPhase, Card, and ActionTypeName
• OnDelayedTriggerCancelled(Action<DelayedTriggerCancelledEventArgs>) fires when a cross-turn effect is rejected or a queued effect is cancelled; the payload includes TriggerId, SourceUnitId, TargetUnitId, TickPhase, Card, and ActionTypeName
• OnBattleRewardOffered(Action<BattleRewardOfferedEventArgs>) fires when post-battle rewards become available
• OnBattleRewardSelected(Action<BattleRewardSelectedEventArgs>) fires when the player picks a reward
• OnBattleRewardSkipped(Action) fires when the player declines the reward
• OnEffectChoiceOffered(Action<EffectChoiceOfferedEventArgs>) fires when a card effect pauses for a player choice
• OnEffectChoiceSelected(Action<EffectChoiceSelectedEventArgs>) fires after the presenter's submitted selection collection is stored; the collection may be empty and then SelectedIndex is -1
• OnEffectChoiceSkipped(Action) fires for an explicit skip or an automatic no-presenter/no-candidate fallback

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

Example:

var result = GCSApi.NodeTypes();

CardTypes

public static IReadOnlyCollection<CardType> CardTypes();

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

Example:

var result = GCSApi.CardTypes();

CardTags

public static IReadOnlyCollection<CardTag> CardTags();

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

Example:

var result = GCSApi.CardTags();

DescriptionTokens

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

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

Example:

var result = GCSApi.DescriptionTokens();