Firearms System

Purpose

This document describes the runtime architecture and behavior of the firearms system: weapon ownership, shooting, reloading, ammo handling, modifications, aiming, audiovisual effects, character state integration, and multiplayer rules.

Overview

The firearms system is responsible for handling ranged weapon behavior, including weapon equipping, shooting, reload flow, ammo selection, weapon modifications, basic aiming behavior, audiovisual effects, and multiplayer synchronization.

At runtime, the system is split primarily between two components. BP_FirearmsComponent handles shooting, reload logic, and the currently selected ammo type, while BP_EquipmentComponent stores weapon runtime data, including the current ammo count for each weapon owned by the character.

This document describes the gameplay-facing firearm flow and the relationship between weapons, ammo, modifications, and character states. Detailed field-by-field reference data for assets should be documented separately in dedicated reference files.

Core Components

BP_FirearmsComponent

BP_FirearmsComponent is the main gameplay component for firearm operation. It handles:

• Shooting.
• Reloading.
• Current ammo type selection.
• Additional shooting conditions.
• Critical hit body part configuration.

This component should be treated as the place where active firearm behavior is executed.

BP_EquipmentComponent

BP_EquipmentComponent is responsible for weapon ownership and persistent runtime weapon data on the character. It stores all weapon entries currently assigned to weapon slots and tracks how many rounds remain in each weapon.

It also determines which weapon is currently in the player’s hands through replicated runtime variables.

Important runtime variables include:

• WeaponInHandsIndex — index of the currently active weapon.
• WeaponInHandsActorRef — reference to the currently spawned weapon actor in hands.

If WeaponInHandsIndex == -1, the character currently has no weapon in hand. Both variables are RepNotify, so they are intended to update correctly across the network.

Weapon Actors

Two main weapon actor classes are used:

• BP_ConnectWeapon — standard firearm actor.
• BP_ConnectWeaponPredicateHit — weapon actor used when the player must see the predicted impact point of a projectile.

BP_ConnectWeaponPredicateHit is used for ballistic weapons such as crossbows. Its purpose is to support projectile trajectory awareness through a predictive marker system.

Equip Slot Flow

When a weapon is added to a weapon slot, the next action depends on the Action After Adding Weapon To Slot parameter in DA_GS_Equipment.

Supported behavior:

• TryToTakeItInHand — the system tries to place the weapon directly into the player’s hands.
• DontTryToTakeItInHand — the weapon remains assigned to a slot but is not automatically taken into hands.

The system does not require a separate documented gameplay state for “equipped on body” versus “equipped in hands”. Instead, the active in-hand state is determined by the replicated WeaponInHandsIndex and WeaponInHandsActorRef values in BP_EquipmentComponent.

When the weapon is not currently held, the back actor system is used for the stowed representation.

Runtime Weapon Data

All runtime data for weapons stored on the character is kept in the Weapons parameter inside BP_EquipmentComponent. Each entry uses the S_DynamicWorldData structure, which is also used for other inventory items.

S_DynamicWorldData contains the following main structure groups:

• Dynamic Parameters World Item
• Dynamic Parameters Weapon
• Dynamic Parameters Skins
• Dynamic Inventory Slots Info
• Dynamic Cloth

Dynamic Parameters World Item (S_DynamicWorldItems)

Fields:

• Quantity — integer.
• ItemData — BP_ItemData.

Dynamic Parameters Weapon (S_DynamicWeapon2)

This structure contains the main firearm runtime data.

Fields:

• AMMO Quantity — current ammo count in weapon.
• AMMO Type — S_Datasets.
• Modifications — array of S_ModifDynamicInfo.
• BackTag — Name.
• AttachSocket — Name.
• RealTimeWeaponStats — S_RealTimeWeaponStats, which stores final weapon stats after modification processing.
• Buffs — array of S_DynamicBuffs.

Dynamic Parameters Skins (S_DynamicSkins)

Fields:

• SkinData — BPDASkins.
• SkinIndex — integer.

Dynamic Inventory Slots Info (S_DynamicInventorySlotsInfo)

Fields:

• Slot Orientation — EItemOrientation.
• Slot Coordinates — Vector2D.
• Slot Name — String.
• Icon Modification Params — array of String.

Dynamic Cloth (S_DynamicCloth)

Fields:

• Health — float.
• Parameters — FStringTwoParams, used to store mutable clothing parameters of different types.

