esx_death

esx_death is the global death system for ESX Legacy. It shows a branded death screen when a player dies, persists the dead state in the database, runs the early-respawn and bleedout timers, applies respawn penalties and exposes exports to revive players. esx_ambulancejob builds on it for EMS revives and distress calls.

OverviewCopy Anchor Link

How it worksCopy Anchor Link

1. es_extended detects the death on the client and triggers esx:onPlayerDeath (client and server) with killer data.
2. esx_death stores is_dead = 1 and death_time (unix seconds), sets the isDead state bag and opens the death screen.
3. After Config.EarlyRespawnTimer the player can hold E for Config.HoldDuration ms to respawn at the closest Config.RespawnPoints entry. Respawning before the bleedout ends costs Config.EarlyRespawnFineAmount from the bank when Config.EarlyRespawnFine is enabled.
4. When the bleedout timer (EarlyRespawnTimer + BleedoutTimer) runs out, the client respawns automatically without a fine.
5. On respawn the configured penalties remove items, cash, black money and weapons. A revive (EMS, admin, txAdmin) keeps everything.

Death screen controlsCopy Anchor Link

Chat (T) and push-to-talk stay enabled. All other controls are disabled while dead.

InstallationCopy Anchor Link

ALTER TABLE `users` ADD COLUMN `is_dead` TINYINT(1) NOT NULL DEFAULT 0;
ALTER TABLE `users` ADD COLUMN `death_time` BIGINT NULL DEFAULT NULL;

set onesync on
ensure esx_lib
ensure es_extended
ensure esx_death
ensure esx_ambulancejob

ConfigurationCopy Anchor Link

Default respawn points:

Config.RespawnPoints = {
    { coords = vector3(341.0, -1397.3, 32.5), heading = 48.5 },     -- Central Los Santos
    { coords = vector3(1836.03, 3670.99, 34.28), heading = 296.06 } -- Sandy Shores
}

Server exportsCopy Anchor Link

IsDeadCopy Anchor Link

exports.esx_death:IsDead(playerId) --> boolean

Returns true if the cached state of the player is dead. Returns false for players whose state is not loaded yet.

GetDeathStateCopy Anchor Link

exports.esx_death:GetDeathState(playerId) --> table | nil

Returns a snapshot or nil when no state is cached:

GetDeadPlayersCopy Anchor Link

exports.esx_death:GetDeadPlayers() --> { [playerId] = 'dead' | 'distress' }

GetDeadPlayerLocationsCopy Anchor Link

exports.esx_death:GetDeadPlayerLocations() --> { [playerId] = { x, y, z } }

ReviveCopy Anchor Link

exports.esx_death:Revive(playerId, reason?) --> ok, wasDead

Revives in place, keeps the inventory, sets hunger and thirst to 500000 through esx_status:set and clears the dead flag in the database. Returns false, false if the player was not dead.

local ok = exports.esx_death:Revive(targetId, 'mymedic')

if ok then
    TriggerClientEvent('esx:showNotification', targetId, 'You have been revived.')
end

SetDeadCopy Anchor Link

exports.esx_death:SetDead(playerId) --> boolean

Marks a player as dead in the database and syncs the death screen to that client. This does not kill the ped; use it together with your own logic.

Client exportsCopy Anchor Link

exports.esx_death:IsDead() --> boolean
exports.esx_death:GetDeathState() --> { dead, earlyRemaining, remaining, distressRemaining }

The server also sets the replicated state bag isDead, so LocalPlayer.state.isDead (client) and Player(src).state.isDead (server) work without exports.

EventsCopy Anchor Link

Server events (local)Copy Anchor Link

AddEventHandler('esx_death:stateChanged', function(playerId, dead, reason)
    if dead then
        print(('Player %s died'):format(playerId))
    elseif reason == 'respawn' then
        print(('Player %s respawned at a hospital'):format(playerId))
    end
end)

Client events (local)Copy Anchor Link

On recovery esx_death also fires esx:onPlayerSpawn (client and server), playerSpawned and esx_basicneeds:resetStatus.

Net events and callbacks (security)Copy Anchor Link

CommandsCopy Anchor Link

The txAdmin "Heal" action (txAdmin:events:healedPlayer) revives the player, or everyone when txAdmin heals all.

Integration tipsCopy Anchor Link

• Block actions while dead (shops, phones, inventories) with LocalPlayer.state.isDead on the client and exports.esx_death:IsDead(source) on the server.
• Use Revive instead of calling NetworkResurrectLocalPlayer yourself; otherwise the database still says dead and the player is restored as dead on the next login.
• To change who gets alerted on distress, listen to esx_death:distress in your own dispatch resource.

Common issuesCopy Anchor Link

• SQL error about is_dead on start: the users table lacks is_dead/death_time and Config.AutoMigrate is off. Run esx_death.sql.
• Two death screens or instant respawn: another death or revive script is still running. Only esx_death should handle death.
• Weapons not removed with ox_inventory: with ox_inventory, weapons are items. Use Config.RemoveItemsAfterRPDeath instead of the weapons option.
• Player respawns dead after relog: expected when they logged out while dead. Revive them or let the timer run out.

RelatedCopy Anchor Link

• esx_ambulancejob
• esx_basicneeds
• Client events
• Commands
• OneSync functions

Frequently asked questions