Hook 节点

🧩

Guide

找到能在 GCS 提交玩法数值或判断前读取、修改或取消结果的 Hook 节点

节点用法

每条 Hook 都必须同步完成，包括通过 Mutator 或状态生命周期级联间接触达的控制路径；任何从 Hook 入口可达的路径都不能连接 Wait、Choice 或 Delayed Trigger，FlowGraph 校验会报告直接违规路径，运行时会在产生部分副作用前跳过该 Hook；Hook 求值中的嵌套操作若间接遇到这些节点，Choice 会退化到 Skipped，Wait 会直接走 Out，Delayed Trigger 会走 Done 且不登记延迟任务；随包 Card、Status 与 Enemy 行为图的这类违规数为 0

Damage Dealt Hook

在攻击者的输出伤害进入防守方 Hook 之前拦截数值；将 Value 经过数学或条件节点计算后写入 Write Hook；伤害结算后的行为应使用 On Damage Dealt

输入

• 无：匹配的值处理点直接启动分支

输出

• Value（Int）：待结算的输出伤害
• Source（UnitRef）：造成这次伤害的攻击者
• Target（UnitRef）：即将受到伤害的单位
• Out（Flow）：继续执行 Hook 计算

参数

• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

Damage Taken Hook

攻击伤害会先经过攻击专用 Hook，状态伤害会先经过 Status Damage Hook，随后该节点在护甲吸收前拦截通用承伤值；将新的 Value 写入 Write Hook 可实现易伤或减伤

输入

• 无：匹配的值处理点直接启动分支

输出

• Value（Int）：护甲吸收前的待定伤害
• Source（UnitRef）：造成这次伤害的攻击者或状态施加者，没有独立来源时回退到 Hook 持有者
• Target（UnitRef）：即将受到伤害的 Hook 持有者
• Out（Flow）：继续执行 Hook 计算

参数

• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

Attack Taken Hook

在防守方拦截带攻击者的伤害，并先于通用 Damage Taken Hook 执行；状态伤害与直接 HP 损失不会进入该处理点；只想修改攻击伤害时，将 Value 写入 Write Hook

输入

• 无：匹配的值处理点直接启动分支

输出

• Value（Int）：待结算的攻击伤害
• Source（UnitRef）：造成这次攻击伤害的攻击者
• Target（UnitRef）：即将受到攻击的 Hook 持有者
• Out（Flow）：继续执行 Hook 计算

参数

• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

HP Gain Hook

在最大 HP 限制之前拦截请求的治疗量；将计算后的 Value 写入 Write Hook 可放大或压低治疗，治疗真正生效后的响应使用 On HP Gained

输入

• 无：匹配的值处理点直接启动分支

输出

• Value（Int）：最大 HP 限制前的待定治疗量
• Source（UnitRef）：提供这次 HP 恢复的单位，没有独立来源时为 Hook 持有者
• Target（UnitRef）：即将获得 HP 的 Hook 持有者
• Out（Flow）：继续执行 Hook 计算

参数

• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

HP Loss Hook

拦截即将实际扣除的 HP；伤害路径中，它位于护甲确定 HP 部分之后；直接 Lose HP 也会进入该处理点；需要统一修改各种 HP 损失时，将 Value 写入 Write Hook

输入

• 无：匹配的值处理点直接启动分支

输出

• Value（Int）：待扣除的 HP
• Source（UnitRef）：造成这次 HP 损失的单位，没有独立来源时为 Hook 持有者
• Target（UnitRef）：即将损失 HP 的 Hook 持有者
• Out（Flow）：继续执行 Hook 计算

参数

• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

Armor Gain Hook

在 Gain Armor 把护甲加到持有者之前拦截数值；将 Value 写入 Write Hook 可调整护甲收益，护甲生效后的响应使用 On Armor Gained

输入

• 无：匹配的值处理点直接启动分支

输出

