GCSApi 参考

API

GCS · API

GCSApi 的全部 public 成员，按 facade 本身的分组方式排列：控制、读取、修改、内容、事件。

用代码把自定义 UI、场景流程、存档系统或调试工具接进 GCS 时，把这一页开在手边。

本页列出 GCSApi 静态 facade 的每一个 public 成员。每个成员放在独立的折叠块里，给出准确签名、返回值，以及没有战斗在跑时的行为。用下面的成员速查直接跳到你要找的成员。

命名空间

本页所有成员都在 TinyGiants.GCS.Runtime.GCSApi 上。

using TinyGiants.GCS.Runtime;

整体约定

GCSApi 是一层很薄的静态封装。每个成员都转发给持有状态的运行时对象：GameCardManager 单例、只读的 IBattleState、可写的 IBattleController，或核心事件通道。facade 本身不存储玩法状态。

三条规则贯穿整个 API 表面：

• 只在 Unity 主线程调用。
• 战斗只存在于 StartBattle 与 DisposeBattle（或下一次 StartBattle）之间。在这个窗口之外，集合类访问器返回空列表，数值类访问器返回安全默认值（0、false、BattlePhase.None），修改类 helper 什么也不做。唯一的例外是 CurrentHand，它在战斗外按设计返回 null。
• 对象类访问器（Manager、Battle、Controller、Player()、FirstAliveEnemy()）在目标不存在时返回 null，用 IsReady 或判空来守卫。

---

成员速查

战斗控制

入口：Manager、IsReady、Battle、Controller、Events

生命周期：StartBattle、TryPlayCard、CanPlayCard、RequiresTarget、EndPlayerTurn、ApplyReward、SkipReward、DisposeBattle

战斗状态

Phase、IsBattleActive、IsBattleOver、IsWaitingForChoice、IsWaitingForReward、TurnNumber、IsPlayerTurn

单位与意图

单位与能量：Player、PlayerEnergy、MaxEnergy、AliveEnemies、FirstAliveEnemy、EnemyCount、AllUnits、Hp、MaxHp、Armor、HpPercent、IsDead、IsAlive

意图：CurrentIntentTag、CurrentIntentValue、PendingIntents

卡牌与状态

牌堆：CurrentHand、Hand、DrawPile、DiscardPile、ExhaustPile、PlayedThisTurn、DrawnThisTurn

卡牌查询：GetEffectiveEnergyCost、GetActiveCard、IsUpgraded、FormatDescription

状态查询：GetStatusStacks、HasStatus、GetStatusApplier、StatusesOn

修改

HP 与护甲：DealDamage、LoseHp、Heal、SetHp、GainArmor、LoseArmor、SetArmor、KillUnit、ReviveUnit

能量与卡牌：GainEnergy、LoseEnergy、SetEnergy、DrawCards、AddCardToHand、MoveCardToPile、ShuffleDrawPile

状态与单位：ApplyStatus、RemoveStatus、ModifyStatusStacks、SummonEnemy、GrantExtraTurn

事件与变量：RaiseGameEvent、GetBattleVariable、SetBattleVariable

内容与事件

数据库：Active*Databases、Cards 等实体方法、FindCard、FindDeck、FindPlayerUnit、FindEnemyUnit、FindStatus、FindEncounter

Run 卡组：GetMasterDeck、SetMasterDeck、AddCardToMasterDeck、RemoveCardFromMasterDeck、UpgradeCardInMasterDeck、ClearMasterDeck

事件：Subscribe<TArgs>、Subscribe、内置快捷方法

注册表：NodeTypes、CardTypes、CardTags、DescriptionTokens

---

Manager 与通道

Manager

public static GameCardManager Manager { get; }

当前活动的 GameCardManager 单例；场景里还没加载 manager 时为 null。manager 持有 run 级状态（master deck、run 加成）和当前战斗。

它为 null 时，facade 的大多数成员会退化成空操作或安全默认值，所以很少需要直接读它。判空用 IsReady 更可读，日常操作优先使用下面的具名 helper，不要直接访问 manager 内部。

IsReady

