事件参考

📡

GCS · Events

全部 43 个内置事件：常量、字符串值、payload 类型、每个字段，以及各自的典型订阅者。

编写监听器时使用这一页。每一行都与出厂的 GCSEventNames 和 GCSEventArgs 源码一致。

本页把 GCSEventNames 中的每个常量和 GCSEventArgs.cs 中的每个 payload class 列成表：六组共 43 个事件。字符串值只有一条规则，常量名前加 GCS_ 前缀，所以 OnCardPlayed 广播出来是 GCS_OnCardPlayed。

这些名字和 Game Card Monitor 的 Event 页签显示的名称完全相同。想确认一张卡实际触发了哪些事件，可以打开 Monitor，在 Play Mode 中执行一次对应操作：

战斗与回合事件

Constant	String value	Payload	Fields	典型用途
OnBattleStarted	GCS_OnBattleStarted	None	None	初始 HUD 刷新、战斗开场动画。
OnTurnStarted	GCS_OnTurnStarted	TurnEventArgs	TurnNumber	回合开始的 UI 刷新。
OnEnemyTurnStarted	GCS_OnEnemyTurnStarted	TurnEventArgs	TurnNumber	敌方阶段横幅或输入锁定。
OnTurnEnded	GCS_OnTurnEnded	TurnEventArgs	TurnNumber	回合结束清理与日志。
OnDrawPhase	GCS_OnDrawPhase	TurnEventArgs	TurnNumber	抽牌阶段 UI 与抽牌数量表现。
OnDiscardPhase	GCS_OnDiscardPhase	TurnEventArgs	TurnNumber	弃牌阶段 UI 与清理。
OnBattleEnded	GCS_OnBattleEnded	BattleEndedEventArgs	Won	胜利或失败遮罩。

---

卡牌事件

Constant	String value	Payload	Fields	典型用途
OnCardPlayed	GCS_OnCardPlayed	CardPlayedEventArgs	Card、InstanceId、TargetUnitId	战斗日志、出牌动画、连击计数。
OnCardModified	GCS_OnCardModified	CardModifiedEventArgs	InstanceId	刷新费用、升级或变形后的卡牌 UI。
OnCardDrawn	GCS_OnCardDrawn	CardLifecycleEventArgs	InstanceId、Card	抽牌动画与手牌刷新。
OnCardDiscarded	GCS_OnCardDiscarded	CardLifecycleEventArgs	InstanceId、Card	弃牌动画与牌堆刷新。
OnCardExhausted	GCS_OnCardExhausted	CardLifecycleEventArgs	InstanceId、Card	消耗（exhaust）动画与牌堆刷新。
OnCardRetained	GCS_OnCardRetained	CardLifecycleEventArgs	InstanceId、Card	保留反馈。
OnCardAddedToHand	GCS_OnCardAddedToHand	CardLifecycleEventArgs	InstanceId、Card	生成卡牌的 UI。
OnCardAddedToDeck	GCS_OnCardAddedToDeck	CardLifecycleEventArgs	InstanceId、Card	Run deck 或加牌反馈。
OnDrawPileShuffled	GCS_OnDrawPileShuffled	None	None	洗牌动画或牌堆计数刷新。

---

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

Constant	String value	Payload	Fields	典型用途
OnUnitHpChanged	GCS_OnUnitHpChanged	UnitHpChangedEventArgs	UnitId、CurrentHp、MaxHp、CurrentArmor、PreviousHp、PreviousArmor	HP 与护甲条。
OnUnitDied	GCS_OnUnitDied	UnitDiedEventArgs	UnitId、Tier	死亡动画、奖励、目标清理。
OnDamageDealt	GCS_OnDamageDealt	DamageEventArgs	SourceUnitId、TargetUnitId、Amount、Lethal	输出伤害日志与命中反馈。
OnDamageTaken	GCS_OnDamageTaken	DamageEventArgs	SourceUnitId、TargetUnitId、Amount、Lethal	受击反应。
OnArmorGained	GCS_OnArmorGained	ArmorChangedEventArgs	UnitId、Amount、CurrentArmor	护甲飘字与护甲条刷新。
OnArmorLost	GCS_OnArmorLost	ArmorChangedEventArgs	UnitId、Amount、CurrentArmor	破甲反馈。
OnEnergyChanged	GCS_OnEnergyChanged	EnergyChangedEventArgs	CurrentEnergy、MaxEnergy	能量 UI 刷新。
OnEnergyGained	GCS_OnEnergyGained	EnergyDeltaEventArgs	Amount、CurrentEnergy	获得能量反馈。
OnEnergySpent	GCS_OnEnergySpent	EnergyDeltaEventArgs	Amount、CurrentEnergy	出牌耗能反馈。

