Melee System

Overview

The melee system in RPG Engine v6 is a close combat subsystem that supports unarmed attacks and melee weapons. It is integrated with the character state system, animation system, damage/impact system, and multiplayer logic.

At the weapon data level, melee weapons are configured through BP_MeleeWMasterClar, which inherits common combat parameters from BP_CommonMasterClar and shared weapon parameters from BP_Weapon_Master_Clar.

High-level architecture

Melee combat is implemented on top of the shared combat architecture. At the core there is a dedicated melee component on the character that drives attack requests, hit checks, combo progression, and integration with the state system.

Hit detection is performed using timed sphere traces between configured trace sockets on the character or weapon meshes. These traces are usually triggered from animation notifies (for example, a check-hits notify placed on the swing section of a montage), which keeps visual timing and gameplay logic in sync.

The melee component works together with Data Assets that describe what the weapon is, which sockets to trace, which combos are available, and what damage profile should be applied. This allows you to configure new melee weapons without changing Blueprint logic.

Unarmed vs armed melee

The same melee framework is used for both unarmed and weapon-based combat. When no melee weapon is equipped, the system falls back to unarmed settings and uses character sockets such as fists or feet for hit detection.

When a melee weapon is equipped, the system switches to weapon-specific settings. In this mode, trace sockets are usually defined on the weapon mesh, damage is taken from the weapon’s damage profile, and weapon-specific animation sets are used.

Because unarmed and armed melee share the same core component and state integration, you can freely mix them in gameplay. For example, a character can perform unarmed attacks when disarmed and automatically switch back to weapon melee after equipping a sword.

Multiplayer behavior

The melee system is designed for server-authoritative multiplayer. Attack input is requested on the client, but the final hit validation and damage application are performed on the server using the same trace logic.

Clients receive replicated information about successful hits and resulting state changes (for example, damage, reactions, or knockdowns). This ensures that all players see consistent outcomes even during fast close combat exchanges.

There is no complex client-side prediction layer baked into melee by default. This keeps the implementation straightforward and easier to debug, while still providing responsive melee combat in typical listen-server and small-session scenarios.

Close Combat Configuration

The close combat layer uses a set of global parameters for hit detection and target engagement.

Global Close Combat Parameters

• CC Unarmed Sockets
  Sockets used for dealing damage when the character attacks without a weapon. These sockets are used for punches, kicks, or other body-based strikes.

• CC Frequency of Checking Hit While Punching
  Damage detection is performed using a timer. On each timer loop, the system performs traces to gather hit information. This parameter controls the time interval between those checks.

• Punch Sphere Trace Size
  Radius of the SphereTrace used during unarmed hit detection.

• CC Target Maximal Attack Distance
  Distance threshold used to decide whether the system can start a direct melee attack. If the distance to the target is less than or equal to this value, CharacterStates.CloseCombat.SimpleAttack is activated. If the target is farther away, CharacterStates.CloseCombat.MoveToTarget is activated instead.

• Catch Target Sphere Trace Size
  Trace size used while searching for a valid victim for special or super-combo attacks.

• Can Be Synchronously Attacked By X Numbers Of AIs
  Defines how many AI characters are allowed to attack the player at the same time.

• EndMoveToTargetTimeCap / EndAttackFromAirTimeCap
  Safety timeout values used to prevent the character from getting stuck in transitional melee states such as moving to the target or performing aerial attacks.

Weapon Data Hierarchy

A melee weapon uses the following clarification hierarchy:

• BP_CommonMaster_Clar
• BP_Weapon_Master_Clar
• BP_Melee_W_Master_Clar

This means a melee weapon includes common combat settings, shared weapon presentation settings, and melee-specific settings.

Parameters From BP_CommonMasterClar

These parameters are inherited by melee weapons and are used by the close combat system.

TypeTag

Defines the weapon type through a gameplay tag.

Special Attacks Container Data

Container or map that stores special attack configuration for the melee system.

DefenceCoefficient

Multiplier applied to incoming melee damage while the character is defending.

Example: — incoming damage = 50 — DefenceCoefficient = 0.5 — final damage while defending = 25

This reduction applies only to melee or unarmed damage. Firearm damage is not reduced by this parameter.

Total Powerful Attacks By Combos

Array.
The number of array elements equals the number of powerful attack options.
Each element value equals the number of attacks in that combo branch.

Total Simple Attacks By Combos

Array.
The number of array elements equals the number of simple attack options.
Each element value equals the number of attacks in that combo branch.

Example: If a weapon has 4 simple combo branches, this array must contain 4 elements.
If the second combo branch contains 3 attacks, then the second array element must be 3.

AirToFloorAmount

Number of available AirToFloor attack options.

AirToTargetAmount

Number of available AirToTarget attack options.

Animations

Reference to the locomotion/animation data asset used by the weapon.