public static bool IsReady { get; }

返回： 存在 GameCardManager 且可以接收调用时为 true。

if (!GCSApi.IsReady)
{
    return;
}

Battle

public static IBattleState Battle { get; }

返回： 当前战斗的只读视图；没有战斗时为 null。

facade 上没有对应便捷访问器时，用它做底层读取。写操作走 战斗修改 里的类型化 helper 或 Controller。

Controller

public static IBattleController Controller { get; }

返回： 当前战斗的写入接口；没有战斗时为 null。

这是效果执行器内部使用的完整修改接口。在它上面做的修改立即作用于权威战斗状态，并广播与内置节点相同的事件，表现层因此保持同步。

修改边界

战斗修改 里的类型化 helper 已覆盖常见操作并自带判空。只有需要那些 helper 没暴露的操作时才用 Controller。

Events

public static IGCSEventChannel Events { get; }

返回： GCS 核心事件通道。

内置事件优先使用 事件快捷方法 里的强类型 On* 方法。只有订阅自定义事件名或做批量操作时才直接用通道。

---

战斗控制

StartBattle

public static void StartBattle(GameEncounter encounter);

参数： encounter 定义这场战斗：玩家单位、敌人阵容、奖励池和规则。传 null 时调用被忽略。

效果： 启动一场新战斗，抽牌堆从持久化的 master deck 生成。已有战斗在进行时会先被释放。起始手牌在方法返回前抽好，OnBattleStarted 也在返回前触发，第一回合的敌人意图同时解析完成。场景里没有 IChoicePresenter 时，卡牌效果里的选择节点按跳过处理。

public GameEncounter Encounter;

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

TryPlayCard

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

参数：

• card：要打出的手牌实例。
• target：目标模式为单体敌人的卡需要的目标单位。其余情况传 null，自我、全体敌人和无目标的卡由引擎自动解析目标。

返回： 卡被接受并打出时为 true；被拒绝时为 false（没有活动战斗、卡不在手牌中、能量不足、卡不可打出，或某个出牌 Hook 取消了这次出牌）。

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

CanPlayCard

public static bool CanPlayCard(CardInstance card);

返回： 允许尝试出牌时为 true：战斗处于 PlayerPhase、卡没有 Unplayable 标记、玩家能量足以支付卡的有效费用。它不会真的打出卡牌。

用它在玩家点击之前驱动卡牌按钮的可用与禁用状态。

RequiresTarget

public static bool RequiresTarget(GameCard card);

返回： 只有目标模式为单体敌人的卡返回 true。自我、全体敌人和无目标的卡返回 false，它们的目标由引擎自动挑选。

var activeCard = GCSApi.GetActiveCard(cardInstance);

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

EndPlayerTurn

public static void EndPlayerTurn();

效果： 结束玩家回合，推进到敌方阶段。在 PlayerPhase 之外没有任何效果。

ApplyReward

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

参数：

• choice：选中的奖励类型（卡牌、能量或费用折扣）。
• pickedCard：choice 为 RewardChoice.Card 时选中的卡；其余情况传 null。

效果： 应用玩家对当前奖励的选择（奖励由 OnBattleRewardOffered 提供），结算奖励步骤并触发 OnBattleEnded。自定义奖励界面从这里调用。

SkipReward

public static void SkipReward();

效果： 放弃当前提供的战后奖励并结束战斗。接到奖励 UI 的跳过按钮上。

DisposeBattle

public static void DisposeBattle();

效果： 拆除活动战斗状态机并清空当前战斗。持久化的 master deck 和 run 加成不受影响，只有进行中的战斗被丢弃。

在没打完就离开战斗场景，或重置测试时调用。

---

战斗状态

Phase

public static BattlePhase Phase { get; }

返回： 当前战斗阶段；没有战斗时为 BattlePhase.None。

IsBattleActive

public static bool IsBattleActive { get; }

返回： 战斗进行中为 true：已开始且尚未分出胜负。

IsBattleOver

public static bool IsBattleOver { get; }

返回： 当前战斗已结束时为 true，即处于 BattleWon 或 BattleLost。

