Grenades System

This file describes the grenade system from input and throw to detonation, damage application, interaction with armor, AI, and player-built structures.
Grenades are integrated with the inventory/equipment system, the shared damage system, Character States, and AI perception.

Core Components and Data

Runtime components

Main classes and components used by the grenade system:

• BP_GrenadesComponent — character component that handles input for throwing grenades and selecting their type.
  
• BP_Grenade_Master — base runtime actor class for grenades, spawned when a grenade is thrown.
  
• ProjectileMovement (component on BP_Grenade_Master) — controls the arc/flight of the grenade immediately after spawn.
  
• RotatingMovement (component on BP_Grenade_Master) — controls grenade rotation during flight, enabled/disabled based on data asset settings.

The grenade is not attached to the character’s hand; it is spawned at the hand socket location at the notify time and immediately controlled by ProjectileMovement.

Item data and Clarification

Grenade instances in the inventory are represented as items:

• World.Items.Types.Grenade — item type for grenades, referencing a specific Clarification asset.
  
• BP_CL_GrenadeMaster — base Clarification Data Asset for grenade configuration.

Children of BP_CL_GrenadeMaster include:

• BP_CL_Grenade_Electro
  
• BP_CL_Grenade_Explosive
  
• BP_CL_Grenade_Flash
  
• BP_CL_Grenade_Poison
  
• BP_CL_Grenade_Smoke
  
• BP_CL_GrenadeMaster_Paint

BP_CL_GrenadeMaster: key parameters

Core fields that define grenade behavior:

• Static Mesh — visual mesh of the grenade.
  
• Spawn Actor — class to spawn on detonation (damage zone, gas zone, etc.).
  
• Detonation Delay — base delay before detonation after activation/spawn.
  
• Damage Type — reference to a damage type (child of BP_DamageTypeMaster) used by the shared damage and armor systems.
  
• Damage Range — base damage values.
  
• Main Damage Zone, Secondary Damage Zone — inner and outer damage/effect zones.
  
• Loudness and OuterRadius — parameters used for AI sound perception.
  
• ActivateByHit — “detonate on first hit” flag used by some grenade types (for example, flash).
  
• DestroyImmediately — whether to destroy the grenade actor immediately after detonation.
  
• GrenadeType — grenade type (explosive, flash, poison, electro, smoke, paint, etc.).
  
• Grenade Camera Shake — camera shake settings for the explosion.
  
• OuterRadius — radius in which AI can “hear” or feel the explosion.
  
• Sound parameters: Sound Type, Meta Explosion Sound, Cue Explosion Sound, FadeOut Sound Delay.
  
• Lifespan — maximum lifetime of the grenade actor.

Child Clarification assets add behavior for specific grenade types (penetration, gas zones, damage ticks, decals, and so on).

Runtime Flow

Throw sequence

Base runtime flow for throwing a grenade:

1. The player presses the grenade throw button.
   
2. BP_GrenadesComponent checks whether CharacterStates.Weapons.ThrowGrenade can be activated.
   
3. If allowed, CharacterStates.Weapons.ThrowGrenade is activated; this state blocks a set of other actions (weapon switching, firing, reloading, melee, etc., per state machine rules).
   
4. A grenade throw animation montage is played on the character.
   
5. At a specific moment in the montage, the ThrowGrenade anim notify is triggered.
   
6. In the ThrowGrenade notify handler, an actor of class BP_Grenade_Master is spawned at the character’s hand socket location.
   
7. ProjectileMovement on BP_Grenade_Master immediately gives the grenade its initial velocity/direction in an arc; if the Clarification asset indicates that the grenade should rotate, RotatingMovement is enabled.
   
8. The grenade flies along its trajectory, collides with the world, and detonates either after Detonation Delay or when ActivateByHit logic triggers.

Character States

The grenade system uses the following Character States at minimum:

• CharacterStates.Weapons.ThrowGrenade — main state for grenade throwing, activated on input, controlling animation and blocking of other actions.
  
