事件参考

📡

Guide

先按事件类别完成速查，再展开查看事件名、载荷参数、触发时机与订阅示例

事件速查只保留定位所需的信息，完整细节放在下方每个事件的折叠项中，这些事件名与 Game Card Monitor 的 Event 页签完全一致

上图展示了事件在实际战斗中的时间顺序，先在分类速查中定位所需事件，再展开对应条目查看事件名、Payload、精确时机和订阅签名

事件速查

战斗与回合

事件	载荷	触发时机
OnBattleStarted	无	玩家、敌人、战斗牌堆和起始手牌已创建，首组敌人 Intent 尚未保证完成
OnTurnStarted	TurnEventArgs	每个玩家回合开始
OnEnemyTurnStarted	TurnEventArgs	每个敌方阶段开始
OnTurnEnded	TurnEventArgs	每个玩家回合结束
OnDrawPhase	TurnEventArgs	玩家回合进入抽牌步骤
OnDiscardPhase	TurnEventArgs	玩家回合进入弃牌步骤
OnBattleEnded	BattleEndedEventArgs	战斗结算为胜利或失败

卡牌

事件	载荷	触发时机
OnCardPlayed	CardPlayedEventArgs	一次出牌被接受并执行
OnCardModified	CardModifiedEventArgs	卡牌实例完成费用修改、升级或变形
OnCardDrawn	CardLifecycleEventArgs	每张卡通过抽牌进入手牌
OnCardDiscarded	CardLifecycleEventArgs	卡牌因手牌溢出或回合结束清理被弃掉
OnCardExhausted	CardLifecycleEventArgs	卡牌进入消耗牌堆
OnCardRetained	CardLifecycleEventArgs	卡牌在回合结束清理时保留在手牌
OnCardAddedToHand	CardLifecycleEventArgs	卡牌被直接创建到手牌
OnCardAddedToDeck	CardLifecycleEventArgs	卡牌被直接加入抽牌堆
OnDrawPileShuffled	无	抽牌堆完成洗牌

单位与数值

事件	载荷	触发时机
OnUnitHpChanged	UnitHpChangedEventArgs	单位 HP 或护甲发生变化
OnUnitDied	UnitDiedEventArgs	单位死亡或从战斗中被移除
OnDamageDealt	DamageEventArgs	攻击者使目标损失 HP
OnDamageTaken	DamageEventArgs	单位因攻击或状态损失 HP
OnArmorGained	ArmorChangedEventArgs	显式护甲获得操作实际增加护甲
OnArmorLost	ArmorChangedEventArgs	伤害吸收或显式护甲损失实际移除护甲
OnEnergyChanged	EnergyChangedEventArgs	玩家当前能量或能量上限发生变化
OnEnergyGained	EnergyDeltaEventArgs	显式能量获得操作实际增加能量
OnEnergySpent	EnergyDeltaEventArgs	正常卡牌支付正数费用或显式损失能量

状态

事件	载荷	触发时机
OnStatusChanged	StatusChangedEventArgs	单位的状态层数发生变化
OnStatusTicked	StatusTickedEventArgs	状态在回合边界进行结算
OnStatusInflicted	StatusTransitionEventArgs	状态应用让单位的最终层数发生变化
OnStatusExpired	StatusTransitionEventArgs	状态自然衰减到 0 层
OnStatusRemoved	StatusTransitionEventArgs	状态被显式移除

敌人与延迟触发

事件	载荷	触发时机
OnEnemyUnitIntentChanged	EnemyUnitIntentChangedEventArgs	敌人解析或重新规划向玩家公开的意图
OnEnemyUnitActing	EnemyUnitActingEventArgs	敌人即将执行当前意图
OnEnemyUnitSummoned	EnemyUnitSummonedEventArgs	战斗中召唤出敌人
OnEnemyPhaseChanged	EnemyPhaseChangedEventArgs	序列模式推进到另一个创作子阶段
OnDelayedTriggerScheduled	DelayedTriggerScheduledEventArgs	跨回合效果进入队列或倒计时推进
OnDelayedTriggerFired	DelayedTriggerFiredEventArgs	排队 Body 及嵌套延迟恢复路径全部完成
OnDelayedTriggerCancelled	DelayedTriggerCancelledEventArgs	延迟触发器被拒绝登记或取消

奖励与选择

事件	载荷	触发时机
OnBattleRewardOffered	BattleRewardOfferedEventArgs	战后奖励可供玩家选择
OnBattleRewardSelected	BattleRewardSelectedEventArgs	玩家应用一项奖励选择
OnBattleRewardSkipped	无	玩家放弃当前奖励
OnEffectChoiceOffered	EffectChoiceOfferedEventArgs	卡牌效果暂停并等待玩家选择
OnEffectChoiceSelected	EffectChoiceSelectedEventArgs	Presenter 提交的选择集合完成写入
OnEffectChoiceSkipped	无	Choice 被显式跳过或自动回退

