事件参考
Guide
先用精简表格定位事件，再展开查看事件名、载荷参数、触发时机与订阅示例
事件总览只保留定位所需的信息，完整细节放在每个事件的折叠项中，这些事件名与 Game Card Monitor 的 Event 页签完全一致
战斗与回合事件
| 事件 | 载荷 | 触发时机 |
|---|---|---|
OnBattleStarted | 无 | 战斗状态、起始手牌和初始敌人意图准备完成 |
OnTurnStarted | TurnEventArgs | 每个玩家回合开始 |
OnEnemyTurnStarted | TurnEventArgs | 每个敌方阶段开始 |
OnTurnEnded | TurnEventArgs | 每个玩家回合结束 |
OnDrawPhase | TurnEventArgs | 玩家回合进入抽牌步骤 |
OnDiscardPhase | TurnEventArgs | 玩家回合进入弃牌步骤 |
OnBattleEnded | BattleEndedEventArgs | 战斗结算为胜利或失败 |
OnBattleStarted
在以下时机触发：战斗状态、起始手牌和初始敌人意图准备完成 典型用途：初始化 HUD 与战斗开场表现
事件标识：
| 项目 | 值 |
|---|---|
| 常量 | 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 | CardPlayedEventArgs | 一次出牌被接受并执行 |
OnCardModified | CardModifiedEventArgs | 卡牌实例的运行时费用或状态发生变化 |
OnCardDrawn | CardLifecycleEventArgs | 每张卡通过抽牌进入手牌 |
OnCardDiscarded | CardLifecycleEventArgs | 卡牌因手牌溢出或回合结束清理被弃掉 |
OnCardExhausted | CardLifecycleEventArgs | 卡牌进入消耗牌堆 |
OnCardRetained | CardLifecycleEventArgs | 卡牌在回合结束清理时保留在手牌 |
OnCardAddedToHand | CardLifecycleEventArgs | 卡牌被直接创建到手牌 |
OnCardAddedToDeck | CardLifecycleEventArgs | 卡牌被直接加入抽牌堆 |
OnDrawPileShuffled | 无 | 抽牌堆完成洗牌 |
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 | UnitHpChangedEventArgs | 单位 HP 或护甲发生变化 |
OnUnitDied | UnitDiedEventArgs | 单位死亡或从战斗中被移除 |
OnDamageDealt | DamageEventArgs | 攻击者使目标损失 HP |
OnDamageTaken | DamageEventArgs | 单位因攻击或状态损失 HP |
OnArmorGained | ArmorChangedEventArgs | 单位获得护甲 |
OnArmorLost | ArmorChangedEventArgs | 单位失去护甲 |
OnEnergyChanged | EnergyChangedEventArgs | 玩家当前能量或能量上限发生变化 |
OnEnergyGained | EnergyDeltaEventArgs | 玩家获得能量 |
OnEnergySpent | EnergyDeltaEventArgs | 玩家花费能量 |
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
在以下时机触发：单位获得护甲 典型用途：护甲飘字与护甲条刷新
事件标识：
| 项目 | 值 |
|---|---|
| 常量 | 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
在以下时机触发：单位失去护甲 典型用途：破甲反馈
事件标识：
| 项目 | 值 |
|---|---|
| 常量 | 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
在以下时机触发：玩家获得能量 典型用途：获得能量反馈
事件标识：
| 项目 | 值 |
|---|---|
| 常量 | 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
在以下时机触发：玩家花费能量 典型用途：出牌耗能反馈
事件标识：
| 项目 | 值 |
|---|---|
| 常量 | 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 | StatusChangedEventArgs | 单位的状态层数发生变化 |
OnStatusTicked | StatusTickedEventArgs | 状态在回合边界进行结算 |
OnStatusInflicted | StatusTransitionEventArgs | 状态被施加到单位 |
OnStatusExpired | StatusTransitionEventArgs | 状态自然衰减到 0 层 |
OnStatusRemoved | StatusTransitionEventArgs | 状态被显式移除 |
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
在以下时机触发：状态被施加到单位 典型用途：状态施加动画
事件标识：
| 项目 | 值 |
|---|---|
| 常量 | 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 | EnemyUnitIntentChangedEventArgs | 敌人解析或重新规划向玩家公开的意图 |
OnEnemyUnitActing | EnemyUnitActingEventArgs | 敌人即将执行当前意图 |
OnEnemyUnitSummoned | EnemyUnitSummonedEventArgs | 战斗中召唤出敌人 |
OnEnemyPhaseChanged | EnemyPhaseChangedEventArgs | 敌人推进到另一个创作行为阶段 |
OnDelayedTriggerScheduled | DelayedTriggerScheduledEventArgs | 跨回合效果进入队列 |
OnDelayedTriggerFired | DelayedTriggerFiredEventArgs | 排队的跨回合效果完成结算 |
OnDelayedTriggerCancelled | DelayedTriggerCancelledEventArgs | 排队的跨回合效果被取消 |
OnEnemyUnitIntentChanged
在以下时机触发：敌人解析或重新规划向玩家公开的意图 典型用途：刷新敌人意图组件
事件标识：
| 项目 | 值 |
|---|---|
| 常量 | 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 Subscribe<EnemyUnitActingEventArgs>(
string eventName,
Action<EnemyUnitActingEventArgs> handler
);
事件参数：
| 名称 | 类型 | 说明 |
|---|---|---|
UnitId | int | 正在行动敌人的运行时 ID |
Intent | IntentTag | 即将执行动作的意图类别 |
返回： IDisposable 订阅句柄，调用 Dispose() 可取消订阅
示例：
IDisposable subscription = GCSApi.Subscribe<EnemyUnitActingEventArgs>(
GCSEventNames.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
在以下时机触发：敌人推进到另一个创作行为阶段 典型用途：敌人行为阶段 UI
事件标识：
| 项目 | 值 |
|---|---|
| 常量 | GCSEventNames.OnEnemyPhaseChanged |
| 字符串值 | GCS_OnEnemyPhaseChanged |
| 载荷类型 | EnemyPhaseChangedEventArgs |
public static IDisposable OnEnemyPhaseChanged(Action<EnemyPhaseChangedEventArgs> handler);
事件参数：
| 名称 | 类型 | 说明 |
|---|---|---|
UnitId | int | 行为阶段发生变化的敌方单位 ID |
OldIndex | int | 变化前的行为阶段索引 |
NewIndex | int | 变化后的行为阶段索引 |
返回： IDisposable 订阅句柄，调用 Dispose() 可取消订阅
示例：
IDisposable subscription = GCSApi.OnEnemyPhaseChanged(args => Debug.Log(args.UnitId));
OnDelayedTriggerScheduled
在以下时机触发：跨回合效果进入队列 典型用途：创建倒计时指示
事件标识：
| 项目 | 值 |
|---|---|
| 常量 | GCSEventNames.OnDelayedTriggerScheduled |
| 字符串值 | GCS_OnDelayedTriggerScheduled |
| 载荷类型 | DelayedTriggerScheduledEventArgs |
public static IDisposable OnDelayedTriggerScheduled(Action<DelayedTriggerScheduledEventArgs> handler);
事件参数：
| 名称 | 类型 | 说明 |
|---|---|---|
SourceUnitId | int | 排队效果关联的来源单位 ID |
RemainingTurns | int | 效果结算前剩余回合数 |
ActionTypeName | string | 排队 Action 的运行时类型名 |
返回： IDisposable 订阅句柄，调用 Dispose() 可取消订阅
示例：
IDisposable subscription = GCSApi.OnDelayedTriggerScheduled(args => Debug.Log(args.SourceUnitId));
OnDelayedTriggerFired
在以下时机触发：排队的跨回合效果完成结算 典型用途：延迟效果触发反馈
事件标识：
| 项目 | 值 |
|---|---|
| 常量 | GCSEventNames.OnDelayedTriggerFired |
| 字符串值 | GCS_OnDelayedTriggerFired |
| 载荷类型 | DelayedTriggerFiredEventArgs |
public static IDisposable OnDelayedTriggerFired(Action<DelayedTriggerFiredEventArgs> handler);
事件参数：
| 名称 | 类型 | 说明 |
|---|---|---|
SourceUnitId | int | 效果关联的来源单位 ID |
ActionTypeName | string | 已结算 Action 的运行时类型名 |
返回： IDisposable 订阅句柄，调用 Dispose() 可取消订阅
示例：
IDisposable subscription = GCSApi.OnDelayedTriggerFired(args => Debug.Log(args.SourceUnitId));
OnDelayedTriggerCancelled
在以下时机触发：排队的跨回合效果被取消 典型用途：移除倒计时指示
事件标识：
| 项目 | 值 |
|---|---|
| 常量 | GCSEventNames.OnDelayedTriggerCancelled |
| 字符串值 | GCS_OnDelayedTriggerCancelled |
| 载荷类型 | DelayedTriggerCancelledEventArgs |
public static IDisposable OnDelayedTriggerCancelled(Action<DelayedTriggerCancelledEventArgs> handler);
事件参数：
| 名称 | 类型 | 说明 |
|---|---|---|
SourceUnitId | int | 被取消效果关联的来源单位 ID |
返回： IDisposable 订阅句柄，调用 Dispose() 可取消订阅
示例：
IDisposable subscription = GCSApi.OnDelayedTriggerCancelled(args => Debug.Log(args.SourceUnitId));
奖励与选择事件
| 事件 | 载荷 | 触发时机 |
|---|---|---|
OnBattleRewardOffered | BattleRewardOfferedEventArgs | 战后奖励可供玩家选择 |
OnBattleRewardSelected | BattleRewardSelectedEventArgs | 玩家应用一项奖励选择 |
OnBattleRewardSkipped | 无 | 玩家放弃当前奖励 |
OnEffectChoiceOffered | EffectChoiceOfferedEventArgs | 卡牌效果暂停并等待玩家选择 |
OnEffectChoiceSelected | EffectChoiceSelectedEventArgs | 玩家完成效果选择 |
OnEffectChoiceSkipped | 无 | 可选的效果选择被跳过 |
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
在以下时机触发：玩家完成效果选择 典型用途：关闭选择器并记录选择
事件标识：
| 项目 | 值 |
|---|---|
| 常量 | GCSEventNames.OnEffectChoiceSelected |
| 字符串值 | GCS_OnEffectChoiceSelected |
| 载荷类型 | EffectChoiceSelectedEventArgs |
public static IDisposable OnEffectChoiceSelected(Action<EffectChoiceSelectedEventArgs> handler);
事件参数：
| 名称 | 类型 | 说明 |
|---|---|---|
SelectedIndex | int | 玩家选中的从 0 开始的候选项索引 |
返回： IDisposable 订阅句柄，调用 Dispose() 可取消订阅
示例：
IDisposable subscription = GCSApi.OnEffectChoiceSelected(args => Debug.Log(args.SelectedIndex));
OnEffectChoiceSkipped
在以下时机触发：可选的效果选择被跳过 典型用途：关闭选择器
事件标识：
| 项目 | 值 |
|---|---|
| 常量 | 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 常量，时机模型见 流图基础