How to Add a Firearms Modification

This guide explains how to add a new weapon modification (silencer, scope, flashlight, grip, clip, collimator, etc.) for an existing firearm in RPG Engine v6. It covers asset creation via ItemsAssistant, clarification setup per modification type, socket data in DT_ModifSocketData, and linking modifications to a weapon.

1. Prerequisites

Before you start, make sure that:

The base firearm is already configured and working in-game (DT_ItemData row, Inventory DataAsset, Clarification DataAsset child of BP_FireW_Master_Clar / BP_Weapon_Master_Clar).
The firearms system and weapon modifications system are understood from:
- firearms-system.md (firearms runtime flow, S_DynamicWeapon2, RealTimeWeaponStats).
- weapon-modifications-reference.md (BP_Modif_W_Data_Master, S_Modif_DynamicInfo, F_ModifSocketsContainer, stat rules).
The ItemsAssistant utility is available and configured in the editor (items-assistant.md).
All meshes, materials and (optionally) actor classes for your modification are imported into the project.

Related docs:

firearms-system.md
weapon-modifications-reference.md
inventory-and-equipment.md
icon-generators.md
how-to-add-firearm.md

2. Step 1 – Create the Modification via ItemsAssistant

Use ItemsAssistant to generate all base assets and the DT_ItemData row.

Open ItemsAssistant (Editor Utility Widget) in the UE editor.
In Item Type, select Modification.
In the modification subtype field, choose the correct type:
- Silencer
- Scope
- Flashlight
- Collimator
- Grip
- Clip
- Other supported modification types in your project.
Fill General Data:
- Name, Short Name, Description, Abbreviation.
- Weight, Price, Rarity.
Fill Inventory Data:
- Texture / Texture Type (Simple / Generated Texture / Generated 2D Array depending on your icon pipeline).
- Size (grid size), Maximum Number In Slot (usually 1 for mods).
- For Sale flag if the mod should appear in vendors.
Fill Clarification Data (basic fields exposed by ItemsAssistant for the chosen modification type).
Press Generate:
- ItemsAssistant will:
  - Create a master BP_ItemData‑child for the modification.
  - Create an Inventory DataAsset (BP_II_Master child or subtype).
  - Create a Clarification DataAsset of the correct modification class (child of BP_Modif_W_Data_Master or a specific mod type).
  - Add/update a row in DT_ItemData referencing these assets.

After generation, you must open the Clarification DataAsset and complete type‑specific settings.

3. Step 2 – Configure Clarification Data by Modification Type

3.1. Silencer

Silencer Clarification DataAsset configures sound, VFX and stat changes for a suppressor.

Key fields:

ShotSound
Meta shot sound used when the silencer is installed (replaces default weapon shot sound).
Muzzle System
Niagara/particle system for muzzle flash when silencer is equipped.
Use it to remove flame or use a different effect.
Tracer System
Tracer effect for bullets when this modification is active.
Required Class (ActorClass)
- Empty: engine will add a new StaticMeshComponent on the weapon and use StaticMesh as its mesh.
- Filled: engine will spawn this actor class, attach it to the weapon and use it as the modification.
StaticMesh
Static mesh used for the silencer if you do not use a dedicated actor.
Type
Logical modification type (e.g. Silencer). Used by compatibility rules and UI filters.
Affected Stat Types And Values (Map<StatType, float>)
Weapon parameters and how they are modified. Supported stat types and rules:
- Accuracy
  Percentage applied to the default value.
  Rule: all modification values are summed and added directly to base accuracy: [ FinalAccuracy = DefaultAccuracy + AccuracyModValues ]
- Rate Of Fire
  Value in rounds per minute, flat additive.
  Rule: all modification values are summed and added to base RoF.
- Damage
  Percent relative to base damage (base = 100%).
  Rule: $$ FinalDamage = DefaultDamage + \left(\frac{DefaultDamage}{100}\right) \cdot \sum DamageModValues $$
- Critical Damage
  Percent relative to base critical damage.
  Rule: $$ FinalCritDamage = DefaultCritDamage + \left(\frac{DefaultCritDamage}{100}\right) \cdot \sum CritDamageModValues $$
- Critical Damage Chance
  Percentage points (0–100). Aggregation rule is defined by design (usually sum with clamp to [0, 100]).
- EffectiveRange
  Additional distance in meters.
  Rule: all values are summed and added to base effective range.

3.2. Clip, Collimator, Grip

These modification types share a similar Clarification layout:

Required Class
Optional actor class to spawn instead of using only a static mesh.
StaticMesh
Static mesh for the modification, used if no actor class is provided.
Type
Logical type (e.g. Clip, Collimator, Grip).
Affected Stat Types And Values
Same stat list and rules as for Silencer:
- Clip typically changes magazine size, reload behavior and/or weight.
- Collimator usually affects accuracy and sighting comfort.
- Grip affects accuracy/spread/handling.

Configure the map according to your weapon design.

3.3. Flashlight

For a flashlight, use a dedicated actor:

Required Class
Create a new class with parent BP_ConnectModif and set it here.
This actor will handle light, toggling, input, etc.
StaticMesh
Type
Affected Stat Types And Values (optional, for weight or minor stat adjustments).

3.4. Scope

Scope Clarification DataAsset configures zoom, FOV, sensitivity and optional distance tracking.

Required Class
- Create a new actor class with parent BP_Con_Scope.
- If you want a distance tracker visible in the scope, create a child from BP_Con_Scope_DT and set it here.
ScopeValues (array)
Each element describes one zoom step:
- Zoom Value — logical zoom level.
- FOV — camera Field Of View.
- Mouse Sensitivity Multiplier — sensitivity multiplier for this zoom.
Subtype
- Default — regular scope.
- DistanceTracker — scope with distance tracking.
Additional Data
DataAsset of class BP_Scope_DistanceTracker. For distance‑tracker scopes you can configure:
- Max Track Distance (meters)
  Maximum distance at which the scope can detect and display range.
  Do not set excessively high values to avoid performance issues.
- Tracking Frequency
  Interval for updating distance. Passed to the timer loop time in BP_Con_Scope_DistanceTracker::StartAim.
StaticMesh
Type
Affected Stat Types And Values
Use this to adjust accuracy and effective range, if needed, in addition to zoom/FOV.

4. Step 3 – Configure Socket Data in DT_ModifSocketData

DT_ModifSocketData stores reusable socket configuration for modifications.

Each row has the following structure:

Socket (Name)
Socket name on the weapon mesh where the modification can be attached.
Limiters (S_SocketBorders)
- LIMITER_Start (Name)
- LIMITER_Finish (Name)
  These are socket names that define the movement range for the modification in edit mode:
- Engine computes the direction and range as LIMITER_Finish – LIMITER_Start.
- The modification can slide between these two points while the player is adjusting its position.
Part Name (E_PartName)
Logical weapon part where this socket lives:
- Bracket_Right, Bracket_Left, Bracket_Upper, Silencer, Clip, Grip, Bracket_Lower, etc.
AbbreviatedName (String)
Short ID for the socket row.
Switchable Input Axis (bool)
If true, you can remap input axes so that mouse movement on X affects camera movement on Y, etc.
Used primarily for side‑mounted magnifiers and scopes whose cameras are tilted relative to the usual view.
Yaw (E_InputViewAxis, values: X, -X, Y, -Y)
Which input axis controls camera yaw.
Pitch (E_InputViewAxis, values: X, -X, Y, -Y)
Which input axis controls camera pitch.
FixCameraRotation (bool)
If true, CameraRotation is added to the camera rotation when aiming through this modification.
CameraRotation (Rotator)
Extra rotation applied to the camera to compensate for the modification’s orientation.
ImageDisplayerRotation (Rotator)
Rotation for the internal display in the modification (for example, rotating the plane showing an image/HUD).
FixDistanceTrackerTransform (bool)
If true, DistanceTrackerTransform is applied to the relevant component.
DistanceTrackerTransform (Transform)
When FixDistanceTrackerTransform = true, this transform is added to the relative transform of the distance‑tracker component (plane that shows current distance to the target in a distance‑tracking scope).

Action:

Open DT_ModifSocketData.
Create a new row for each new socket you want to use:
- Set Socket, Part Name, AbbreviatedName.
- Configure Limiters if the modification should move along a path.
- Adjust input/camera fields for scopes/magnifiers as needed.

5. Step 4 – Link Modifications to a Weapon (Clarification Data)

Open the Clarification DataAsset of the firearm (child of BP_FireW_Master_Clar / BP_Weapon_Master_Clar).

Locate the Characteristics → Modifications section (names can differ slightly; follow your project’s clar asset).

5.1. Weapon Parts And Allowed Quantity Of Modifications

This block defines weapon parts and how many modifications each part can accept.

Common parts: Bracket_Right, Bracket_Left, Bracket_Upper, Silencer, Clip, Grip, Bracket_Lower.
For each part, configure:
- Which modification types are allowed.
- How many mods can be installed simultaneously on that part.