战斗与回合事件

OnBattleStarted

玩家、敌人、战斗牌堆和起始手牌创建后触发，此时 Phase 仍为 Initialize，首组敌人 Intent 随后解析，适合初始化基础 HUD 与战斗开场表现；需要刷新 Intent 的 UI 应监听 OnEnemyUnitIntentChanged，或在 StartBattle 返回后读取当前状态

事件标识：

项目	值
常量	GCSEventNames.OnBattleStarted
字符串值	GCS_OnBattleStarted
载荷类型	无

public static IDisposable OnBattleStarted(Action handler);

事件参数：

名称	类型	说明
—	—	此事件没有载荷参数

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

示例：

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

OnTurnStarted

在以下时机触发：每个玩家回合开始 典型用途：回合开始 UI 刷新

事件标识：

项目	值
常量	GCSEventNames.OnTurnStarted
字符串值	GCS_OnTurnStarted
载荷类型	TurnEventArgs

public static IDisposable OnTurnStarted(Action<TurnEventArgs> handler);

事件参数：

名称	类型	说明
TurnNumber	int	当前战斗回合数，从 1 开始

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

示例：

IDisposable subscription = GCSApi.OnTurnStarted(args => Debug.Log(args.TurnNumber));

OnEnemyTurnStarted

在以下时机触发：每个敌方阶段开始 典型用途：敌方阶段横幅与输入锁定

事件标识：

项目	值
常量	GCSEventNames.OnEnemyTurnStarted
字符串值	GCS_OnEnemyTurnStarted
载荷类型	TurnEventArgs

public static IDisposable OnEnemyTurnStarted(Action<TurnEventArgs> handler);

事件参数：

名称	类型	说明
TurnNumber	int	当前战斗回合数，从 1 开始

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

示例：

IDisposable subscription = GCSApi.OnEnemyTurnStarted(args => Debug.Log(args.TurnNumber));

OnTurnEnded

在以下时机触发：每个玩家回合结束 典型用途：回合结束清理与战斗日志

事件标识：

项目	值
常量	GCSEventNames.OnTurnEnded
字符串值	GCS_OnTurnEnded
载荷类型	TurnEventArgs

public static IDisposable OnTurnEnded(Action<TurnEventArgs> handler);

事件参数：

名称	类型	说明
TurnNumber	int	当前战斗回合数，从 1 开始

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

示例：

IDisposable subscription = GCSApi.OnTurnEnded(args => Debug.Log(args.TurnNumber));

OnDrawPhase

在以下时机触发：玩家回合进入抽牌步骤 典型用途：抽牌阶段 UI 与抽牌数量表现

事件标识：

项目	值
常量	GCSEventNames.OnDrawPhase
字符串值	GCS_OnDrawPhase
载荷类型	TurnEventArgs

public static IDisposable OnDrawPhase(Action<TurnEventArgs> handler);

事件参数：

名称	类型	说明
TurnNumber	int	当前战斗回合数，从 1 开始

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

示例：

IDisposable subscription = GCSApi.OnDrawPhase(args => Debug.Log(args.TurnNumber));

OnDiscardPhase

在以下时机触发：玩家回合进入弃牌步骤 典型用途：弃牌阶段 UI 与清理

事件标识：

项目	值
常量	GCSEventNames.OnDiscardPhase
字符串值	GCS_OnDiscardPhase
载荷类型	TurnEventArgs

public static IDisposable OnDiscardPhase(Action<TurnEventArgs> handler);

事件参数：

名称	类型	说明
TurnNumber	int	当前战斗回合数，从 1 开始

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

示例：

IDisposable subscription = GCSApi.OnDiscardPhase(args => Debug.Log(args.TurnNumber));

OnBattleEnded

在以下时机触发：战斗结算为胜利或失败 典型用途：胜利或失败表现

事件标识：

项目	值
常量	GCSEventNames.OnBattleEnded
字符串值	GCS_OnBattleEnded
载荷类型	BattleEndedEventArgs

public static IDisposable OnBattleEnded(Action<BattleEndedEventArgs> handler);

事件参数：

名称	类型	说明
Won	bool	玩家是否赢得战斗

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

示例：

IDisposable subscription = GCSApi.OnBattleEnded(args => Debug.Log(args.Won));

卡牌事件

OnCardPlayed

在以下时机触发：一次出牌被接受并执行 典型用途：出牌动画、战斗日志与连击计数

事件标识：

项目	值
常量	GCSEventNames.OnCardPlayed
字符串值	GCS_OnCardPlayed
载荷类型	CardPlayedEventArgs

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

事件参数：