• CharacterStates.Weapons.SwitchGrenadeType — state used when changing grenade type via UI; temporarily blocks certain actions (firing/melee) according to the state machine.

While ThrowGrenade is active, many other states (weapon switching, reload, some melee attacks, etc.) either cannot be activated or are forcibly deactivated, ensuring an atomic throw animation flow.

Grenade Types

The grenade system supports several types implemented as different Clarification assets based on BP_CL_GrenadeMaster.

Explosive Grenades

Explosive grenades deal area damage and interact with physical materials, buildings, and vehicles.

Key aspects:

• Base damage comes from the Damage Type and Main Damage Zone settings.
  
• Secondary Damage Zone can be used for an outer falloff zone with lower damage.
  
• PenetrableMaterials and BlockingMaterials define which physical materials allow damage penetration and which block it.
  
• Explosive grenades can:
  • damage other players,
    
  • damage or destroy vehicles,
    
  • destroy player-built structures from the building system.

Flash Grenades

Flash grenades detonate on a timer or on first hit (ActivateByHit) and apply vision and hearing impairment.

Key aspects:

• On detonation, the system checks whether the player was looking at the explosion and whether proper protective gear is equipped.
  
• If the player looked at the explosion and has no appropriate protection (for example, glasses/mask), the grenade applies:
  • a blinding effect (bright flash/whiteout),
    
  • a deafening effect (ringing, altered sound).
    
• Flash grenades do not primarily use HP damage; the main logic is visual/audio effects and states.

Smoke Grenades

Smoke grenades create a visual smoke screen.

• Behavior: spawn a smoke effect that hides vision for players.
  
• AI line-of-sight blocking can be minimal or absent; at the system level smoke is described as a visual obstruction.

Poison (Gas) Grenades

Poison grenades create a gas zone that applies periodic health damage.

Key aspects:

• On detonation, a gas zone (Damage Zone Class) is spawned and runs between AffectZoneInitialDelay and AffectZoneEndTime.
  
• GasType defines the gas type used to check against protective masks/gear.
  
• Players inside the zone periodically take HP damage (damage ticks).
  
• If the character has a mask that protects against this exact GasType, the damage is blocked.
  
• If the mask protects against a different gas type, damage is still applied.

Electro Grenades

Electro grenades apply several damage ticks in an area.

Key aspects:

• Damage is split into multiple sequential ticks within the effect radius.
  
• A dedicated Damage Type is used so armor and stats can handle this damage correctly.
  
• Example: a special rubber armor with class DA_ArmorClass_Electro can partially or fully absorb electro grenade damage.

Paint Grenades

Paint grenades are used for visual marking.

• On detonation, decals are spawned; count, material, and settings are driven by DecalsQuantity, Decal Material, and Decal Settings.
  
• Paint grenades do not apply gameplay damage in the current version; they are purely visual.

Damage, Armor and Destruction

Damage calculation

All damaging grenades rely on the shared damage system:

• Damage Type (child of BP_DamageTypeMaster) defines the base damage type and its interaction with armor and stats.
  
• Main Damage Zone and Secondary Damage Zone control radii and falloff.
  
• Electro and poison grenades use their own Damage Type plus specific parameters (ticks, gas zones, etc.).

Flash grenades primarily work through status/effects (blindness, deafness) and do not rely on classic HP damage.

Armor and protection

The armor system handles grenade damage via armor classes and explicit parameters:

• BP_ArmorClass_Master defines armor classes, including a GrenadeDefense field.
  
• GrenadeDefense specifies which grenade types and how effectively the armor can block or reduce.
  
• Special armor classes like the rubber vest DA_ArmorClass_Electro are tuned to absorb electro grenade damage.
  
• Poison grenade protection is handled through masks/respirators that are checked against GasType.

Destruction and vehicles

Explosive grenades interact with the environment and vehicles:

• They can damage vehicles and other characters within their radius.
  
• They can destroy player-built structures from the building system.
  
• They account for penetration through certain physical materials and blocking by others but do not simulate physical shrapnel.