IsWaitingForChoice

public static bool IsWaitingForChoice { get; }

返回： 战斗暂停、等待玩家解决卡牌效果选择时为 true（见 OnEffectChoiceOffered）。

IsWaitingForReward

public static bool IsWaitingForReward { get; }

返回： 战斗暂停、等待玩家解决战后奖励时为 true（见 OnBattleRewardOffered）。

TurnNumber

public static int TurnNumber { get; }

返回： 当前战斗回合数，从 1 开始；没有战斗时为 0。

IsPlayerTurn

public static bool IsPlayerTurn { get; }

返回： 当前处于玩家回合（相对敌方阶段而言）时为 true。

---

玩家、单位与能量

Player

public static UnitState Player();

返回： 当前战斗中的玩家单位；没有战斗时为 null。

PlayerEnergy

public static int PlayerEnergy { get; }

返回： 玩家当前能量；没有战斗时为 0。

MaxEnergy

public static int MaxEnergy { get; }

返回： 玩家每回合的能量上限，含 run 加成和每回合能量 Hook；没有战斗时为 0。

AliveEnemies

public static IReadOnlyList<UnitState> AliveEnemies();

返回： 当前战斗中存活的敌方单位。永不为 null。

FirstAliveEnemy

public static UnitState FirstAliveEnemy();

返回： 第一个存活的敌方单位；一个都不剩时为 null。作默认目标很顺手。

EnemyCount

public static int EnemyCount();

返回： 当前战斗中存活敌方单位的数量。

AllUnits

public static IReadOnlyList<UnitState> AllUnits();

返回： 当前战斗中所有存活单位，玩家在前、存活敌人在后。永不为 null。

每次调用都分配一个新列表，逐帧读取时请缓存结果。

Hp

public static int Hp(UnitState unit);

返回： 单位当前 HP；unit 为 null 时返回 0。

MaxHp

public static int MaxHp(UnitState unit);

返回： 单位最大 HP；unit 为 null 时返回 0。

Armor

public static int Armor(UnitState unit);

返回： 单位当前护甲（格挡）；unit 为 null 时返回 0。

HpPercent

public static int HpPercent(UnitState unit);

返回： 单位 HP 占最大值的整数百分比，0 到 100；unit 为 null 时返回 0。

IsDead

public static bool IsDead(UnitState unit);

返回： 单位已死亡时为 true。null 的单位视为已死亡。

IsAlive

public static bool IsAlive(UnitState unit);

返回： 单位非 null 且还有 HP 时为 true。

---

敌人意图

CurrentIntentTag

public static IntentTag CurrentIntentTag(UnitState enemy);

返回： 敌人下回合计划行动的类别（攻击、防御、增益、减益等）。null 或非敌方单位返回 IntentTag.Unknown。

CurrentIntentValue

public static int CurrentIntentValue(UnitState enemy);

返回： 敌人计划行动展示的数字，比如即将造成的伤害或格挡值。没有数字可展示时返回 -1：无数值意图、隐藏意图或非敌方单位。

PendingIntents

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

返回： 敌人下回合计划的完整意图条目列表（一个敌人可能预告多个动作），给出的是未经整形的原始意图。永不为 null。

遭遇战的意图显示模式不作用于这里，只作用于 OnEnemyUnitIntentChanged 事件的 payload。想要真实计划就读这个方法，想要玩家该看到的内容就用事件 payload。

---

牌堆与卡牌查询

CurrentHand

public static IReadOnlyList<CardInstance> CurrentHand { get; }

返回： 玩家手牌中的卡；没有战斗时为 null。

与 Hand() 等价，区别只在战斗外的取值：这个属性返回 null，Hand() 返回空列表，与 GameCardManager.CurrentHand 保持一致。

Hand

public static IReadOnlyList<CardInstance> Hand();

返回： 玩家当前手牌。永不为 null。

DrawPile

public static IReadOnlyList<CardInstance> DrawPile();

返回： 玩家当前抽牌堆。永不为 null。堆顶是最后一个元素，下一张要抽的牌是 DrawPile()[DrawPile().Count - 1]。

