API Reference

Guide

Every public GCSApi member, grouped to match the facade: control, state reads, mutations, content, and events

Namespace

All members are defined 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

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

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

Intents: CurrentIntentTag, CurrentIntentValue, PendingIntents

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

Card queries: GetEffectiveEnergyCost, GetActiveCard, IsUpgraded, FormatDescription

Status queries: GetStatusStacks, HasStatus, GetStatusApplier, StatusesOn

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

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

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

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 it for low-level reads when no convenience accessor exists on the facade; for writes, use the typed helpers under Battle mutation or 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 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

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 (no active battle, card not in hand, not enough energy, 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 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

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

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 unit that originally applied the status, or null when unknown; useful for retaliation effects that hit the source

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

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

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 the unit's hit points directly, ignoring armor, while still running loss hooks and death checks

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 the unit, clamped to its maximum hit points

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 the unit's current hit points to an exact value, clamped to its valid range

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

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

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

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 the status's stack rule (additive, max, or replace) and max-stack cap, and runs inflict and receive hooks

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; 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, or into the discard pile when the hand is full

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

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 wraps Subscribe with the matching GCSEventNames constant and payload type, and returns IDisposable

Battle and turns
Cards
Units and damage
Statuses and energy
Choices and triggers

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

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 a card is discarded, by overflow or at end of turn
OnCardExhausted(Action<CardLifecycleEventArgs>) fires when a card is exhausted
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

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
OnEnemyUnitSummoned(Action<EnemyUnitSummonedEventArgs>) fires when an enemy is summoned mid-battle
OnEnemyPhaseChanged(Action<EnemyPhaseChangedEventArgs>) fires as the enemy phase progresses

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 is applied to a unit
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

OnDelayedTriggerScheduled(Action<DelayedTriggerScheduledEventArgs>) fires when a cross-turn effect is queued
OnDelayedTriggerFired(Action<DelayedTriggerFiredEventArgs>) fires when a queued cross-turn effect resolves
OnDelayedTriggerCancelled(Action<DelayedTriggerCancelledEventArgs>) fires when a queued cross-turn effect is cancelled
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 when the player resolves an effect choice
OnEffectChoiceSkipped(Action) fires when an effect choice is skipped

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

The facade contract​

Surface map​

Manager and channels​

Battle control​

Battle status​

Player, units, and energy​

Enemy intents​

Card piles and card queries​

Status queries​

Battle mutation​

Content discovery​

Run deck​

Events​

Extension registries​

The facade contract

Surface map

Manager and channels

Battle control

Battle status

Player, units, and energy

Enemy intents

Card piles and card queries

Status queries

Battle mutation

Content discovery

Run deck

Events

Extension registries