> For the complete documentation index, see [llms.txt](https://coderanch-redm-store.gitbook.io/coderanch-redm-store-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://coderanch-redm-store.gitbook.io/coderanch-redm-store-docs/coderanch-cdeathscreen.md).

# CodeRanch - cDeathScreen

## Requirements

* [cBase](https://github.com/CodeRanchRed/cBase) — must start before cDeathScreen
* A supported framework: VORP, RedemRP, RSG, QBRCore, or standalone

## Installation

{% stepper %}
{% step %}
Place `cBase` and `cDeathScreen` in your resources folder
{% endstep %}

{% step %}
In `server.cfg`:

```lua
ensure cBase
ensure cDeathScreen
```

{% endstep %}

{% step %}
Edit `cDeathScreen/config.lua` to your liking
{% endstep %}

{% step %}
Add your death webhook in `cBase/config.lua`:

```lua
Webhooks = {
    ["deaths"] = "https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE",
}
```

{% endstep %}

{% step %}
*(Optional)* Add your Discord bot token in `cBase/shared/sv_config.lua` for avatar fetching:

```lua
Config.DiscordBotToken = "Bot YOUR_TOKEN_HERE"
```

{% endstep %}
{% endstepper %}

## Config Reference

```lua
Config.LangPreference      = "en"       -- en, tr, ar, fr, it, es
Config.DeathTimerDuration  = 30000      -- ms before auto-respawn fires
Config.DeadHealthThreshold = 10         -- health value considered dead (RDR2 range: 0–200)
Config.RespawnAtHospital   = true       -- false = respawn at death coords
Config.AllowCallForHelp    = true
Config.CallForHelpRadius   = 200.0      -- game units
Config.CallForHelpCooldown = 30         -- seconds between calls
Config.LogDeaths           = true
Config.LogRespawns         = false
Config.DeathLogWebhook     = "deaths"   -- must match a key in cBase Webhooks
Config.FallbackAvatarUrl   = "https://i.pravatar.cc/128?img=8"
```

### Keys (native input hashes)

| Action            | Default | Hash         |
| ----------------- | ------- | ------------ |
| Toggle info panel | J       | `0xF3830D8E` |
| Respawn           | F       | `0xB2F377E8` |
| Call for help     | T       | `0x9720FCEE` |

### Hospital Spawns

Each entry needs `x`, `y`, `z`, `h` (heading), and `label`. The nearest one to the death position is used.

### Map Zones

Each entry needs `name`, `x`, `y`. The closest zone centre to the death position is used as the location label.

## Exports

### Server — `exports["cDeathScreen"]`

```lua
-- Check if a player is downed
exports["cDeathScreen"]:IsPlayerDead(src)  --> boolean

-- Revive a player (spawnPos optional, falls back to nearest hospital)
exports["cDeathScreen"]:RevivePlayer(src, { x, y, z, h })

-- Force open the death screen without the player dying in-world
exports["cDeathScreen"]:ForceOpenScreen(src, {
    killerName = "Unknown",
    deathType  = "Fall Damage",
    location   = "Annesburg",
})

-- Read the current death session (returns nil if not downed)
local s = exports["cDeathScreen"]:GetDeathSession(src)
-- s.killerName, s.deathType, s.location, s.deathPos, s.hospital, s.timeStr
```

### Client — `exports["cDeathScreen"]`

```lua
exports["cDeathScreen"]:IsDead()       -- boolean
exports["cDeathScreen"]:IsScreenOpen() -- boolean
exports["cDeathScreen"]:OpenScreen({ killerName, deathType, location, time, distance })
exports["cDeathScreen"]:CloseScreen()
```

## Quick Integration Examples

**Gate an action while downed (client)**

```lua
if exports["cDeathScreen"]:IsDead() then return end
```

**Medic revive at a custom position (server)**

```lua
exports["cDeathScreen"]:RevivePlayer(targetSrc, {
    x = 1221.07, y = -1326.83, z = 90.47, h = 90.0
})
```

**Custom framework down-state (server)**

```lua
exports["cDeathScreen"]:ForceOpenScreen(src, {
    killerName = data.attacker,
    deathType  = data.cause,
    location   = data.area,
})
```