DiscardPile

public static IReadOnlyList<CardInstance> DiscardPile();

返回： 玩家当前弃牌堆。永不为 null。

ExhaustPile

public static IReadOnlyList<CardInstance> ExhaustPile();

返回： 玩家当前消耗（exhaust）牌堆。永不为 null。

PlayedThisTurn

public static IReadOnlyList<CardInstance> PlayedThisTurn();

返回： 本回合打出的卡牌实例，按打出顺序排列。永不为 null。

DrawnThisTurn

public static IReadOnlyList<CardInstance> DrawnThisTurn();

返回： 本回合抽到的卡牌实例，按抽取顺序排列。永不为 null。

GetEffectiveEnergyCost

public static int GetEffectiveEnergyCost(CardInstance card);

返回： 卡牌实例经战斗调整后的能量费用，计入单卡 modifier、run 级费用增减和出牌费用 Hook。卡为 null 或没有战斗时返回 0。

费用角标该显示的是这个数，不是卡牌资产上的基础费用。

GetActiveCard

public static GameCard GetActiveCard(CardInstance card);

返回： 实例背后实际生效的卡牌定义：实例已升级时是升级形态，否则是基础卡。实例为 null 时返回 null。

IsUpgraded

public static bool IsUpgraded(CardInstance card);

返回： 卡牌实例当前处于升级形态时为 true。

FormatDescription

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

参数：

• card：要格式化描述文本的卡牌。
• instance：可选的活动实例，用于解析实例相关数值（升级状态、费用增减）。传 null 则按基础定义格式化。

返回： 把 {Damage}、{Stacks:Poison} 这类 token 解析成最终显示文本后的描述；卡为 null 时返回空字符串。

token 通过 DescriptionTokenRegistry 解析，你注册的自定义 IDescriptionToken 会自动参与。自定义卡牌视图想显示与 GCS 自带 UI 相同的文本时用它。

---

状态查询

GetStatusStacks

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

返回： 该状态在单位身上的层数；单位没有这个状态或 unit 为 null 时为 0。

HasStatus

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

返回： 单位持有至少 minStacks 层该状态时为 true。minStacks 默认为 1。

GetStatusApplier

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

返回： 最初施加该状态的单位；未知时为 null。做反击类效果（打回施加者）时有用。

StatusesOn

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

返回： 单位身上当前每个状态到层数的映射。永不为 null。

返回的是单位状态表的实时视图，只做读取，不要跨修改缓存它。

---

战斗修改

由 controller 支撑的操作

下面每个 helper 都转发给活动战斗的 controller，没有战斗在跑时什么也不做。它们执行与内置 FlowGraph 节点相同的规则、触发相同的事件，所以请用它们，不要直接改运行时状态字段。

DealDamage

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

参数：

• target：要伤害的单位。
• amount：减免前的原始伤害。
• attacker：记为攻击者的单位，启用造成伤害类 Hook 和击杀归属。无归属的直接伤害传 null。
• bypassArmor：为 true 时伤害无视护甲，直接扣 HP。

效果： 走完整管线造成伤害：护甲吸收、伤害修正 Hook（Vulnerable、Weak、Strength）、死亡判定，以及 Thorns 这类反应触发。效果等同一个 Deal Damage 节点。

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

LoseHp

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

效果： 直接扣减单位 HP，无视护甲，但仍会运行失血 Hook 和死亡判定。

Heal

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

效果： 治疗单位，以最大 HP 为上限。

SetHp

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

效果： 把单位当前 HP 设为指定值，并收在有效范围内。

GainArmor

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

效果： 按护甲获取规则给单位增加护甲（格挡）。

LoseArmor

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

效果： 移除单位护甲，下限为 0。

SetArmor

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

效果： 把单位护甲设为指定值。

KillUnit

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

效果： 立即把单位打到 0 HP。可选的 source 记为击杀触发的归属者。

ReviveUnit

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

效果： 把死亡单位复活到最大 HP 的一定比例。hpPercent 取 0 到 1，0.5f 就是半血。

GainEnergy

public static void GainEnergy(int amount);

