Weapon Buffs and Debuffs

Purpose and Scope

Weapon buffs are a separate type of buffs that are equipped into a dedicated buff slot on a melee weapon. They are not passive character buffs placed directly on the player.

Weapon buffs use the same clarification data asset as other buffs: BP_Buff_ClarData. The general buff parameters remain the same, but the runtime usage is different because the buff is attached to a weapon and can participate in debuff and special attack logic.

This document describes: — weapon buffs equipped into melee weapons — how weapon buffs are assigned through the inventory UI — how weapon buffs interact with special attacks — how weapon buffs allow an attacker to apply debuffs to a victim

Core idea

A weapon buff is still a regular buff item of type World.Items.Types.Buff. The difference is that it is placed into the weapon buff slot instead of being activated as a passive self-buff on the player.

Like other buffs, a weapon buff uses BP_Buff_ClarData and activates a CharacterState tag. For weapon buffs, the tag structure must always be:

CharacterStates.Buffs.Weapon.<TagName>

Example: — CharacterStates.Buffs.Weapon.SwordFire

The active weapon buff becomes part of the attacker’s gameplay state and can then be used as a condition for: — special attacks — debuff application to the victim

Weapon buff slot

Each melee weapon has exactly one weapon buff slot.

Weapon buffs are equipped into that separate slot on the melee weapon.

To equip a weapon buff: 1. Add the buff item to the inventory. 2. Equip the melee weapon into its equipment slot. 3. Double-click the equipped weapon. 4. The weapon details panel opens on the right side. 5. In that panel, find the buff slot named Weapons. 6. Click that slot. 7. A dropdown list appears with all items that can be equipped on this weapon as buffs. 8. Select the desired buff item.

This means weapon buffs are assigned through the weapon details UI, not through the four passive character buff slots.

Active state behavior

A weapon buff is considered active at all times while it is equipped on the weapon.

It does not activate only when the weapon is currently in the player’s hands. If the player equips a buff on a back weapon, that weapon also uses the buff visually while it is on the character’s back. weapon buff adds an overlay material, that visual change can also appear on the back weapon. A weapon with an ice buff may visibly show the ice overlay even while it is stored on the character.

Because of this, weapon buffs are persistent equipment-linked states, not temporary “only while swinging” effects.

Supported weapon buffs

Each melee weapon controls which buff items are allowed on it through the Possible Buffs parameter in its clarification data asset.

Possible Buffs is an array of Name. It must contain row names from DT_ItemData.

This array defines all buff items that are allowed to appear in the weapon buff dropdown for that weapon.

Example

Suppose there is a buff item: — row name in DT_ItemData: BF_SWS_Fire

This item can exist in the inventory as a normal buff item. To allow it to be equipped on a specific weapon, add its row name to Possible Buffs in the weapon clarification data asset.

Example: — Possible Buffs contains BF_SWS_Fire

After that, when the player opens the weapon details panel for that weapon, the game allows BF_SWS_Fire to be selected in the Weapons buff slot.

BP_Buff_ClarData

Weapon buffs use the same BP_Buff_ClarData asset as passive character buffs.

The parameters are the same: — StaticMesh — Character Tag — Actions After Using If Buff In Use — Actions After Using If Buff Not In Use — Remove From Inventory After Deactivating

For weapon buffs, the most important rule is the gameplay tag structure:

CharacterStates.Buffs.Weapon.<TagName>

Notes for weapon buffs

Actions After Using If Buff In Use describes what should happen while the weapon buff is active.

Because the weapon buff stays active while equipped, these actions may affect both the weapon in hand and the same weapon while it is visually attached on the character, depending on the configured effect type.

Actions After Using If Buff Not In Use is used for cleanup or for behavior that must apply when the buff is equipped but the main active-use conditions are not met.

Weapon buffs vs passive character buffs

The main difference between a passive character buff and a weapon buff is not the data asset class. Both use BP_Buff_ClarData.

The actual difference is runtime behavior: — a passive character buff affects the player directly — a weapon buff is attached to a melee weapon — a weapon buff remains active while equipped on that weapon — a weapon buff can affect the visual state of the equipped or back-mounted weapon — a weapon buff can be used as a condition for applying debuffs to a victim — a weapon buff can be used as a condition for selecting special attack behavior

