API 参考

Guide

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

命名空间

所有成员都定义在 TinyGiants.GCS.Runtime.GCSApi

using TinyGiants.GCS.Runtime;

整体约定

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

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

只在 Unity 主线程调用
活动战斗存在于 StartBattle 与 DisposeBattle（或下一次 StartBattle）之间，在此范围之外，集合访问器返回空列表，数值访问器返回安全默认值（0、false、BattlePhase.None），修改方法不执行操作，唯一例外是 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

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

它为 null 时，facade 的大多数成员会退化成空操作或安全默认值，所以很少需要直接读取它，判空使用 IsReady 更清楚，日常操作优先使用下面的具名 helper，以保持与公开 API 的空值和事件语义一致

示例：

GameCardManager manager = GCSApi.Manager;

IsReady

public static bool IsReady { get; }

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

示例：

if (!GCSApi.IsReady)
{
    return;
}

Battle

public static IBattleState Battle { get; }

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

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

示例：

IBattleState battle = GCSApi.Battle;

Controller

public static IBattleController Controller { get; }

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

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

修改边界

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

示例：

IBattleController controller = GCSApi.Controller;

Events

public static IGCSEventChannel Events { get; }

返回： GCS 核心事件通道

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

示例：

IGCSEventChannel channel = GCSApi.Events;

战斗控制

StartBattle

public static void StartBattle(GameEncounter encounter);

参数：

名称	类型	说明
`encounter`	`GameEncounter`	定义这场战斗：玩家单位、敌人阵容、奖励池和规则，传 `null` 时调用被忽略

返回： 无返回值（void），满足运行条件时执行对应操作

