How to Add New Character Buff

Purpose and Scope

This guide explains how to add a new character buff item that the player can use from the inventory.

Use this workflow when the buff: — is an item of type World.Items.Types.Buff — belongs to one of the character buff categories — activates a CharacterState on the player — is handled by BP_BuffComponent — must work through the State System and DT_CharacterStates

This guide is for character buffs only.

Do not use this workflow for: — melee weapon buffs placed into the weapon buff slot — melee attack debuffs applied through ANS_CC_Debuffs

Supported buff categories

Character buffs use one of these categories: — Health — Armor — Experience — Damage

When creating the item in Item Assistant, you choose the buff category there. This category must match the gameplay tag namespace and the logic you later add in BP_BuffComponent.

Core idea

A character buff in this project is not just an inventory item. It is a full chain: 1. Create the item as Buff in Item Assistant. 2. Generate the item row and data assets. 3. Create a new CharacterStates.Buffs... gameplay tag. 4. Assign that tag in the buff clarification asset. 5. Register the state in DT_CharacterStates. 6. Add the tag to BP_BuffComponent. 7. Implement activation and deactivation logic in the state solvers.

After that, the buff becomes a normal State System participant and other gameplay logic can react to it.

Step 1. Create the buff in Item Assistant

Open Item Assistant and create a new item.

Set: — Item Type = Buff — Buff Category = one of: — Health — Armor — Experience — Damage

Then fill: — all General fields — all Inventory fields

After that, the tool creates the required data assets and adds a new row to the item database: — item data asset — inventory data asset — clarification data asset — new row in DT_ItemData

Step 2. Create the gameplay tag

Open Project Settings and add a new gameplay tag for the buff.

Use the correct namespace based on the buff category: — CharacterStates.Buffs.Armor.<BuffName> — CharacterStates.Buffs.Damage.<BuffName> — CharacterStates.Buffs.Experience.<BuffName> — CharacterStates.Buffs.Health.<BuffName>

Examples: — CharacterStates.Buffs.Armor.ExtraArmor — CharacterStates.Buffs.Damage.Berserk — CharacterStates.Buffs.Experience.DoubleXP — CharacterStates.Buffs.Health.ExtraLife

The category in the tag must match the category chosen in Item Assistant.

Step 3. Fill the clarification asset

Open the created BP_Buff_ClarData asset for the new buff.

Fill at least: — Character Tag — Actions After Using If Buff In Use — Actions After Using If Buff Not In Use — Remove From Inventory After Deactivating, if needed by design

In Character Tag, set the gameplay tag created in Project Settings.

Example: — CharacterStates.Buffs.Health.ExtraLife

The clarification asset is what connects the inventory buff item to the runtime State System.

Step 4. Register the state in DT_CharacterStates

Open DT_CharacterStates.

Create a new character state row for the buff tag and fill all required fields for that state.

At this stage, define: — which components participate in the state logic — which components validate or react to the state — any other required fields used by your project setup for this state

This step is required because buff activation goes through the shared State System, and the mediator validates states against DT_CharacterStates.

Step 5. Add the tag to BP_BuffComponent HandleState

Open BP_BuffComponent.

Find the parameter: — HandleState

Add the new gameplay tag there.

This tells BP_BuffComponent that it must handle this state as one of its supported buff states. Without this, the component will not participate correctly in state-driven buff logic.

Step 6. Add activation logic

In BP_BuffComponent, open: — Activate State Solver

Find the Switch node used for buff tags.

Add the new gameplay tag to the switch and call: — Activate BF On Character

This is the activation entry for the new character buff. When the state becomes active, the component will route the new buff through this branch.

Step 7. Add deactivation logic

In BP_BuffComponent, open: — Deactivate State Solver

Find the Switch node used for buff tags.

Add the new gameplay tag to the switch and call: — Deactivate BF

This ensures the buff is removed correctly when it expires, is toggled off, or is otherwise deactivated by gameplay logic.

Step 8. Test the buff in game

After setup, test the full flow: 1. Obtain the new buff item. 2. Use it from the inventory. 3. Verify that the item resolves to the correct clarification asset. 4. Verify that the Character Tag is activated. 5. Verify that DT_CharacterStates allows the state. 6. Verify that BP_BuffComponent catches the tag through HandleState. 7. Verify that Activate State Solver runs. 8. Verify that deactivation also works through Deactivate State Solver.

A correctly configured character buff should behave as a normal runtime state, not as a one-off isolated item effect.

Sanity check

Before considering the buff finished, verify all of the following: — the item was created through Item Assistant — Item Type is Buff — Buff Category is correct — General and Inventory data are filled — the generated row exists in DT_ItemData — the gameplay tag exists in Project Settings — the tag uses the correct namespace for its category — the same tag is assigned in BP_Buff_ClarData — the state exists in DT_CharacterStates — the tag was added to BP_BuffComponent.HandleState — Activate State Solver contains the new tag and calls Activate BF On Character — Deactivate State Solver contains the new tag and calls Deactivate BF

Example: Extra Life

Extra Life is a Health-category character buff. Its tag is: — CharacterStates.Buffs.Health.ExtraLife

This buff works differently from simple stat buffs. Instead of only modifying a number, it spawns an actor behind the player that absorbs incoming damage. While that spawned actor still has HP, it protects the player as additional health. The buff can end either when the actor runs out of HP or when the player removes the buff manually.

To support such a buff, the project uses custom logic in: — BP_BuffComponent — BPI BC TryToReduceDamageByBuffs — TryToApplyDamageOnBuffExtraLife

During incoming damage processing, the project first tries to reduce damage through armor and buffs. In the branch for Health-category buff reduction, TryToApplyDamageOnBuffExtraLife contains a switch that currently handles: — CharacterStates.Buffs.Health.ExtraLife

If the player has CharacterStates.Buffs.Health.ExtraLife, the function calculates how much damage should be redirected to the spawned buff actor and how much, if any, should still reach the player.

If the player has a different Health buff, you can add your own calculation rules there.

If none of the listed Health buffs are active, the incoming damage passes through without Health-buff reduction.

Notes for custom Health buffs

Health-category buffs are not all required to behave like Extra Life.

You can create another Health buff with its own rules, but if it must affect damage reduction, you also need to extend the relevant logic in BP_BuffComponent, especially in the branch that processes Health-type buff mitigation.

Otherwise, the new tag may activate correctly as a state but will not change incoming damage behavior.