Combat Triggers

Buffs can trigger effects off the back of a variety of other parts of the combat lifecycle. Building off these allows you to create rich and detailed combat effects.

Table of Contents

  1. Buff Timing Triggers
  2. Action-Based Triggers
  3. Resource Management Triggers
  4. Damage and Healing Triggers
  5. Special System Triggers
  6. Custom Triggers

Buff Timing Triggers

These triggers are related to when buffs are processed during combat rounds.

beforeTechniqueEffects

  • When it triggers: Before any technique is executed by the buff owner
  • Condition: Automatically triggered when the entity with this buff uses any technique
  • Usage: Used for pre-technique modifications, costs, requirements, and effects
  • Examples: Enhancing damage, modifying technique properties, applying costs

afterTechniqueEffects

  • When it triggers: After any technique is executed by the buff owner
  • Condition: Automatically triggered when the entity with this buff uses any technique
  • Usage: Effects that react to or follow up on technique execution
  • Examples: Post-technique healing, delayed damage, follow-up buffs

onStackGainEffects

  • When it triggers: When this buff gains stacks
  • Condition: Automatically triggered whenever the stack count increases
  • Usage: Effects that scale with or react to stacking
  • Examples: Building secondary buffs, tracking stack milestones

onRoundEffects

  • When it triggers: At the end of each combat round
  • Condition: Automatically triggered at round end for all entities with buffs that have these effects
  • Usage: End-of-round processing like DoT damage, healing over time, buff decay, stack management
  • Examples: Poison damage, regeneration, buff duration reduction

onRoundStartEffects

  • When it triggers: At the beginning of each combat round
  • Condition: Automatically triggered at round start for all entities with buffs that have these effects
  • Usage: Start-of-round effects like barrier restoration, buff application, preparation effects
  • Examples: Shield regeneration, stance preparation, round-based buff application

onCombatStartEffects

  • When it triggers: At the very beginning of combat
  • Condition: Automatically triggered when combat begins for entities with buffs that have these effects
  • Usage: Combat initialization effects, stance setup, initial preparations
  • Examples: Initial barrier application, combat preparation buffs

Action-Based Triggers

These triggers are based on specific actions taken during combat.

use.{techniqueType}

  • When it triggers: When a technique of a specific type is used
  • Condition: Triggered when the entity uses any technique matching the specified type
  • Usage: Type-specific bonuses and effects based on technique element
  • Examples:
    • use.fist - Triggers when using fist techniques
    • use.blood - Triggers when using blood techniques

use.{specificEffect}

  • When it triggers: When a technique with a specific effect type is used
  • Condition: Triggered based on the technique’s effect kinds
  • Usage: Effect-specific bonuses and reactions
  • Examples:
    • use.damage - When using techniques that deal damage
    • use.heal - When using techniques that heal
    • use.buffSelf - When using techniques that apply buffs
    • use.buffTarget - When using techniques that buff the target

use.artefact

  • When it triggers: When an artefact activates during a technique
  • Condition: Triggered once per technique execution that causes an artefact to fire
  • Usage: Artefact synergy effects, bonuses that scale with artefact usage

Resource Management Triggers

These triggers relate to spending and consuming resources during combat.

spend.{resourceName}

  • When it triggers: When a specific resource is spent as a technique cost
  • Condition: Triggered when techniques consume specific resources through their cost requirements
  • Usage: Resource-spending bonuses, cost reductions, spending-based effects
  • Examples:
    • spend.Qi Vial - Triggers when Qi Vials are consumed for technique costs
    • spend.{buffName} - Triggers when specific buffs are consumed as costs

consume.{buffName}

  • When it triggers: When a specific buff is consumed/removed
  • Condition: Triggered when buffs are removed through consumption, expiration, or manual removal
  • Usage: Buff consumption effects, cleanup effects, consume-based bonuses
  • Examples: Special effects when certain buffs expire or are consumed

Damage and Healing Triggers

These triggers relate to taking or dealing damage and healing.

takeDamage

  • Condition: Triggered every time the entity receives unblocked damage from any source (after defense calculations)
  • Usage: Damage-based reactions, defensive responses, damage-triggered effects

takeDamage-normal

  • Condition: Triggered when the entity receives untyped (physical) damage. Use for damage-type-specific reactions alongside takeDamage.
  • Usage: Type-specific defensive responses

takeDamage-{damageType}

  • Condition: Triggered when the entity receives damage of the specified type (true, corrupt, disrupt, etc.)
  • Usage: Type-specific defensive or offensive reactions

blockDamage

  • Condition: Triggered every time the entity fully blocks damage from a hit (using barrier or damage resistance)
  • Usage: Reflection effects, counters, parry mechanics

damageHp

  • Condition: Triggered every time the entity deals damage to the opponents health (so not blocked by barrier or damage resistance)
  • Usage: Poison effects, leech mechanics

