How to Add a New Character State

This guide explains how to add and configure a new character state in RPG Engine v6, using the CharacterStates.Weapons.Reload state as a practical example.

The process involves creating a Gameplay Tag, configuring the rules in DT_CharacterStates, implementing component validation checks via BPI_StateMachine, and triggering the state from the input component.

Step 1: Create the Gameplay Tag

Before adding rules, the state needs a Gameplay Tag.

1. Open Project Settings.
2. Navigate to the Gameplay Tags section.
3. Create a new tag. For this example, the tag is CharacterStates.Weapons.Reload.

Step 2: Configure DT_CharacterStates

The central rules for the state are defined in DT_CharacterStates.

1. Open DT_CharacterStates.
2. Add a new row. The Row Name must exactly match the Gameplay Tag (CharacterStates.Weapons.Reload).
3. Set the CharacterState field to the newly created tag (CharacterStates.Weapons.Reload).

Define Component Checks

To ensure the state is only activated when conditions are met, assign components that must validate the request:

• ServerMustPassComponents: Add Modules.FirearmsComponent and Modules.InventoryComponent. The server will query both before allowing the reload.
• ClientMustPassComponents: Add Modules.FirearmsComponent. The client will perform a local check (such as distance to a wall) before sending the request to the server.

Configure Tag Transitions and Restrictions

For the Reload example, configure the remaining fields as follows:

• Necessary Tags For Activating: Leave Empty. No specific states are required to start a reload.
• Forbidden Tags For Activating: Add states that block reloading (for example, various movement or unusual skill states).
• Before Activating Cancel Tags: Set to CharacterStates.Weapons.Shoot. This ensures shooting is cancelled before reloading starts.
• After Activating Cancel Tags: Set to CharacterStates.Weapons.Aim. This forces the character out of aiming mode when reloading begins.
• Remove On Death: Check this box (true).
• Remove After Activation: Check this box (true). This turns the state into a one-shot activation, meaning it does not need to be manually deactivated later.
• Prohibit ReActivation: Check this box (true).

Step 3: Implement Validation in Components

Components use the BPI_StateMachine interface to validate and execute state logic.

Server Validation (BPI_SM_ServerCheck)

Open the components assigned in ServerMustPassComponents and implement BPI_SM_ServerCheck:

1. In BP_FirearmsComponent: Add logic to check if a firearm is currently held and if it has a clip modification. Return true if both conditions are met.
2. In BP_EquipmentComponent: Add logic to check if the player has compatible ammo in their inventory, and if the current weapon's ammo count is below maximum. Return true if valid.

Client Validation (BPI_SM_ClientPreCheck)

Open the component assigned in ClientMustPassComponents and implement BPI_SM_ClientPreCheck:

1. In BP_FirearmsComponent: Add logic to trace the distance in front of the character. If the character is too close to a wall, return false to block the reload animation. Otherwise, return true.

Step 4: Make Components React to the State

If a component needs to execute logic when the state activates, it must register itself and implement the solver function.

1. Open BP_FirearmsComponent and BP_EquipmentComponent.
2. Locate the HandleStates array variable.
3. Add CharacterStates.Weapons.Reload to the array. If the tag is not in this array, the component will ignore the state activation.
4. Open the BPI_SM_ActivateStateSolver function in BP_FirearmsComponent.
5. Add a branch for the Reload tag and call your execution logic. For example, call Multicast_PlayReloadMontage.

Note: Because Remove After Activation is true in the data table, you do not need to manually call BPI_MM_DeactivateState for this state. The BPI_SM_DeactivateStateSolver logic will still run automatically after the state has been deactivated.

Step 5: Connect to Input

Finally, bind the state activation to player input. It is recommended to use one InputAction per state for cleaner rebinding logic in the future.

1. Create an Input Action, such as IA_Reload.
2. Add it to the relevant Input Mapping Context, such as IMC_OnFoot.
3. Open BP_InputsComponent.
4. Add the IA_Reload event.
5. From the Pressed execution pin, call the internal ActivateState wrapper function (which passes the call to BPI_MM_ActivateState on the BP_ModulesMediator).
6. Pass CharacterStates.Weapons.Reload as the parameter.

The engine and the mediator will automatically handle routing the activation request from the client to the server, running the validation checks, and executing the solver logic across all registered components.