How To Add a Firearm

This guide explains the full pipeline for adding a new firearm using ItemsAssistant: from meshes and materials to Clarification data, locomotion, widgets, modifications, skins, and icon generation.

---

Quick Steps

1. Import SkeletalMesh / StaticMesh, textures, materials, and add sockets.
   
2. Create the weapon via ItemsAssistant (ItemType = Weapon, firearm subtype).
   
3. Manually configure the generated Clarification DataAsset (meshes, sounds, aim, animations, characteristics, modifications).
   
4. Create weapon skins (see how-to-add-weapon-skin.md) and register them in the Inventory DataAsset.
   
5. Configure the Interact Actor (ammo, skin, default modifications).
   
6. Set up modification list and Modification Custom Preview widget in the Inventory DataAsset.
   
7. Generate icons via BP_EngineWeaponIconGener and assign Texture2DArray / icon textures.

---

Step 1. Prepare Meshes, Materials, and Sockets

1. Import the SkeletalMesh of the weapon.
   
2. Import the StaticMesh of the weapon (for the world pickup actor).
   
3. Import textures and create materials:
   • Recommended: create a material instance or child of M_UsingItemBase already present in the project.
   • If you use your own base material:
     • Add the function MF_WeaponFunctionality.
     • Connect its outputs to Emissive and Opacity Mask.
     • Use M_UsingItemBase as a reference example.
4. Add sockets to the SkeletalMesh:
   • Blow – muzzle flash location.
     
   • EjectBullet – shell ejection location.
     
   • Sockets for modifications – will be covered in the firearms modification guide.
5. Add sockets to the StaticMesh:
   • Add almost the same set of sockets for modifications as on the SkeletalMesh.
   • Details are also explained in the “add firearm modification” documentation.

---

Step 2. Create the Firearm via ItemsAssistant

1. Open ItemsAssistant.
   

2. Set ItemType = Weapon.
   

3. In Clarification Data, select a firearm subtype in WeaponSubtype, for example:

   • World.Items.Weapon.Type.Rifle
   • Or another firearm tag you use.
     This enables firearm‑specific Clarification fields.

4. Fill General Data:

   • Name
     
   • ShortName
     
   • Description
     
   • Abbreviation
     
   • Weight
     
   • Price
     
   • Rarity

5. Fill Inventory Data:

   • Size – inventory grid size.
     
   • MaximumNumberInSlot – usually 1 for firearms.
     
   • Texture – icon texture or Generated.
     
   • TextureType – for weapons with modifications use Generated 2D Array.

6. Fill Clarification Data (firearms‑specific fields):

   General firearm parameters:

   • CustomBackActor = false
     
   • DestroyBackByAnimNotify = false
     
   • CheckWall = true
     
   • CheckWallDistance – pick a value convenient for you, e.g. 200.
     
   • FireMode – Single or Auto.
     
   • RateOfFire – e.g. 600 (rounds per minute, any value you need).
     
   • AccuracyPercent – 0–100, where 100 = best accuracy.
     
   • Critical Hit Damage Percent
     
   • Critical Hit Damage Chance
     
   • Shot Loudness – for AI; how loud the shot is.
     
   • Shot Loudness Range – for AI; how far AI can hear the shot.
     
   • Use Hot Barrel Effect (optional) – true if you want the hot barrel visual effect:
     • You will need a separate mask texture that defines which parts of the weapon change color.
       
   • Blow Socket – string, e.g. Blow.
     
   • Eject Bullet Socket – string, e.g. EjectBullet.

7. Press Generate.

ItemsAssistant will automatically create:

• BP_ItemData (master item asset).
  
• Inventory DataAsset (child of BP_II_Master / BP_II_ConMaster).
  
• Clarification DataAsset (child of BP_Fire_W_Master_Clar).
  
• A row in DT_ItemData.
  
• Interact Actor (BP_Int_Weapon_...).

---

Step 3. Configure the Clarification DataAsset (Manual Setup)

Open the generated firearm Clarification DataAsset (child of BP_Fire_W_Master_Clar) and fill the following categories.

3.1. Category: Common