名称	类型	说明
Card	GameCard	实际打出的有效卡牌定义
InstanceId	int	被打出卡牌实例的运行时 ID
TargetUnitId	int?	选中目标的单位 ID；没有选定目标时为 null

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

示例：

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

OnCardModified

在以下时机触发：卡牌实例增加费用规则、完成有效升级或变形 典型用途：刷新费用、升级或变形后的卡牌 UI；没有升级版本、已经升级或变形结果未改变实例时不会触发

事件标识：

项目	值
常量	GCSEventNames.OnCardModified
字符串值	GCS_OnCardModified
载荷类型	CardModifiedEventArgs

public static IDisposable OnCardModified(Action<CardModifiedEventArgs> handler);

事件参数：

名称	类型	说明
InstanceId	int	发生变化的卡牌实例运行时 ID

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

示例：

IDisposable subscription = GCSApi.OnCardModified(args => Debug.Log(args.InstanceId));

OnCardDrawn

在以下时机触发：每张卡通过抽牌进入手牌 典型用途：抽牌动画与手牌刷新

事件标识：

项目	值
常量	GCSEventNames.OnCardDrawn
字符串值	GCS_OnCardDrawn
载荷类型	CardLifecycleEventArgs

public static IDisposable OnCardDrawn(Action<CardLifecycleEventArgs> handler);

事件参数：

名称	类型	说明
InstanceId	int	受影响卡牌实例的运行时 ID
Card	GameCard	该卡牌实例当前生效的卡牌定义

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

示例：

IDisposable subscription = GCSApi.OnCardDrawn(args => Debug.Log(args.InstanceId));

OnCardDiscarded

在以下时机触发：卡牌因手牌溢出或回合结束清理被弃掉 典型用途：弃牌动画与牌堆刷新

事件标识：

项目	值
常量	GCSEventNames.OnCardDiscarded
字符串值	GCS_OnCardDiscarded
载荷类型	CardLifecycleEventArgs

public static IDisposable OnCardDiscarded(Action<CardLifecycleEventArgs> handler);

事件参数：

名称	类型	说明
InstanceId	int	受影响卡牌实例的运行时 ID
Card	GameCard	该卡牌实例当前生效的卡牌定义

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

示例：

IDisposable subscription = GCSApi.OnCardDiscarded(args => Debug.Log(args.InstanceId));

OnCardExhausted

在以下时机触发：卡牌进入消耗牌堆 典型用途：消耗动画与牌堆刷新

事件标识：

项目	值
常量	GCSEventNames.OnCardExhausted
字符串值	GCS_OnCardExhausted
载荷类型	CardLifecycleEventArgs

public static IDisposable OnCardExhausted(Action<CardLifecycleEventArgs> handler);

事件参数：

名称	类型	说明
InstanceId	int	受影响卡牌实例的运行时 ID
Card	GameCard	该卡牌实例当前生效的卡牌定义

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

示例：

IDisposable subscription = GCSApi.OnCardExhausted(args => Debug.Log(args.InstanceId));

OnCardRetained

在以下时机触发：卡牌在回合结束清理时保留在手牌 典型用途：保留反馈与手牌刷新

事件标识：

项目	值
常量	GCSEventNames.OnCardRetained
字符串值	GCS_OnCardRetained
载荷类型	CardLifecycleEventArgs

public static IDisposable OnCardRetained(Action<CardLifecycleEventArgs> handler);

事件参数：

名称	类型	说明
InstanceId	int	受影响卡牌实例的运行时 ID
Card	GameCard	该卡牌实例当前生效的卡牌定义

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

示例：

IDisposable subscription = GCSApi.OnCardRetained(args => Debug.Log(args.InstanceId));

OnCardAddedToHand

在以下时机触发：卡牌被直接创建到手牌 典型用途：生成卡牌的表现

事件标识：

项目	值
常量	GCSEventNames.OnCardAddedToHand
字符串值	GCS_OnCardAddedToHand
载荷类型	CardLifecycleEventArgs

public static IDisposable OnCardAddedToHand(Action<CardLifecycleEventArgs> handler);

事件参数：

名称	类型	说明
InstanceId	int	受影响卡牌实例的运行时 ID
Card	GameCard	该卡牌实例当前生效的卡牌定义

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

示例：

IDisposable subscription = GCSApi.OnCardAddedToHand(args => Debug.Log(args.InstanceId));

OnCardAddedToDeck

在以下时机触发：卡牌被直接加入抽牌堆 典型用途：加牌反馈与牌堆刷新

事件标识：

项目	值
常量	GCSEventNames.OnCardAddedToDeck
字符串值	GCS_OnCardAddedToDeck
载荷类型	CardLifecycleEventArgs

public static IDisposable OnCardAddedToDeck(Action<CardLifecycleEventArgs> handler);

事件参数：

名称	类型	说明
InstanceId	int	受影响卡牌实例的运行时 ID
Card	GameCard	该卡牌实例当前生效的卡牌定义

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

