Contested Health System

Overview

Contested Health is the white bar that appears over your health bar after you take damage. It acts as a temporary buffer that damage eats before real HP, and can be converted back into real HP by dealing damage (melee or firearm), by class abilities (camo, stims), or by specific weapon perks.

When you take damage, the damage doesn't immediately kill real HP, it's instead "booked" as contested health, which sits on top of your base HP as a temporary buffer. Contested Health fades over time, and further damage eats contested before real HP. You recover real HP by dealing damage while the contested health is still available: each melee strike and firearm hit converts some contested back into real HP, capped by per-damage and per-action limits. Class abilities offer dedicated conversion paths: Medicae Stims, and Sniper's camo cast (with PveSniperPurificationRestoreContestedHealth). Higher difficulties shrink the per-hit conversion cap by up to -50%. Three classes carry perks that directly buff the conversion rate, and several weapon-specific perks double it for particular strikes.

This doc covers the whole contested health system: gain, fade, conversion, caps, and every perk that touches it. For the stims that interact with this system, see this writeup.

Gaining Contested Health

There are three ways to build your contested bar: taking damage (converts real hp to contested hp), the Stim-shot's sustained contested fill (adds contested health on top of existing real HP), and Bulwark's class ability that can restore contested directly (adds contested health on top of existing real HP).

1. Taking damage (converts real HP to contested)

Contested is generated when you take damage. The portion of any incoming damage that gets "booked" as contested (rather than deducted from real HP) is controlled by HEALTH_TRAIL_INITIAL_LENGTH. Default is baseline (unmodified); the main thing that changes it in live play is the PveMutatorNoContestedHealthNoMortalWound mutator, which sets HEALTH_TRAIL_INITIAL_LENGTH -100% PERCENT_MULT (disables the system entirely).

The RestoreHealthTrail status effect (status_effects.sso, duration 0.1s, REFRESH type, uses StatusEffectLogicRestoreHealthTrailServer) is the tiny ticking effect that keeps the trail logic alive when you take hits. It's in the player's vulnerableTo list in pc_marine_pve_server.cls, so it applies to every Space Marine.

This is the universal, always-on source. Every Marine, every class, every difficulty - taking hits produces contested automatically.

2. Stim-granted contested (sustained fill)

The Stim-shot explicitly fills your contested buffer over time via the HealStimAddContestedHealth status effect:

• Duration: 25s, 1.8 tps, REFRESH

• Each tick applies HealingStimContested settings (DamagePointsRestoringHealingUpToValueSettings, addContestedHealthPercent=3, restoreTotalTime=1, healSource="STIMSHOT")

Each tick adds 3% contested (stacks additively). Over the 25s duration, that's 1.8 tps × 25s × 3% = 135% theoretical total, but you're hard-capped at 100% contested by HEALTH_TRAIL_INITIAL_LENGTH. In practice this means:

• Time to fill a full contested bar from zero: ~18.5 seconds (1.8 tps × 18.5s × 3% ≈ 100%)

• The remaining ~6.5s of the 25s duration is buffered - if you take damage and your contested drops, the status continues topping it back up until the 25s runs out

• This works on top of any contested you'd get from taking damage (the status and damage-booking are independent sources)