Because of this, weapon buffs are part of melee combat logic, not just player self-buff logic.

Special attacks integration

Weapon buffs are also used in the Special Attacks Container Data parameter of the melee weapon clarification data asset.

Parameter type:

map<GameplayTag, BP_CC_SPA_Container>

This map connects a character state tag used by a melee animation to a special attack container asset.

BP_CC_SPA_Container

BP_CC_SPA_Container is a data asset used by the melee special attack system.

Parameters

Special Attacks — map<GameplayTag, BP_CC_SPA_Data_Master>

The key of this map is a gameplay tag.

In the current structure, Special Attacks is keyed by GameplayTag, not by enum buff type. In practice, these keys are matched against the active weapon buff tag.

The value is a BP_CC_SPA_Data_Master data asset that describes what happens for that special attack entry.

BP_CC_SPA_Data_Master

Parent class: PrimaryDataAsset

Variables

Variable	Type	Description
Effect Type	E_EffectType	Type of gameplay or visual effect.
Cascade Particle	ParticleSystem	Cascade particle system used by the effect.
Niagara System	NiagaraSystem	Niagara particle system used by the effect.
Spawn Place	E_PlaceToSpawn	Place where the effect should be spawned.
Attach To	E_ZeroLocationComponent	Component the effect should be attached to.
Custom Attach Socket	name	Custom socket used for attachment.
Orient In Direction Of	E_OrientInDirectionOf	Defines how the effect is oriented.
Add Rotation	Rotator	Additional world rotation for the effect.
Custom Spawn On Socket	name	Custom socket used as the spawn point.
Add To Spawn Place Location	float	Additional location offset from the spawn point.
Probability of Use	float	Probability from 0 to 1 that this entry is used.
Damage	float	Damage dealt by the effect, if applicable.
Need to activate a new state	bool	If true, the system activates another state during special attack execution.
Damage Type	BP_DamageTypeMaster_C	Damage type used by the effect.
Lifespan	float	Lifetime of the spawned effect or actor.
Activate Tag	GameplayTag	Character state activated by this special attack.

Activate Tag is the tag that is activated when the special attack logic requests a new state.

How special attacks work

The general runtime flow is:

The player starts a melee hit animation.
That animation contains the anim notify AN_CC_ActivateState.
AN_CC_ActivateState has a Tag parameter of type GameplayTag.
By default, this tag is CharacterStates.CloseCombat.SpecialAttack.
You may use another tag if needed, but then the same tag must exist as a key in Special Attacks Container Data.

After that, the system performs the following logic: 1. It reads the clarification data asset of the weapon currently associated with the attack. 2. It reads the Special Attacks Container Data map from that weapon. 3. It finds the BP_CC_SPA_Container whose key matches the tag passed by AN_CC_ActivateState. 4. It checks which weapon buff is currently equipped on that weapon. 5. It compares the active weapon buff tag with the keys in Special Attacks inside that BP_CC_SPA_Container. 6. If a matching key is found, the system gets the corresponding BP_CC_SPA_Data_Master. 7. It reads Need to activate a new state. 8. If that value is true, the system reads Activate Tag. 9. The system calls ActivateState(Activate Tag) through BP_ModulesMediator.

By default, this special attack usually spawns some temporary effect or damage zone at the hit location, but technically it is just a normal CharacterState. Its gameplay logic can be implemented however the project needs.

Debuffs

Debuffs are applied through the anim notify state ANS_CC_Debuffs.

This notify state must be added to the melee attack Anim Montage.

In the notify details, configure: — Data

This parameter references a data asset with parent class:

BP_DA_Debuff_ANS_Data

BP_DA_Debuff_ANS_Data

This data asset contains the debuff setup used by ANS_CC_Debuffs.

Main parameter

Debuff Effects Data — S_DebuffsContainer

S_DebuffsContainer contains an array of S_DebuffsSingle.

S_DebuffsSingle

S_DebuffsSingle contains: — Debuff — GameplayTag — Probability — float in range 0..1

Debuff is the CharacterState tag that may be activated on the victim.

Probability defines the chance to activate that debuff when a valid hit happens during the notify window.

Debuff notify placement

ANS_CC_Debuffs should be placed inside the active time range of another anim notify state: ANS_CheckHits.

