Installation

6 min readUpdated 2 weeks ago

Overview

ML HealthSystem is a medical and survival system with per-body-part injury tracking, bleeding, fractures with bone-attached 3D casts, a last-stand and death cycle with a respawn selector, blood types with a transfusion compatibility matrix, staged diseases with player-to-player contagion, and an optional life-points permadeath layer. Live medical state is synced to nearby players in real time; only persistent data is written to the database.

Framework, inventory, target, notify, and progressbar are resolved through ml_bridge and detected at runtime.

Quick Start

  1. Extract the resource into your resources folder as ml_healthsystem.
  2. Copy the items from _INSTALL/ox_items.txt into your inventory resource, and drop the icons from _INSTALL/images/ into ox_inventory/web/images/.
  3. Add the ensure block to server.cfg:
server.cfg
1ensure ox_lib
2ensure oxmysql
3ensure ml_bridge
4ensure ml_healthsystem
  1. Start the server. Database tables are created on first run.
Load Order

ml_healthsystem must start AFTER ml_bridge, ox_lib, and oxmysql. The dependencies are declared in fxmanifest.lua, but the ensure order in server.cfg must still place the bridge first.

Database

Auto Import

The enabled tables are created with CREATE TABLE IF NOT EXISTS on first startup. There is no SQL file to run manually.

  • ml_healthsystem: persisted medical state per player. One row per identifier, with a health_data LONGTEXT column (injuries, blood, fractures, diseases serialized to JSON).
  • ml_health_tents: player-placed respawn tent positions (identifier, coords, heading, label).
  • ml_lifepoints: life-points balance per identifier. Only created when Config.LifePoints.Enabled is true.
Live state, not the database

Active injuries, bleeding, blood level, and disease stages are kept live during a session and replicated in real time. The ml_healthsystem table is the persistence snapshot, not the live source of truth.

Items

_INSTALL/ox_items.txt contains the medical items, respawn tent and optional zombie antidote definitions. Copy the needed entries into ox_inventory/data/items.lua. Item names must match Config.MedicalItems, Config.RespawnTent.Item and, when enabled, Config.ZombieTransformation.Cure.Item. The script binds item use through ML Bridge. The antidote is only used when its optional cure is enabled.

The shipped item keys are English:

Bandages / Dressings

  • crafted_gauze: Crafted Gauze
  • field_dressing: Field Dressing
  • elastic_bandage: Elastic Bandage
  • packing_bandage: Packing Bandage
  • ifak: IFAK
  • surgical_kit: Surgical Kit
  • tourniquet: Tourniquet
  • improvised_tourniquet: Improvised Tourniquet
  • suture_kit: Suture Kit

Casts / Fractures

  • arm_cast: Arm Cast
  • leg_cast: Leg Cast
  • neck_brace: Neck Brace
  • body_cast: Body Cast

Cures / Painkillers

  • retroxin: Retroxin
  • herbal_infusion: Herbal Infusion
  • paracetamol: Paracetamol
  • radiation_antidote: Radiation Antidote
  • antibiotics: Antibiotics
  • vitalex: Vitalex
  • vitamin_cocktail: Vitamin Cocktail
  • painkillers: Painkillers
  • morphine: Morphine

Blood / Revival / Survival

  • empty_syringe: Empty Syringe
  • blood_bag_500: Blood Bag (500ml)
  • saline_500: Saline Drip (500ml)
  • revive_kit: Revive Kit
  • ecg: Defibrillator (reusable)
  • epinephrine: Epinephrine
  • respawn_tent: Respawn Tent

Optional zombie antidote

The transformation and its cure both ship disabled. To offer an antidote, enable Config.ZombieTransformation.Enabled and Config.ZombieTransformation.Cure.Enabled in shared/config/zombie.lua. The default cure item is zombie_antidote, with medic-only treatment and self-treatment disabled. Configure those rules before distributing the item.

ox_inventory/data/items.lua
1['zombie_antidote'] = {
2    label = 'Zombie Antidote',
3    weight = 100,
4    stack = true,
5    close = true,
6    description = 'Special treatment for a transformed patient',
7    client = { image = 'epinephrine.png' },
8}

Use the supplied epinephrine.png inventory image or select your own. For another inventory, create the equivalent item definition. If you rename the item, update Cure.Item to match. The transformation itself does not require an antidote, an NPC zombie resource or an addon ped.

