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

# Players: death state

> Downed and dead states, injuries, revive and respawn.

<Badge color="blue">Server</Badge> Part of [Players](/api/players).

## Death state

See the [Death system](/concepts/death-system) for states, rules and the downed flow.

### Read

```lua theme={"dark"}
UgCore.Players.GetDeathState(source) -> 'Alive' | 'Downed' | 'Dead'
UgCore.Players.IsDead(source) -> boolean
UgCore.Players.IsDowned(source) -> boolean
UgCore.Players.GetInjuries(source) -> UgInjury[]
UgCore.Players.GetCauseOfDeath(source) -> UgCauseOfDeath?
```

<ResponseField name="UgInjury" type="table">
  <Expandable title="fields">
    <ResponseField name="region" type="UgBodyRegion" />

    <ResponseField name="category" type="UgDamageCategory" />

    <ResponseField name="weapon" type="integer?">Weapon hash of the last hit.</ResponseField>
    <ResponseField name="attacker" type="integer?">Player source of the last hit, when confirmed.</ResponseField>

    <ResponseField name="hits" type="integer" />

    <ResponseField name="lastAt" type="integer">Unix seconds.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="UgCauseOfDeath" type="table">
  <Expandable title="fields">
    <ResponseField name="region" type="UgBodyRegion" />

    <ResponseField name="category" type="UgDamageCategory" />

    <ResponseField name="weapon" type="integer?" />

    <ResponseField name="killer" type="integer?">Only when a recorded `weaponDamageEvent` confirms it.</ResponseField>
    <ResponseField name="at" type="integer">Unix seconds.</ResponseField>
  </Expandable>
</ResponseField>

### Change

```lua theme={"dark"}
UgCore.Players.ClearInjuries(source, region?) -> ok, errorCode
UgCore.Players.Down(source, cause?) -> ok, errorCode
UgCore.Players.Kill(source, cause?) -> ok, errorCode
UgCore.Players.Revive(source, options?) -> ok, errorCode
UgCore.Players.Respawn(source, coords?) -> ok, errorCode
```

| Function | From | To | Hook |
| - | - | - | - |
| `Down` | `Alive` | `Downed` | `Players:BeforeDown` |
| `Kill` | `Alive`, `Downed` | `Dead` | |
| `Revive` | `Downed`, `Dead` | `Alive`, in place | `Players:BeforeRevive` |
| `Respawn` | `Downed`, `Dead` | `Alive`, at `coords` | `Players:BeforeRespawn` |

<ResponseField name="Revive options" type="UgReviveOptions">
  <Expandable title="fields">
    <ResponseField name="by" type="integer">Player source who revived.</ResponseField>

    <ResponseField name="reason" type="string" />

    <ResponseField name="health" type="integer" default="200">101 to 200.</ResponseField>

    <ResponseField name="clearInjuries" type="boolean" />
  </Expandable>
</ResponseField>

<ResponseField name="coords" type="vector4">Respawn position. Defaults to `respawn.coords` in `config/players.lua`. Respawn always clears injuries.</ResponseField>

```lua theme={"dark"}
-- An ambulance resource, after its own job, item and distance checks
local ok, err = UgCore.Players.Revive(target, { by = source, reason = 'cpr', clearInjuries = false })
```

## Hooks

| Hook | Payload | Cancelling |
| - | - | - |
| `Players:BeforeDown` | `{ source, cause }` | Keeps the player alive. `Down` returns `no_permission`. |
| `Players:BeforeBleedout` | `{ source }` | Keeps the player downed. The bleedout retries later. |
| `Players:BeforeRevive` | `{ source, by, reason, health, clearInjuries }` | `Revive` returns `no_permission`. |
| `Players:BeforeRespawn` | `{ source, coords }` | `Respawn` returns `no_permission`. |

## Enums

| Enum | Values |
| - | - |
| `UgCore.Enums.DeathState` | `Alive`, `Downed`, `Dead` |
| `UgCore.Enums.BodyRegion` | `Head`, `Neck`, `Torso`, `LeftArm`, `RightArm`, `LeftLeg`, `RightLeg`, `Unknown` |
| `UgCore.Enums.DamageCategory` | `Gunshot`, `Stab`, `Blunt`, `Explosion`, `Fire`, `Fall`, `Vehicle`, `Drowning`, `Animal`, `Unknown` |


## Related topics

- [UgCore.Players](/api/players.md)
- [Quickstart](/quickstart.md)
- [Statebags](/developers/statebags.md)
- [Death system](/concepts/death-system.md)
- [Player object](/api/player.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.