• MainSkeletalMesh – reference to the weapon SkeletalMesh.
  
• MainSkeletalMeshAnimBP – simple AnimBP for weapon animations:
  • You can copy the logic from ABP_Rifle_1.
    
• InteractStaticMesh – StaticMesh for the world pickup actor.
  
• AttachToBodyComponent – the skeletal mesh component used when the weapon is placed on the player’s back.
  
• Main Mesh Start Montage – can be left null for firearms (used for special equip animations; see melee guide for an example).

3.2. Category: Sockets

• Blow – muzzle flash socket.
  
• EjectBullet – shell ejection socket.
  
• AttachSockets:
  • MainSocket – socket used when the weapon is in the character’s hands.
    
  • SecondSocket – not used for standard firearms with one mesh (only for two‑component weapons).

Back map for holstering the weapon:

• Back – map:
  • Key: equipment slot / cell type where the weapon is stored when not in hands, e.g. OnBack.
    
  • Value: socket name on the character skeleton where the MainSkeletalMeshComponent of the back actor attaches, e.g. BackWeaponSocket.

3.3. Add sockets to all character skeletons

You must add the same sockets used in Clarification to all character skeletons that may equip this weapon. In the project there are three main skeleton types:

• UE5
  
• UE4
  
• MetaHuman

If you plan to have character skins based on these skeletons, add:

• MainSocket (and any other relevant sockets) to each of these skeletons.

First‑person aim:

• If the weapon supports first person mode (in the current version FP is activated when the player aims with a magnified scope):
  • Add the same MainSocket name to SK_Mannequin_Arms_Skeleton.
    
  • This is required for correct positioning in FP mode.

Later, in the BP_LocomotionData_Master DataAsset (see Animations), you will be able to choose FP animations:

• FP Idle
  
• FP Crouch Idle

If you do not fill these, default FP animations will be used.

3.4. Category: Sounds

• ShotSoundType – choose MetaSound / SoundCue.
  
• ShotSound – usually MetaSound:
  • The MetaSound asset contains advanced logic to control shot sound parameters depending on:
    • How many shots have been fired in a row without a pause.
      
    • Remaining ammo in the magazine.
      
• Shot Loudness / Shot Loudness Range – already set in Step 2; used by AI.

3.5. Category: AdditionalInformation

• Ammo/Priority – array of BP_ItemData references for ammo types that can be used by this weapon:
  • Fill it in priority order:
    • Lower index = higher priority when automatically loading ammo from the inventory.
      
• ShootAdditionalCondition – additional gameplay condition required for shooting:
  • Example: a crossbow might require the state CharacterStates.Weapons.Aim before it is allowed to fire.

3.6. Category: Aim

Aim data is defined by a BPW_Aim_ClarData DataAsset. It contains:

• Field Of View – float; target FOV while aiming.
  
• PredicateHit – bool.
  
• PredicateMarker – UserWidget class (aim marker widget).
  
• Transition Aim Mode Curve – CurveFloat for interpolation from current camera FOV to target aiming FOV.

This Aim DataAsset is used when the player aims and no scope modification is installed on the weapon. When a scope is installed, its own aim data (from the modification) is used instead.

LeanOffset

• LeanOffset – map:
  • Keys (Gameplay Tags):
    • CharacterStates.Effects.CameraRightShoulder
      
    • CharacterStates.Effects.CameraLeftShoulder
      
  • Value: LeanData (map: Right / Left → vector).

The project includes a “change camera shoulder” mechanic. LeanOffset defines, for a chosen main shoulder:

• If the player selects the right shoulder as the main camera position (CharacterStates.Effects.CameraRightShoulder active), then during lean right/left the camera will move by offsets defined in LeanData.
• Similarly for the left shoulder state.

If you are not sure how to set this up, you can copy values from an existing firearm and tweak them by testing camera movement in‑game.

3.7. Category: Animations

Weapons use a locomotion DataAsset to control:

• Which animation layer is active while the weapon is equipped.
  
• Which dodge, dash, jump‑dash, and double‑jump montages are used.
  
• Optional per‑skin overrides via RetargetModifier.

