Health, Shields & Energy

USKHealthComponent · USKShieldComponent · USKEnergyComponent

Three components, each independent. Health is on every pawn; shields and energy are optional and can be left off entirely. Nothing breaks when a component is missing — the systems that would have used it simply behave as though the resource is infinite or absent.

Incoming damage is routed in a fixed order. Knowing it explains most "why didn't that hurt" questions:

Health

Property	Default	Purpose
Max Health	100	Starting and maximum hit points.
Faction	Neutral	Which team this pawn is on. Projectiles pass straight through matching factions.
God Mode	Off	Blocks all damage permanently — shield and health both untouched. Doubles as an accessibility option.
Ignore Damage Off Screen	On	Ignores damage while the owner is past the top or bottom of the view.
Off Screen Damage Margin	0	Extra distance past the edge before damage stops registering.

Functions

Function	Purpose
Heal	Restores health, capped at maximum. Ignored on a dead pawn.
Reset Health	Restores Max Health to its authored value and fills to full. Safe on dead pawns.
Override Max Health	Sets a new maximum for this spawn only — used by wave and spawn-point health overrides. The baseline is untouched, so the next reset restores the original.
Reinitialise	Re-establishes the baseline and fully heals, clearing any invulnerability. Used on pool reuse.
Force Kill	Sets health to zero and fires the death event. Bypasses every damage guard.
Activate Invulnerability	Blocks damage for a number of seconds. A duration of 0 does nothing — for permanent immunity use God Mode.
Hold Invulnerable	The untimed version: immune until toggled back. Used for "immune until an event", such as a boss during its entrance.
Set God Mode	Toggles God Mode at runtime.

Events

Event	Fires
On Damaged	Damage actually landed on health, with the amount and causer.
On Death	Health reached zero.
On Health Changed	Any change at all — damage, healing, reset, override. This is the one to bind a health bar to.
On Invulnerability Changed	Immunity turned on or off. Drives the blinking feedback.

Shields

A regenerating buffer in front of health. Add the component to a pawn to give it one; leave it off and damage goes straight to health.

Property	Default	Purpose
Max Shield	100	Capacity of the buffer.
Start Shield Percent	50	How full it is at spawn. Starting partial gives the player something to regain rather than only something to lose.
Shield Regen Rate	2.5	Points restored per second once regeneration resumes.
Regen Energy Cost Per Point	10	Energy spent per shield point regained. This is what makes shields and weapons compete for the same generator.
Regen Delay After Hit	1	Seconds of no regeneration after taking a hit, so a shield cannot tank sustained fire.

An absorbed hit still fires the health component's damage event so hit feedback plays, but the pawn deliberately does not squash, flash or shake — the shield's own effect slots below carry that job instead, which is what makes an absorbed hit look different from a real one.

Feedback

Property	Fires
Shield Hit Effect / Sound	Every absorbed hit. The Niagara system is attached to the pawn, so it follows the ship.
Shield Break Effect / Sound	The moment the shield drops to zero.

Functions

Function	Purpose
Absorb Hit	Offers damage to the shield. Returns true if it was absorbed. Called by the damage router — you rarely call it yourself.
Add Shield	Restores points. What a Shield pickup calls.
Refill To Start Percent	Resets to the spawn level. Used on respawn.
Is Up	True while the shield holds at least one point.

Energy

A regenerating generator that energy-costed weapons draw from, and that shields spend to rebuild themselves. It is the resource that forces a choice between shooting and staying protected.

Property	Default	Purpose
Max Energy	100	Capacity.
Regen Rate	40	Energy per second restored.
Regen Delay	0	Seconds after spending before regeneration resumes. 0 regenerates continuously.

Two ways to spend

Function	Behaviour
Consume Energy	All or nothing. Returns false and spends nothing if the full amount isn't available — the weapon simply doesn't fire.
Drain Energy	Spends up to the amount available. Used by the front gun, which is never blocked.
Has Energy	Tests availability without spending.
Refill To Full	Instantly tops up. Used on respawn.

Ammo

Ammo has no component of its own — it belongs to the weapon that uses it, so two ammo weapons on the same ship keep separate supplies. Capacity, cost per volley and trickle refill are set on the weapon asset and are covered under Weapons.

An Ammo pickup refills ammo-costed weapons, and the game mode's emergency ammo drop watches whichever mount is running lowest. See Pickups & Drops.

Showing them on the HUD

Each component broadcasts a change event carrying the current and maximum value. Bind the matching HUD update function and pass the percentage to a resource bar — the whole wiring is one node per resource. See HUD & UI.

Where next