plugMedical Listeners

Medical listener hooks and lifecycle payloads for 0r-ambulancejob

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

circle-exclamation

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:

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

Client Examples

Play a custom effect on laststand

React only to hospital respawn

Server Examples

Log revive source and target

Trigger another resource only for EMS revives

Handle all recovery paths from one place

Listen for paid facility invoices

Example Payloads

Revive

Death

Respawn

Billing Invoice Paid

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.

Last updated