This is important because hit detection against the victim happens during ANS_CheckHits.

So the logic is: — while ANS_CheckHits is active, the system checks whether the attack actually hit a victim — if a hit happened during the ANS_CC_Debuffs window, the system tries to activate the configured debuff on the victim

Debuff validation

Even if the notify wants to apply a debuff, the system still checks whether that debuff is allowed to be activated.

This validation is done through DA_DebuffContainer.

DA_DebuffContainer stores a list of all debuff data assets derived from BP_DA_DebuffData_Master.

These data assets define under which conditions the attacking player is allowed to apply a specific debuff.

BP_DA_DebuffData_Master

Parameters

Variable	Type	Description
Debuff Tag	GameplayTag	Debuff state that may be activated on the victim.
Options for Required Buffs	S_RequiredStates_Operands[]	Conditions required for debuff activation.
Value	float	Generic parameter used by gameplay logic, for example duration.

S_RequiredStates_Operands

Fields: — BuffsList — GameplayTagContainer

BuffsList contains the required gameplay tags that must be present for the debuff to be allowed.

In practice, this is commonly used to require a specific weapon buff on the attacker.

How debuff application works

The runtime flow is:

The attack Anim Montage contains ANS_CheckHits.
Inside that hit window, the montage also contains ANS_CC_Debuffs.
A valid hit against a victim is detected.
ANS_CC_Debuffs reads its BP_DA_Debuff_ANS_Data.
The system checks all configured S_DebuffsSingle entries.
For each entry, it rolls the Probability.
If a debuff passes the probability check, the system looks into DA_DebuffContainer.
It finds the corresponding BP_DA_DebuffData_Master by matching Debuff Tag.
It checks Options for Required Buffs.
If all required conditions are satisfied, the debuff state is activated on the victim.
If the conditions are not satisfied, the debuff is not applied.

So a debuff is not just direct damage or only a visual effect. In this system, a debuff means activating a CharacterState on the victim.

Important rule

The required buffs in Options for Required Buffs are checked on the attacker, not on the victim.

This is the key link between weapon buffs and debuffs: — the attacker equips a weapon buff — that weapon buff stays active while equipped — the attacker lands a hit — the system checks whether that weapon buff allows a specific debuff — if yes, the victim receives the debuff state

Example: combustion

DA_DBF_Combustion

Debuff Tag = CharacterStates.Effects.DebuffCombustion
Options for Required Buffs = CharacterStates.Buffs.Weapon.SwordFire
Value = not used

This is read as:

The attacker is allowed to apply CharacterStates.Effects.DebuffCombustion to the victim only if the attacker currently has the gameplay tag CharacterStates.Buffs.Weapon.SwordFire.

Example: stun

DA_DBF_Stun

Debuff Tag = CharacterStates.Effects.DebuffStun
Options for Required Buffs = empty
Value = 1.5

This is read as:

The attacker is allowed to apply CharacterStates.Effects.DebuffStun without additional buff requirements.

Value = 1.5 can then be used by gameplay code to define the stun duration, for example 1.5 seconds.

Design rules

Use weapon buffs when the buff must be attached to a melee weapon and affect melee behavior.

Typical use cases: — enabling a special attack branch — allowing a debuff on hit — spawning attack-specific visual effects — changing melee hit behavior based on the equipped weapon buff — changing the persistent visual appearance of the weapon, including the back weapon version

Do not document such buffs as passive character buffs, because their slot, UI flow, and runtime role are different.

Summary of the relationship

The relationship between the systems is:

DT_ItemData defines the buff item row
BP_Buff_ClarData defines the weapon buff behavior and tag
Possible Buffs on the melee weapon defines which buff rows are allowed on that weapon
the weapon has exactly one weapon buff slot
the equipped weapon buff remains active while it stays equipped
Special Attacks Container Data defines which special attack container is used for a given melee state
BP_CC_SPA_Container maps weapon buff tags to special attack data
BP_CC_SPA_Data_Master defines what the matching special attack actually does
ANS_CC_Debuffs tries to apply debuffs during hit windows
BP_DA_Debuff_ANS_Data defines which debuffs are attempted and with what probability
DA_DebuffContainer and BP_DA_DebuffData_Master define whether the attacker is allowed to apply those debuffs