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 auto-detected at runtime. There is nothing to hardcode.

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

All three 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 all 29 inventory entries the system uses (28 medical items plus the respawn tent). Copy the contents into ox_inventory/data/items.lua. Item names must stay identical to shared/config/items.lua (Config.MedicalItems) and the tent item (Config.RespawnTent.Item). "On use" wiring is handled by the script through Bridge.BindUsableItem: no client/server blocks to add in ox.

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

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 three tables exist in the database.

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 disabled. Enable them (and the cast props) in shared/config/fractures.lua:

shared/config/fractures.lua
1Config.Fractures = {
2    enabled = false,  -- set true to enable bone fractures and casts
3}

The AntiBunnyHop knob is in shared/config/security.lua:

shared/config/security.lua
1Config.AntiBunnyHop = {
2    Enabled     = true,
3    Sensitivity = 'medium',   -- 'low' | 'medium' | 'high' | 'extreme'
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 (encrypted) and cannot be edited by the customer. This covers Config.Performance, Config.DamageControl, the blood-group probabilities and compatibility matrix, weapon LifePoints penalties, the AntiBunnyHop sensitivity presets, and body-part balance. Tune behavior through the shared/config/*.lua files listed above and the AntiBunnyHop Sensitivity selector, not the internal balance.

Full domain breakdown of the split config: core, vitals, bodyparts, diseases, items, anim_presets, masks, effects, fractures, integrations, item_diseases, lifecycle, security, ui, respawn, open. Discord logging webhooks are set in server/config_server.lua.