forge-health owns the player health lifecycle on top of forge-combat’s
native provider. It does not neutralize native health, native owns death, downed and respawn. This
package layers a themed FORGE downed screen and a give-up respawn on top, and configures the
downed/respawn rules through forge-gameplay-rules.
NPC death stays with combat and loot; only players are routed here.
What it does
At character activation it:
- Tracks the player so their death routes to the downed screen (not to loot).
- Binds the native death/downed/revived delegates to forge-combat events, retrying until the
pawn exists (activation race).
- Applies the world health rules once (via forge-gameplay-rules), using the live player
controller as the world context: downed on, AutoRespawn on, native downed widget off.
Then, driven by forge-combat events:
forge-combat:server:downed → show the FORGE downed screen (forge-health:client:death).forge-combat:server:revived (teammate healed past the threshold) → hide it.forge-combat:server:died (bleed-out, give-up, lethal) → hide it; native AutoRespawn returns the
player at the nearest start.
The give-up respawn
The downed screen’s “Respawn now” button gives up: it deals a lethal finishing hit so the downed
state ends in death, and native AutoRespawn brings the player back.
forge-health never calls RespawnPlayerBy*AtTransform directly. That manual path re-initializes
native inventory on a fresh pawn and currently crashes (HInventorySystemTypes.cpp:43). Giving up
and letting native AutoRespawn handle it is the safe path. A custom respawn location is a
follow-up once that platform path is safe.
Exports
| Export | Signature | Purpose |
|---|
Respawn | Respawn(character_id) | force-respawn a downed player now (lethal finish → native AutoRespawn). Drive your own downed UX with this. |
exports["forge-health"]:Respawn(cid) -- give up: finish + native respawn at the nearest start
Events
Consumed (from forge-combat): downed, revived, died. Consumed from characters:
forge-characters:server:activated / :deactivated. Client round-trip:
| Event | Direction | Meaning |
|---|
forge-health:client:death | server → client | open the downed screen |
forge-health:client:respawn_done | server → client | close the downed screen |
forge-health:server:respawn_request | client → server | ”Respawn now” clicked → give up |
Configuration
Config = {
Enabled = true,
Rules = {
DownedEnabled = true, -- bleed-out downed state at 0 HP (revivable) instead of instant death
AutoRespawn = true, -- native owns respawn; "Respawn now" gives up → native respawns
ShowDefaultUI = false, -- hide the native downed widget; the FORGE downed screen is the UI
DownedDuration = nil, -- native default 300s bleed-out
DownedReviveRatio = nil, -- native default 0.5 (heal to 50% to revive)
},
}
nil leaves the native default. Rules are applied once when the ruleset component is up (first
activation, when a live controller exists as the world context), then retried quietly until they take.
See also