The DamagePointsRestoringHealingUpToValueSettings type name refers to the per-tick "up to 3%" ceiling (each single tick doesn't try to add more than 3%), not an overall cap on the stim's total contribution - the status continues ticking for the full 25s window.

See this writeup for the Stim-shot equipment details and how the contested fill interacts with the Medicae Stim for wound-clearing.

3. Ability-granted contested (banner, camo)

The Bulwark's class ability can restore contested health directly when a specific perk is equipped. This is event-based (the ability has to be cast/activated) rather than sustained fill.

How Contested Fades

Contested decays over time. The relevant modifier is HEALTH_TRAIL_FADING_SPEED:

• Player base (damagable_survival_module.sso): HEALTH_TRAIL_FADING_SPEED -30% PERCENT_SUM. Player fade is 30% slower than the bare base rate.

• Hard lower-bound cap (modifiers_caps_library.sso): HEALTH_TRAIL_FADING_SPEED percentLowerBound 25%. You can never stack fade-slowdown below 25% of base rate, no matter how many perks you layer.

Perks that slow fade

Converting Contested to Real HP

This is the core mechanic of the system: you recover real HP from contested by dealing damage. Two separate conversion paths exist, controlled by different modifier chains.

Melee conversion (baseline, all classes)

Every melee strike runs the modifier chain from damage_points_restoring_melee_settings_collection.sso plus damage_points_restoring_melee_settings.sso:

• HEALTH_REGEN_BY_HIT - base direct HP regen per hit (flat)

• LIGHT_TAP_HEALTH_REGEN / LIGHT_HOLD_HEALTH_REGEN / HEAVY_TAP_HEALTH_REGEN / HEAVY_HOLD_HEALTH_REGEN - strike-type modifiers on the base regen

• HEALTH_TRAIL_RESTORING_ABSOLUTE - flat contested conversion per hit (all sources)

• HEALTH_TRAIL_RESTORING_MELEE_ABSOLUTE - flat contested conversion per hit (melee specifically)

Combined, every melee strike converts some contested to real HP. The baseline is present on every melee action (LIGHT_TAP, LIGHT_HOLD, HEAVY_TAP, HEAVY_HOLD), plus a CUSTOM hook for weapon-specific strikes.

Base numeric values for the modifiers are set in code (not in the config files), so the exact per-hit conversion in real HP isn't visible here. But the system clearly exists and is always on.

Firearm conversion (baseline for all classes)

Every firearm hit runs the chain from damage_points_restoring_firearm_settings.sso:

baseForHealthRestoring         =   "POINTS_TAKEN_BY_DAMAGE"
healthTrailRestoringPercentModifiers = [ "HEALTH_TRAIL_RESTORING_FIREARM_PERCENT" ]
maxHealthRestorePerDamageModifier   = [ "HEALTH_TRAIL_MAX_RESTORE_PER_DAMAGE",
                                         "HEALTH_TRAIL_TOTAL_MAX_RESTORE",
                                         "HEALTH_TRAIL_TOTAL_MAX_RESTORE_FIREARM" ]

The base is POINTS_TAKEN_BY_DAMAGE (so conversion is proportional to damage dealt), scaled by HEALTH_TRAIL_RESTORING_FIREARM_PERCENT. The baseline value for this modifier is set in compiled code (not visible in the .sso configs) and is nonzero by default for every class - all Space Marines convert contested into real HP by shooting enemies, even without any perks. Class and weapon perks ADD to the baseline rather than enabling it from zero.

The exact baseline percent is not exposed in the config files, but class perks that modify it use PERCENT_SUM additions (e.g. Tactical's PveSoldierHealthTrailRestoreByFirearmDamage +30% PERCENT_SUM), which stack on top of the baseline. The per-hit and per-action caps (HEALTH_TRAIL_MAX_RESTORE_PER_DAMAGE, HEALTH_TRAIL_TOTAL_MAX_RESTORE_FIREARM) are also present for all classes.

Finisher / Execute conversion

Finishers are the fastest and most complete conversion path in the game. The finisher preset (damagable_health_restoring_library_pve.sso, finisherPresets.default) is split into two tables: meleeSettings (melee executions - the big animated finisher, grab finisher, stun finisher) and rangedSettings (gunstrike finishers - when a gunstrike delivers the lethal blow and triggers a finisher).

The two tables have different healing values. The melee table is uniformly strong across all enemy classes; the ranged table is weaker against fodder/common and matches melee against elite+.

Melee finishers (executions, grabs, stun finishers)

Every melee finisher on every enemy type restores healthRestoringPercent=100. Combined with healthTrailAsExtraHealing=100 on the default healing module, this converts your entire contested bar to real HP and adds direct heal on top.

Ranged finishers (gunstrike finishers)

Two key asymmetries vs melee finishers:

• Gunstrike finishers on FODDER/COMMON only give 50% restore, not 100%. A gunstrike-kill on a hormagaunt or cultist restores half the contested-to-HP value that a melee execute on the same enemy would.

• healthRestoringMin floor (present only on ranged finishers): sets a minimum absolute HP restoration regardless of how little contested you have. 0.1 on fodder, 1 on elite+ - so even a low-contested gunstrike finisher on a boss guarantees a small base heal.

• Elite+ gunstrike finishers match melee finisher value (100%).

The finisher preset is applied automatically per kill - no class perk required. Every Space Marine triggers the correct table based on whether the killing hit was melee-class or gunstrike-class.

The meta workflow: Stim-shot at low HP → wait ~18.5s for contested to fill → execute any enemy → full contested bar converts to real HP → incap counter resets (because the Stim-shot is still applying STIMSHOT-source heal ticks while you're meleeing, and at some point one of those ticks crosses 100% real HP). Use a melee finisher, not a gunstrike finisher, if your kill target is fodder/common - the melee version pays 100% where the ranged version pays 50%.

Regular (non-lethal) gunstrikes

A gunstrike that does not kill an enemy triggers the prompt-fired weapon hit, which deals firearm damage tagged as dmg_type_gunstrike. Contested conversion goes through the firearm settings chain (damage_points_restoring_firearm_settings.sso) - the same pipeline as any other firearm hit. Since gunstrikes deal very high damage (weapon-base damage plus large gunstrike multipliers), the proportional contested → real HP conversion is correspondingly large. In practice a single non-lethal gunstrike can convert a significant chunk of contested even without gunstrike-specific healing perks.

Three class perks grant armor-segment restoration on non-lethal gunstrikes (via PerkTriggerGunstrike with enableTriggerOnLethal=False):

These do not directly touch contested - they grant armor - but on a class that stacks this perk plus melee play, each gunstrike gives you armor back on top of the firearm-chain contested conversion.

Caps on conversion

Three cap modifier chains clamp conversion regardless of source:

So a single heavy strike can't convert your entire contested bar at once - there's a per-hit cap, and a per-action cap. Both scale with the perks that scale conversion itself (most perks boost the conversion modifier AND the corresponding total-max modifier by the same percentage, so you don't hit a ceiling mismatch).

Difficulty modifiers on conversion

From difficulty_presets_library.sso, higher difficulties nerf the per-hit cap:

On Lethal and Absolute, each individual hit converts at most half of what a Normal-difficulty hit would. This is a significant reason melee-healing is less reliable at top difficulties even with the same perk setup.

Class Perks Affecting Conversion

General melee conversion (all weapons)

Weapon-specific +100% on certain strikes

These perks apply +100% PERCENT_SUM to both HEALTH_TRAIL_RESTORING_MELEE_ABSOLUTE and HEALTH_TRAIL_TOTAL_MAX_RESTORE_MELEE, but only on specific strike types in the kata (PerkTriggerMeleeStrike gated by strike UID list):

Each of these doubles the conversion on the specified strikes only. Pairing PveBerserkIncreaseHealthTrailRestoring (+50% baseline) with a weapon perk (+100% on specific strikes) gives a 2.5x multiplier on those strikes (+50% on normal strikes).

Firearm conversion perks

Ability-based contested restoration

Specific class abilities can restore contested health directly (not through the damage-dealing conversion path):

Direct kill-triggered HP restoration (adjacent to the system)

These aren't strictly contested conversion - they directly heal real HP on kills, bypassing the trail:

These use PerkApplicationRestoreHealth rather than going through the trail conversion pipeline, so they're immune to difficulty nerfs on HEALTH_TRAIL_MAX_RESTORE_PER_DAMAGE - they always heal their given % of real HP regardless of difficulty.

Practical Notes

• Stim-shot + execute is the fastest way to get back to full HP. Pop a Stim-shot at low HP, let the 25s contested fill run, execute any enemy to cash in the full bar. Great for HP restoration. For wound-clearing, either layer a Medicae Stim onto this or pop the stimshot when you are above 90% health.

• Ranged conversion is usually faster and more consistent than melee, despite the high per-hit melee numbers. Contested fades continuously from the moment you take the damage. Every second you spend closing distance, getting staggered, parrying, dodging, or repositioning is a second of contested decay and no conversion. At range you're just dealing damage, with no risk of interruption and no positioning cost. Even if a single heavy melee strike technically converts more than a single firearm hit, you'll land vastly more firearm hits per second of contested window - and avoid the hits that would eat your contested in the first place. On Lethal/Absolute this gap widens further because melee conversion is penalized by the HEALTH_TRAIL_MAX_RESTORE_PER_DAMAGE -50% difficulty nerf.

• Execute to top off real HP before the contested fades. Contested is fading the entire time. A timely finisher cashes it before the fade robs you. If you're sitting on a big contested bar with no urgent threats, find a fodder kill and melee-finish it - healthRestoringPercent=100 on every threat class in the melee preset.

• Bulwark banner with PveTankContestedHealthForBanner is the best team-wide trail restore. Allies inside the zone recover contested directly, on top of the armor-regen effects. Trades off with 33% slower banner recharge.

• On Lethal/Absolute, expect melee healing to feel half as strong. The -50% per-damage cap means you need more hits per unit of HP recovered. This is on top of the higher enemy damage values at those difficulties - another reason to default to ranged conversion at top difficulty.

Game Files

Server pak ({GAME_FILES_ROOT_SERVER})

• ssl\damage\damagable\damagable_survival_module.sso - Player base survival modifiers: HEALTH_REGEN_BY_HIT, HEALTH_TRAIL_FADING_SPEED, INCAP_TIME_TO_DIE

• ssl\damage\damagable\damage_points_restoring\damage_points_restoring_settings.sso - Top-level wiring of which modifier names apply to health regen vs trail restore

• ssl\damage\damagable\damage_points_restoring\damage_points_restoring_melee_settings.sso - Which modifiers govern melee-based trail conversion (absolute + caps)

• ssl\damage\damagable\damage_points_restoring\damage_points_restoring_melee_settings_collection.sso - Per-strike-type modifier lists (LIGHT_TAP, LIGHT_HOLD, HEAVY_TAP, HEAVY_HOLD, CUSTOM)

• ssl\damage\damagable\damage_points_restoring\damage_points_restoring_melee_preset_pve.sso - PvE melee preset structure

• ssl\damage\damagable\damage_points_restoring\damage_points_restoring_firearm_settings.sso - Firearm-based conversion (HEALTH_TRAIL_RESTORING_FIREARM_PERCENT), base is POINTS_TAKEN_BY_DAMAGE

• ssl\damage\damagable\damage_points_restoring\damagable_health_restoring_library_pve.sso - Where stim-based contested grants live (HealingStimContested)

• ssl\status_effects\status_effect_descriptions\status_effects.sso - RestoreHealthTrail (0.1s REFRESH status to start/refresh fade timer), HealStimAddContestedHealth

• ssl\status_effects\factories\status_effect_logic_factory.sso - StatusEffectLogicRestoreHealthTrailServer, StatusEffectLogicAddContestedHealthServer

• ssl\status_effects\logic\restore_contested_health\status_effect_logic_add_contested_health_server.sso - Server module type

• ssl\player\modifiers\cap_logic\modifiers_caps_library.sso - Hard caps (e.g. HEALTH_TRAIL_FADING_SPEED can't go below 25%)

• ssl\characters\player\marine\pc_marine_pve_server.cls - Player PvE vulnerability list (includes RestoreHealthTrail and HealStimAddContestedHealth)

• ssl\game_mode\difficulty_system\difficulty_presets_library.sso - Per-difficulty HEALTH_TRAIL_MAX_RESTORE_PER_DAMAGE penalties

• ssl\player\mutators\game_mutators_factory.sso - PveMutatorNoContestedHealthNoMortalWound (strips the system via HEALTH_TRAIL_INITIAL_LENGTH -100%)

• ssl\player\perks\perk_server_factory.sso - All class perks that touch the trail system