At the documentation level, destruction is limited to building system structures and actor health logic, not full world-wide physical destruction.

AI Reaction and Loudness

Grenades integrate with AI via sound parameters:

• Loudness and OuterRadius on BP_CL_GrenadeMaster are used to generate a sound event on explosion.
  
• AI can “hear” the explosion within OuterRadius and react according to its behavior (aggro, investigate, search).
  
• The grenade system only publishes the event; specific reactions are implemented in the AI system.

Inventory, States and Usage

Inventory model

Grenades in the inventory are regular stackable items:

• Item type: World.Items.Types.Grenade.
  
• Grenades are stored in the shared grid inventory, with no dedicated grenade slot or hotbar.
  
• On throw, the corresponding stack count is reduced.

There is no separate “grenade in hand” item; the runtime actor BP_Grenade_Master is created directly on the ThrowGrenade notify.

State integration

Key points:

• CharacterStates.Weapons.ThrowGrenade controls the throw animation and blocks conflicting actions such as firing, reloading, or melee.
  
• CharacterStates.Weapons.SwitchGrenadeType is used when opening/using the grenade selection UI, temporarily restricting some weapon actions.
  
• The state machine is configured so grenade throwing is an atomic action and cannot be mixed with weapon switching, reloads, etc.

Multiplayer

In multiplayer the grenade system works in a server-authoritative manner:

• The client processes input and calls logic on BP_GrenadesComponent, but spawning BP_Grenade_Master happens on the server.
  
• Grenade flight physics, detonation, damage calculation, effect application, and destruction are all computed on the server.
  
• Clients receive replicated state (grenade position, explosion, damage results, visual and audio effects).
  
• Client-side prediction (local fake explosions before server confirmation) is not used.

This ensures consistent damage and destruction across all clients.

UI and Grenade Selection

Grenade selection widget

Grenade type selection is implemented through a dedicated UI widget:

• WB_GrenadeTypes_List — radial menu for grenade type selection.
  
• When opened, the menu shows available grenade types (explosive, flash, smoke, poison, electro, paint, etc.) with icons and counts.
  
• The player selects a type by hovering with the cursor over the corresponding sector.

If a selected grenade type has multiple subtypes (for example, Explosive_1 and Explosive_2), the player can cycle between them using the mouse wheel; the UI displays the count for each subtype.

Integration with states

When opening/using WB_GrenadeTypes_List, the CharacterStates.Weapons.SwitchGrenadeType state is typically activated to:

• avoid conflicts with other weapon actions during selection,
  
• synchronize the selected grenade type between client and server.

There is no separate UI systems file dedicated solely to grenades yet, so this document only covers grenade UI in terms of type selection and quantities.

Limitations and Design Notes

Important limitations to explicitly state:

• No trajectory preview/arc: grenades are thrown “by feel” based on animation, without a trajectory marker.
  
• No “cook” mode: detonation is driven by Detonation Delay and/or ActivateByHit, not by holding the grenade.
  
• No shrapnel simulation or complex ballistic fragment modeling: the system uses damage zones and basic material penetration instead.
  
• Destruction is limited to building-system structures and actor health logic; there is no full, global physical destruction of the entire world.

Related Docs

The grenade system is closely connected with the following subsystems and documentation files:

• docs/systems/inventory-equipment/inventory-and-equipment.md — grenade storage, stacks, and usage from inventory.
  
• docs/systems/firearms/firearms-system.md — shared damage system, interaction with armor and BP_DamageTypeMaster.
  
• docs/systems/stats/stats-and-survival-system.md — periodic damage (poison/gas) and impact on character stats.
  
• docs/systems/ai/ai-combat-and-behavior.md — AI reaction to grenade loudness and explosion radius.
  
• docs/systems/vehicles/vehicles-system.md and docs/systems/interaction/interaction-and-items.md — damage to vehicles and interaction with the environment.
  
• docs/reference/reference-data-tables.md — item and Clarification assets for grenade types.