Stats and Survival System

This document describes the character stats and survival layer in RPG Engine v6.
It covers Health, Energy, Hunger, Thirst, Temperature, Contamination/Hygiene, Breath, Smell, and explains how they interact with damage, armor, buffs, and skills.

Core Components

BP_StatsComponent — main component that stores and updates all survival stats over time.
BP_GameState + WorldSettings data asset — defines global world parameters such as GlobalTemperaturesRange.
Buff/Skill systems — modify stat values, regeneration rates, and incoming/outgoing damage, but are documented separately.

All survival updates are driven by timers inside BP_StatsComponent, which apply regeneration and damage ticks according to configurable parameters.

Health

Health model

Health is the primary life stat:

Health — current health value.
HealthMaximal — maximum health; the effective range is 0–100.

Health is reduced by incoming combat damage and survival penalties (starvation, thirst, extreme temperature, breath holding, poisoned water, and similar effects).
When Health reaches 0, normal death/respawn logic applies (defined in the character and respawn systems).

Health regeneration

Health has built-in regeneration controlled by BP_StatsComponent:

HealthRegenerationDelta — how much Health is restored per regeneration tick.
HealthRegenerationFrequency — how often Health regeneration ticks.

If survival conditions allow regeneration, Health is increased by HealthRegenerationDelta every HealthRegenerationFrequency seconds until it reaches HealthMaximal.
When some survival stats reach critical values (for example, Hunger or Thirst at 0), Health regeneration is disabled and replaced by damage-over-time.

Energy

Energy model

Energy is the stamina-like resource used by movement and combat:

Energy — current value stored in BP_StatsComponent.
In documentation and code it is referred to as Energy, not Stamina.

Energy is consumed by high-effort actions such as sprinting and melee attacks.
If Energy is depleted, actions that require it can be restricted or feel heavier (movement/melee systems define the exact behavior).

Energy consumption and regeneration

Energy consumption while running:

EnergyConsumingDelta — how much Energy is consumed per tick during sprinting.
EnergyConsumingFrequency — how often Energy consumption ticks while sprinting.

Energy regeneration:

EnergyRegenerationDelta — how much Energy is restored per tick when regeneration is allowed.
EnergyRegenerationFrequency — how often Energy regeneration ticks.

When the character is idle or performing low-effort actions, Energy regenerates according to the regeneration parameters.
During sprinting or melee combat, Energy decreases over time and regeneration is paused or reduced until high-effort actions stop.

Hunger and Thirst

Shared model

Hunger and Thirst are survival stats that continuously decrease over time and through actions:

Hunger — 100 means fully fed, 0 means starving.
Thirst — 100 means fully hydrated, 0 means dehydrated.

Both stats move from 100 down to 0. There is no special “comfort subrange”; the whole 0–100 interval is valid, with 0 treated as the critical state.
Food and drinks (usable items) restore Hunger and Thirst; their setup is described in the usable-items documentation.

Hunger effects

When Hunger reaches 0:

Health regeneration is turned off.
A periodic starvation damage is applied to Health using:
- HungerDamageDelta — damage per tick caused by starvation.
- HungerDamageFrequency — how often starvation damage ticks.

While Hunger remains at 0, Health will continue to decrease with the configured frequency until the player eats and raises Hunger above 0.
Other survival damage sources can stack on top of starvation damage.

Thirst effects

When Thirst reaches 0:

Health regeneration is turned off.
A periodic dehydration damage is applied to Health using:
- ThirstDamageDelta — damage per tick caused by dehydration.
- ThirstDamageFrequency — how often dehydration damage ticks.

Thirst uses its own frequency and delta, allowing dehydration to be tuned separately from starvation.
Dehydration damage works alongside other survival effects and is processed by the same timer system in BP_StatsComponent.

Temperature

Temperature model

Temperature is represented as a single float stat in BP_StatsComponent:

Temperature — current body temperature.

Global world limits for temperature are defined in the game state:

BP_GameState.WorldSettings → GlobalTemperaturesRange (float range) — minimum and maximum global temperature range.

Inside BP_StatsComponent, a safe range is configured:

NoDamageTemperatureRange — float range of body temperature where no temperature-based damage is applied.

Clothing and environment

Clothing and armor affect body temperature through the Impact on Temperature parameter in their Clarification assets:

Positive Impact on Temperature raises body temperature.
Negative Impact on Temperature lowers body temperature.

Examples:

On a cold map, equipping warm clothing (with positive impact) helps keep Temperature inside NoDamageTemperatureRange.
On a hot map, lighter clothing with negative impact can prevent overheating by lowering Temperature.

Environment and world settings (such as map climate) shift the baseline temperature using GlobalTemperaturesRange and level-specific logic.

Temperature damage

When Temperature goes outside the safe range defined by NoDamageTemperatureRange, BP_StatsComponent starts applying periodic damage:

TemperatureDamageDelta — damage per tick caused by being too cold or too hot.
TemperatureDamageFrequency — how often temperature damage ticks.

Temperature damage affects Health directly and does not consume Energy.
The damage continues until Temperature moves back into the safe range, typically by changing clothing, environment, or both.

Contamination / Hygiene

Contamination model

Body contamination (hygiene) represents how dirty the character is.
Higher contamination makes the character easier to sense via the smell system for other players.

Key points:

Contamination grows over time and due to specific actions (moving through dirty environments, lack of hygiene, etc.).
Contamination is reduced by hygiene actions such as taking a shower.
The exact variable name and numeric range are stored in BP_StatsComponent and can be tuned without code changes.