---

状态事件

Constant	String value	Payload	Fields	典型用途
OnStatusChanged	GCS_OnStatusChanged	StatusChangedEventArgs	UnitId、Status、Stacks	刷新状态 widget。
OnStatusTicked	GCS_OnStatusTicked	StatusTickedEventArgs	UnitId、Status、Timing、StacksBefore、StacksAfter、HpBefore、HpAfter	结算动画与战斗日志。
OnStatusInflicted	GCS_OnStatusInflicted	StatusTransitionEventArgs	UnitId、Status、Stacks、SourceUnitId	状态施加动画。
OnStatusExpired	GCS_OnStatusExpired	StatusTransitionEventArgs	UnitId、Status、Stacks、SourceUnitId	自然到期动画。
OnStatusRemoved	GCS_OnStatusRemoved	StatusTransitionEventArgs	UnitId、Status、Stacks、SourceUnitId	净化或移除动画。

---

敌人与延迟触发事件

Constant	String value	Payload	Fields	典型用途
OnEnemyUnitIntentChanged	GCS_OnEnemyUnitIntentChanged	EnemyUnitIntentChangedEventArgs	UnitId、Intents	意图 widget 刷新。
OnEnemyUnitActing	GCS_OnEnemyUnitActing	EnemyUnitActingEventArgs	UnitId、Intent	攻击前摇表现，例如演示里的突进动画。
OnEnemyUnitSummoned	GCS_OnEnemyUnitSummoned	EnemyUnitSummonedEventArgs	SummonerId、SummonedUnitId、Tier	召唤动画与布局刷新。
OnEnemyPhaseChanged	GCS_OnEnemyPhaseChanged	EnemyPhaseChangedEventArgs	UnitId、OldIndex、NewIndex	敌人行为阶段 UI。
OnDelayedTriggerScheduled	GCS_OnDelayedTriggerScheduled	DelayedTriggerScheduledEventArgs	SourceUnitId、RemainingTurns、ActionTypeName	倒计时指示。
OnDelayedTriggerFired	GCS_OnDelayedTriggerFired	DelayedTriggerFiredEventArgs	SourceUnitId、ActionTypeName	延迟效果触发反馈。
OnDelayedTriggerCancelled	GCS_OnDelayedTriggerCancelled	DelayedTriggerCancelledEventArgs	SourceUnitId	移除倒计时 UI。

---

奖励与选择事件

Constant	String value	Payload	Fields	典型用途
OnBattleRewardOffered	GCS_OnBattleRewardOffered	BattleRewardOfferedEventArgs	CardCandidates	显示奖励选择器。
OnBattleRewardSelected	GCS_OnBattleRewardSelected	BattleRewardSelectedEventArgs	Choice、SelectedCard	关闭奖励选择器并更新 run deck。
OnBattleRewardSkipped	GCS_OnBattleRewardSkipped	None	None	关闭奖励选择器。
OnEffectChoiceOffered	GCS_OnEffectChoiceOffered	EffectChoiceOfferedEventArgs	PromptText、Candidates、AllowSkip	显示 FlowGraph 选择器。
OnEffectChoiceSelected	GCS_OnEffectChoiceSelected	EffectChoiceSelectedEventArgs	SelectedIndex	关闭选择器并记录选择。
OnEffectChoiceSkipped	GCS_OnEffectChoiceSkipped	None	None	关闭选择器。

---

Payload 类型