damageBlocked

  • Condition: Triggered every time the entity fails to break through barrier or damage resistance, and does 0 damage
  • Usage: Recoil effects, powerup mechanics

damageSelf

  • Condition: Triggered for each 1% of max HP dealt as self-damage
  • Usage: Self-harm penalties, masochistic bonuses, self-damage reactions

damageSelf-{damageType}

  • Condition: Triggered for each 1% of max HP dealt as self-damage of the specified type
  • Usage: Type-specific self-damage reactions

fullHeal

  • Condition: Triggered when the entity heals itself from less than full health to full health
  • Usage: Overheal effects, Healthy buff activations

fullBarrier

  • Condition: Triggered when the entity refills its barrier from less than full to full
  • Usage: Overbarrier effects

overHeal

  • Condition: Triggered when the entity heals while already at full health
  • Usage: Overheal bonuses, effects that activate on excess healing

critDamage

  • Condition: Triggered when the entity deals a critical hit that damages the opponent’s HP (not blocked)
  • Usage: Crit-damage amplifiers, bonus effects on critical strikes

critHeal

  • Condition: Triggered when a healing effect critically heals the entity
  • Usage: Enhanced healing-crit bonuses, healing-crit reactions

critBarrier

  • Condition: Triggered when a barrier application critically increases the entity’s barrier
  • Usage: Barrier-crit bonuses, shield amplification effects

Special System Triggers

These triggers are related to specific game systems and mechanics.

interceptBuffEffects

  • When it triggers: When specific buffs are about to be applied
  • Condition: Triggered when buffs matching the interception criteria are being applied
  • Usage: Buff interception, application modification, buff blocking
  • Properties:
    • cancelApplication: true - Prevents the buff from being applied
    • cancelApplication: false - Triggers effects but allows buff application
  • Examples: Immunity effects, buff transformation, application penalties

triggeredBuffEffects

  • When it triggers: Based on custom trigger strings
  • Condition: Triggered when the specified trigger string is activated
  • Usage: Custom trigger-based effects, complex conditional interactions
  • Properties:
    • listenToOpponent: true - This trigger also fires when the opponent triggers the same event
  • Examples: Formation triggers, contingency effects, custom reaction systems

blockTriggerEffects

  • When it triggers: Prevents specific triggers from executing on this buff
  • Condition: When the specified trigger string is about to fire on this buff
  • Usage: Suppressing unwanted trigger effects from other buffs
  • Properties:
    • trigger: string - The trigger to block
    • condition?: TechniqueCondition - Optional condition; blocking only applies if condition is met
    • effects?: BuffEffect[] - Effects to run instead of blocking outright

damageInterceptorEffects

  • When it triggers: Before incoming damage is applied to the entity
  • Condition: Runs whenever damage would be dealt to this entity
  • Usage: Modifying incoming damage (multiply, reduce, or add expressions), or reacting to it before it lands

InterceptorPhase type:

type InterceptorPhase = 'beforeGuardian' | 'preBarrier' | 'postBarrier';

The damage pipeline executes interceptors in this order:

PhaseWhen it runsUse case
'beforeGuardian'Very start of the pipeline, before guardian/puppet interception and every other mitigationFull-negation effects (e.g. a Grace Period that zeroes a hit before puppets absorb it)
'preBarrier'After guardian/puppet interception, before barrier absorptionDefault. Damage reduction, reflect effects
'postBarrier'After barrier absorption, before damage reductionEffects that should see post-barrier net damage
  • trigger?: TechniqueCondition - Condition that must be met for the interceptor to run
  • damageModifier: DamageModifier - How to modify the damage (multiply, reduce, or expression)
  • effects?: BuffEffect[] - Additional effects to run when the interceptor fires
  • phase?: InterceptorPhase - Which phase of the damage pipeline this interceptor runs in. Defaults to 'preBarrier'. (The old afterBarrier boolean field is no longer used: use phase: 'postBarrier' instead of afterBarrier: true and phase: 'preBarrier' instead of afterBarrier: false.)
  • damageTypes?: (DamageType | 'normal')[] - Restrict to specific damage types; 'normal' matches untyped physical damage

Example:

damageInterceptorEffects: [
  {
    damageModifier: { kind: 'multiply', value: 0.5 }, // Reduce incoming damage by 50%
    effects: [
      { kind: 'buffSelf', amount: { value: 1, stat: undefined }, buff: defensiveStance }
    ],
    damageTypes: ['normal', 'true']
  }
]

techniqueAmplifierEffects

  • When it triggers: Before outgoing damage, barrier, heal, or temporary health effects are applied
  • Usage: Amplifying the entity’s own outgoing effects (e.g., increase all damage by 50%)
  • Properties:
    • trigger?: TechniqueCondition - Optional condition
    • amplifier: { kind: 'multiply', value: number, cantUpgrade?: boolean } - Multiplier to apply
    • effects?: BuffEffect[] - Effects to run when amplifying (e.g., consume stacks of the amplifier buff)
    • appliesTo: ('damage' | 'barrier' | 'heal' | 'tempHealth')[] - Which effect kinds to amplify