示例：

IDisposable subscription = GCSApi.OnCardAddedToDeck(args => Debug.Log(args.InstanceId));

OnDrawPileShuffled

在以下时机触发：抽牌堆完成洗牌 典型用途：洗牌动画与牌堆计数刷新

事件标识：

项目	值
常量	GCSEventNames.OnDrawPileShuffled
字符串值	GCS_OnDrawPileShuffled
载荷类型	无

public static IDisposable OnDrawPileShuffled(Action handler);

事件参数：

名称	类型	说明
—	—	此事件没有载荷参数

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

示例：

IDisposable subscription = GCSApi.OnDrawPileShuffled(() => Debug.Log("OnDrawPileShuffled"));

单位、HP、护甲、伤害与能量事件

OnUnitHpChanged

在以下时机触发：单位 HP 或护甲发生变化 典型用途：HP 与护甲条

事件标识：

项目	值
常量	GCSEventNames.OnUnitHpChanged
字符串值	GCS_OnUnitHpChanged
载荷类型	UnitHpChangedEventArgs

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

事件参数：

名称	类型	说明
UnitId	int	受影响单位的运行时 ID
CurrentHp	int	变化后的 HP
MaxHp	int	单位最大 HP
CurrentArmor	int	变化后的护甲
PreviousHp	int	变化前的 HP
PreviousArmor	int	变化前的护甲

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

示例：

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

OnUnitDied

在以下时机触发：单位死亡或从战斗中被移除 典型用途：死亡表现、奖励与目标清理

事件标识：

项目	值
常量	GCSEventNames.OnUnitDied
字符串值	GCS_OnUnitDied
载荷类型	UnitDiedEventArgs

public static IDisposable OnUnitDied(Action<UnitDiedEventArgs> handler);

事件参数：

名称	类型	说明
UnitId	int	死亡或被移除单位的运行时 ID
Tier	string	创作时配置的单位层级

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

示例：

IDisposable subscription = GCSApi.OnUnitDied(args => Debug.Log(args.UnitId));

OnDamageDealt

在以下时机触发：攻击者使目标损失 HP 典型用途：输出伤害日志与命中反馈

事件标识：

项目	值
常量	GCSEventNames.OnDamageDealt
字符串值	GCS_OnDamageDealt
载荷类型	DamageEventArgs

public static IDisposable OnDamageDealt(Action<DamageEventArgs> handler);

事件参数：

名称	类型	说明
SourceUnitId	int	来源单位 ID；没有单位来源时为 -1
TargetUnitId	int	受伤单位的运行时 ID
Amount	int	经过护甲与修正后实际损失的 HP
Lethal	bool	这次伤害是否击杀目标

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

示例：

IDisposable subscription = GCSApi.OnDamageDealt(args => Debug.Log(args.SourceUnitId));

OnDamageTaken

在以下时机触发：单位因攻击或状态损失 HP 典型用途：受击反应

事件标识：

项目	值
常量	GCSEventNames.OnDamageTaken
字符串值	GCS_OnDamageTaken
载荷类型	DamageEventArgs

public static IDisposable OnDamageTaken(Action<DamageEventArgs> handler);

事件参数：

名称	类型	说明
SourceUnitId	int	来源单位 ID；没有单位来源时为 -1
TargetUnitId	int	受伤单位的运行时 ID
Amount	int	经过护甲与修正后实际损失的 HP
Lethal	bool	这次伤害是否击杀目标

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

示例：

IDisposable subscription = GCSApi.OnDamageTaken(args => Debug.Log(args.SourceUnitId));

OnArmorGained

在以下时机触发：显式 Gain Armor 经过 Hook 后实际增加单位护甲，直接 Set Armor 不触发 典型用途：护甲飘字与护甲条刷新

事件标识：

项目	值
常量	GCSEventNames.OnArmorGained
字符串值	GCS_OnArmorGained
载荷类型	ArmorChangedEventArgs

public static IDisposable OnArmorGained(Action<ArmorChangedEventArgs> handler);

事件参数：

名称	类型	说明
UnitId	int	受影响单位的运行时 ID
Amount	int	本次实际增加的护甲值
CurrentArmor	int	变化后的护甲

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

示例：

IDisposable subscription = GCSApi.OnArmorGained(args => Debug.Log(args.UnitId));

OnArmorLost

在以下时机触发：单位因伤害吸收或显式 Lose Armor 实际失去护甲 典型用途：破甲反馈

事件标识：

项目	值
常量	GCSEventNames.OnArmorLost
字符串值	GCS_OnArmorLost
载荷类型	ArmorChangedEventArgs

public static IDisposable OnArmorLost(Action<ArmorChangedEventArgs> handler);

事件参数：

