Medical Listeners

MedicalListeners lets you attach custom logic to the medical lifecycle without editing the core encrypted files.

Files:

modules/medical_listeners/client.lua
modules/medical_listeners/server.lua

Keep listeners non-blocking. Do not use Wait or long loops inside these functions because they can run during death-related flows.

Available Functions#

The listener names below are defined on both client and server:

MedicalListeners.onPlayerRevive(data)
MedicalListeners.onPlayerRecovered(data)
MedicalListeners.onPlayerHeal(data)
MedicalListeners.onPlayerDeath(data)
MedicalListeners.onPlayerLaststand(data)
MedicalListeners.onPlayerRespawn(data)
MedicalListeners.onPlayerSpawn(data)
MedicalListeners.onPlayerDeathStateChange(data)
MedicalListeners.onBillingInvoiceCreated(data)
MedicalListeners.onBillingInvoicePaid(data)
MedicalListeners.onBillingInvoiceCancelled(data)
MedicalListeners.onBillingExternalPaymentReceived(data)

Emission Notes#

Currently emitted on both client and server:

onPlayerRevive
onPlayerRecovered
onPlayerDeath
onPlayerLaststand
onPlayerDeathStateChange

Currently emitted client-side only:

onPlayerHeal
onPlayerRespawn
onPlayerSpawn

Server-side functions for the client-only entries can still exist safely, but the current core does not emit those three listener names on the server.

Currently emitted server-side only:

onBillingInvoiceCreated
onBillingInvoicePaid
onBillingInvoiceCancelled
onBillingExternalPaymentReceived

Listener Semantics#

`onPlayerRevive`#

Triggered when a downed player is revived back to alive. Use this for revive-specific integrations.

`onPlayerRecovered`#

Triggered when a player returns from dead or laststand to alive. This is broader than revive and can include respawn or sync recovery flows.

`onPlayerHeal`#

Triggered on the heal branch. Use this for full-heal integrations that are not tied to death recovery.

`onPlayerDeath`#

Triggered when the player enters dead.

`onPlayerLaststand`#

Triggered when the player enters laststand.

`onPlayerRespawn`#

Triggered when the player respawns through the hospital respawn flow.

`onPlayerSpawn`#

Triggered on framework / game spawn sync points.

`onPlayerDeathStateChange`#

Triggered on every real death-state transition, such as alive->laststand, laststand->dead, or dead->alive.

`onBillingInvoiceCreated`#

Triggered after a facility invoice is created and any external invoice id is saved.

`onBillingInvoicePaid`#

Triggered after a facility invoice is marked paid, facility account deposit is processed, and the facility log is written.

`onBillingInvoiceCancelled`#

Triggered after an unpaid facility invoice is cancelled.

`onBillingExternalPaymentReceived`#

Triggered when the external billing bridge reports payment for a matching invoice. This is emitted before the invoice is marked paid by the bridge callback.

Medical Listener Payload#

Each medical lifecycle listener receives a single data table.

Type:

MedicalListenerPayload

Type file:

modules/types/medical_listeners.lua

Fields:

source
target
previousState
newState
reason
context

Field Descriptions#

source: The actor or source that triggered the action. In command-based revives this can be the admin or EMS player. In local or sync-driven flows this can be the player themselves.

target: The player affected by the medical action.

previousState: The previous medical state. Possible values are alive, laststand, and dead.

newState: The new medical state. Possible values are alive, laststand, and dead.

reason: A short string describing why the listener was triggered.

context: Optional table with extra information about the trigger. The content depends on the flow.

Billing Listener Payload#

Billing listeners receive a billing-specific data table.

Fields:

invoice
source
facility_id
invoice_id
invoice_no
patient_identifier
patient_name
doctor_identifier
doctor_name
amount
reason
status
external_provider
external_invoice_id
context

invoice contains the mapped invoice row, including:

id
facility_id
invoice_no
patient_identifier
patient_name
doctor_identifier
doctor_name
amount
reason
preset_key
status
external_provider
external_invoice_id
paid_at
created_at
updated_at

Billing listener context.action can be created, paid, cancelled, or external_paid.

Reason Constants#

Use the shared constants instead of hardcoding strings when possible:

MedicalListeners.REASONS.ADMIN_COMMAND
MedicalListeners.REASONS.EMS_REVIVE
MedicalListeners.REASONS.NPC_DOCTOR
MedicalListeners.REASONS.HOSPITAL_RESPAWN
MedicalListeners.REASONS.FRAMEWORK_SYNC
MedicalListeners.REASONS.FRAMEWORK_SPAWN_SYNC
MedicalListeners.REASONS.STATEBAG_SYNC
MedicalListeners.REASONS.LOAD_SYNC
MedicalListeners.REASONS.DAMAGE
MedicalListeners.REASONS.ADMIN_DAMAGE
MedicalListeners.REASONS.LASTSTAND_TIMEOUT
MedicalListeners.REASONS.LASTSTAND_CRAWL_LIMIT
MedicalListeners.REASONS.DISCONNECT
MedicalListeners.REASONS.CLIENT_SYNC
MedicalListeners.REASONS.COMPAT_EXPORT

Notes:

The constants table covers the canonical shared reasons.
Some runtime features may pass additional raw reasons such as health_system.

Helper Functions#

These helpers are available in MedicalListeners:

MedicalListeners.isAliveState(state)
MedicalListeners.isDownedState(state)
MedicalListeners.isRecovery(data)
MedicalListeners.isRevive(data)
MedicalListeners.isRespawn(data)
MedicalListeners.matchesReason(data, reason)
MedicalListeners.getTransitionKey(data)

Helper Examples#

if MedicalListeners.isRecovery(data) then
    print(("Recovered via %s"):format(data.reason))
end

if MedicalListeners.matchesReason(data, MedicalListeners.REASONS.NPC_DOCTOR) then
    print("Recovery came from NPC doctor")
end

Client Examples#

Play a custom effect on laststand#

function MedicalListeners.onPlayerLaststand(data)
    if data.reason == MedicalListeners.REASONS.DAMAGE then
        ShakeGameplayCam("SMALL_EXPLOSION_SHAKE", 0.15)
    end
end

React only to hospital respawn#

function MedicalListeners.onPlayerRespawn(data)
    if MedicalListeners.isRespawn(data) then
        print(("Respawned at facility %s"):format(data.context and data.context.facilityId or "unknown"))
    end
end

Server Examples#

Log revive source and target#

function MedicalListeners.onPlayerRevive(data)
    print(("Revive source=%s target=%s reason=%s"):format(
        tostring(data.source),
        tostring(data.target),
        tostring(data.reason)
    ))
end

Trigger another resource only for EMS revives#

function MedicalListeners.onPlayerRevive(data)
    if not MedicalListeners.matchesReason(data, MedicalListeners.REASONS.EMS_REVIVE) then
        return
    end

    TriggerEvent("my-resource:server:onEmsRevive", data.target, data.source)
end

Handle all recovery paths from one place#

function MedicalListeners.onPlayerRecovered(data)
    if MedicalListeners.isRespawn(data) then
        TriggerEvent("my-resource:server:onHospitalRecovery", data.target)
        return
    end

    TriggerEvent("my-resource:server:onGeneralRecovery", data.target, data.reason)
end

Listen for paid facility invoices#

function MedicalListeners.onBillingInvoicePaid(data)
    TriggerEvent("my-resource:server:onMedicalInvoicePaid", {
        invoiceId = data.invoice_id,
        facilityId = data.facility_id,
        patient = data.patient_identifier,
        amount = data.amount,
    })
end

Example Payloads#

Revive#

{
    source = 1,
    target = 24,
    previousState = "dead",
    newState = "alive",
    reason = "admin_command",
    context = {
        from = "commands:adminRevive"
    }
}

Death#

{
    source = 24,
    target = 24,
    previousState = "laststand",
    newState = "dead",
    reason = "laststand_timeout",
    context = {
        from = "laststandTimer"
    }
}

Respawn#

{
    source = 24,
    target = 24,
    previousState = "dead",
    newState = "alive",
    reason = "hospital_respawn",
    context = {
        facilityId = 3,
        respawnPoint = {
            x = 0.0,
            y = 0.0,
            z = 0.0,
            w = 0.0
        }
    }
}

Billing Invoice Paid#

{
    invoice_id = 12,
    invoice_no = "EMS-1-260502101530-0042",
    facility_id = 1,
    patient_identifier = "license:xxxx",
    patient_name = "John Doe",
    amount = 750,
    reason = "Revive",
    status = "paid",
    external_provider = "manual",
    external_invoice_id = "",
    context = {
        action = "paid",
        invoice_id = 12
    }
}

Notes#

context is not a fixed schema. It changes depending on the action.
source does not always mean "the player who revived someone". In sync-based flows it may represent the affected player or system-originated action.
Billing listeners are defined in both client and server files for consistency, but they are emitted server-side only.