This was already set up when adding the firearm; you usually don’t need to change it for a single new modification, unless you are enabling a new part.

5.2. Instance Modifications (Default Mods on Weapon)

Instance Modifications is an array of structures describing mods installed by default when the weapon is created.

Structure fields:

Clarification Data Asset
The modification’s Clarification DataAsset (your silencer/scope/etc.).
SocketData (DataTableRowHandle)
Reference to a row in DT_ModifSocketData that defines which socket on the weapon this mod uses.
Additional Transform (Transform)
Offset applied on top of the transform from the socket:
- Final modification transform = transform from socket data + Additional Transform.

Use this array to pre‑install mods (e.g. a rifle that ships with a built‑in collimator and grip).

5.3. ModificationAndSockets (All Allowed Modifications)

ModificationAndSockets is a Map that defines which modifications are allowed on this weapon, and on which sockets they can be mounted.

Key: modification Clarification DataAsset.
Value: F_ModifSocketsContainer.

F_ModifSocketsContainer fields:

Sockets Data — array of DataTableRowHandle
Each handle points to a row in DT_ModifSocketData.
The modification can be attached to any of these sockets.
CanBeRotated (E_RotAxis)
Defines whether the player can rotate the modification in edit mode, and around which axis.
If CanBeRotated != No, rotation is allowed around the specified axis.

Example:

In DA_CL_Rifle, you might have:
DA_CL_Collimator_1 → [0] CollimatorR1_1_1, [1] CollimatorR1_1_2
This means DA_CL_Collimator_1 can be attached to two different sockets, whose data is stored in DT_ModifSocketData rows CollimatorR1_1_1 and CollimatorR1_1_2.

Action:

For each new modification Clarification asset:
- Add a key to ModificationAndSockets.
- Add all relevant socket rows to Sockets Data.
- Set CanBeRotated if rotation in edit mode should be allowed.
Optionally, add the modification to Instance Modifications if the weapon should spawn with it installed by default.

At runtime, the firearm system will:

Use ModificationAndSockets to know which mods are compatible and where they can be attached.
Store active mods in S_DynamicWeapon2.Modifications as S_Modif_DynamicInfo.
Aggregate their stat effects into RealTimeWeaponStats.

6. Step 5 – Test In‑Game

Give yourself the new modification item via:
- Debug loadout, console command, or vendor inventory, using the new DT_ItemData row.
In-game, open the inventory:
- Equip the firearm that supports this modification.
- Double‑click the weapon icon to open the full weapon panel.
- Check that:
  - The modification appears in the list of compatible mods for the relevant part.
  - It can be installed/removed correctly.
  - The mesh appears at the correct socket on the weapon (in hands, on back, in world as pickup if relevant).
Enter the modification edit mode (if available for this mod type):
- Verify that movement is limited between the LIMITER_Start and LIMITER_Finish sockets.
- If rotation is allowed, check that it works around the axis specified by CanBeRotated.
For scopes and magnifiers:
- Aim through the scope and ensure:
  - FOV and mouse sensitivity match ScopeValues.
  - Camera rotation is corrected according to FixCameraRotation and CameraRotation if configured.
  - Distance tracker (if used) displays correct distance and updates with the specified Tracking Frequency up to Max Track Distance.
Fire the weapon with the modification installed:
- Verify stat changes (accuracy, RoF, damage, critical chance/damage, effective range) behave as expected according to Affected Stat Types And Values and the rules in weapon-modifications-reference.

7. Quick Checklist

Use this checklist before considering the modification complete:

Modification created via ItemsAssistant with Item Type = Modification (General, Inventory, Clarification filled).
Clarification DataAsset configured:
- Correct type (Silencer / Scope / Flashlight / Collimator / Grip / Clip).
- Required Class and StaticMesh set appropriately.
- ScopeValues / Subtype / Additional Data configured for scopes if needed.
- Affected Stat Types And Values filled according to design and stat rules.
New socket rows added to DT_ModifSocketData for any new sockets:
- Socket, Limiters, Part Name, AbbreviatedName.
- Input/camera fields configured for scopes/magnifiers if required.
Weapon Clarification DataAsset updated:
- Weapon Parts And Allowed Quantity Of Modifications supports the target part if needed.
- ModificationAndSockets has entries for the new modification with correct Sockets Data and CanBeRotated.
- Instance Modifications contains the new mod if it should be installed by default.
In‑game tests confirm:
- Mod appears in the weapon UI and can be installed.
- Visual attachment and optional edit/rotation behave correctly.
- Firearms stats and behavior match the configured modifications.
- Scopes/trackers work visually and functionally as expected.