Payload type	Fields
TurnEventArgs	int TurnNumber
CardPlayedEventArgs	GameCard Card、int InstanceId、int? TargetUnitId
CardModifiedEventArgs	int InstanceId
UnitHpChangedEventArgs	int UnitId、int CurrentHp、int MaxHp、int CurrentArmor、int PreviousHp、int PreviousArmor
UnitDiedEventArgs	int UnitId、string Tier
StatusChangedEventArgs	int UnitId、GameStatus Status、int Stacks
StatusTickedEventArgs	int UnitId、GameStatus Status、string Timing、int StacksBefore、int StacksAfter、int HpBefore、int HpAfter
EnemyUnitIntentChangedEventArgs	int UnitId、IReadOnlyList<IntentEntry> Intents
EnemyUnitActingEventArgs	int UnitId、IntentTag Intent
EnemyPhaseChangedEventArgs	int UnitId、int OldIndex、int NewIndex
EnergyChangedEventArgs	int CurrentEnergy、int MaxEnergy
DelayedTriggerScheduledEventArgs	int SourceUnitId、int RemainingTurns、string ActionTypeName
DelayedTriggerFiredEventArgs	int SourceUnitId、string ActionTypeName
DelayedTriggerCancelledEventArgs	int SourceUnitId
BattleRewardOfferedEventArgs	IReadOnlyList<GameCard> CardCandidates
BattleRewardSelectedEventArgs	RewardChoice Choice、GameCard SelectedCard
EffectChoiceOfferedEventArgs	string PromptText、IReadOnlyList<ChoiceCandidate> Candidates、bool AllowSkip
EffectChoiceSelectedEventArgs	int SelectedIndex
BattleEndedEventArgs	bool Won
EnemyUnitSummonedEventArgs	int SummonerId、int SummonedUnitId、string Tier
CardLifecycleEventArgs	int InstanceId、GameCard Card
DamageEventArgs	int SourceUnitId、int TargetUnitId、int Amount、bool Lethal
ArmorChangedEventArgs	int UnitId、int Amount、int CurrentArmor
EnergyDeltaEventArgs	int Amount、int CurrentEnergy
StatusTransitionEventArgs	int UnitId、GameStatus Status、int Stacks、int SourceUnitId

---

快捷方法覆盖范围

上面表格里除一个事件外，每个事件都有同名的 GCSApi 快捷方法，GCSEventNames.OnUnitHpChanged 对应 GCSApi.OnUnitHpChanged(...)。四种订阅形式覆盖全部场景：

• GCSApi.OnBattleStarted(handler) 和其他无 payload 快捷方法接收 Action。
• GCSApi.OnUnitHpChanged(args => ...) 和其他 typed 快捷方法接收 Action<TArgs>。
• GCSApi.Subscribe<TArgs>(GCSEventNames.SomeEvent, handler) 按名订阅，handler 带类型。
• GCSApi.Subscribe(GCSEventNames.SomeEvent, handler) 按名订阅，无 payload。

例外是 OnEnemyUnitActing，它没有快捷方法。带上 payload 类型按名订阅即可：

var sub = GCSApi.Subscribe<EnemyUnitActingEventArgs>(
    GCSEventNames.OnEnemyUnitActing,
    args => PlayAttackWindup(args.UnitId, args.Intent));

通过 GCSApi.RaiseGameEvent 触发的自定义事件同样没有快捷方法，按名订阅即可。

---

Nullability 说明

Field	可能为 null	原因
CardPlayedEventArgs.TargetUnitId	是	有些卡打出时不需要目标，该字段是 int?。
payload 中的 GameCard 字段	极少，但 UI 代码仍应防御	Runtime 会尽量跳过 null 卡牌，防御式 UI 没有成本。
payload 中的 GameStatus 字段	极少，但 UI 代码仍应防御	状态数据库在内容创作期间可能变动。
IReadOnlyList payload	按非 null 处理	Runtime 为每个内置事件都提供列表。

---

事件名与 FlowGraph 入口

图入口和 Hook（On Card Played 入口、伤害 Hook 等）是图内部的创作层时机点，不是通道广播，所以没有 GCSEventNames 常量。本参考只覆盖运行时事件通道。图侧的时机见入口与 Hook。