• Value（Int）：待增加的护甲
• Source（UnitRef）：提供这次护甲的单位，没有独立来源时为 Hook 持有者
• Target（UnitRef）：即将获得护甲的 Hook 持有者
• Out（Flow）：继续执行 Hook 计算

参数

• Cards Only（CardsOnly）（Boolean）：关闭；开启后只匹配上下文中带有来源卡牌的护甲获得请求
• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

Armor Loss Hook

拦截显式 Lose Armor 的数值，伤害吸收护甲与回合开始重置不会进入该处理点；需要抵抗明确的护甲移除时，将 Value 写入 Write Hook

输入

• 无：匹配的值处理点直接启动分支

输出

• Value（Int）：待移除的显式护甲值
• Source（UnitRef）：造成这次护甲损失的单位，没有独立来源时为 Hook 持有者
• Target（UnitRef）：即将失去护甲的 Hook 持有者
• Out（Flow）：继续执行 Hook 计算

参数

• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

Armor Reset Hook

遭遇战规则为 Reset On Turn Start 时，在持有者回合开始触发；传入的 Value 为常规重置目标 0，写入其他非负数可指定重置后保留的护甲，使用 Cancel Hook 则完全保留当前护甲

输入

• 无：匹配的值处理点直接启动分支

输出

• Value（Int）：重置后的待定护甲，初始为 0
• Target（UnitRef）：正在重置护甲的 Hook 持有者
• Out（Flow）：继续执行 Hook 计算

参数

• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

Energy Gain Hook

在显式 Gain Energy 把能量加给玩家之前拦截数值，不控制常规回合开始补充，后者应使用 Energy Per Turn Hook；将 Value 写入 Write Hook 可调整额外获得的能量

输入

• 无：匹配的值处理点直接启动分支

输出

• Value（Int）：待增加的显式能量
• Out（Flow）：继续执行 Hook 计算

参数

• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

Energy Spend Hook

拦截显式 Lose Energy 的数值；打出卡牌会直接扣除已确认费用，不经过该处理点，因此卡牌折扣应使用 Card Cost Hook；将 Value 写入 Write Hook 可调整额外能量损失

输入

• 无：匹配的值处理点直接启动分支

输出

• Value（Int）：待扣除的显式能量
• Out（Flow）：继续执行 Hook 计算

参数

• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

Energy Per Turn Hook

拦截玩家的最大能量基准，Battle Rules > Starting Energy 大于零时采用该值，否则采用玩家单位的基础能量，之后再加上 Run 加成；回合开始时 GCS 会把该结果作为补充值，刷新战斗 UI 时也可能再次查询；Cancel Hook 会回退到这个未经 Hook 修改的基础值，不会停止回合开始的能量补充；该分支应保持纯计算，不要加入一次性特效或音效；将 Value 写入 Write Hook 可修改能量基准

输入

• 无：匹配的值处理点直接启动分支

输出

• Value（Int）：待定的最大能量与回合开始补充值
• Out（Flow）：继续执行 Hook 计算

参数

• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

Inflict Status Hook

在施加方拦截状态层数，执行顺序位于接收方 Hook 与状态叠加规则之前；读取 Status、Stacks、Source 与 Target 可以按状态、层数和接收方决定怎样修改或取消本次施加

输入

• 无：匹配的值处理点直接启动分支

输出

• Status（StatusRef）：即将施加的状态
• Stacks（Int）：进入施加方 Hook 的待定层数
• Source（UnitRef）：施加状态的单位
• Target（UnitRef）：即将接收状态的单位
• Out（Flow）：继续执行 Hook 计算

参数

• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

Receive Status Hook

在接收方拦截经过 Inflict Status Hook 处理后的层数，执行顺序位于状态叠加规则之前；读取 Status、Stacks、Source 与 Target 可以按施加方和状态决定怎样修改或取消本次接收

输入

• 无：匹配的值处理点直接启动分支

输出

