How to Add a New Melee Weapon (Sword + Shield)

This guide walks through the full workflow of adding a melee weapon of type “sword + shield” using ItemsAssistant, including setup of meshes, animation blueprints,«`markdown # How to Add a New Melee Weapon (Sword + Shield)

This guide walks through the full workflow of adding a melee weapon of type “sword + shield” using ItemsAssistant, including manual setup of meshes, animation blueprints, traces, animation notifies, chooser tables, back actor, impact data, buffs, and basic skin setup.

1. Create the Sword+Shield Item via ItemsAssistant

Open the ItemsAssistant Editor Utility Widget in the UE editor.
In Item Type, select Weapon (melee vs firearm is controlled by the Subtype, there is no separate WeaponType field).
In the General Data section, fill basic item info:
- Name: e.g. Sword and Shield.
- Short Name: e.g. Swd+Shld.
- Description: short description for tooltips.
- Abbreviation: internal code, e.g. SWD_SHLD.
- Weight, Price, Rarity according to your balance.
In the Inventory Data section:
- Size: logical size in grid cells, e.g. 2x4.
- Maximum Number In Slot: 1 for weapons.
- Texture / Texture Type: either a simple icon UTexture2D or Generated if you plan to use an icon generator.
In the Clarification Data section (type = Weapon):
- Subtype: set your melee subtype that corresponds to close‑combat weapons, for example:
  - World.Items.Weapon.Type.Melee for one‑component melee.
  - World.Items.Weapon.Type.TwoComponentMelee (or the exact tag/name you use) for sword+shield.
- CustomBackActor: true — we will use a custom back actor that supports two meshes.
- DestroyBackByAnimNotify: true — back actor will be removed via animation notify when equipping/unequipping.
- Check Wall: false for this example (you can enable later and set Check Wall Distance if needed).
Click Generate. ItemsAssistant will create and wire:
- A master item DataAsset (BP_ItemData child) for the sword+shield.
- An Inventory DataAsset (child of BP_IIMaster / BP_IIConMaster).
- A Clarification DataAsset of melee weapon class (e.g. BP_Melee_W_Master_Clar, named DA_CL_SwordShield).
- A new row in DT_ItemData referencing all these assets.

2. Configure the Interact Actor (`BP_Int_SwordShield`)

Open the generated interact actor BP_Int_SwordShield.
In its General Data, set the reference to your sword+shield BP_ItemData created by ItemsAssistant.
Make sure the actor’s Static Mesh (or setup) looks correct for a pickup in the world (you can refine this later via skins or visual assets).

3. Fill the Clarification Asset (`DA_CL_SwordShield`)

The Clarification asset for melee weapons inherits from BP_CommonMaster_Clar, BP_Weapon_Master_Clar, and BP_Melee_W_Master_Clar. Fields are grouped into logical sections: Common, Weapon (main/second mesh, sockets, back), Melee (trace sockets, possible buffs), Animations, and Close Combat.

3.1. Main Mesh and Anim BP

Main Skeletal Mesh
- Set the sword USkeletalMesh as the MainSkeletalMesh.
- This mesh is used for in‑hand visuals and as the base for melee trace/hit detection.
Main Skeletal Mesh Anim BP

Create a dedicated AnimBlueprint for the sword mesh (similar to an existing ABP_Sword):
- Parent class: use the same base as your existing weapon mesh AnimBPs.
- Implement the BPI_ABP interface.
- Add a bool variable bState.
- Add the event BPI_UpdateStartAnimPlayed from the interface and inside simply Set bState from the event’s bool parameter.
- In the AnimGraph:
  - Add a Blend Pose by Bool node driven by bState.
  - True branch: one‑frame animation or pose for the “normal/open” sword state.
  - False branch: pose where the sword is in “closed” state (before the start montage plays).
  - Route the blended pose into the DefaultSlot, then to the final Output Pose.
Assign this AnimBlueprint class to MainSkeletalMeshAnimBP.
Main Mesh Start Montage
- Set an UAnimMontage with the “draw/open” animation that plays when the weapon is equipped (sword coming from the back or sheath) into Main Mesh Start Montage.
Interact Static Mesh
- Ensure InteractStaticMesh is filled with a Static Mesh used for the world interact actor (pickup). This is separate from the skeletal mesh used in hands.
AttachToBodyComponent and AttachSockets
- AttachToBodyComponent: specify the character mesh/component used when attaching the weapon to the body/back.
- AttachSockets (sAllowedSockets):
  - MainSocket: socket name on the character skeleton where the main weapon mesh (sword) attaches when in hands.
  - SecondSocket: socket name for the second mesh (shield) when in hands (we will create these sockets on each character skeleton).

3.2. Second Mesh (Shield)

For two‑component melee weapons like sword+shield you must fill all Second Mesh fields.

SecondSkeletalMesh
- Assign the shield USkeletalMesh as SecondSkeletalMesh.
SecondMeshAnimBP

Create a separate AnimBlueprint for the shield mesh using the same pattern as for the sword:
- Parent class: your standard weapon/secondary mesh AnimBP base.
- Implement BPI_ABP.
- Add a bool variable (e.g. bShieldState).
- Add the BPI_UpdateStartAnimPlayed event and set the bool from its parameter.
- In AnimGraph:
  - Use Blend Pose by Bool (closed vs open shield pose).
  - Feed into DefaultSlot and then the final output.
Assign this AnimBP class to SecondMeshAnimBP.
SecondBackMesh
- Set the mesh that will represent the shield on the character’s back when the weapon is holstered (used by the back actor).
SecondMeshStartMontage
- Optionally set an UAnimMontage that plays for the second mesh when equipping the weapon (e.g. specific shield draw animation).
SecondMeshBackSocket
- Set the socket name on the back actor (BP_WeaponBack / BP_DoubleWeaponBack) where the shield back mesh attaches when the weapon is on the back.

3.3. Trace Sockets for Hits

The melee system relies on sockets on the weapon meshes for trace‑based hit detection.

Add sockets on the sword mesh
- Open the MainSkeletalMesh (sword) in the Skeletal Mesh editor.
- Add several sockets along the blade, for example:
  - SwordTip
  - SwordMid
  - SwordBase
- These sockets will be used for line traces during attack windows.
Add sockets on the shield mesh
- Open the SecondSkeletalMesh (shield).
- Add sockets on the parts of the shield that will be used to hit the target, e.g.:
  - ShieldEdge_01
  - ShieldEdge_02
- These sockets are used when the shield is doing a bash‑type hit.
Fill the Trace section in Clarification
- Main Mesh Trace Sockets: list all socket names from the sword mesh that should be used for traces.
- Second Mesh Trace Sockets: list all socket names from the shield mesh, used only for two‑component melee weapons.
Animation notifies for trace windows
- In your sword and shield attack montages, add notifies that enable and disable tracing using the above socket lists (see section 4.4 for details on core notifies).
- This lets you precisely control when hits can connect during each swing.

3.4. Character Attach Sockets and Back Map

Your project uses different character skeleton types (UE4, UE5, Metahuman), so you must ensure sockets exist on each one and that back mapping is correct.

Add hand sockets on each character skeleton

For each player/AI skeleton variant (UE5, UE4, Metahuman):
- Open the character’s USkeletalMesh.
- Add a socket (e.g. on hand_r or a dedicated bone) that will serve as MainSocket for the sword.
- Add another socket (e.g. on hand_l or another suitable bone) that will serve as SecondSocket for the shield.
Configure the Back map

In the Clarification asset, there is a Back map used for holstering the weapon:
- Key: the equipment slot / cell type where the weapon is stored when not in hands, e.g. OnBack.
- Value: the socket name on the character skeleton where the MainSkeletalMeshComponent of the back actor attaches, e.g. BackWeaponSocket.
The SecondMeshBackSocket field is used for the shield’s attachment to the back actor (see 3.2).

3.5. Custom Back Actor (`BP_DoubleWeaponBack`)

Because we enabled CustomBackActor = true, we must provide a back actor that supports two USkeletalMeshComponents.

Select or create a back actor
- If your project already contains BP_DoubleWeaponBack (child of BP_WeaponBack with two skeletal mesh components), use it.
- This actor is designed to automatically initialize both the sword and shield back meshes; you typically do not need any extra configuration.
Assign the custom back actor
- In the Clarification asset, set Custom Back Actor to BP_DoubleWeaponBack.
- Keep DestroyBackActorByAnimNotify = true so that equip/unequip montages can destroy the back actor exactly when needed through anim notifies.

3.6. Animations, Locomotion Data, and RetargetModifier

Melee weapons use a locomotion data asset to control which animation layer, dodges, dashes, and special moves are bound to the character while the weapon is equipped. Additionally, you can override behavior per character skin using RetargetModifier.

3.6.1. Locomotion Data

Create a locomotion DataAsset for the sword+shield
- Parent class: BP_LocomotionData_Master.
- Configure key fields:
  - Locomotion / AnimLayer: AnimInstance class of the locomotion/overlay layer that will be plugged into the main character AnimBP when the sword+shield is equipped.
  - Abrupt Movement / Dodge, Dash, JumpDash, DoubleJump: montage references for dodge/dash/jump‑dash/double‑jump used with this melee weapon.
  - Actions / Actions: DataTable row handle for contextual character actions (if you use them).
  - First Person / FP Idle, FP Crouch Idle: first‑person idle animations while standing/crouching, if you support FP mode.
Link the locomotion data to the weapon
- In the Clarification asset, in the Animations section, set Animations to your BP_LocomotionData_Master child asset.
- This ensures the correct animation layer and movement behaviors are activated when the sword+shield is equipped.
Wall check (optional)
- If you want wall‑check behavior for this weapon, set CheckWall = true and configure CheckWallDistance (e.g. distance at which the weapon is considered too close to a wall and attacks may be limited or changed).
- For this heavy melee weapon example, we keep CheckWall disabled.

3.6.2. RetargetModifier (optional per‑skin overrides)

RetargetModifier is a map that allows you to adjust how the weapon is held for different player character skins.

Key: the name of a character skin DataAsset (identifier for a specific player skin).
Value: a struct with retargeting settings for this skin, including:
- Bone rotation offsets for specific bones (how much to rotate certain bones when this skin is used).
- useCustomAnimLayer (bool).
- CustomAnimLayer (Anim Layer class or AnimBP used as a linked layer).

Behavior:

If useCustomAnimLayer = false, only the bone rotation offsets are applied for this skin; the weapon still uses the default animation layer from the common locomotion/overlay setup.
If useCustomAnimLayer = true, the system will additionally link the CustomAnimLayer AnimBP/AnimLayer into the player’s main AnimBP when this weapon is in hands and this specific skin is active.
- This is useful when you want certain skins to hold or animate the weapon slightly differently (different hand pose, grip, shoulder offset, etc.) without changing the base animation set for all characters.

4. Close Combat Logic: Chooser Tables, Notifies, and Clarification Fields

The close‑combat melee logic is built on top of Chooser Tables, animation notifies, and the Close Combat fields in BP_CommonMaster_Clar.

4.1. Attack Types and Chooser Tables

The melee system uses four logical attack types:

AirToFloor – attacker in the air, target on the ground.
AirToTarget – attacker and target at different heights.
AttackDash – dash movement towards target with an attack.
Attacks – ground simple and powerful combo attacks.

For each attack type you create a separate Chooser Table asset.

AirToFloor Chooser

Main parameter: Index – ordinal number of the variant in this attack type.
Logic: the system can pick a random combo index and then use Index within that combo to step through the attacks.

AirToTarget Chooser

Typical fields per entry:

Index – index in this attack family.
UpdateDamageSettings – whether to use the MinDamage/MaxDamage defined in this entry.
MinDamage, MaxDamage – damage range for this animation.
CriticalHitProbability – chance of a critical hit for this animation.
FinishMoveTTRule – rule describing when the move is considered finished (time/trajectory‑based).

This lets you give different AirToTarget animations different damage, crit chance, and finish rules.

AttackDash Chooser

Top‑level fields:

MinDamage, MaxDamage, CriticalHitProbability – damage and crit parameters.

Inside this chooser there is a nested chooser that stores animation variants with:

Distance – float or range describing at what distance to the target this animation should be used.
FinishRule – how to determine when the dash attack has completed.
UpdateDamageSettings – whether this variant overrides damage settings.

Attacks Chooser (Simple and Powerful)

Top level:

Powerful (bool) – marks whether this entry belongs to the powerful‑attack family.
MinDamage, MaxDamage, CriticalHitProbability, UpdateDamageSettings.

Inside:

One nested chooser for simple attacks.
Another nested chooser for powerful attacks.

In the nested simple attacks chooser:

ComboIndex – ID of the combo chain this entry belongs to.

Inside each ComboIndex branch there are further nested entries for specific attack animations:

AttackIndex – ordinal number of the strike within the current combo chain.
EnergyConsumption – how much energy this strike consumes.
IsClosingBlow – whether this strike is the last strike in the combo.
FinishRule – rule for determining when this strike is finished.
ProceedRule – extra checks required to proceed to the next strike (hit confirmation, resources, etc.).
CustomHitReact – whether the victim should play a special hit reaction.
WaitForCombo – whether the system should wait for specific information or a window from the victim before continuing the combo (used for “true combo” behavior, especially in powerful chains).

Selection logic:

For ground attacks, the system randomly selects a ComboIndex, then plays strikes in order of AttackIndex.
If the player does not continue the combo within a certain time window (e.g. ~1 second), the current combo index is reset, and the next attack pick starts from a new random combo.

4.2. Melee Overlay AnimBP for the Character

Create an overlay AnimBlueprint for melee with parent class ABP_Overlay_Melee.
Implement the following Blueprint interface events and return the appropriate Chooser assets for the sword+shield weapon:
- BPI_ABP_GetChooserCloseCombatData – main chooser for ground attacks (Attacks).
- BPI_ABP_GetChooserAttackFloor – chooser for AirToFloor.
- BPI_ABP_GetChooserAirToTarget – chooser for AirToTarget.
- BPI_ABP_GetChooserMoveToTarget – chooser for AttackDash.
Ensure all melee attack animations used in these choosers are retargeted to your main combat skeleton (e.g. SK_UEFN_Mannequin).

4.3. Fill Close Combat Section in Clarification

Back in the DA_CL_SwordShield Clarification asset, fill the Close Combat parameters:

DefenceCoefficient
- Float in the range 0..1.
- The higher the value, the less incoming melee damage the character receives while in a defending state (e.g. blocking with the shield).
Total Powerful Attacks By Combos
- Array where:
  - Index = ComboIndex for powerful combos (from the powerful nested choosers).
  - Value = number of strikes in that powerful combo chain.
- Used by the melee system to understand how many attacks are in each powerful combo.
Total Simple Attacks By Combos
- Array where:
  - Index = ComboIndex for simple combos.
  - Value = number of simple strikes in that combo.
AirToFloorAmount
- Number of AirToFloor variants in your AirToFloor chooser (i.e. how many entries/indices exist).
AirToTargetAmount
- Number of AirToTarget variants in your AirToTarget chooser.

These values keep the Clarification data in sync with the actual choosers and allow the runtime melee system to correctly iterate over combos and air attacks.

4.4. Core Animation Notifies for Melee

The melee system relies on several key animation notifies and notify states inside attack montages:

AN_ResetComboAttack
- Regular Anim Notify.
- Call it when you want the CanAttack (or similar) parameter in BP_MeleeComponent to be set back to true.
- Typically used near the end of a combo window or after a strike finishes, so the player can start a new combo or next attack.
AN_CC_CameraShake
- Regular Anim Notify.
- Triggers a camera shake when a hit is performed (usually aligned with the impact frame of an attack).
- Use it on key frames of heavy hits to emphasize impact.
ANS_CheckHits
- Anim Notify State and the main notify for melee hit checking.
- While this notify state is active, the melee system will perform hit checks using the trace sockets defined in the weapon Clarification.
- Parameters of ANS_CheckHits allow you to configure:
  - Which sockets are used or ignored during this window (for example, ignore some sockets for specific attacks).
  - Which part of the weapon deals damage:
    - MainSkeletalMesh (sword only).
    - SecondSkeletalMesh (shield only).
    - Both (both sword and shield can cause hits in this window).

Typical setup:

Add ANS_CheckHits to the swing portion of the montage; configure which part (main/second/both) and socket filtering.
Add AN_CC_CameraShake at the moment of visual impact.
Add AN_ResetComboAttack at the end of the combo window or when the combo should be fully reset.

5. Damage, Impact, and Buff Integration

5.1. Damage Type

In the Clarification asset there is a DamageType field (e.g. under characteristics/damage):

Assign a class derived from BP_DamageTypeMaster configured as a melee‑type damage.
In that DamageType you typically configure:
- Overall damage category (e.g. a “Melee” enum entry).
- Camera shake class applied to the victim on hit.
- Whether the victim should play hit‑reaction animations (PlayHitReact).

5.2. Impact Data, `BP_DA_AdvancedImpact`, and `BP_DA_ImpactEffects`

BP_ImpactData reference in Clarification
- The Impact Data field in BP_CommonMaster_Clar points to a BP_ImpactData DataAsset controlling hit VFX/SFX/decals.
- For melee, you use the CC Impact Data block inside BP_ImpactData. This block can work in Simple or Advanced mode.
- For this example, use Advanced impact for finer control.
BP_DA_AdvancedImpact (Advanced CC Impact Data)
- BP_DA_AdvancedImpact stores a map from Mesh Component Part to impact effects:
  - Mesh Component Part is an E_MeshComponentType enum: MainSkeletalMesh, SecondSkeletalMesh, Both.
- It can hold different sets for:
  - Normal hits.
  - Critical hits.
  - Blocked hits.
BP_DA_ImpactEffects (concrete VFX/SFX for a case)

A BP_DA_ImpactEffects asset stores actual effect data:
- EffectType: whether to use a Niagara System or a Cascade Particle.
- The Niagara/Cascade asset for the hit effect (blood, sparks, dust, etc.).
- ImpactDecals: S_ImpactDecalContainer with:
  - Decal Material.
  - Decal Size.
  - Decal Lifespan.
- SoundType and Sound Cue: which sound to play on hit (2D or spatial).
- Socket: optional socket name used as the attachment point for the effect (e.g. the blade tip or shield edge).
For the sword+shield you can, for example:
- Create one BP_DA_ImpactEffects for typical sword slashes on flesh/armor.
- Create another BP_DA_ImpactEffects for shield bash impacts.
- In BP_DA_AdvancedImpact, map:
  - MainSkeletalMesh → sword hit effects asset.
  - SecondSkeletalMesh → shield bash effects asset.
Link BP_DA_AdvancedImpact to BP_ImpactData and the weapon
- In BP_ImpactData.CCImpactData, set:
  - ImpactType = Advanced.
  - The AdvancedImpact field to your BP_DA_AdvancedImpact asset.
- In DA_CL_SwordShield, set the Impact Data field to this BP_ImpactData asset.
- Now sword and shield hits will use the correct per‑mesh, per‑case impact effects.

5.3. Possible Buffs

In BP_Melee_W_Master_Clar, the PossibleBuffs array contains the list of buffs allowed on this weapon.
Each entry is a row name from DT_ItemData representing a World.Items.Types.Buff item that can be slotted into the melee buff slot for this weapon.
Add row names of your melee buffs, for example:
- BF_SWS_Fire – a fire buff for the sword.
- BF_SWS_Ice – an ice buff for the sword.
These buffs are configured via BP_BuffClarData and integrated into the buff/debuff system. When a buff is assigned to the melee weapon, hits from this weapon can trigger debuffs (combustion, slowdown, stun, etc.) according to the buff and debuff configuration.

6. Item Data and Skins (`DT_ItemData`, `BP_ItemData`, Inventory Data)

The following item data layer is automatically set up by ItemsAssistant, but understanding it helps when debugging or doing manual changes.

6.1. `DT_ItemData`

DT_ItemData is the main registration UDataTable for inventory items. For each weapon it stores:

A GeneralData block:
- Name
- Short Name
- Description
- Abbreviation
- Weight
- Price
- Type (e.g. World.Items.Types.Weapon)
- Rarity
References to:
- The master item DataAsset (BP_ItemData child).
- The Inventory DataAsset (BP_IIMaster child, often BP_IIConMaster).
- The Clarification DataAsset (for melee, a BP_Melee_W_Master_Clar child).
Type/category values used for:
- Inventory filters.
- Equipment slot validation.
- Trading and loot systems.

6.2. `BP_ItemData` (Master Item DataAsset)

A BP_ItemData child is the master data asset for the item:

Holds high‑level item information and references:
- Link to Inventory DataAsset.
- Link to the Clarification DataAsset.
May cache or mirror some GeneralData values for convenience (name, description, abbreviation, etc.).
Is used by UI, trading, save/load, and other systems as the central entry point instead of accessing the UDataTable directly.

6.3. Inventory DataAsset (`BP_IIMaster` / `BP_IIConMaster`)

The Inventory DataAsset controls how the item behaves and appears in the inventory grid. Typical parameters include:

Texture / Texture Type: simple icon texture or generated icons.
Size: width/height in grid cells.
Maximum Number In Slot: maximum stack size (for weapons, usually 1).
ForSale flag: whether this item can be sold by vendors or appears in vendor stock.
ConnectActor: for connectable items, this class is used when the item is held in hands (separate from the world interact actor).

SimpleVisualizationSkins

For melee weapons that support skins, the Inventory DataAsset (usually a child of BP_IICSkinsMaster) also contains a SimpleVisualizationSkins (or similar) array:

Here you define which skin DataAssets (BP_DA_Skins children) are available for this weapon.
Each skin entry typically contains:
- Interact object mesh overrides.
- Connect object mesh overrides (in‑hand representation).
- Connect‑to‑body object mesh overrides (back or body representation).
- Icon/texture data.

To create and configure a weapon skin for melee weapons, see the separate documentation file dedicated to skins (weapon/clothing skins and BP_DA_Skins workflow).

6.4. `ItemsAssistant` Integration

On Generate, ItemsAssistant:

Creates:
- A Clarification DataAsset (with the correct parent type – BP_Melee_W_Master_Clar for melee).
- An Inventory DataAsset (child of BP_IIMaster or its children).
- A master BP_ItemData asset.
Adds or updates a row in DT_ItemData:
- Fills GeneralData from the General Data UI.
- Wires references to the created BP_ItemData, Inventory DataAsset, and Clarification DataAsset.

After these steps the sword+shield weapon:

Can appear in the inventory grid and be equipped into the Melee equipment slot.
Uses its Clarification Data for melee behavior (meshes, traces, combos, impact, buffs).
Can participate in trading, loot, and save/load systems without extra manual wiring.