Related Structures

S_Datasets:

• ItemData — BP_ItemData.

S_ModifDynamicInfo:

• Modification Data — BP_Modif_W_Data_Master.
• Sockets Container — FModifSocketsContainer.
• Transform From Socket — Transform.
• Used Socket Index — integer.
• Static Mesh Reference — SceneComponent.

FModifSocketsContainer:

• Sockets Data — array of DataTableRowHandle.
• CanBeRotated — ERotAxis.

Fire Modes and Shooting Model

The system currently supports two fire modes:

• Single
• Auto

Semi-auto input gating is handled at the input level and does not need separate documentation here.

The shot delivery model is determined by ammo behavior rather than by the weapon class itself.

General behavior:

• Standard firearms usually use line trace shots.
• Special ballistic cases can use actor-based projectiles.
• Crossbows use the predictive-hit variant because the player must see the projectile landing marker.

The firing socket is Blow. The Eject Bullet socket is used only for visual shell ejection.

Accuracy and Spread

The system uses accuracy and spread, but it does not currently use a dedicated recoil system.

Key rules:

• AccuracyPercent should be documented as the base accuracy parameter of the weapon.
• Dependence Of Accuracy On Continuous Shooting represents spread growth during continuous fire.
• Aiming down sights (ADS) does not directly modify accuracy or spread in the current implementation.

Weapon feel is primarily controlled through accuracy and spread behavior rather than camera recoil or recoil patterns.

Ammo and Reload Integration

Ammo should be described as “ammo in weapon”, not as a separate magazine gameplay object. Reload behavior is tied directly to the inventory system because ammunition is taken from the player’s inventory.

High-level reload description:

• The weapon checks for a suitable ammo type in inventory.
• The system selects ammo by priority.
• Ammo is consumed from the inventory.
• The weapon runtime state is updated.

Ammo availability checks use ammo type priority. If multiple compatible ammo types are available, the system selects according to ammo priority rather than only by presence.

Reload can be blocked under certain conditions, including wall proximity. The explicit reload state is represented by the gameplay tag:

• CharacterStates.Weapons.Reload

Damage, Critical Hits, and Armor

Critical damage is not limited to headshots. The system can also use a critical chance value, and additional body parts can be configured as critical hit zones through Critical Hit Body Parts in BP_FirearmsComponent.

A typical critical damage formula:

• FinalDamage = BaseDamage * (CriticalHitDamagePercent / 100)

Damage Type and Damage Type Critical should be treated as separate handlers for normal and critical damage processing.

Armor interaction is checked through armor class and bullet tags (for example, tags defining which bullets the armor is designed to stop). Armor items and ammo types together determine whether damage is reduced, blocked, or fully applied.

Aiming and Scopes

For non-scoped weapons, aiming simply narrows the player camera FOV. There is no separate advanced ADS system that needs a large standalone section.

Aim data is defined by BPW_Aim_ClarData, which contains:

• Field Of View — float.
• PredicateHit — bool.
• PredicateMarker — UserWidget class.
• Transition Aim Mode Curve — CurveFloat used for interpolation from current camera FOV to target aiming FOV.

For scoped optics, zoom values are stored in ScopeValues, and both FOV and mouse sensitivity can change depending on the selected magnification. Visibility modes may include normal mode as well as modes such as thermal or night vision.

Optic categories should be described as different optic types provided through weapon modification assets.

Weapon Modifications

Weapon modifications can be changed through the inventory UI. The player opens the full weapon panel by double-clicking the weapon icon, which reveals complete weapon information and allows swapping installed modifications using items currently available in inventory. The same panel also allows changing the weapon skin.

Compatibility is controlled through Weapon Parts And Allowed Quantity Of Modifications. This system divides the weapon into logical parts such as:

• BracketRight
• BracketLeft
• BracketUpper
• Silencer
• Clip
• Grip
• BracketLower

This allows multiple modifications of similar categories to coexist on different weapon parts while still enforcing slot-specific rules. For example, different sights may be installed on BracketUpper and BracketRight, while Silencer accepts only silencers, Clip accepts only clip-type modifications, and BracketLower can be limited to flashlight-type modifications.

Instance Modifications should be documented as the default modifications a weapon receives by default when it is created or spawned.

Stat Modification Rules