• Status（StatusRef）：即将接收的状态
• Stacks（Int）：经过施加方 Hook 后的待定层数
• Source（UnitRef）：施加状态的单位，未提供来源时回退为接收方 Hook 持有者
• Target（UnitRef）：即将接收状态的 Hook 持有者
• Out（Flow）：继续执行 Hook 计算

参数

• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

Status Damage Hook

在通用 Damage Taken Hook 之前拦截状态提供的伤害；给 Status 指定资产可只匹配这一种状态，不指定则匹配全部状态伤害，这项筛选对 Status 与 Card 注册的 Hook 都有效；将 Value 写入 Write Hook 可单独调整状态跳伤

输入

• 无：匹配的值处理点直接启动分支

输出

• Value（Int）：匹配状态的待定伤害
• Source（UnitRef）：造成这次状态伤害的状态施加者，没有独立来源时回退到 Hook 持有者
• Target（UnitRef）：即将受到状态伤害的 Hook 持有者
• Out（Flow）：继续执行 Hook 计算

参数

• Status（GameStatus）：无；指定要匹配的伤害来源状态，留空时匹配全部状态伤害
• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

Card Cost Hook

在持久费用规则与预览 Hook 计算后拦截玩家卡牌的有效费用；预览查询可能反复发生，并会抑制普通 Mutator 与 VFX 副作用，排在既存等待后的预览也会在延迟快照恢复时保留预览模式；正式 TryPlayCard 以当前有效费用作为 Incoming 再执行提交路径；取消预览会保留进入该次预览前的费用，取消正式提交会拒绝本次出牌；将 Value 写入 Write Hook 修改数字费用

输入

• 无：匹配的值处理点直接启动分支

输出

• Card（CardRef）：正在计算有效费用的卡牌实例
• Value（Int）：待定有效费用，正式提交收到同一个当前有效费用，不会改用虚构的 0
• Out（Flow）：继续执行 Hook 计算

参数

• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

Card Playable Hook

TryPlayCard 与 CanPlayCard 在费用和内置 Unplayable 检查后执行，Card 提供正在检查的实例，Playable 提供进入当前 Hook 的待定结果；连接 Cancel Hook 可以拒绝出牌，也可以用 Write Hook 写入明确的布尔值

输入

• 无：可出牌检查直接启动分支

输出

• Card（CardRef）：正在检查是否可打出的卡牌实例
• Playable（Bool）：经过更早 Hook 后进入当前 Hook 的待定可打出结果，初始为开启
• Out（Flow）：继续执行 Hook 控制分支

参数

• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

Draw Count Hook

在 Draw Cards 开始抽牌循环前拦截数量，Hook 结果同时决定实际抽取尝试次数与常规抽牌超过手牌上限后的溢出数量；将 Value 写入 Write Hook 可增加或减少本次抽牌数

输入

• 无：匹配的值处理点直接启动分支

输出

• Value（Int）：待抽取的卡牌数量
• Out（Flow）：继续执行 Hook 计算

参数

• Turn Draw Only（TurnDrawOnly）（Boolean）：关闭；开启后只匹配玩家回合开始的常规抽牌，不匹配起手牌、Action 或 API 抽牌
• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1

Hand Size Hook

GCS 在抽牌、创建手牌或其他上限检查中查询遭遇战最大手牌数时拦截该值；Cancel Hook 会回退到 Battle Rules > Max Hand Size，忽略本次查询中的 Hook 修改；解析器可能执行多次，因此分支应保持确定性，不要放展示效果；将 Value 写入 Write Hook 可替换手牌上限

输入

• 无：匹配的值处理点直接启动分支

输出

• Value（Int）：待定的最大手牌数
• Out（Flow）：继续执行 Hook 计算

参数

• Priority（Number）：0；Status 与 Card Hook 都会参与同一排序，数字越小越先执行，同值保持注册顺序
• Scope（Option）：Battle；仅 Card 有效，可选 Battle 或 Turns；Status Hook 忽略
• Turns（Number）：1；仅 Card 有效，Scope = Turns 时的持续回合数，最小为 1