How to Add a New Debuff

Purpose and Scope

This guide explains how to add a new debuff that is applied to the victim as a Character State, typically during melee attacks.

Use this workflow when the debuff: — is a Character State on the victim — is attempted by the attacker during an attack animation — can require specific buffs on the attacker — must be driven by probabilities from Anim Notifies

Core idea

In this system, debuffs are just Character States on the victim.

High-level flow: 1. The attacker hits the victim. 2. The attacker tries to apply one or more debuffs. 3. If probability and conditions succeed, a debuff Character State is activated on the victim. 4. The victim’s BP_BuffComponent handles the debuff’s runtime logic.

There is no separate “debuff system” — everything is built on top of: — Character States, — BP_BuffComponent, — data assets (BP_DA_DebuffData_Master, BP_DA_Debuff_ANS_Data), — and DA_DebuffContainer.

Step 1. Create the debuff Character State

Follow your existing “How to add new character state” process:

1. Create a gameplay tag for the debuff, usually under an effects namespace such as:

   • CharacterStates.Effects.<DebuffName>.

2. Add a new row for this tag to DT_CharacterStates.

3. Fill all required fields (which components participate, solver setups, etc.).

At this point, the debuff exists as a standard Character State, but is not yet connected to melee or debuff data assets.

Step 2. Register the debuff in BP_BuffComponent

Open BP_BuffComponent.

1. Find the parameter:
   • HandleState.
2. Add the new debuff gameplay tag to this list/container.

This marks the debuff as something BP_BuffComponent is responsible for.

Activation and deactivation solvers

Still in BP_BuffComponent:

1. Open Activate State Solver.
   • Find the Switch over gameplay tags.
   • Add your new debuff tag as a branch.
   • In this branch, call a function that implements debuff activation logic (e.g. start a timer, apply FX, set flags).
2. Open DeactivateStateSolver.
   • Again, find the Switch over gameplay tags.
   • Add the debuff tag as a branch.
   • In this branch, call the matching deactivation function (stop timers, clear FX, remove flags).

This is exactly the same pattern you use when adding any other Character State to BP_BuffComponent.

Step 3. Create the main debuff data asset (rules)

Now define the rules for this debuff in a data asset.

1. Create a child data asset from:
   • BP_DA_DebuffData_Master.

Fill the key parameters:

• Debuff Tag
  • set to the debuff gameplay tag you created in Step 1.
• Options for Required Buffs
  • this is an array.
  • each entry describes which buffs the attacker must have to be allowed to apply this debuff.
  • typical use case: elemental weapon buffs or character buffs that “unlock” certain debuffs.
  • leave it empty if the debuff should always be allowed (no required buffs).

This asset describes: — what debuff we are talking about (tag), — what conditions (attacker buffs) are required.

Step 4. Add the debuff to DA_DebuffContainer

Open DA_DebuffContainer.

1. Add your BP_DA_DebuffData_Master child asset to the array/list of debuffs.

DA_DebuffContainer is the global registry of debuffs used by the melee / ANS system.
If you skip this, the game will not find your debuff rules when trying to apply it.

Step 5. Create the AnimNotify debuff data asset (probabilities)

Now configure how the debuff is attempted during an attack.

1. Create a data asset from:
   • parent class BP_DA_Debuff_ANS_Data.

Inside this asset you define which debuffs this notify can attempt:

• For each debuff entry:
  • Debuff = the debuff gameplay tag.
  • Probability = a float from 0.0 to 1.0:
    • 0.0 — never applied.
    • 1.0 — always applied (if allowed by rules).
    • between 0.0 and 1.0 — chance per hit window.

One BP_DA_Debuff_ANS_Data can contain multiple debuffs, each with a separate probability.

Step 6. Connect ANS_CC_Debuffs in the attack montage

Open the attack Anim Montage that should be able to apply this debuff.

1. Add an Anim Notify State:
   • ANS_CC_Debuffs.
2. In its details, set:
   • Data = your BP_DA_Debuff_ANS_Data asset from Step 5.

Placement recommendation: — Place ANS_CC_Debuffs so it overlaps the actual hit-check window (ANS_CheckHits). — This ensures debuffs are only attempted on real hits.

Step 7. Runtime flow

After configuration, a melee hit with this montage behaves roughly like this:

1. The attacker swings the melee weapon.
2. While ANS_CheckHits is active, a victim is detected.
3. At the same time, ANS_CC_Debuffs is active and points to BP_DA_Debuff_ANS_Data.
4. For each debuff in BP_DA_Debuff_ANS_Data:
   • A random roll is made against Probability.
   • If the roll passes, that debuff tag is “selected”.
5. The system looks up that debuff tag in DA_DebuffContainer:
   • finds the BP_DA_DebuffData_Master entry,
   • checks Options for Required Buffs on the attacker:
     • does the attacker have the required buff(s)?
6. If all required buffs are present (or none are required):
   • the victim’s State System is asked to activate the debuff Character State.
7. On the victim’s character:
   • BP_BuffComponent sees this tag in HandleState,
   • Activate State Solver is called and runs your debuff activation branch.
8. When the debuff ends:
   • the State System deactivates the tag,
   • DeactivateStateSolver runs and cleans up effects.

Final checklist

Before considering the new debuff complete, confirm:

• Character State:
  • Debuff gameplay tag is created.
  • New row in DT_CharacterStates is added and correctly filled.
• Buff component:
  • Tag is added to BP_BuffComponent.HandleState.
  • Activate State Solver has a branch for this tag and calls your debuff activation function.
  • DeactivateStateSolver has a branch and calls your deactivation function.
• Debuff rules:
  • Child asset from BP_DA_DebuffData_Master exists.
  • Debuff Tag is set correctly.
  • Options for Required Buffs contains the necessary attacker buffs (or is empty if not needed).
  • Asset is added to DA_DebuffContainer.
• AnimNotify data:
  • Asset from BP_DA_Debuff_ANS_Data exists.
  • It contains your debuff tag with an appropriate Probability.
• Animation:
  • Attack montage includes ANS_CC_Debuffs.
  • ANS_CC_Debuffs.Data references your BP_DA_Debuff_ANS_Data.
  • The notify window overlaps with the actual hit-check window.

If any of these steps are missing, the debuff may not be applied at all or may activate without the intended logic.

Notes

• The actual gameplay effect (slow, damage over time, stun, etc.) is implemented inside:
  • BP_BuffComponent for the victim, and/or
  • other components reacting to the active debuff Character State.
• From the engine’s point of view, a debuff is just another Character State. All “special behavior” comes from:
  • how you configure BP_DA_DebuffData_Master and BP_DA_Debuff_ANS_Data,
  • and how you handle the tag inside BP_BuffComponent.