名称	类型	说明
UnitId	int	受影响单位的运行时 ID
Amount	int	本次实际失去的护甲值
CurrentArmor	int	变化后的护甲

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

示例：

IDisposable subscription = GCSApi.OnArmorLost(args => Debug.Log(args.UnitId));

OnEnergyChanged

在以下时机触发：玩家当前能量或能量上限发生变化 典型用途：完整刷新能量 UI

事件标识：

项目	值
常量	GCSEventNames.OnEnergyChanged
字符串值	GCS_OnEnergyChanged
载荷类型	EnergyChangedEventArgs

public static IDisposable OnEnergyChanged(Action<EnergyChangedEventArgs> handler);

事件参数：

名称	类型	说明
CurrentEnergy	int	变化后的玩家能量
MaxEnergy	int	玩家当前结算后的每回合能量上限

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

示例：

IDisposable subscription = GCSApi.OnEnergyChanged(args => Debug.Log(args.CurrentEnergy));

OnEnergyGained

在以下时机触发：显式 Gain Energy 经过 Hook 后实际增加玩家能量，回合开始补充与直接 Set Energy 不触发 典型用途：获得能量反馈

事件标识：

项目	值
常量	GCSEventNames.OnEnergyGained
字符串值	GCS_OnEnergyGained
载荷类型	EnergyDeltaEventArgs

public static IDisposable OnEnergyGained(Action<EnergyDeltaEventArgs> handler);

事件参数：

名称	类型	说明
Amount	int	本次实际增加的能量值
CurrentEnergy	int	变化后的玩家能量

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

示例：

IDisposable subscription = GCSApi.OnEnergyGained(args => Debug.Log(args.Amount));

OnEnergySpent

在以下时机触发：玩家正常打出卡牌并支付正数费用，或显式执行 Lose Energy 造成实际能量损失 典型用途：出牌耗能反馈与额外能量损失日志

事件标识：

项目	值
常量	GCSEventNames.OnEnergySpent
字符串值	GCS_OnEnergySpent
载荷类型	EnergyDeltaEventArgs

public static IDisposable OnEnergySpent(Action<EnergyDeltaEventArgs> handler);

事件参数：

名称	类型	说明
Amount	int	本次实际支付或损失的能量值
CurrentEnergy	int	变化后的玩家能量

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

示例：

IDisposable subscription = GCSApi.OnEnergySpent(args => Debug.Log(args.Amount));

状态事件

OnStatusChanged

在以下时机触发：单位的状态层数发生变化 典型用途：刷新状态组件

事件标识：

项目	值
常量	GCSEventNames.OnStatusChanged
字符串值	GCS_OnStatusChanged
载荷类型	StatusChangedEventArgs

public static IDisposable OnStatusChanged(Action<StatusChangedEventArgs> handler);

事件参数：

名称	类型	说明
UnitId	int	受影响单位的运行时 ID
Status	GameStatus	层数发生变化的状态
Stacks	int	变化后的层数

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

示例：

IDisposable subscription = GCSApi.OnStatusChanged(args => Debug.Log(args.UnitId));

OnStatusTicked

在以下时机触发：状态在回合边界进行结算 典型用途：状态结算动画与战斗日志

事件标识：

项目	值
常量	GCSEventNames.OnStatusTicked
字符串值	GCS_OnStatusTicked
载荷类型	StatusTickedEventArgs

public static IDisposable OnStatusTicked(Action<StatusTickedEventArgs> handler);

事件参数：

名称	类型	说明
UnitId	int	受影响单位的运行时 ID
Status	GameStatus	本次结算的状态
Timing	string	触发本次状态结算的回合边界时机
StacksBefore	int	结算前层数
StacksAfter	int	结算后层数
HpBefore	int	结算前单位 HP
HpAfter	int	结算后单位 HP

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

示例：

IDisposable subscription = GCSApi.OnStatusTicked(args => Debug.Log(args.UnitId));

OnStatusInflicted

在以下时机触发：状态应用让单位存储的最终层数发生变化；被上限或 Max 叠加规则截断且层数未变时不会触发 典型用途：状态施加动画

事件标识：

项目	值
常量	GCSEventNames.OnStatusInflicted
字符串值	GCS_OnStatusInflicted
载荷类型	StatusTransitionEventArgs

public static IDisposable OnStatusInflicted(Action<StatusTransitionEventArgs> handler);

事件参数：

名称	类型	说明
UnitId	int	受影响单位的运行时 ID
Status	GameStatus	被施加、到期或移除的状态
Stacks	int	本次状态变化对应的层数
SourceUnitId	int	施加者单位 ID；没有来源时为 -1

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

示例：

IDisposable subscription = GCSApi.OnStatusInflicted(args => Debug.Log(args.UnitId));

OnStatusExpired

在以下时机触发：状态自然衰减到 0 层 典型用途：自然到期动画

事件标识：