Verify

After first start, the server console prints the version banner (ml_healthsystem) via the bridge version check. Confirm there are no missing-locale errors on screen and that the medical-state and tent tables exist. Check the Life Points table too when that feature is enabled.

Test the admin revive command. The default command is /revive <playerId> (configurable in shared/config/ui.lua under Config.Commands.Revive), and it requires admin permission through Bridge.HasPermission / your framework's ACE setup. The debug menu is /meddebug when Config.Debug = true.

  • Script not starting: check the ensure order; ml_bridge, ox_lib, and oxmysql must load before ml_healthsystem.
  • Items not usable: verify every key from _INSTALL/ox_items.txt is present in ox_inventory/data/items.lua with the exact same names. A mismatch between the inventory item name and Config.MedicalItems / Config.RespawnTent.Item breaks the use binding.
  • `MISSING: <key>` on screen: a locale key is absent. Set Config.Locale (in shared/config/core.lua) to a language that ships in locales/, or add the missing key to your custom locale file. There is no silent fallback.
  • Admin command not working: check Bridge.HasPermission resolves your group, and that the ACE permission is assigned in server.cfg. A QBCore god/admin group is also accepted.
  • Tables not created: confirm oxmysql is running and connected before ml_healthsystem; the MySQL.ready callbacks only fire once the DB connection is up.

Configuration

Config is split by domain across shared/config/*.lua (plus shared/config.lua for the Config root and server/config_server.lua for Discord webhooks). The most common first edits:

shared/config/core.lua
1Config.Debug              = false      -- console debug + the /meddebug menu
2Config.Locale             = 'en'       -- any file present in locales/ (e.g. 'it')
3Config.Theme              = 'default'  -- 'default' | 'cyberpunk' | 'wasteland' | 'noir' | 'fantasy'
4Config.DisableHealthRegen = true       -- disables native GTA health regen
  • Config.Debug: enables debug prints and the /meddebug menu.
  • Config.Locale: default 'en'. To add a language, copy locales/en.lua and translate the values.
  • Config.Theme: UI theme.
  • Config.DisableHealthRegen: set false only on arcade servers that want native regen.

Fractures ship enabled. Turn them off in shared/config/fractures.lua:

shared/config/fractures.lua
1Config.Fractures = {
2    enabled = false,
3}

Configure AntiBunnyHop in shared/config/security.lua:

shared/config/security.lua
1Config.AntiBunnyHop = {
2    Enabled     = true,
3    Sensitivity = 'medium',
4    Notify      = true,
5    Message     = "Slow down! Don't jump so often.",
6}
  • Sensitivity selects a preset: low only catches extreme bunny hops, medium is the recommended standard, high is aggressive, extreme ragdolls almost always.

Diseases, items, and masks are customer-editable. The six diseases shipped in shared/config/diseases.lua (influenza, patogeno_vx_9, radiazioni, infezione, intossicazione, tetano) are defaults, add, remove, or modify them freely. The same applies to Config.MedicalItems in shared/config/items.lua and the masks in shared/config/masks.lua.

Escrowed balance files are not editable

internal/balance/*.lua is escrowed and cannot be edited. This covers Config.Performance, Config.DamageControl, weapon LifePoints penalties, AntiBunnyHop sensitivity presets and body-part balance. Blood-type weights, compatibility and reactions are editable in shared/config/blood_groups.lua. Other customer settings are in shared/config/*.lua and server/config_server.lua.

Configuration is split across core, vitals, blood_groups, bodyparts, diseases, items, anim_presets, masks, effects, fractures, integrations, item_diseases, lifecycle, security, ui, respawn, zombie and open. Discord logging webhooks are set in server/config_server.lua. Enable player zombie transformation and configure its profiles in shared/config/zombie.lua; it is disabled by default.

Configure blood-type checks in shared/config/blood_groups.lua. The default rejects incompatible bags before consumption or damage. Existing groups in the database remain unchanged.

shared/config/blood_groups.lua
1Config.Blood.Transfusion.Compatibility = 'abo_rh'
2Config.Blood.Transfusion.IncompatibleAction = 'reject'
3Config.Blood.Transfusion.LegacyRh = 'abo'