效果： 给玩家增加能量。不封顶：能量可以超出每回合上限。

LoseEnergy

public static void LoseEnergy(int amount);

效果： 扣减玩家能量，下限为 0。

SetEnergy

public static void SetEnergy(int value);

效果： 把玩家能量设为指定值，以每回合上限封顶。

DrawCards

public static void DrawCards(int count);

效果： 从抽牌堆抽卡进手牌。抽牌堆抽空时弃牌堆会洗回来，抽到手牌上限即停。

ApplyStatus

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

参数：

• target：接受状态的单位。
• status：要施加的状态资产。
• stacks：层数，必须为正数才有效果。
• source：记为施加者的单位，供反击类效果查询。可选。

效果： 按状态自身的叠层规则（叠加、取最大或替换）和层数上限施加层数，并运行施加与承受两侧的 Hook。

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

RemoveStatus

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

效果： 从单位身上移除若干层状态。传负数则整个移除该状态。

ModifyStatusStacks

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

效果： 按带符号的 delta 调整层数，绕过施加管线：不触发施加与承受 Hook，也不做叠层规则重算。想要正常的施加语义时用 ApplyStatus。

AddCardToHand

public static CardInstance AddCardToHand(GameCard card);

效果： 把卡牌定义实例化进玩家手牌；手牌已满时进弃牌堆。

返回： 创建出的卡牌实例；没有战斗时为 null。

MoveCardToPile

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

效果： 把已有的卡牌实例移动到另一个牌堆。

ShuffleDrawPile

public static void ShuffleDrawPile();

效果： 随机洗玩家的抽牌堆。

GrantExtraTurn

public static void GrantExtraTurn();

效果： 当前回合结算完后，给玩家一个额外回合。

SummonEnemy

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

效果： 向当前战斗召唤一个新的敌方单位。可选的 summoner 记为召唤者。

返回： 生成的敌方单位状态；没有战斗时为 null。

RaiseGameEvent

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

效果： 按名字触发（Raise）一个自定义内部战斗事件。它同时送达代码订阅者和任何通过 On Internal Event 入口节点监听它的卡牌或状态流图，是你的游戏系统通向已编排卡牌行为的桥梁。

GetBattleVariable

public static object GetBattleVariable(string name);

返回： 之前由 SetBattleVariable 或 Set Variable 节点存入的战斗作用域变量；未设置或没有战斗时为 null。

SetBattleVariable

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

效果： 写入一个战斗作用域变量，流图和 GetBattleVariable 都能读到。变量随战斗生灭。

---

内容检索

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

返回： manager 上配置的各内容类型活动数据库。没有活动 manager 时每个方法都返回空列表，永不为 null。

Cards、Decks、PlayerUnits、EnemyUnits、Statuses、Encounters

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

返回： 跨全部活动数据库的该类型全部实体。永不为 null。

缓存浏览器数据

每次调用都会遍历活动数据库并分配新列表。菜单、收藏浏览器和任何高频刷新的面板请缓存结果。

FindCard

public static GameCard FindCard(string guid);

返回： 活动卡牌数据库中匹配该稳定 GUID 的卡牌；没有匹配时为 null。GUID 不受重命名影响，是存档数据和外部工具应该用的键。

FindDeck

public static GameDeck FindDeck(string guid);

返回： 匹配的 GameDeck，或 null。

FindPlayerUnit

public static GamePlayerUnit FindPlayerUnit(string guid);

返回： 匹配的玩家单位资产，或 null。

FindEnemyUnit

public static GameEnemyUnit FindEnemyUnit(string guid);

返回： 匹配的敌方单位资产，或 null。

FindStatus

public static GameStatus FindStatus(string guid);

返回： 匹配的状态资产，或 null。

FindEncounter

public static GameEncounter FindEncounter(string guid);

返回： 匹配的遭遇战资产，或 null。

---

Run 卡组

Master deck 是 run 级的卡牌列表，每场战斗开始时由它生成抽牌堆。它在整个 run 期间跨战斗持久存在，且独立于任何遭遇战预设的起始卡组，所以肉鸽式的获卡、升级和删卡都记录在这里。