Weapon modifications can change several weapon parameters. All modification values are aggregated and applied to the base weapon stats to produce RealTimeWeaponStats.

Supported stat changes include:

• Rate Of Fire — rounds per minute, flat additive. All modification values are added to the base rate of fire.
• Damage — percent relative to base damage. Base weapon damage is treated as 100. Final damage is computed by adding summed modification values on top of the default value.
• Critical Damage — percent applied to base critical damage using the same aggregation rule as damage.
• Critical Damage Chance — chance for a hit to be treated as critical.
• Range at which the bullet does not lose its killing power — additive value in meters.
• Number of Bullets — overrides the default clip size by taking the highest value among selected modifications.
• Accuracy — percentage-based modifier added to the default accuracy.

The final processed values are stored in RealTimeWeaponStats.

Visual and Audio Layer

The main audiovisual layer of the firearm system includes:

• MuzzleFlash
• Tracer System
• Eject Bullet System
• ShotSound
• ShootCameraShake

Shot loudness is also gameplay-relevant. Shot Loudness and Shot Loudness Range are used for AI or bot reaction to gunfire.

Silencers may override the base audiovisual behavior by providing their own shot sound, muzzle effect, and tracer system.

Character State Integration

The firearm system is integrated with character gameplay tags and state restrictions.

ShootAdditionalCondition should be documented as an additional required gameplay condition for shooting. For example, a crossbow may require the state CharacterStates.Weapons.Aim before it is allowed to fire.

The system also uses a ForbiddenStates list to block shooting. Known blocked examples include:

• CharacterStates.Movement.Run
• CharacterStates.Movement.Swim
• CharacterStates.Movement.Falling
• CharacterStates.Movement.Flying
• CharacterStates.Weapons.Reload
• CharacterStates.Weapons.ThrowGrenade
• CharacterStates.Weapons.SwitchWeapon
• CharacterStates.Weapons.SwitchAmmoType
• CharacterStates.CloseCombat.SimpleAttack
• CharacterStates.CloseCombat.PowerfulAttack
• CharacterStates.CloseCombat.SpecialAttack
• CharacterStates.AI.UnderFlashbangEffect
• CharacterStates.UI.OpenMap
• CharacterStates.UI.OpenInventory
• CharacterStates.UnusualSkills.OnLadder
• CharacterStates.Movement.Jump

Other forbidden states may also be configured in the data.

A wall check is also present in the firearm system. It affects shooting, weapon pose, and reload behavior.

Multiplayer Behavior

The firearm system is server-authoritative.

• The server validates hits.
• The server controls ammo consumption and reload.
• The server controls weapon-in-hands state.
• Ammo state and weapon modifications are replicated to clients.

All gameplay-relevant weapon changes are applied on the server and then replicated to ensure consistency across the network.

Client-side prediction for firearms is not a focus of this document. Visual responsiveness is handled in a straightforward way suitable for typical listen-server and small-session scenarios.

Scope of This Document

This file covers:

• Firearm architecture.
• Weapon equip and in-hand flow.
• Shooting flow.
• Ammo and reload integration.
• Modification integration.
• Basic aiming and scope behavior.
• Character state restrictions.
• Multiplayer basics.

Detailed asset field documentation should remain in dedicated reference documents rather than in this overview file.

Related Docs

The firearms system is closely connected with:

• docs/systems/state/state-system.md — character states that gate shooting, aiming, and reloading.
  
• docs/systems/inventory-equipment/inventory-and-equipment.md — weapon storage, equip slots, and ammo in inventory.
  
• docs/systems/melee/melee-system.md — shared state rules and combat integration between firearms and melee.
  
• docs/systems/grenades/grenades-system.md — shared damage pipeline, armor interaction, and combat roles.
  
• docs/systems/stats/stats-and-survival-system.md — survival stats and buffs that modify damage and stamina.
  
• docs/systems/ai/ai-combat-and-behavior.md — AI aiming, reaction to shots, and loudness-based perception.
  
• docs/systems/save-load/save-load-and-sessions.md — saving weapon loadouts, ammo state, and runtime weapon data.
  
• docs/reference/reference-gameplay-tags.md — gameplay tags used for weapon states and categories.
  
• docs/reference/reference-data-tables.md — ammo and weapon rows in DTItemData and related tables.
  
• docs/reference/weapon-modifications-reference.md — detailed reference for weapon modifications and attachment assets.