Hook Nodes

🧩

Guide

Find the Hook node that reads, modifies, or cancels a pending gameplay value before GCS commits it

Node Usage

Every Hook must resolve synchronously, including control reached indirectly through a Mutator or status lifecycle cascade. Do not connect Wait, Choice, or Delayed Trigger anywhere reachable from a Hook entry; FlowGraph validation reports a direct path, runtime skips that Hook before partial side effects, and a nested operation encountered during Hook resolution degrades Choice to Skipped, Wait to Out, and Delayed Trigger to Done without scheduling deferred work. The shipped Card, Status, and Enemy graphs contain no violating Hook path

Damage Dealt Hook

Intercepts an attacker's outgoing damage before the defender's attack and damage-taken hooks run; connect Value through math or conditions into Write Hook; use On Damage Dealt for behavior that should happen after the hit resolves

Inputs

• None: The matching value point starts the branch

Outputs

• Value (Int): Pending outgoing damage
• Source (UnitRef): The attacking Hook holder
• Target (UnitRef): The unit that will receive the damage
• Out (Flow): Continues into the Hook calculation

Parameters

• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

Damage Taken Hook

Intercepts incoming damage after an attack-specific hook, or after Status Damage Hook for status ticks, but before armor absorbs it; connect the replacement Value to Write Hook for vulnerability or resistance

Inputs

• None: The matching value point starts the branch

Outputs

• Value (Int): Pending damage before armor absorption
• Source (UnitRef): The attacker or status applier when one is known, otherwise the defending Hook holder
• Target (UnitRef): The defending Hook holder
• Out (Flow): Continues into the Hook calculation

Parameters

• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

Attack Taken Hook

Intercepts attacker-driven damage on the defender before the general Damage Taken Hook; status damage and direct HP loss do not enter this value point; connect Value to Write Hook when only attacks should be changed

Inputs

• None: The matching value point starts the branch

Outputs

• Value (Int): Pending attack damage
• Source (UnitRef): The attacking unit
• Target (UnitRef): The defending Hook holder
• Out (Flow): Continues into the Hook calculation

Parameters

• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

HP Gain Hook

Intercepts the requested healing amount before max-HP clamping; connect the calculated Value to Write Hook to amplify or suppress healing; the after-the-fact Entry is On HP Gained

Inputs

• None: The matching value point starts the branch

Outputs

• Value (Int): Pending healing amount before the max-HP cap
• Source (UnitRef): The unit responsible for the heal, or the healed Hook holder when no source was supplied
• Target (UnitRef): The healed Hook holder
• Out (Flow): Continues into the Hook calculation

Parameters

• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

HP Loss Hook

Intercepts actual HP loss; in the damage path it runs after armor has determined the HP portion; it also runs for direct Lose HP; connect Value to Write Hook for mechanics that modify HP loss regardless of how that loss was requested

Inputs

• None: The matching value point starts the branch

Outputs

• Value (Int): Pending HP loss
• Source (UnitRef): The unit responsible for the HP loss, or the affected Hook holder when no source was supplied
• Target (UnitRef): The Hook holder that will lose HP
• Out (Flow): Continues into the Hook calculation

Parameters

• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

Armor Gain Hook

Intercepts armor before Gain Armor adds it to the holder; connect Value to Write Hook for armor scaling; use On Armor Gained for a reaction after the armor changes

Inputs

• None: The matching value point starts the branch

Outputs

• Value (Int): Pending armor gain
• Source (UnitRef): The unit responsible for the armor gain, or the receiving Hook holder when no source was supplied
• Target (UnitRef): The Hook holder gaining armor
• Out (Flow): Continues into the Hook calculation

Parameters

• Cards Only (CardsOnly) (Boolean): Off; When enabled, matches armor created by a card context and ignores other armor gains
• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

Armor Loss Hook

Intercepts an explicit Lose Armor amount; armor consumed by damage and turn-start reset do not use this value point; connect Value to Write Hook for resistance to explicit armor removal

Inputs

• None: The matching value point starts the branch

Outputs

• Value (Int): Pending explicit armor loss
• Source (UnitRef): The unit responsible for the armor loss, or the affected Hook holder when no source was supplied
• Target (UnitRef): The Hook holder losing armor
• Out (Flow): Continues into the Hook calculation

Parameters

• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

Armor Reset Hook

Runs at the holder's turn start when the encounter rule is Reset On Turn Start; the incoming Value is 0, the normal reset target; write a different non-negative value to choose the armor left after reset, or use Cancel Hook to leave the current armor untouched

Inputs

• None: The matching value point starts the branch

Outputs

• Value (Int): Pending post-reset armor value, initially 0
• Target (UnitRef): The Hook holder whose armor is being reset
• Out (Flow): Continues into the Hook calculation

Parameters

• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

Energy Gain Hook

Intercepts the amount passed to an explicit Gain Energy operation before it is added to the player; it does not control the normal turn-start refill; use Energy Per Turn Hook for that baseline; connect Value to Write Hook for bonuses or penalties to energy gains

Inputs

• None: The matching value point starts the branch

Outputs

• Value (Int): Pending explicit energy gain
• Out (Flow): Continues into the Hook calculation

Parameters

• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

Energy Spend Hook

Intercepts the amount passed to an explicit Lose Energy operation; card play subtracts the accepted cost directly and does not use this value point, so card discounts belong in Card Cost Hook; connect Value to Write Hook for explicit energy-drain modifiers