项目	值
常量	GCSEventNames.OnStatusExpired
字符串值	GCS_OnStatusExpired
载荷类型	StatusTransitionEventArgs

public static IDisposable OnStatusExpired(Action<StatusTransitionEventArgs> handler);

事件参数：

名称	类型	说明
UnitId	int	受影响单位的运行时 ID
Status	GameStatus	被施加、到期或移除的状态
Stacks	int	本次状态变化对应的层数
SourceUnitId	int	施加者单位 ID；没有来源时为 -1

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

示例：

IDisposable subscription = GCSApi.OnStatusExpired(args => Debug.Log(args.UnitId));

OnStatusRemoved

在以下时机触发：状态被显式移除 典型用途：净化或显式移除反馈

事件标识：

项目	值
常量	GCSEventNames.OnStatusRemoved
字符串值	GCS_OnStatusRemoved
载荷类型	StatusTransitionEventArgs

public static IDisposable OnStatusRemoved(Action<StatusTransitionEventArgs> handler);

事件参数：

名称	类型	说明
UnitId	int	受影响单位的运行时 ID
Status	GameStatus	被施加、到期或移除的状态
Stacks	int	本次状态变化对应的层数
SourceUnitId	int	施加者单位 ID；没有来源时为 -1

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

示例：

IDisposable subscription = GCSApi.OnStatusRemoved(args => Debug.Log(args.UnitId));

敌人与延迟触发事件

OnEnemyUnitIntentChanged

在以下时机触发：敌人初次进入战斗、规划下一轮行为，或状态层数与活动 Card Hook 的变化让公开意图需要实时重算 典型用途：刷新敌人意图组件

事件标识：

项目	值
常量	GCSEventNames.OnEnemyUnitIntentChanged
字符串值	GCS_OnEnemyUnitIntentChanged
载荷类型	EnemyUnitIntentChangedEventArgs

public static IDisposable OnEnemyUnitIntentChanged(Action<EnemyUnitIntentChangedEventArgs> handler);

事件参数：

名称	类型	说明
UnitId	int	敌方单位的运行时 ID
Intents	IReadOnlyList<IntentEntry>	当前向玩家公开的意图列表

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

示例：

IDisposable subscription = GCSApi.OnEnemyUnitIntentChanged(args => Debug.Log(args.UnitId));

OnEnemyUnitActing

在以下时机触发：敌人即将执行当前意图 典型用途：行动前摇表现，例如突进

事件标识：

项目	值
常量	GCSEventNames.OnEnemyUnitActing
字符串值	GCS_OnEnemyUnitActing
载荷类型	EnemyUnitActingEventArgs

public static IDisposable OnEnemyUnitActing(Action<EnemyUnitActingEventArgs> handler);

事件参数：

名称	类型	说明
UnitId	int	正在行动敌人的运行时 ID
Intent	IntentTag	即将执行动作的意图类别

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

示例：

IDisposable subscription = GCSApi.OnEnemyUnitActing(args => Debug.Log(args.UnitId));

OnEnemyUnitSummoned

在以下时机触发：战斗中召唤出敌人 典型用途：召唤表现与布局刷新

事件标识：

项目	值
常量	GCSEventNames.OnEnemyUnitSummoned
字符串值	GCS_OnEnemyUnitSummoned
载荷类型	EnemyUnitSummonedEventArgs

public static IDisposable OnEnemyUnitSummoned(Action<EnemyUnitSummonedEventArgs> handler);

事件参数：

名称	类型	说明
SummonerId	int	召唤者单位 ID；未提供召唤者时为 -1
SummonedUnitId	int	被召唤敌人的运行时 ID
Tier	string	被召唤敌人的创作层级

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

示例：

IDisposable subscription = GCSApi.OnEnemyUnitSummoned(args => Debug.Log(args.SummonerId));

OnEnemyPhaseChanged

在 SequencePatternNode 完成当前重复次数并推进到另一个创作子阶段时触发 典型用途：敌人序列阶段 UI

事件标识：

项目	值
常量	GCSEventNames.OnEnemyPhaseChanged
字符串值	GCS_OnEnemyPhaseChanged
载荷类型	EnemyPhaseChangedEventArgs

public static IDisposable OnEnemyPhaseChanged(Action<EnemyPhaseChangedEventArgs> handler);

事件参数：

名称	类型	说明
UnitId	int	行为阶段发生变化的敌方单位 ID
PatternNodeId	string	活动子阶段发生变化的序列模式节点 ID
OldIndex	int	变化前的子阶段索引
NewIndex	int	变化后的子阶段索引

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

示例：

IDisposable subscription = GCSApi.OnEnemyPhaseChanged(args =>
    Debug.Log($"Enemy {args.UnitId}: {args.PatternNodeId} {args.OldIndex} -> {args.NewIndex}"));

