Ammo System

Purpose

This document describes how ammunition works in the firearms system: storage, selection, reload behavior, shot delivery, damage processing, armor interaction, state restrictions, and multiplayer behavior.

Overview

Ammo is part of a weapon’s runtime state. There is no separate gameplay entity for magazines or clips. Each weapon stores:

• how many rounds are currently loaded,
• which ammo type is currently used,

while the player inventory acts as the source of ammunition for reloads.

Ammo configuration defines:

• how shots are delivered (hitscan vs projectile),
• how damage and armor interaction are processed.

Runtime Storage

Weapons owned by a character are stored in the Weapons array of BP_EquipmentComponent. Each entry uses the S_DynamicWorldData structure. Ammo data is located inside the Dynamic Parameters Weapon block (S_DynamicWeapon2).

Ammo-related fields:

• AMMO Quantity — current number of rounds loaded in this weapon.
• AMMO Type — S_Datasets, reference to the data describing the ammo type.

S_Datasets contains:

• ItemData — BP_ItemData for the ammo item.

This combination defines both the type of ammo used by the weapon and its current ammo count.

Ammo Source and Model

Ammo in the weapon is refilled from the player’s inventory. When the weapon reloads, it pulls compatible ammo items from the inventory and updates its AMMO Quantity and AMMO Type accordingly.

Conceptually, the system distinguishes:

• loaded ammo — number of rounds currently stored in the weapon,
• reserve ammo — ammo items stored in the inventory.

There is no separate runtime object representing magazines or clips. For gameplay and documentation purposes, the weapon simply has “ammo in weapon” plus matching ammo items in inventory.

Ammo Selection and Priority

BP_FirearmsComponent is responsible for tracking the currently selected ammo type and for driving reload logic.

When the weapon needs ammo (for example, during reload), the system:

1. Scans the inventory for compatible ammo types.
2. Applies ammo type priority rules.
3. Selects the best available ammo type based on priority and quantity.
4. Updates the weapon’s AMMO Type and AMMO Quantity.

If several compatible ammo types are available, their priority determines which ammo is used first. This allows a single weapon to support multiple ammo types while preserving deterministic behavior.

Reload Behavior

Reload is tightly integrated with the inventory and weapon runtime data.

High-level reload flow:

1. The weapon checks the current AMMO Type and compatible ammo types.
2. The system finds suitable ammo items in the player’s inventory and applies ammo priority.
3. Required ammo is consumed from inventory.
4. The weapon’s AMMO Quantity and AMMO Type are updated.

Reload can be blocked by gameplay conditions (for example, when the character is too close to a wall). Reload is represented by the gameplay tag:

• CharacterStates.Weapons.Reload

Game logic uses this tag both to drive animations and to prevent conflicting actions during reload.

Shot Delivery Model

The way a shot is delivered is defined by ammo and weapon configuration.

Supported shot models:

• hitscan (line trace),
• projectile (actor-based bullet).

Standard firearms typically use hitscan (line trace) shots. Projectile-based behavior is used for ballistic weapons such as crossbows, where travel time and trajectory matter.

Crossbows use the BP_ConnectWeaponPredicateHit weapon actor, which supports:

• projectile-based shots,
• prediction of impact point through a marker.

Sockets used in the shot process:

• fire origin: Blow,
• shell ejection: Eject Bullet (visual effect only).

The ammo configuration determines whether the weapon uses hitscan or a projectile actor when firing.

Damage and Critical Hits

Ammo participates in damage calculation by defining how the hit is processed and which damage types are used.

Key damage handlers:

• Damage Type — handler for normal hits.
• Damage Type Critical — handler for critical hits.

Critical hits are defined by:

• critical hit chance,
• a list of critical body parts.

Critical body parts are configured in the Critical Hit Body Parts array of BP_FirearmsComponent. This allows critical hits from heads and any other specified bones.

A typical critical damage formula is:

CriticalDamage = BaseDamage * (CriticalHitDamagePercent / 100)

Ammo data and weapon data together define the final damage applied to the target.

Armor Interaction

Armor interaction combines armor class with bullet tags defined on ammo.

Typical configuration:

• armor items specify which bullet classes they are designed to protect against,
• ammo defines bullet tags such as “designed for these bullets”.

During damage processing, the system:

• checks armor class,
• checks bullet tags,
• applies armor mitigation or penetration rules depending on the combination.

This allows different ammo types (for example, standard, armor‑piercing, special) to interact with armored targets in different ways.

Accuracy and Continuous Fire

Ammo does not define recoil; the system uses accuracy and spread instead of a dedicated recoil system.

Weapon-side parameters that affect how ammo behaves during fire:

• AccuracyPercent — base accuracy of the weapon.
• Dependence Of Accuracy On Continuous Shooting — how spread increases when firing continuously.

Aiming down sights (ADS) changes the camera’s field of view but does not directly change accuracy or spread. Ammo works together with these weapon parameters to determine hit precision and spread patterns.

Aiming and Ballistic Prediction

Projectile-based ammo types can use ballistic prediction to show the player where the projectile is expected to land.

Aiming configuration is defined in the BP_W_Aim_ClarData asset:

• Field Of View — target FOV in aim mode.
• PredicateHit — enables or disables predictive hit mode.
• PredicateMarker — UserWidget class used as a predicted impact marker.
• Transition Aim Mode Curve — CurveFloat that controls how smoothly the camera FOV transitions into aim mode.

Crossbows and other ballistic weapons use these fields to provide an aim helper for projectile impact.

Character State Restrictions

Ammo usage is affected by character and weapon states.

Examples:

• ShootAdditionalCondition can require specific states before firing.
  A crossbow can require the CharacterStates.Weapons.Aim tag to be active before a shot is allowed.

• A list of ForbiddenStates prevents firing while certain tags are active, such as:

  • movement states: run, swim, falling, flying, jump, parkour,
  • weapon states: reload, throw grenade, switch weapon, switch ammo type, shoot,
  • melee attack states,
  • various special ability states,
  • UI states: open map, open inventory,
  • flashbang and similar effect states.

A wall‑check system also affects weapon behavior:

• blocks or alters shooting when the character is too close to a wall,
• influences weapon pose,
• can block reload when there is not enough space.

These restrictions apply equally regardless of ammo type, but they define when ammo can actually be used.

Multiplayer Behavior

The ammo system is server‑authoritative.

On the server:

• hits are validated,
• ammo consumption is applied,
• reloads are performed,
• weapon runtime state (including ammo) is updated.

On clients:

• current ammo state is received through replication,
• visual feedback (muzzle flash, tracers, impact effects) is synchronized with server‑confirmed actions.

Ammo state and weapon modifications are part of the replicated weapon data, so all players see consistent ammo counts and shot behavior in multiplayer sessions.

Related docs

• docs/systems/inventory-and-equipment.md — how ammo items are stored in inventory and referenced by weapons.
• docs/systems/firearms/firearms-system.md — firearm runtime architecture and how weapons consume and update ammo.
• docs/systems/firearms/scopes-and-aiming.md — aiming behavior and prediction that works together with ammo delivery models.