Create a locomotion DataAsset for the weapon

1. Create a new DataAsset with parent class BP_LocomotionData_Master.
   
2. Configure key fields:
   • Locomotion / AnimLayer – AnimInstance class of the locomotion/overlay layer used when this weapon is equipped.
     
   • Abrupt Movement / Dodge, Dash, JumpDash, DoubleJump – montage references for dodge/dash/jump‑dash/double‑jump.
     
   • Actions / Actions – DataTable row handle for contextual actions (optional).
     
   • First Person / FP Idle, FP Crouch Idle – FP idle animations (standing/crouching) if FP mode is supported.

Link the locomotion data to the weapon

• In the weapon Clarification asset, in the Animations section:
  • Set Animations to your BP_LocomotionData_Master child asset.

This ensures the correct animation layer and movement behavior are activated when the weapon is equipped.

CheckWall / CheckWallDistance

• CheckWall / CheckWallDistance:
  • When CheckWall = true, at the given distance the system performs a trace to check if the player is near a wall.
    
  • If true, the weapon will be slightly lowered (an animation defined in your weapon anim layer’s WallDetected field will be activated).

3.8. Category: Close Combat

• For firearms, do not fill the Close Combat category.

3.9. Category: Effect

• For firearms, do not fill the Effect category:
  • All impact effects are configured in ammo DataAssets.

3.10. Category: Back

• For firearms, do not fill the Back category here:
  • The Back map used for holstering was already described in Sockets and is enough.

3.11. Category: Widgets

• AimWidget – the aim reticle widget.
  
• EmptyAim – bool:
  • If true, no aim widget is shown.

3.12. Category: Engine – RetargetModifier

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

• Key: character skin DataAsset name.
  
• Value: struct with retargeting settings:
  • Bone rotation offsets for specific bones.
    
  • useCustomAnimLayer (bool).
    
  • CustomAnimLayer (AnimLayer class / AnimBP used as a linked layer).

Behavior:

• If useCustomAnimLayer = false:
  • Only bone rotation offsets are applied.
  • Weapon still uses the default animation layer from common locomotion/overlay.
• If useCustomAnimLayer = true:
  • In addition to bone offsets, the CustomAnimLayer AnimBP/AnimLayer is linked into the player’s main AnimBP when this weapon is in hands and this specific skin is active.
  • Use this when you want certain skins to hold or animate the weapon slightly differently (hand pose, grip, shoulder offset, etc.) without changing base animations for everyone.

3.13. Category: Effects (Firearm Effects)

• MuzzleFlash – particle / Niagara system for muzzle flash.
  
• ShootCameraShake – camera shake class when firing.
  
• VictimHitCameraShake – camera shake class applied to the victim on hit.
  
• UseHotBarrelEffect – bool:
  • If true, enables hot barrel visual changes based on firing.
    
• HotBarrelData – struct:
  • Index of the component whose material will change.
    
  • MaterialIndexes – which material slots (indices) on that component will be affected.
    
• HotBarrelOneStepSize – float:
  • Increment used when calculating heat growth for visual effect.

3.14. Category: Characteristics

Fire mode:

• Fire Mode:
  • Single
    
  • Auto

Semi‑auto input gating is implemented at the input system level and does not need extra configuration here.

Other fields:

• Rate Of Fire – base rate of fire (rounds per minute); all modification values will be added to this base.
  
• AccuracyPercent – base accuracy parameter of the weapon (0–100).
  
• Dependence Of Accuracy On Continuous Shooting – CurveFloat:
  • Represents how spread grows during continuous fire.

Critical hit parameters:

• Critical Hit Damage Percent – if damage is critical, actual damage is:
  • Damage * (Critical Hit Damage Percent / 100).
    
• Critical Hit Damage Chance – chance for a hit to be critical:
  • Initially, a critical hit is considered when the bullet hits the head bone.
    
  • This parameter is designed so that not only headshots can be critical.
    
  • Recommended range: 5%–10%.

3.15. Category: Modifications (Overview)

• Weapon Parts And Allowed Quantity Of Modifications – key parameter for setting up weapon modifications.