GetMasterDeck

public static IReadOnlyList<MasterDeckEntry> GetMasterDeck();

返回： 当前 run 卡组条目。永不为 null。

SetMasterDeck

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

效果： 整体替换持久化 master deck。传 null 则清空。

AddCardToMasterDeck

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

效果： 向 run 卡组添加一条卡牌条目。isUpgraded 控制该条目是否以升级形态起始。

RemoveCardFromMasterDeck

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

效果： 按 GUID 移除匹配的卡牌条目。removeFirstOnly 保持默认 true 时只移除一条匹配；传 false 移除全部匹配。

返回： 至少移除了一条时为 true。

UpgradeCardInMasterDeck

public static bool UpgradeCardInMasterDeck(string cardGuid);

效果： 升级第一条尚未升级的匹配条目。

返回： 有条目被升级时为 true。

ClearMasterDeck

public static void ClearMasterDeck();

效果： 清空 run 卡组并重置 run 级加成。通常在开新 run 时调用。

---

事件

每个订阅方法都返回 IDisposable。在 OnDisable、OnDestroy 或 UI 拆除路径里释放句柄；泄漏的订阅会活过场景重载，继续往已销毁的对象上触发。

Subscribe<TArgs>

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

参数：

• eventName：GCSEventNames 里的事件名常量，或自定义名字。
• handler：事件触发时调用的回调。

返回： 可释放的订阅句柄。

泛型参数必须与事件发布的 payload 类型一致。用不同的 TArgs 订阅一个已被占用的事件名会被拒绝并打错误日志；用不匹配的类型触发也不会调用 handler。经 RaiseGameEvent 触发的自定义事件，payload 以 IReadOnlyDictionary<string, object> 的形式送达。

private IDisposable _sub;

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

void OnDisable()
{
    _sub?.Dispose();
}

Subscribe

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

返回： 无参数事件的可释放订阅句柄。

OnBattleStarted

public static IDisposable OnBattleStarted(Action handler);

触发时机： 战斗启动完成，每场战斗一次。

自定义 UI 重建所有可见战斗面板的天然入口。

OnCardPlayed

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

触发时机： 一张卡被打出。payload 携带卡牌、实例 id 和可选的目标单位 id。

驱动手牌视图、弃牌与消耗计数、战斗日志条目和出牌 VFX。

OnUnitHpChanged

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

触发时机： 单位的 HP 或护甲发生变化。payload 同时携带新值和旧值。

驱动自定义血条、飘字伤害数字和单位头像框。

全部内置事件快捷方法

每个快捷方法都是 Subscribe 加上对应的 GCSEventNames 常量和 payload 类型的封装，返回 IDisposable。

战斗与回合

• OnBattleStarted(Action)：战斗开始时触发一次。
• OnBattleEnded(Action<BattleEndedEventArgs>)：战斗分出胜负时触发一次。
• OnTurnStarted(Action<TurnEventArgs>)：每个玩家回合开始时触发。
• OnEnemyTurnStarted(Action<TurnEventArgs>)：每个敌方阶段开始时触发一次。
• OnTurnEnded(Action<TurnEventArgs>)：每个玩家回合结束时触发。
• OnDrawPhase(Action<TurnEventArgs>)：每个玩家回合的抽牌步骤触发。
• OnDiscardPhase(Action<TurnEventArgs>)：每个玩家回合的弃牌步骤触发。
• OnDrawPileShuffled(Action)：抽牌堆被洗牌时触发。

卡牌

• OnCardPlayed(Action<CardPlayedEventArgs>)：任何卡被打出时触发。
• OnCardModified(Action<CardModifiedEventArgs>)：卡牌的运行时费用或状态变化时触发。
• OnCardDrawn(Action<CardLifecycleEventArgs>)：每有一张卡抽进手牌就触发。
• OnCardDiscarded(Action<CardLifecycleEventArgs>)：卡被弃掉时触发，无论是溢出还是回合结束。
• OnCardExhausted(Action<CardLifecycleEventArgs>)：卡被消耗（exhaust）时触发。
• OnCardRetained(Action<CardLifecycleEventArgs>)：卡在回合结束时被保留在手牌时触发。
• OnCardAddedToHand(Action<CardLifecycleEventArgs>)：卡被直接创建进手牌时触发。
• OnCardAddedToDeck(Action<CardLifecycleEventArgs>)：卡被加入抽牌堆时触发。