效果： 启动一场新战斗，抽牌堆从持久化的 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`	`CardInstance`	要打出的手牌实例
`target`	`UnitState`	目标模式为单体敌人的卡需要的目标单位，其余情况传 `null`，自我、全体敌人和无目标的卡由引擎自动解析目标

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

示例：

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

CanPlayCard

public static bool CanPlayCard(CardInstance card);

参数：

名称	类型	说明
`card`	`CardInstance`	卡牌实例

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

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

示例：

bool result = GCSApi.CanPlayCard(cardInstance);

RequiresTarget

public static bool RequiresTarget(GameCard card);

参数：

名称	类型	说明
`card`	`GameCard`	卡牌定义

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

示例：

var activeCard = GCSApi.GetActiveCard(cardInstance);

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

EndPlayerTurn

public static void EndPlayerTurn();

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.EndPlayerTurn();

ApplyReward

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

参数：

名称	类型	说明
`choice`	`RewardChoice`	选中的奖励类型（卡牌、能量或费用折扣）
`pickedCard`	`GameCard`	`choice` 为 `RewardChoice.Card` 时选中的卡；其余情况传 `null`

选择	对本局 Run 的影响
`RewardChoice.Card`	把 `pickedCard` 作为未升级卡加入当前 master deck，传入 `null` 时不添加卡牌
`RewardChoice.Energy`	后续战斗的每回合能量增加 `1`

| RewardChoice.Cost | 当前 master deck 中每张卡的费用变化减少 1，之后新加入的卡不继承这次减费 |

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.ApplyReward(RewardChoice.Card, rewardCard);

SkipReward

public static void SkipReward();

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.SkipReward();

DisposeBattle

public static void DisposeBattle();

返回： 无返回值（void），满足运行条件时执行对应操作

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

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

示例：

GCSApi.DisposeBattle();

战斗状态

Phase

public static BattlePhase Phase { get; }

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

示例：

BattlePhase value = GCSApi.Phase;

IsBattleActive

public static bool IsBattleActive { get; }

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

示例：

bool value = GCSApi.IsBattleActive;

IsBattleOver

public static bool IsBattleOver { get; }

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

示例：

bool value = GCSApi.IsBattleOver;

IsWaitingForChoice

public static bool IsWaitingForChoice { get; }

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

示例：

bool value = GCSApi.IsWaitingForChoice;

IsWaitingForReward

public static bool IsWaitingForReward { get; }

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

示例：

bool value = GCSApi.IsWaitingForReward;

TurnNumber

public static int TurnNumber { get; }

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

示例：

int value = GCSApi.TurnNumber;

IsPlayerTurn

public static bool IsPlayerTurn { get; }

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

示例：

bool value = GCSApi.IsPlayerTurn;

玩家、单位与能量

Player

public static UnitState Player();

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

示例：

UnitState result = GCSApi.Player();

PlayerEnergy

public static int PlayerEnergy { get; }

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

示例：

int value = GCSApi.PlayerEnergy;

MaxEnergy

public static int MaxEnergy { get; }

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

示例：

int value = GCSApi.MaxEnergy;

AliveEnemies

public static IReadOnlyList<UnitState> AliveEnemies();

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

示例：

var result = GCSApi.AliveEnemies();

FirstAliveEnemy

public static UnitState FirstAliveEnemy();

返回： 第一个存活的敌方单位；没有存活敌人时返回 null，适合作为默认目标

示例：

UnitState result = GCSApi.FirstAliveEnemy();

EnemyCount

public static int EnemyCount();

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

示例：

int result = GCSApi.EnemyCount();

AllUnits

public static IReadOnlyList<UnitState> AllUnits();

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

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

示例：

var result = GCSApi.AllUnits();

Hp

public static int Hp(UnitState unit);

参数：

名称	类型	说明
`unit`	`UnitState`	要读取或修改的单位

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

示例：

int result = GCSApi.Hp(unit);

MaxHp

public static int MaxHp(UnitState unit);

参数：

名称	类型	说明
`unit`	`UnitState`	要读取或修改的单位

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

示例：

int result = GCSApi.MaxHp(unit);

Armor

public static int Armor(UnitState unit);

参数：

名称	类型	说明
`unit`	`UnitState`	要读取或修改的单位

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

示例：

int result = GCSApi.Armor(unit);

HpPercent

public static int HpPercent(UnitState unit);

参数：

名称	类型	说明
`unit`	`UnitState`	要读取或修改的单位

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

示例：

int result = GCSApi.HpPercent(unit);

IsDead

public static bool IsDead(UnitState unit);

参数：

名称	类型	说明
`unit`	`UnitState`	要读取或修改的单位

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

示例：

bool result = GCSApi.IsDead(unit);

IsAlive

public static bool IsAlive(UnitState unit);

参数：

名称	类型	说明
`unit`	`UnitState`	要读取或修改的单位

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

示例：

bool result = GCSApi.IsAlive(unit);

敌人意图

CurrentIntentTag

public static IntentTag CurrentIntentTag(UnitState enemy);

参数：

名称	类型	说明
`enemy`	`UnitState`	要读取的敌方单位

返回： 敌人下回合计划行动的类别（攻击、防御、增益、减益等），null 或非敌方单位返回 IntentTag.Unknown；创作时选择 IntentKind.Hidden 也会返回 IntentTag.Unknown，因此这个 API 不会泄露隐藏计划

示例：

IntentTag result = GCSApi.CurrentIntentTag(enemy);

CurrentIntentValue

public static int CurrentIntentValue(UnitState enemy);

参数：

名称	类型	说明
`enemy`	`UnitState`	要读取的敌方单位

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

示例：

int result = GCSApi.CurrentIntentValue(enemy);

PendingIntents

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

参数：

名称	类型	说明
`enemy`	`UnitState`	要读取的敌方单位

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

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

示例：

var result = GCSApi.PendingIntents(enemy);

牌堆与卡牌查询

CurrentHand

public static IReadOnlyList<CardInstance> CurrentHand { get; }

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

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

示例：

var value = GCSApi.CurrentHand;

Hand

public static IReadOnlyList<CardInstance> Hand();

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

示例：

var result = GCSApi.Hand();

DrawPile

public static IReadOnlyList<CardInstance> DrawPile();

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

示例：

var result = GCSApi.DrawPile();

DiscardPile

public static IReadOnlyList<CardInstance> DiscardPile();

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

示例：

var result = GCSApi.DiscardPile();

ExhaustPile

public static IReadOnlyList<CardInstance> ExhaustPile();

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

示例：

var result = GCSApi.ExhaustPile();

PlayedThisTurn

public static IReadOnlyList<CardInstance> PlayedThisTurn();

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

示例：

var result = GCSApi.PlayedThisTurn();

DrawnThisTurn

public static IReadOnlyList<CardInstance> DrawnThisTurn();

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

示例：

var result = GCSApi.DrawnThisTurn();

GetEffectiveEnergyCost

public static int GetEffectiveEnergyCost(CardInstance card);

参数：

名称	类型	说明
`card`	`CardInstance`	卡牌实例

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

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

示例：

int result = GCSApi.GetEffectiveEnergyCost(cardInstance);

GetActiveCard

public static GameCard GetActiveCard(CardInstance card);

参数：

名称	类型	说明
`card`	`CardInstance`	卡牌实例

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

示例：

GameCard result = GCSApi.GetActiveCard(cardInstance);

IsUpgraded

public static bool IsUpgraded(CardInstance card);

参数：

名称	类型	说明
`card`	`CardInstance`	卡牌实例

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

示例：

bool result = GCSApi.IsUpgraded(cardInstance);

FormatDescription

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

参数：

名称	类型	说明
`card`	`GameCard`	要格式化描述文本的卡牌
`instance`	`CardInstance`	可选的活动实例，用于解析实例相关数值（升级状态、费用增减），传 `null` 则按基础定义格式化

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

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

示例：

string result = GCSApi.FormatDescription(card);

状态查询

GetStatusStacks

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

参数：

名称	类型	说明
`unit`	`UnitState`	要读取或修改的单位
`status`	`GameStatus`	状态定义

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

示例：

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

HasStatus

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

参数：

名称	类型	说明
`unit`	`UnitState`	要读取或修改的单位
`status`	`GameStatus`	状态定义
`minStacks`	`int`	要求的最小层数，默认为 `1`

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

示例：

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

GetStatusApplier

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

参数：

名称	类型	说明
`unit`	`UnitState`	要读取或修改的单位
`status`	`GameStatus`	状态定义

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

示例：

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

StatusesOn

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

参数：

名称	类型	说明
`unit`	`UnitState`	要读取或修改的单位

返回： 单位身上当前每个状态到层数的映射，永不为 null，返回值是单位状态表的实时视图，只用于读取，状态发生修改后应重新获取，不应继续使用修改前缓存的视图

示例：

var result = GCSApi.StatusesOn(unit);

战斗修改

由 controller 支撑的操作

以下方法都转发给活动战斗的 controller；没有活动战斗时不执行操作，它们遵循与内置 FlowGraph 节点相同的规则并触发相同事件，修改战斗状态时应使用这些方法，直接写入运行时状态字段会跳过 Hook、事件和表现层刷新

DealDamage

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

参数：

名称	类型	说明
`target`	`UnitState`	要伤害的单位
`amount`	`int`	减免前的原始伤害
`attacker`	`UnitState`	记为攻击者的单位，启用造成伤害类 Hook 和击杀归属，无归属的直接伤害传 `null`
`bypassArmor`	`bool`	为 `true` 时伤害无视护甲，直接扣 HP

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

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

LoseHp

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

参数：

名称	类型	说明
`target`	`UnitState`	目标单位
`amount`	`int`	要应用的数值

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.LoseHp(target, 10);

Heal

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

参数：

名称	类型	说明
`target`	`UnitState`	目标单位
`amount`	`int`	要应用的数值

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.Heal(target, 10);

SetHp

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

参数：

名称	类型	说明
`target`	`UnitState`	目标单位
`value`	`int`	新的绝对值

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.SetHp(target, 10);

GainArmor

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

参数：

名称	类型	说明
`target`	`UnitState`	目标单位
`amount`	`int`	要应用的数值

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.GainArmor(target, 10);

LoseArmor

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

参数：

名称	类型	说明
`target`	`UnitState`	目标单位
`amount`	`int`	要应用的数值

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.LoseArmor(target, 10);

SetArmor

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

参数：

名称	类型	说明
`target`	`UnitState`	目标单位
`value`	`int`	新的绝对值

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.SetArmor(target, 10);

KillUnit

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

参数：

名称	类型	说明
`target`	`UnitState`	目标单位
`source`	`UnitState`	可选的来源单位

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.KillUnit(target);

ReviveUnit

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

参数：

名称	类型	说明
`target`	`UnitState`	目标单位
`hpPercent`	`float`	复活后恢复的最大 HP 比例，取值 `0` 到 `1`

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.ReviveUnit(target, 0.5f);

GainEnergy

public static void GainEnergy(int amount);

参数：

名称	类型	说明
`amount`	`int`	要应用的数值

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.GainEnergy(10);

LoseEnergy

public static void LoseEnergy(int amount);

参数：

名称	类型	说明
`amount`	`int`	要应用的数值

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.LoseEnergy(10);

SetEnergy

public static void SetEnergy(int value);

参数：

名称	类型	说明
`value`	`int`	新的绝对值

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.SetEnergy(10);

DrawCards

public static void DrawCards(int count);

参数：

名称	类型	说明
`count`	`int`	卡牌数量

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.DrawCards(2);

ApplyStatus

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

参数：

名称	类型	说明
`target`	`UnitState`	接受状态的单位
`status`	`GameStatus`	要施加的状态资产
`stacks`	`int`	层数，必须为正数才有效果
`source`	`UnitState`	记为施加者的单位，供反击类效果查询，可选

返回： 无返回值（void），满足运行条件时执行对应操作

效果： 按状态自身的叠层规则（叠加、取最大或替换）和层数上限施加层数，并运行施加与承受两侧的 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);

参数：

名称	类型	说明
`target`	`UnitState`	目标单位
`status`	`GameStatus`	状态定义
`stacks`	`int`	状态层数

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.RemoveStatus(target, status, 2);

ModifyStatusStacks

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

参数：

名称	类型	说明
`target`	`UnitState`	目标单位
`status`	`GameStatus`	状态定义
`delta`	`int`	带符号的层数变化，正数增加、负数减少

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

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

AddCardToHand

public static CardInstance AddCardToHand(GameCard card);

参数：

名称	类型	说明
`card`	`GameCard`	卡牌定义

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

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

示例：

CardInstance result = GCSApi.AddCardToHand(card);

MoveCardToPile

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

参数：

名称	类型	说明
`card`	`CardInstance`	卡牌实例
`pile`	`PileScope`	目标牌堆

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.MoveCardToPile(cardInstance, PileScope.Discard);

ShuffleDrawPile

public static void ShuffleDrawPile();

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.ShuffleDrawPile();

GrantExtraTurn

public static void GrantExtraTurn();

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.GrantExtraTurn();

SummonEnemy

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

参数：

名称	类型	说明
`enemy`	`GameEnemyUnit`	要读取的敌方单位
`summoner`	`UnitState`	可选的召唤来源单位

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

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

示例：

EnemyUnitState result = GCSApi.SummonEnemy(enemy);

RaiseGameEvent

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

参数：

名称	类型	说明
`eventName`	`string`	事件名
`args`	`IReadOnlyDictionary<string, object>`	可选的事件载荷

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.RaiseGameEvent("MyCustomEvent");

GetBattleVariable

public static object GetBattleVariable(string name);

参数：

名称	类型	说明
`name`	`string`	变量名

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

示例：

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

SetBattleVariable

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

参数：

名称	类型	说明
`name`	`string`	变量名
`value`	`object`	新的绝对值

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.SetBattleVariable("ComboCount", 10);

内容检索

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

示例：

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

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

缓存浏览器数据

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

示例：

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

FindCard

public static GameCard FindCard(string guid);

参数：

名称	类型	说明
`guid`	`string`	资源的稳定 GUID

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

示例：

GameCard result = GCSApi.FindCard(guid);

FindDeck

public static GameDeck FindDeck(string guid);

参数：

名称	类型	说明
`guid`	`string`	资源的稳定 GUID

返回： 匹配的 GameDeck，或 null

示例：

GameDeck result = GCSApi.FindDeck(guid);

FindPlayerUnit

public static GamePlayerUnit FindPlayerUnit(string guid);

参数：

名称	类型	说明
`guid`	`string`	资源的稳定 GUID

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

示例：

GamePlayerUnit result = GCSApi.FindPlayerUnit(guid);

FindEnemyUnit

public static GameEnemyUnit FindEnemyUnit(string guid);

参数：

名称	类型	说明
`guid`	`string`	资源的稳定 GUID

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

示例：

GameEnemyUnit result = GCSApi.FindEnemyUnit(guid);

FindStatus

public static GameStatus FindStatus(string guid);

参数：

名称	类型	说明
`guid`	`string`	资源的稳定 GUID

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

示例：

GameStatus result = GCSApi.FindStatus(guid);

FindEncounter

public static GameEncounter FindEncounter(string guid);

参数：

名称	类型	说明
`guid`	`string`	资源的稳定 GUID

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

示例：

GameEncounter result = GCSApi.FindEncounter(guid);

Run 卡组

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

GetMasterDeck

public static IReadOnlyList<MasterDeckEntry> GetMasterDeck();

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

示例：

var result = GCSApi.GetMasterDeck();

SetMasterDeck

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

参数：

名称	类型	说明
`entries`	`IList<MasterDeckEntry>`	run deck 条目

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.SetMasterDeck(entries);

AddCardToMasterDeck

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

参数：

名称	类型	说明
`card`	`GameCard`	卡牌定义
`isUpgraded`	`bool`	卡牌是否从升级状态开始

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.AddCardToMasterDeck(card);

RemoveCardFromMasterDeck

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

参数：

名称	类型	说明
`cardGuid`	`string`	卡牌的稳定 GUID
`removeFirstOnly`	`bool`	`true` 只移除一个匹配项，`false` 移除全部匹配项

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

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

示例：

bool result = GCSApi.RemoveCardFromMasterDeck(cardGuid);

UpgradeCardInMasterDeck

public static bool UpgradeCardInMasterDeck(string cardGuid);

参数：

名称	类型	说明
`cardGuid`	`string`	卡牌的稳定 GUID

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

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

示例：

bool result = GCSApi.UpgradeCardInMasterDeck(cardGuid);

ClearMasterDeck

public static void ClearMasterDeck();

返回： 无返回值（void），满足运行条件时执行对应操作

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

示例：

GCSApi.ClearMasterDeck();

事件

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

Subscribe<TArgs>

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

参数：

名称	类型	说明
`eventName`	`string`	`GCSEventNames` 里的事件名常量，或自定义名字
`handler`	`Action<TArgs>`	事件触发时调用的回调

返回： 可释放的订阅句柄

泛型参数必须与事件发布的 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);

参数：

名称	类型	说明
`eventName`	`string`	内置常量或自定义无参事件名
`handler`	`Action`	事件触发时调用的无参回调

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

示例：

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

OnBattleStarted

public static IDisposable OnBattleStarted(Action handler);

参数：

名称	类型	说明
`handler`	`Action`	事件触发时调用的回调

返回： IDisposable 订阅句柄，调用 Dispose() 可取消订阅

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

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

示例：

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

OnCardPlayed

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

参数：

名称	类型	说明
`handler`	`Action<CardPlayedEventArgs>`	接收载荷的强类型回调

返回： IDisposable 订阅句柄，调用 Dispose() 可取消订阅

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

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

示例：

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

OnUnitHpChanged

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

参数：

名称	类型	说明
`handler`	`Action<UnitHpChangedEventArgs>`	接收载荷的强类型回调

返回： IDisposable 订阅句柄，调用 Dispose() 可取消订阅

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

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

示例：

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

全部内置事件快捷方法

每个快捷方法都是 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] 类，注册表只扫描一次已加载的程序集

示例：

var result = GCSApi.NodeTypes();

CardTypes

public static IReadOnlyCollection<CardType> CardTypes();

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

示例：

var result = GCSApi.CardTypes();

CardTags

public static IReadOnlyCollection<CardTag> CardTags();

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

示例：

var result = GCSApi.CardTags();

DescriptionTokens

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

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

示例：

var result = GCSApi.DescriptionTokens();

整体约定​

成员速查​

Manager 与通道​

战斗控制​

战斗状态​

玩家、单位与能量​

敌人意图​

牌堆与卡牌查询​

状态查询​

战斗修改​

内容检索​

Run 卡组​

事件​

扩展注册表​

整体约定

成员速查

Manager 与通道

战斗控制

战斗状态

玩家、单位与能量

敌人意图

牌堆与卡牌查询

状态查询

战斗修改

内容检索

Run 卡组

事件

扩展注册表