# Installation

> Setup guide for ML HealthSystem

Category: HEALTH SYSTEM · Source: https://miciomods.it/docs/ml-healthsystem-installation · Last updated: 2026-10-05

## 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**

```cfg
ensure ox_lib
ensure oxmysql
ensure ml_bridge
ensure ml_healthsystem
```

1. Start the server. Database tables are created on first run.

> **WARNING:** 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

> **INFO:** 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`.

> **TIP:** 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**

```lua
['zombie_antidote'] = {
    label = 'Zombie Antidote',
    weight = 100,
    stack = true,
    close = true,
    description = 'Special treatment for a transformed patient',
    client = { image = 'epinephrine.png' },
}
```

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`.

**Troubleshooting**

- **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**

```lua
Config.Debug              = false      -- console debug + the /meddebug menu
Config.Locale             = 'en'       -- any file present in locales/ (e.g. 'it')
Config.Theme              = 'default'  -- 'default' | 'cyberpunk' | 'wasteland' | 'noir' | 'fantasy'
Config.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**

```lua
Config.Fractures = {
    enabled = false,
}
```

Configure AntiBunnyHop in `shared/config/security.lua`:

**shared/config/security.lua**

```lua
Config.AntiBunnyHop = {
    Enabled     = true,
    Sensitivity = 'medium',
    Notify      = true,
    Message     = "Slow down! Don't jump so often.",
}
```

- `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`.

> **WARNING:** 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.

Configuration is split across core, vitals, 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.