Contamination itself does not apply direct damage or classic stat penalties; its main gameplay impact is through smell-based detection.

Smell visualization

Smell intensity is visualized with a Niagara effect called Smell Sensation:

Several orange wavy lines rise upward from the character.
The stronger the smell (higher contamination), the brighter and longer these particles appear.

Smell Sensation is only visible when a character is in a special smell detection mode (for example, while using a Smell-related skill).
Under normal conditions, other players do not see smell particles.

Breath and Swimming

Breath model

Breath is used for underwater and breath-holding situations.
While the character is holding their breath (for example, underwater), the available air gradually runs out.

When air is exhausted, suffocation damage is applied to Health using:

BreathHoldingAirDamageDelta — damage per tick when the character has no air left.
BreathHoldingAirDamageFrequency — how often suffocation damage ticks.

Breath capacity is independent of Energy, Hunger, and Thirst; those stats influence other survival aspects but do not change maximum breath time directly.
Swimming and underwater movement systems decide when the character is considered to be holding breath.

Poisoned Water

Poisoned or contaminated water can apply a damage-over-time effect to Health after the character drinks or is otherwise exposed to unsafe water sources.

Key parameters:

Poison By Water Damage Time — total duration of the poison effect.
Poison By Water Damage Frequency — how often poison damage ticks during that duration.

Poisoned water damage affects only Health; it does not directly modify Hunger or Thirst values, but it represents a survival risk associated with using unsafe resources.

Smell System

Smell detection

The smell system connects contamination to detection by other players:

Higher contamination values create a stronger smell signal.
Smell is used only between players and smell-related abilities; AI does not use smell detection.

Players who activate smell detection (through the Smell skill or similar mechanics) can see Smell Sensation particles above smelly characters.
This makes it easier to track or avoid players who have neglected hygiene.

To reduce smell and contamination, characters can perform hygiene actions, such as taking a shower in an appropriate interaction zone.

Integration with skills

Smell is integrated with UnusualSkills and the skill tree:

Smell-related skills control when smell detection mode is active.
While active, they enable smell visualization and increase effective detection range for smelly targets.

Skill and UnusualSkills documentation provides detailed configuration of these abilities and their UI.
The survival system simply exposes contamination and smell intensity as a data source for those skills.

Periodic Updates and Timers

All survival stats and survival-related damage are updated periodically inside BP_StatsComponent using timers.
The main configurable parameters are:

Health:

HealthRegenerationDelta / HealthRegenerationFrequency — Health regeneration ticks (when allowed).

Energy:

EnergyConsumingDelta / EnergyConsumingFrequency — Energy consumption while sprinting.
EnergyRegenerationDelta / EnergyRegenerationFrequency — Energy regeneration in rest/low-effort states.

Hunger and Thirst:

HungerDamageDelta / HungerDamageFrequency — starvation damage when Hunger is 0.
ThirstDamageDelta / ThirstDamageFrequency — dehydration damage when Thirst is 0.

Temperature:

TemperatureDamageDelta / TemperatureDamageFrequency — damage from being outside NoDamageTemperatureRange.

Breath holding:

BreathHoldingAirDamageDelta / BreathHoldingAirDamageFrequency — suffocation damage when the character runs out of air.

Poisoned water:

Poison By Water Damage Time / Poison By Water Damage Frequency — duration and tick frequency for poisoned water damage.

By tuning these values, designers can quickly adjust how harsh or forgiving the survival experience is without modifying Blueprint logic.

Damage Pipeline and Interactions

The global damage pipeline combines survival stats, armor, buffs, skills, and item configuration:

Base damage creation
A damage source (weapon, grenade, environment, poison, survival effect) produces a base damage value and a damage type.
Outgoing damage modifiers (attacker)
Before damage is applied, the attacker’s weapon components, learned skills, and active buffs can increase outgoing damage.
Incoming damage modifiers (target)
The target’s skills and buffs can reduce incoming damage (resistances, shields, debuffs on attackers, etc.).
Armor interaction
Armor processes the modified damage:
- Armor class and damage type rules decide how much damage is absorbed or blocked.
- GrenadeDefense and bullet-design tags allow armor to specialize against specific damage categories.
- If armor durability is depleted or the hit zone is unprotected, damage passes directly to Health.
Final Health change
The final damage value is applied to the target’s Health.

Survival penalties (Hunger=0, Thirst=0, extreme Temperature, Breath holding, poisoned water) bypass armor in most cases and are applied directly as damage-over-time to Health.
All survival and damage calculations run on the server, keeping the stats and survival layer fully server-authoritative in multiplayer.

The stats and survival system is closely connected with:

docs/systems/inventory-equipment/inventory-and-equipment.md — items that restore Hunger and Thirst or apply buffs and debuffs.
docs/systems/firearms/firearms-system.md — damage pipeline, armor interaction, and damage types.
docs/systems/grenades/grenades-system.md — grenade damage and armor classes that affect grenade protection.
docs/systems/customization/character-customization.md — clothing and armor that change Impact on Temperature and survival behavior.
docs/systems/ai/ai-combat-and-behavior.md — how AI engages the player, indirectly influenced by survival state.
docs/systems/save-load/save-load-and-sessions.md — saving and restoring survival stats and active buffs.
docs/reference/reference-data-tables.md — global stats configuration, temperature ranges, and world settings.