> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rathforge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# forge-health

> The player health lifecycle: a themed downed screen and a give-up respawn over native health.

`forge-health` owns the **player** health lifecycle on top of [forge-combat](/packages/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](/packages/forge-gameplay-rules).

NPC death stays with combat and loot; only players are routed here.

## What it does

At character activation it:

1. **Tracks the player** so their death routes to the downed screen (not to loot).
2. **Binds the native death/downed/revived delegates** to forge-combat events, retrying until the
   pawn exists (activation race).
3. **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.

<Warning>
  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.
</Warning>

## 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. |

```lua theme={null}
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

```lua theme={null}
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

* [forge-combat](/packages/forge-combat), the native-backed HP and damage driver underneath.
* [forge-gameplay-rules](/packages/forge-gameplay-rules), how the downed/respawn rules are toggled.