Conceptually, each weapon is split into abstract parts:

• BracketRight
  
• BracketLeft
  
• BracketUpper
  
• BracketLower
  
• Clip
  
• Silencer
  
• Grip
  
• (And any other parts you define.)

Each part defines which types of modifications can be installed there. Examples:

• Part: Bracket_Upper:
  • Only modifications of type Collimator or Scope should be allowed.
    
• Part: Clip:
  • Only modifications of type Clip can be installed.
    
• Part: Silencer:
  • Only modifications of type Silencer can be installed; Clip or Scope cannot.
    
• Part: Bracket_Lower:
  • You may decide that only modifications of type Flashlight are allowed there.
  • In that case, add only Flashlight to ModificationsAllowed for this part.

This abstraction allows several modifications of the same type to be installed on different parts:

• Two sights: one on Bracket_Upper, another on Bracket_Right.
• Because parts differ, the system does not confuse these two sights.

Details for:

• Instance Modifications
  
• ModificationAndSockets

will be covered in the separate firearms modifications documentation.

---

Step 4. Create Weapon Skins

Create skins for the weapon using the guide how-to-add-weapon-skin.md:

1. Create BP_DA_Weapon_Skins DataAssets for each skin.
   
2. Fill materials for interact/weapon/back meshes.
   
3. Set icon fields and register skins in the weapon’s inventory DataAsset later.

---

Step 5. Inventory DataAsset: Skins and Texture Type

Open the generated Inventory DataAsset of the weapon:

1. Fill SimpleVisualizationSkins:
   • Add all DA_Skin_... assets you created for this weapon.
2. Set Inventory Texture Type:
   • Choose Generated2DArray (for weapons with modification‑based icon arrays).

---

Step 6. Configure the Interact Actor

Open the generated interact actor BP_Int_Weapon_... and:

1. Ensure the Data Asset reference points to the correct BP_ItemData.
   
2. Set the Skin parameter:
   • Choose a default weapon skin (one of your DA_Skin_...).

Fill:

• AMMO Data – reference to BP_ItemData of ammo (if the weapon should spawn loaded).
  
• AMMO Quantity – amount of ammo in the weapon on spawn.
  
• ModificationsUserSetup – optional:
  • Use if you want to override default modifications for this specific interact actor instance.

---

Step 7. Configure Modifications and Preview Widget

1. In the firearm Clarification DataAsset, fill the modification list:

   • Use the separate modifications guide to:
     • Add supported modifications.
       
     • Configure Instance Modifications and ModificationAndSockets.

2. Open the weapon’s Inventory DataAsset and configure:

   • Modification Custom Preview – widget that visualizes weapon parts and modifications:
     • Copy an existing preview widget and adjust it.
       
     • This widget must visually match what you defined in:
       • Weapon Parts And Allowed Quantity Of Modifications.
         
     • Arrange UI cells to represent all weapon parts and allowed modification types for each part.

---

Step 8. Icon Generation

Use BP_EngineWeaponIconGener as described in icon-generators.md:

1. Open the L_RecordWeapons map.
   
2. Set Target Data = the weapon BP_ItemData.
   
3. For each skin (if any), set SkinData accordingly.
   
4. Adjust the generator camera and press UpdateCameraSettings.
   
5. Start PIE and wait while the generator captures icons.
   
6. Use DA_TrashContainer to assemble icons into Texture2DArray:
   • Follow the standard workflow:
     • Select generated textures.
       
     • Run Fill Generated Icons To Temp Array.
       
     • Copy textures from DA_TrashContainer.Texture to a new Texture2DArray.SourceTextures.
       
7. Assign icon arrays and single icons:
   • In BP_DA_Skins (for each skin) or in the weapon Inventory DataAsset:
     • Icons Regular Resolution / Icons Custom Resolution – Texture2DArray with icon slices.
       
     • Icon Regular Resolution / Icon Custom Resolution – single UTexture2D icons for generic use.

Additionally, the icon generator automatically fills:

• ModificationIndexesOfTextures in the weapon Clarification DataAsset:
  • This mapping is used at runtime to select correct array slices for each modification configuration.