单位与伤害

• OnUnitHpChanged(Action<UnitHpChangedEventArgs>)：单位 HP 或护甲变化时触发。
• OnUnitDied(Action<UnitDiedEventArgs>)：单位死亡或被移除时触发。
• OnDamageDealt(Action<DamageEventArgs>)：攻击者造成伤害时触发；payload 含是否致命。
• OnDamageTaken(Action<DamageEventArgs>)：单位承受伤害时触发，来源可以是攻击或状态。
• OnArmorGained(Action<ArmorChangedEventArgs>)：单位获得护甲时触发。
• OnArmorLost(Action<ArmorChangedEventArgs>)：单位失去护甲时触发。
• OnEnemyUnitIntentChanged(Action<EnemyUnitIntentChangedEventArgs>)：敌人重新规划意图时触发。
• OnEnemyUnitSummoned(Action<EnemyUnitSummonedEventArgs>)：战斗中有敌人被召唤时触发。
• OnEnemyPhaseChanged(Action<EnemyPhaseChangedEventArgs>)：敌方阶段推进时触发。

状态与能量

• OnStatusChanged(Action<StatusChangedEventArgs>)：单位的状态层数变化时触发。
• OnStatusTicked(Action<StatusTickedEventArgs>)：状态在回合边界结算时触发。
• OnStatusInflicted(Action<StatusTransitionEventArgs>)：状态被施加到单位时触发。
• OnStatusExpired(Action<StatusTransitionEventArgs>)：状态自然衰减到 0 层时触发。
• OnStatusRemoved(Action<StatusTransitionEventArgs>)：状态被显式移除时触发。
• OnEnergyChanged(Action<EnergyChangedEventArgs>)：玩家能量或能量上限变化时触发。
• OnEnergyGained(Action<EnergyDeltaEventArgs>)：玩家获得能量时触发。
• OnEnergySpent(Action<EnergyDeltaEventArgs>)：玩家花费能量时触发。

选择与延迟触发

• OnDelayedTriggerScheduled(Action<DelayedTriggerScheduledEventArgs>)：跨回合效果入队时触发。
• OnDelayedTriggerFired(Action<DelayedTriggerFiredEventArgs>)：入队的跨回合效果结算时触发。
• OnDelayedTriggerCancelled(Action<DelayedTriggerCancelledEventArgs>)：入队的跨回合效果被取消时触发。
• OnBattleRewardOffered(Action<BattleRewardOfferedEventArgs>)：战后奖励可选时触发。
• OnBattleRewardSelected(Action<BattleRewardSelectedEventArgs>)：玩家选中奖励时触发。
• OnBattleRewardSkipped(Action)：玩家放弃奖励时触发。
• OnEffectChoiceOffered(Action<EffectChoiceOfferedEventArgs>)：卡牌效果暂停等待玩家选择时触发。
• OnEffectChoiceSelected(Action<EffectChoiceSelectedEventArgs>)：玩家做出效果选择时触发。
• OnEffectChoiceSkipped(Action)：效果选择被跳过时触发。

事件名常量和 payload 字段见事件参考。

---

扩展注册表

NodeTypes

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

返回： 所有已注册的流图节点类型，内置节点加上用户程序集中发现的自定义 [FlowNode] 类。注册表只扫描一次已加载的程序集。

CardTypes

public static IReadOnlyCollection<CardType> CardTypes();

返回： 所有已注册的卡牌类型，含自定义 [CardType] 分类。

CardTags

public static IReadOnlyCollection<CardTag> CardTags();

返回： 所有已注册的卡牌标签，含自定义 [CardTag] 分类。

DescriptionTokens

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

返回： 所有已注册的描述 token，含 FormatDescription 使用的自定义 [DescriptionToken] 解析器。