OnDelayedTriggerScheduled

跨回合效果进入队列时触发，所选阶段推进倒计时但尚未到期时会再次触发，适合按 TriggerId 创建或更新独立倒计时指示

事件标识：

项目	值
常量	GCSEventNames.OnDelayedTriggerScheduled
字符串值	GCS_OnDelayedTriggerScheduled
载荷类型	DelayedTriggerScheduledEventArgs

public static IDisposable OnDelayedTriggerScheduled(Action<DelayedTriggerScheduledEventArgs> handler);

事件参数：

名称	类型	说明
TriggerId	int	当前战斗内的触发器标识，同一触发器的每次更新与终态事件都会沿用该值
SourceUnitId	int	登记时捕获的来源单位 ID，没有来源时为 -1
TargetUnitId	int	登记时捕获的目标单位 ID，没有目标时为 -1
RemainingTurns	int	触发前还需经过的匹配阶段边界次数
TickPhase	DelayedTickPhase	推进倒计时并触发效果的阶段边界
Card	GameCard	登记时捕获的关联卡牌定义，没有关联卡牌时为 null
ActionTypeName	string	关联卡牌名称，没有可用卡牌名称时使用 Delayed Effect

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

示例：

IDisposable subscription = GCSApi.OnDelayedTriggerScheduled(args =>
    Debug.Log($"Trigger {args.TriggerId}: {args.RemainingTurns}"));

OnDelayedTriggerFired

排队的跨回合 Body 及其中全部 Wait 或 Choice 恢复路径完成后触发，适合完成该 TriggerId 对应的指示与效果反馈

事件标识：

项目	值
常量	GCSEventNames.OnDelayedTriggerFired
字符串值	GCS_OnDelayedTriggerFired
载荷类型	DelayedTriggerFiredEventArgs

public static IDisposable OnDelayedTriggerFired(Action<DelayedTriggerFiredEventArgs> handler);

事件参数：

名称	类型	说明
TriggerId	int	OnDelayedTriggerScheduled 此前发布的当前战斗内标识
SourceUnitId	int	登记时捕获的来源单位 ID，没有来源时为 -1
TargetUnitId	int	登记时捕获的目标单位 ID，没有目标时为 -1
TickPhase	DelayedTickPhase	该触发器实际结算的阶段边界
Card	GameCard	登记时捕获的关联卡牌定义，没有关联卡牌时为 null
ActionTypeName	string	关联卡牌名称，没有可用卡牌名称时使用 Delayed Effect

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

示例：

IDisposable subscription = GCSApi.OnDelayedTriggerFired(args => Debug.Log(args.TriggerId));

OnDelayedTriggerCancelled

延迟触发器在入队前被拒绝登记或排队的跨回合效果被取消时触发，适合移除该 TriggerId 对应的待执行指示

事件标识：

项目	值
常量	GCSEventNames.OnDelayedTriggerCancelled
字符串值	GCS_OnDelayedTriggerCancelled
载荷类型	DelayedTriggerCancelledEventArgs

public static IDisposable OnDelayedTriggerCancelled(Action<DelayedTriggerCancelledEventArgs> handler);

事件参数：

名称	类型	说明
TriggerId	int	为被取消触发器分配的当前战斗内标识，存在此前的排队更新时与其保持一致
SourceUnitId	int	登记时捕获的来源单位 ID，没有来源时为 -1
TargetUnitId	int	登记时捕获的目标单位 ID，没有目标时为 -1
TickPhase	DelayedTickPhase	被取消触发器原本等待的阶段边界
Card	GameCard	登记时捕获的关联卡牌定义，没有关联卡牌时为 null
ActionTypeName	string	关联卡牌名称，没有可用卡牌名称时使用 Delayed Effect

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

示例：

IDisposable subscription = GCSApi.OnDelayedTriggerCancelled(args => Debug.Log(args.TriggerId));

奖励与选择事件

OnBattleRewardOffered

在以下时机触发：战后奖励可供玩家选择 典型用途：打开奖励选择器

事件标识：

项目	值
常量	GCSEventNames.OnBattleRewardOffered
字符串值	GCS_OnBattleRewardOffered
载荷类型	BattleRewardOfferedEventArgs

public static IDisposable OnBattleRewardOffered(Action<BattleRewardOfferedEventArgs> handler);

事件参数：

名称	类型	说明
CardCandidates	IReadOnlyList<GameCard>	卡牌奖励提供的候选卡列表

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

示例：

IDisposable subscription = GCSApi.OnBattleRewardOffered(args => Debug.Log(args.CardCandidates.Count));

OnBattleRewardSelected

在以下时机触发：玩家应用一项奖励选择 典型用途：关闭奖励选择器并刷新 run deck

事件标识：

项目	值
常量	GCSEventNames.OnBattleRewardSelected
字符串值	GCS_OnBattleRewardSelected
载荷类型	BattleRewardSelectedEventArgs