Example:

techniqueAmplifierEffects: [
  {
    amplifier: { kind: 'multiply', value: 1.5 }, // +50% to all outgoing damage
    appliesTo: ['damage'],
    effects: [
      { kind: 'consumeSelf', amount: { value: 1, stat: undefined }, buff: empoweredBuff }
    ]
  }
]

buffAmplifierEffects

  • When it triggers: When a buff is created on the entity that has this effect
  • Usage: Modifying how many stacks are granted when a specific buff is applied to self
  • Properties:
    • trigger?: TechniqueCondition - Optional condition
    • target: string - Matches buffs by name, buffType, or flag
    • modifier: { kind: 'add' | 'multiply', value: number, cantUpgrade?: boolean } - How to modify stacks
    • effects?: BuffEffect[] - Effects to run when amplifying (e.g., consume stacks of the amplifier)

Example:

buffAmplifierEffects: [
  {
    target: 'Blood Corruption',
    modifier: { kind: 'add', value: 1 }, // +1 extra stack when Blood Corruption is applied
    effects: [
      { kind: 'consumeSelf', amount: { value: 1, stat: undefined }, buff: amplifierBuff }
    ]
  }
]

Custom Triggers

These are specific custom triggers used by various systems in the game.

contingency

  • When it triggers: Special trigger used by Immortal Fang techniques
  • Condition: Activated by specific Immortal Fang technique interactions
  • Usage: Contingency-based effects in the Immortal Fang technique school
  • Examples: Emergency responses, backup effects, failure contingencies

Formation (formationCoreFlag)

  • When it triggers: When formation-based effects are activated
  • Condition: Triggered by formation system interactions
  • Usage: Formation-specific bonuses and effects
  • Examples: Formation technique synergies, group combat bonuses

guardianBroken.{buffName}

  • When it triggers: When a guardian sub-entity (declared via guardianIntercept) reaches 0 HP
  • Condition: Equivalent to a triggeredBuffEffects entry with trigger: 'guardianBroken.${name}' on the guardian buff itself
  • Usage: Effects that fire when a guardian is destroyed

Implementation Notes

Trigger Processing Order

  1. Pre-Technique: beforeTechniqueEffects are processed before technique execution
  2. Technique Execution: Main technique effects with embedded triggers
  3. Post-Technique: Various action-based triggers (use.*, spend.*)
  4. Damage/Healing: takeDamage, damageSelf triggers during damage processing
  5. End of Round: onRoundEffects at round conclusion
  6. Start of Round: onRoundStartEffects at round beginning

Priority System

  • Buffs with higher priority values are processed first
  • Default priority is 0 if not specified
  • Buffs with priority 1 execute before priority 0, which executes before priority -1

Parent Buff Prevention

  • Triggers cannot activate buffs that are already in the parent chain
  • Prevents infinite recursion in buff trigger chains
  • Each trigger call maintains a list of parent buff names to avoid cycles

Condition Evaluation

  • All triggers respect buff conditions (TechniqueCondition)
  • Failed conditions may remove buffs if removeOnConditionFailed is true
  • Condition types include: chance, buff, hp, condition, and inventoryItem
  • Use allowTriggers: true on a condition to let triggeredBuffEffects fire even when the condition fails

Usage Examples

Basic Damage Reaction

triggeredBuffEffects: [
  {
    trigger: 'takeDamage',
    effects: [
      {
        kind: 'heal',
        amount: { value: 10, stat: "power" }
      }
    ]
  }
]

Resource Spending Bonus

triggeredBuffEffects: [
  {
    trigger: 'spend.Qi Vial',
    effects: [
      {
        kind: 'buff',
        buff: strengthBuff,
        amount: { value: 1, stat: undefined }
      }
    ]
  }
]

Technique Type Synergy

triggeredBuffEffects: [
  {
    trigger: 'use.fist',
    effects: [
      {
        kind: 'damage',
        amount: { value: 1, stat: 'power' },
      }
    ]
  }
]

Listen to Opponent

triggeredBuffEffects: [
  {
    trigger: 'use.damage',
    listenToOpponent: true, // Also triggers when the OPPONENT uses damage
    effects: [
      { kind: 'buffSelf', amount: { value: 1, stat: undefined }, buff: counterStance }
    ]
  }
]

Damage Interceptor

damageInterceptorEffects: [
  {
    damageModifier: { kind: 'reduce', percent: 30 },
    damageTypes: ['normal']
  }
]

Technique Amplifier

techniqueAmplifierEffects: [
  {
    amplifier: { kind: 'multiply', value: 1.5 },
    appliesTo: ['damage', 'heal'],
    effects: [
      { kind: 'consumeSelf', amount: { value: 1, stat: undefined }, buff: focusBuff }
    ]
  }
]