External Death Screen

Overview

External mode disables only the bundled death-screen NUI and its focus handling. Sky Ambulancejob continues to own the death state, persistence, bleed-out timer, dispatch requests, AI Medic requests, respawn rules, reconnect handling, death causes, injuries, and revives.

An external death-screen resource is responsible for presentation and user input. It should read the published state and request supported actions instead of creating a second death system.

Job Configurator Setup

Use the following path:

/jobconfig → Ambulance Jobs → Settings → Death Screen → General → Integration → Screen Mode → External → Save

Changes saved through the Job Configurator apply live. A resource restart is not required.

Recommended Integration Flow

1. Call getDeathState() when the external resource starts.
2. Listen to sky_ambulancejob:deathStateChanged for complete state snapshots.
3. Replace the external UI state whenever a new snapshot arrives.
4. Use requestDeathAction() for dispatch, respawn, and AI Medic actions.
5. Hide the external UI when state.dead becomes false.

Do not maintain a second authoritative timer or death state. Use remainingSeconds for display and the availability fields to enable or disable actions.

Client Death State

getDeathState()

Returns a complete snapshot for the local player. The export is registered in both internal and external screen modes.

local state = exports["sky_ambulancejob"]:getDeathState()

Example snapshot:

{
    dead = true,
    phase = "downed",
    screenMode = "external",
    handlingMode = "natural",
    bodyStable = true,
    deathTimestamp = 1786788000,
    remainingSeconds = 420,

    canRespawn = false,
    respawnBlockedReason = "timer_active",

    canRequestDispatch = true,

    canRequestAiMedic = false,
    aiMedicBlockedReason = "timer_active",
    aiMedicState = "idle",
    aiMedicReason = nil,

    cause = {
        category = "vehicle",
        weaponHash = 0,
        attackerServerId = nil
    }
}

Death State Fields

Death Phases

Respawn Blocked Reasons

AI Medic State

The standard AI Medic lifecycle uses these states:

AI Medic Blocked Reasons

Death Cause

When available, state.cause contains:

{
    category = "vehicle",
    weaponHash = 0,
    attackerServerId = nil
}

Pending AI Medic Offer

When a remote AI Medic offer is waiting for the player, the client snapshot additionally contains:

state.aiMedicOffer = {
    pending = true,
    dispatcherName = "Alex",
    remainingSeconds = 25
}

The object is omitted when no offer is pending.

Death State Event

sky_ambulancejob:deathStateChanged

This local client event publishes the same complete snapshot as getDeathState(). Use it for UI updates instead of polling every frame.

AddEventHandler("sky_ambulancejob:deathStateChanged", function(state)
    if not state.dead then
        -- Hide the external death screen.
        return
    end

    -- Show or update the external death screen.
    -- Display state.remainingSeconds.
    -- Use the canRequest* fields to control action buttons.
end)

Call getDeathState() once during resource startup because an external resource can start after the current death began and therefore may not have seen the first event.

Requesting Death Actions

requestDeathAction(action, payload?)

Requests an action for the local player. Sky Ambulancejob validates the current death state, timers, prices, medic availability, cooldowns, and all other restrictions.

local success, result = exports["sky_ambulancejob"]:requestDeathAction(action, payload)

Supported actions:

Request a Dispatch

local success, result = exports["sky_ambulancejob"]:requestDeathAction("request_dispatch")

Request an Early Respawn

local success, result = exports["sky_ambulancejob"]:requestDeathAction("request_early_respawn", {
    hospitalId = "pillbox" -- Optional configured hospital ID
})

Request an AI Medic

local success, result = exports["sky_ambulancejob"]:requestDeathAction("request_ai_medic")

Respond to an AI Medic Offer

local success, result = exports["sky_ambulancejob"]:requestDeathAction("respond_ai_medic_offer", {
    accepted = true
})

Set accepted to false to reject the offer.

Action Results

A successful request returns:

true, {
    action = "request_dispatch"
}

A rejected request returns:

false, {
    code = "timer_active",
    message = "The configured waiting time has not elapsed."
}

The code is the machine-readable value intended for program logic. The English message is a developer diagnostic. External UIs should map the code to their own localized user-facing message.

Possible action error codes include:

invalid_action
invalid_payload
player_not_dead
respawn_in_progress
knockout_active
dispatch_disabled
dispatch_already_sent
early_respawn_disabled
timer_active
medics_online
self_respawn_blocked
ai_medic_disabled
body_not_stable
revive_blocked
already_active
on_cooldown
cooldown_active
no_pending_offer
request_blocked_by_hook
request_failed
payment_failed
not_enough_money
disabled
not_dead
remote_wait
target_offline

Simple Client Death Check

Use isDead() when only a boolean is required:

local dead = exports["sky_ambulancejob"]:isDead()

For an external death screen, getDeathState() is normally preferable because it also provides the timer, phase, action availability, and blocked reasons.

Server API

getDeathState(playerId)

Returns the server-authoritative death snapshot for a player. It returns nil for an invalid or offline player.

local state = exports["sky_ambulancejob"]:getDeathState(playerId)

if not state then
    -- Invalid player ID or the player is offline.
    return
end

isDead(playerId)

Use this export when only a server-side boolean is required:

local dead = exports["sky_ambulancejob"]:isDead(playerId)

revive(playerId, reason?)

Revives a player through the normal server-authoritative cleanup and logging path:

local success = exports["sky_ambulancejob"]:revive(
    playerId,
    "external_deathscreen"
)

The reason may also be supplied as a table:

local success = exports["sky_ambulancejob"]:revive(playerId, {
    reason = "external_deathscreen"
})

Internal UI Exports

These client exports belong to the bundled internal death-screen UI:

exports["sky_ambulancejob"]:open()
exports["sky_ambulancejob"]:updateTime(seconds)
exports["sky_ambulancejob"]:addTime(seconds)

They must not be used by an external death-screen integration. In external mode they return:

false, {
    code = "external_deathscreen_active",
    message = "The bundled deathscreen UI is disabled because external mode is active."
}

Read the timer through getDeathState() and request gameplay actions through requestDeathAction().

Authority and Security

The external death screen must not:

• set the player death state itself;
• maintain a separate authoritative bleed-out timer;
• revive the local player directly from client code;
• trigger undocumented internal server events;
• trust a client-provided player ID; or
• bypass requestDeathAction() validation.

Sky Ambulancejob remains authoritative for death state, persistence, respawn, payments, dispatch, AI Medic availability, and revive handling.

Support

When opening an integration support request, include the Sky Ambulancejob version, whether the integration runs on the client or server, the requested action, and the returned error code.