CheckWall

Enables wall checking for the weapon.

CheckWallDistance

Distance used for wall checking when CheckWall is enabled.

Impact Data

Impact data asset that controls what effects are spawned when the weapon hits different physical materials.

Typical usage: — blood effects when striking a character body; — sparks when striking metal.

Aim Widget

UI-related aim widget parameter inherited from the common weapon layer.

EmptyAim

Additional aim-related parameter inherited from the common weapon layer.

RetargetModifier

Used to correct hand and arm alignment caused by live retargeting.
This parameter allows you to change arm angles, and its values may vary depending on the active character skin.

Parameters From BP_Weapon_Master_Clar

These inherited parameters control how the melee weapon is represented in hand, in the world, and on the character body.

MainSkeletalMesh

Main skeletal mesh of the weapon.
This is the main component used to deal damage.

MainSkeletalMeshAnimBP

Animation Blueprint used by the main weapon mesh.

InteractStaticMesh

Static mesh used to initialize the interactable actor in the world.
A static mesh is used here instead of a skeletal mesh for optimization.

Main Mesh Start Montage

Montage triggered when the weapon is picked up or equipped.

AttachToBodyComponent

Mesh or asset used to display the weapon on the character body when the weapon is not in hand.

VictimHitCameraShake

Camera shake played on the victim when the victim receives a hit.

AttachSockets

Allowed weapon attachment sockets.
The documentation references this as a structure containing at least: — MainSocket — SecondSocket

These sockets are used when attaching the weapon to the character.

UniqueWeaponEnum

Unique weapon identifier used by the character Animation Blueprint.
It allows the animation system to determine which weapon is currently in hand and select the correct EffectorTarget.

Custom Back Actor

Custom actor class used instead of the default BPWeaponBack when the weapon is stored on the character.

Example: For a two-part weapon such as sword + shield, a dedicated back actor such as BPDoubleWeaponBack can be used.

DestroyBackActorByAnimNotify

If true, the back actor is not destroyed immediately when the weapon is picked up.
Instead, destruction is controlled more precisely through animation timing.

Parameters From BP_Melee_W_Master_Clar

These are the melee-specific parameters.

Main Mesh Trace Sockets

Array of trace sockets that must exist on the main weapon mesh.
These sockets are used for hit detection on the main combat component.

Example: For a sword, these sockets must exist on the sword mesh.

Second Mesh Trace Sockets

Array of trace sockets on the second weapon mesh.
This array must be filled only if the weapon consists of two combat parts.

Example: For a sword-and-shield weapon, these sockets exist on the shield mesh.

SecondSkeletalMesh

Second skeletal mesh of the weapon.
Used only when the weapon consists of two parts.

SecondMeshAnimBP

Animation Blueprint used by the second mesh.

SecondBackMesh

Mesh used to represent the second weapon part when the weapon is stored on the character body.

SecondMeshStartMontage

Montage triggered for the second weapon part when the weapon is picked up or equipped.

PossibleBuffs

Array of buffs that can be applied to the weapon.

Filling rule: the array must contain row names from DTItemData.

Example from the documentation: — BFSWSIce — BFSWSFire

SecondMeshBackSocket

Socket used to attach the second weapon part to the back actor.

Attack Selection

Strike animation selection is based on the ChooserTable tool.
Each attack type uses its own Chooser Table.

The documentation explicitly states that attack selection is configured through weapon-linked animation layers, and each attack category can use a different chooser.

Chooser Table Structure

CHT_CC_SWS_Attacks

This chooser contains information about simple and super attacks.

Parameters documented in this chooser:

• Powerful
  Attack type flag.

• CriticalHitPropability
  Probability of dealing critical damage.

• Min/Max damage
  Minimum and maximum damage range.

• UpdateDamageSettings
  If true, the damage settings defined in the chooser entry are used.
  If false, previously initialized damage settings remain active.

Simple Attack Combo Configuration

Inside the simple attack chooser, each combo branch is identified by a unique Combo Index.

A combo branch contains one or more attacks.
The number of attacks in the branch must match the corresponding value in Total Simple Attacks By Combos.

Each individual attack entry can include the following documented parameters:

EnergyConsumption

Amount of stamina spent to perform the strike.

isClosingBlow

If true, the character must learn the ClosingBlow skill to use this strike.

FinishAttackRule

Defines how long the player can wait before continuing the combo.
If the next attack is not performed within the allowed time, the combo ends.

Supported behavior mentioned in the documentation:

• Timer
  If UseCustomAnimDuration == false, the animation length is used.
  If UseCustomAnimDuration == true, CustomAnimDuration must also be filled.

• Bind OnLanded()
  If this rule is selected, the combo ends when the OnLanded() event is triggered.
  The documentation notes that this is used in attacks performed in the air.