Inputs

• None: The matching value point starts the branch

Outputs

• Value (Int): Pending explicit energy loss
• Out (Flow): Continues into the Hook calculation

Parameters

• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

Energy Per Turn Hook

Intercepts the player's resolved maximum energy: Battle Rules > Starting Energy when it is greater than zero, otherwise the player unit's base energy, plus the run bonus; at turn start GCS assigns this result as the refill amount, and the same resolver can also be queried while refreshing battle UI. Cancel Hook returns that unmodified base value rather than stopping the turn-start refill; keep this Hook free of one-shot presentation effects, and connect Value to Write Hook to change the baseline

Inputs

• None: The matching value point starts the branch

Outputs

• Value (Int): Pending maximum energy and turn-start refill value
• Out (Flow): Continues into the Hook calculation

Parameters

• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

Inflict Status Hook

Runs on the applying unit before the receiver's status Hook and before stack rules are applied. Status identifies the incoming status, Stacks carries the pending count, and the unit ports identify both parties; connect Out to cancellation or an explicit replacement stack value

Inputs

• None: The matching value point starts the branch

Outputs

• Status (StatusRef): The status about to be inflicted
• Stacks (Int): Pending stack count before the receiver's Hook and stack rule
• Source (UnitRef): The applying Hook holder
• Target (UnitRef): The receiving unit
• Out (Flow): Continues into the Hook calculation

Parameters

• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

Receive Status Hook

Runs on the receiving unit after any Inflict Status Hook has changed the pending count and before the status's stack rule is applied. Status identifies the incoming status, Stacks carries the current pending count, and the unit ports keep the original applier and receiver; connect Out to cancellation or an explicit replacement stack value

Inputs

• None: The matching value point starts the branch

Outputs

• Status (StatusRef): The status about to be received
• Stacks (Int): Pending stack count after source-side Hooks
• Source (UnitRef): The applying unit, or the receiving Hook holder when no source was supplied
• Target (UnitRef): The receiving Hook holder
• Out (Flow): Continues into the Hook calculation

Parameters

• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

Status Damage Hook

Intercepts damage supplied by a status before the general Damage Taken Hook; set Status to limit either a status or active card Hook to one damage status, or leave it unassigned to match every status-damage source; connect Value to Write Hook for tick-specific scaling

Inputs

• None: The matching value point starts the branch

Outputs

• Value (Int): Pending damage from the matching status
• Source (UnitRef): The status applier when one is known, otherwise the damaged Hook holder
• Target (UnitRef): The damaged Hook holder
• Out (Flow): Continues into the Hook calculation

Parameters

• Status (GameStatus): None; Selected damage status, or every status-damage source when None
• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

Card Cost Hook

Intercepts the player's effective card cost after persistent cost rules and preview Hook calculation have been applied; preview queries can occur repeatedly and suppress regular Mutator and VFX side effects, and a preview queued behind an existing wait retains preview mode after its deferred snapshot resumes; the committed TryPlayCard pass runs the Hook with the current effective cost as Incoming; cancelling a preview keeps the cost from before that preview, while cancelling the committed pass rejects the play; connect Card into a filter and Value into Write Hook for the numeric cost

Inputs

• None: The matching value point starts the branch

Outputs

• Card (CardRef): Card instance whose effective cost is being evaluated
• Value (Int): Pending effective cost; the committed play pass receives the same current effective cost, not a synthetic 0
• Out (Flow): Continues into the Hook calculation

Parameters

• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

Card Playable Hook

Runs during CanPlayCard and TryPlayCard after energy sufficiency and the built-in Unplayable keyword check; Card identifies the candidate and Playable carries the current decision; connect the branch to Cancel Hook or write an explicit Boolean to reject or preserve the play

Inputs

• None: The playability check starts the branch

Outputs

• Card (CardRef): Card instance being checked
• Playable (Bool): Current playability after earlier Hooks, initially true
• Out (Flow): Continues into the Hook control branch

Parameters

• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

Draw Count Hook

Intercepts the count supplied to a draw before the loop starts; turn-draw overflow is calculated from the resolved value, so reduced or increased draw counts produce matching discard lifecycle events; connect Value to Write Hook for extra or reduced draws

Inputs

• None: The matching value point starts the branch

Outputs

• Value (Int): Pending number of cards to draw
• Out (Flow): Continues into the Hook calculation

Parameters

• Turn Draw Only (TurnDrawOnly) (Boolean): Off; When enabled, matches the regular player-turn draw step and ignores opening-hand and explicit draw operations
• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1

Hand Size Hook

Intercepts the encounter's maximum hand size whenever GCS needs the limit for drawing, adding a card, or related checks. Cancel Hook returns Battle Rules > Max Hand Size, ignoring Hook changes for that query; because the resolver can run more than once, keep the branch deterministic and free of presentation side effects; connect Value to Write Hook to replace the cap

Inputs

• None: The matching value point starts the branch

Outputs

• Value (Int): Pending maximum hand size
• Out (Flow): Continues into the Hook calculation

Parameters

• Priority (Number): 0; Smaller values run first across both status and active card Hooks
• Scope (Option): Battle; Card only: Battle or Turns; status Hooks ignore it
• Turns (Number): 1; Card only: lifetime when Scope = Turns, clamped to at least 1