public static IDisposable OnBattleRewardSelected(Action<BattleRewardSelectedEventArgs> handler);

事件参数：

名称	类型	说明
Choice	RewardChoice	玩家选中的奖励类型
SelectedCard	GameCard	卡牌奖励中选中的卡；其他奖励类型为 null

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

示例：

IDisposable subscription = GCSApi.OnBattleRewardSelected(args => Debug.Log(args.Choice));

OnBattleRewardSkipped

在以下时机触发：玩家放弃当前奖励 典型用途：关闭奖励选择器

事件标识：

项目	值
常量	GCSEventNames.OnBattleRewardSkipped
字符串值	GCS_OnBattleRewardSkipped
载荷类型	无

public static IDisposable OnBattleRewardSkipped(Action handler);

事件参数：

名称	类型	说明
—	—	此事件没有载荷参数

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

示例：

IDisposable subscription = GCSApi.OnBattleRewardSkipped(() => Debug.Log("OnBattleRewardSkipped"));

OnEffectChoiceOffered

在以下时机触发：卡牌效果暂停并等待玩家选择 典型用途：打开 FlowGraph 选择器

事件标识：

项目	值
常量	GCSEventNames.OnEffectChoiceOffered
字符串值	GCS_OnEffectChoiceOffered
载荷类型	EffectChoiceOfferedEventArgs

public static IDisposable OnEffectChoiceOffered(Action<EffectChoiceOfferedEventArgs> handler);

事件参数：

名称	类型	说明
PromptText	string	显示给玩家的提示文本
Candidates	IReadOnlyList<ChoiceCandidate>	效果流图生成的候选项
AllowSkip	bool	玩家是否可以跳过这次选择

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

示例：

IDisposable subscription = GCSApi.OnEffectChoiceOffered(args => Debug.Log(args.PromptText));

OnEffectChoiceSelected

Presenter 提交的选择集合写入 Choice 节点的 Chosen 端口后、等待选择状态清理前触发；Presenter 调用选中回调但返回空集合时仍会发布，SelectedIndex 为 -1 典型用途：记录本次选择结果

事件标识：

项目	值
常量	GCSEventNames.OnEffectChoiceSelected
字符串值	GCS_OnEffectChoiceSelected
载荷类型	EffectChoiceSelectedEventArgs

public static IDisposable OnEffectChoiceSelected(Action<EffectChoiceSelectedEventArgs> handler);

事件参数：

名称	类型	说明
SelectedIndex	int	兼容字段，保存第一个已选索引，Presenter 返回空选择时为 -1
SelectedIndices	IReadOnlyList<int>	按 Presenter 返回顺序排列的全部已选索引，相对于 OnEffectChoiceOffered 提供的候选项
SelectedCandidates	IReadOnlyList<ChoiceCandidate>	按 Presenter 返回顺序排列的全部已选候选对象

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

示例：

IDisposable subscription = GCSApi.OnEffectChoiceSelected(args =>
    Debug.Log($"Selected {args.SelectedIndices.Count} candidates"));

OnEffectChoiceSkipped

Presenter 调用 onSkipped，或者 GCS 因场景中没有 Presenter 或没有候选项而通过跳过路径完成 Choice 时触发 典型用途：关闭选择器或记录自动回退

事件标识：

项目	值
常量	GCSEventNames.OnEffectChoiceSkipped
字符串值	GCS_OnEffectChoiceSkipped
载荷类型	无

public static IDisposable OnEffectChoiceSkipped(Action handler);

事件参数：

名称	类型	说明
—	—	此事件没有载荷参数

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

示例：

IDisposable subscription = GCSApi.OnEffectChoiceSkipped(() => Debug.Log("OnEffectChoiceSkipped"));

订阅生命周期

保存 GCSApi.On* 或 GCSApi.Subscribe* 返回的 IDisposable，并在订阅者停用或销毁时调用 Dispose()，避免场景切换后继续收到事件

private IDisposable _subscription;

private void OnEnable()
{
    _subscription = GCSApi.OnBattleEnded(args => Debug.Log(args.Won));
}

private void OnDisable()
{
    _subscription?.Dispose();
    _subscription = null;
}

空值约定

字段	约定
CardPlayedEventArgs.TargetUnitId	没有选定目标时为 null
BattleRewardSelectedEventArgs.SelectedCard	非卡牌奖励时为 null
SourceUnitId / SummonerId	没有对应单位来源时为 -1
IReadOnlyList 字段	内置事件按非 null 列表提供

事件名与 FlowGraph 入口

图入口和 Hook（例如 On Card Played 与伤害 Hook）是 FlowGraph 内部时机，不通过事件通道广播，因此没有 GCSEventNames 常量

参考

时机模型见 流图基础