ProceedRule

Special validation rule used when an additional condition must be checked before continuing the attack.

Documented usage: super-combo attacks may first grab a victim and then perform a follow-up strike. Between these actions, the victim may die or disappear, so validity must be checked before the strike continues.

Documented fields inside this logic include:

• UseCustomHit
  If true, a special damage animation is played on the victim.

• AnimMontage
  Damage animation played on the victim.

• NeedShadow
  If true, visual copies of the victim are spawned during strikes to make the attack look more spectacular.

WaitForCombo / TimerWaitForCombo

Used in animations that belong to super-combo sequences.

Powerful Attacks

The documentation states that the chooser structure for powerful attacks is similar to the structure used for simple attacks.

This means powerful attacks use the same general logic: — attack branch selection; — damage settings; — combo timing rules; — optional validation rules before proceeding.

Aerial Attacks

The system supports at least two documented aerial branches: — AirToFloor — AirToTarget

The number of available attack options for these branches is controlled through: — AirToFloorAmount — AirToTargetAmount

These values define how many attack variants exist for each aerial category.

Hit Detection

The documentation confirms two main melee hit-detection modes:

Unarmed Hit Detection

Uses: — CC Unarmed Sockets — timer-based hit checks — Punch Sphere Trace Size

Weapon Hit Detection

Uses: — Main Mesh Trace Sockets — Second Mesh Trace Sockets when applicable

This means melee hit detection is driven by configured sockets and repeated checks over time, not only by a single overlap event.

Impact Data

Melee uses Impact Data for hit feedback.

For close combat, the relevant branch is CC Impact Data, which supports two modes:

Simple

Use this mode when effects do not need to differ by weapon part.

Advanced

Use this mode when effects must depend on which mesh component caused the hit.

The documentation explicitly states that Advanced mode is useful for weapons with several combat components, such as sword + shield.

AdvancedImpact can differentiate effects for: — Main Skeletal Mesh — Second Skeletal Mesh — Both

For each hit type, different data assets can be assigned: — normal hit; — critical hit; — blocked hit.

Effect data can include: — Niagara or Cascade particles; — decals; — spawn socket; — sound type; — sound cue.

Blocking

The block system uses DefenceCoefficient to reduce incoming melee damage while defending.

Blocked hits can also use dedicated impact reactions through the close combat impact data setup.
This allows blocked strikes to spawn different effects from normal or critical hits.

Cameras

The documented camera parameter for melee weapons is:

VictimHitCameraShake

Camera shake played on the victim after a successful hit.

This parameter is inherited from BP_Weapon_Master_Clar and is available for melee weapons.

State Integration

The documentation confirms direct integration with character states.

Examples of documented close combat states: — CharacterStates.CloseCombat.SimpleAttack — CharacterStates.CloseCombat.MoveToTarget

The target-distance logic uses CC Target Maximal Attack Distance to decide which of these states should be activated.

This means melee is not isolated from the rest of the gameplay framework.
It operates through the same state-based architecture used by other gameplay systems.

Summary of Numeric and Structural Rules

• DefenceCoefficient is a damage multiplier applied only when defending against melee or unarmed damage.
• Total Simple Attacks By Combos and Total Powerful Attacks By Combos are arrays.
• Number of elements in these arrays = number of combo branches.
• Value of each element = number of attacks inside that combo branch.
• AirToFloorAmount = number of AirToFloor attack variants.
• AirToTargetAmount = number of AirToTarget attack variants.
• CC Frequency of Checking Hit While Punching controls timer interval for unarmed hit checks.
• Punch Sphere Trace Size controls unarmed trace radius.
• CC Target Maximal Attack Distance controls whether the system attacks immediately or first moves to the target.
• PossibleBuffs must contain row names from DTItemData.
• Main Mesh Trace Sockets must exist on the main weapon mesh.
• Second Mesh Trace Sockets must exist on the second weapon mesh when a second combat component is used.

Related Docs

The melee system is closely connected with:

• docs/systems/state/state-system.md — melee attack states, forbidden states, and state transitions.
  
• docs/systems/inventory-equipment/inventory-and-equipment.md — melee weapons as items, slots, and on-body equipment.
  
• docs/systems/firearms/firearms-system.md — shared state framework and combat priority between melee and firearms.
  
• docs/systems/stats/stats-and-survival-system.md — Energy consumption, Health damage, and buffs that affect melee combat.
  
• docs/systems/ai/ai-combat-and-behavior.md — AI melee behavior, target selection, and hit reactions.
  
• docs/systems/customization/character-customization.md — character skins and melee weapon visuals.
  
• docs/reference/reference-gameplay-tags.md — melee-related tags in the CharacterStates.CloseCombat hierarchy.
  
• docs/reference/reference-data-tables.md — data tables that register melee weapons and related assets.