# F.A.Q

> Frequently asked questions for ML HealthSystem

Category: HEALTH SYSTEM · Source: https://miciomods.it/docs/ml-healthsystem-faq · Last updated: 2026-07-09

## Setup

**How do I change the language?**

Set `Config.Locale` in `shared/config/core.lua`. Default is `'en'`. Use any file present in the `locales/` folder.

**shared/config/core.lua**

```lua
Config.Locale = 'en'  -- language code; see the locales/ folder
```

**Where is the config? There is no shared/config.lua with everything in it.**

The config is split across `shared/config/*.lua`, one file per domain: `core`, `vitals`, `bodyparts`, `diseases`, `items`, `anim_presets`, `masks`, `effects`, `fractures`, `integrations`, `item_diseases`, `lifecycle`, `security`, `ui`, `respawn`, `open`. Server-only values (webhooks, Life Points, inventory wipe, revive/hospital reset) live in `server/config_server.lua`. All of these are unencrypted and editable.

Balance numbers (`internal/balance/*.lua`) are escrowed and cannot be edited, see the Configuration section.

**Why is the script not starting?**

1. Check `server.cfg` ensure order: `oxmysql` → `ox_lib` → `ml_bridge` → `ml_healthsystem`.
2. Verify `ml_bridge` is present in the resources folder and started.
3. Check the server console for dependency errors.

**Why are items not working when used?**

1. Confirm the entries from `_INSTALL/ox_items.txt` are in `ox_inventory/data/items.lua`.
2. Restart the inventory resource after adding items.
3. Item names must match exactly between `shared/config/items.lua` (`Config.MedicalItems`) and the inventory. "On use" is wired by the script through `Bridge.BindUsableItem`: do not add your own `server.export`/`client.export` to these items.
4. Drop the PNGs from `_INSTALL/images/` into `ox_inventory/web/images/`.

**Why do admin commands return "no permission"?**

1. `Bridge.HasPermission` checks the framework ACE permissions.
2. For QBCore/QBox: the player needs `god`, `admin`, or `superadmin`.
3. Console commands (source 0) bypass permission checks.
4. Life Points staff rights are a separate list, `Config.LifePoints.StaffPermissions` in `server/config_server.lua` (defaults `god`, `admin`).

## Damage and Injuries

**How does body-part damage work?**

The system tracks 9 body zones: head, neck, chest, spine, pelvis, left/right arm, left/right leg. Each hit maps to a zone via bone detection. Wounds accumulate per zone with 4 severity levels. Minor, Painful, Severe, Critical (`Config.WoundLevels` in `shared/config/vitals.lua`), each with its own movement rate. Per-part gameplay flags (armored, can-fracture, fracture restrictions, cast duration) live in `Config.BodyParts` in `shared/config/bodyparts.lua`. The fracture thresholds and chances are balance numbers in the escrowed `internal/balance/balance.lua` and are not editable.

**How do fractures work?**

Fractures ship **disabled** by default: `Config.Fractures.enabled = false` in `shared/config/fractures.lua`, and every part has `canFracture = false` in `shared/config/bodyparts.lua`. To enable, set `Config.Fractures.enabled = true` and flip `canFracture = true` on the parts that should break.

When active, accumulated bone damage past the threshold triggers a fracture and applies the penalties in `Config.FracturePenalties` (per part: `allowShoot`, `allowDrive`, `limp`, `sprint`, `aimShake`, `shakeIntensity`). Cast items (`arm_cast`, `leg_cast`, `neck_brace`, `body_cast`) fix fractures and attach a visible bone-mounted plaster prop.

**What triggers vehicle crash injuries?**

Impact speed is checked against `Config.VehicleCrash.Tiers` in `shared/config/effects.lua`. Three tiers ship: 40+ km/h, 70+ km/h, 100+ km/h. Each tier has independent `damage`, `bleedChance`, `fractureChance`, and `stagger`. The shipped defaults keep `fractureChance = 0` on all tiers to avoid random deaths from crashes. Edit the tier table to retune.

**How does armor protection work?**

Parts flagged `armored = true` in `Config.BodyParts` (`shared/config/bodyparts.lua`) benefit from equipped armor, chest, spine, pelvis by default. Protection reduces bleed chance by 80% and damage by 20% (`Config.ArmorSettings.BleedReduction` / `DamageReduction` in `shared/config/vitals.lua`) and requires armor above `MinArmorForProtection` (5.0).

## Blood System

**How does the blood type system work?**

Each character is assigned a blood type (0, A, B, AB) on first join. Transfusions check compatibility: type 0 is universal donor, type AB is universal receiver; incompatible transfusions are rejected. The assignment probabilities and the compatibility matrix are medical constants in the escrowed `internal/balance/blood_groups.lua` and are not customer-editable. Blood volumes and thresholds (`MaxVolume`, `WeaknessThreshold`, `CriticalLevel`, regen rates) are editable in `Config.Blood` in `shared/config/vitals.lua`.

**What happens at low blood levels?**

Below `WeaknessThreshold` (4.5L): movement penalties and screen effects. Below `CriticalLevel` (3.0L): severe debuffs and visual impairment. At `DeathThreshold` (0.0L): death from blood loss. Blood regenerates at `RegenRate` (0.05/tick), boosted to `RegenBoost` by a saline drip. Bleeding drains blood per `Config.Blood.BleedingRates` scaled by the active bleed level (1-4).

## Diseases

**Which diseases ship by default?**

Six, in `shared/config/diseases.lua`: `influenza` (Viral Flu), `patogeno_vx_9` (VX-9 Pathogen), `radiazioni` (Radiation Sickness), `infezione` (Wound Infection), `intossicazione` (Food Poisoning), `tetano` (Tetanus). These are starting defaults, not a fixed set, add, remove, or rewrite diseases freely (stages, effects, cures, contagion) in that file. Each disease references locale keys for its stage names and messages, so a new disease also needs matching keys in `locales/`.

**How does disease contagion work?**

Contagious diseases spread by proximity. Each disease's `contagious` block defines `distance`, `chance` (per check), `interval`, and `useMasks`. Of the shipped diseases only `influenza` is contagious. Masks cut infection chance, `Config.MaskSystem` (`shared/config/masks.lua`) supports item-based masks and clothing-based protection, each with a `protection` percentage (0-100).

**Can diseases kill the player?**

Yes. A stage with `terminal = true` runs `lastStand` and `death` effects. Among the defaults, `patogeno_vx_9`, `radiazioni`, `infezione`, and `tetano` have terminal stages. Cure items respect `maxCurableStage`: applying the cure past that stage fails with the disease's `tooLateMessage`. `influenza` and `intossicazione` are non-fatal (`intossicazione` even has `naturalRecovery`).

**Which item cures which disease?**

From `shared/config/items.lua` (`Config.MedicalItems`):

- `paracetamol` → `influenza`
- `retroxin` → `patogeno_vx_9`
- `radiation_antidote` → `radiazioni`
- `antibiotics` → `infezione`, `tetano`
- `herbal_infusion` → `intossicazione`
- `vitalex` → `infezione`, `tetano`, `intossicazione`, `influenza` (broad cure)
- `vitamin_cocktail` → `infezione`

Cures are tied to disease keys, so renaming a disease means updating the matching item's `disease` field.

**How do disease suppressors work?**

Suppressors pause progression without curing. A disease's `treatment.suppressors` maps an item to a `keepAt` stage and a `duration`, optionally `pauseEffects = true`. Example: `vitalex` holds `influenza` at stage 1 for 1h. Progression resumes when the suppressor expires.

## Life Points

**What is the Life Points system?**

A permadeath layer. Each character starts at `Config.LifePoints.StartingPoints` (default 100, in `server/config_server.lua`). Deaths deduct points based on cause: `DefaultPenalty`, `PlayerKillPenalty`, per-NPC `NPCOverrides`, per-`ExternalReasons` (disease, bleedout, starvation, etc.), and per-weapon-class penalties. When points hit `MinPoints` (0), the inventory is wiped except items in `Config.InventoryWipe.Whitelist`. State persists in the `ml_lifepoints` table.

**Can I adjust Life Point penalties per weapon?**

The per-weapon-class penalties (`WeaponPenalties`) and the extra player-kill weapon penalties (`PlayerKillWeapons`) are balance numbers in the escrowed `internal/balance/weapon_penalties.lua` and cannot be edited. The editable Life Points knobs in `server/config_server.lua` are: `StartingPoints`, `MinPoints`, `DefaultPenalty`, `PlayerKillPenalty`, `NPCOverrides`, `ExternalReasons`, `StaffPermissions`, and `ExportAllowlist`. Geographic death-zone penalties live in `Config.LifePoints.Zones` (`shared/config/integrations.lua`).

**Who can modify Life Points without losing them?**

Roles in `Config.LifePoints.StaffPermissions` (default `god`, `admin`) revive without penalty and may call the modify exports. To restrict which resources may call `SetLifePoints` / `AddLifePoints` / `RemoveLifePoints`, populate `Config.LifePoints.ExportAllowlist` (empty = any server resource).

## Integration

**How do I integrate with a radiation script?**

Configure `Config.RadiationIntegration` in `shared/config/integrations.lua` (poll interval, `DiseaseName = 'radiazioni'`, `CureThreshold`, `Thresholds`, `CureItems`, anti-abuse `EntryGrace` and `RequireAntidoteForCure`). The connector at `open/client/radiation_connector.lua` (and `open/server/radiation_connector.lua`) reads the radiation level and drives the `radiazioni` disease when thresholds are crossed. Both connector files are in the open `open/` folder, edit them to match the exports of your radiation script.

**How do external scripts infect a player on contact?**

`Config.ContactInfection` (`shared/config/integrations.lua`) exposes a reusable contact-infection surface, inert until called. Defaults apply `patogeno_vx_9` at 35% per contact. Call it server-side with `exports.ml_healthsystem:InfectFromContact(src, opts)` or client-side via `TriggerServerEvent('ml_healthsystem:server:ContactInfection')`: for zombie, hazard, or trap scripts.

**Can I disable the death system for certain players?**

Use the server export:

```lua
exports.ml_healthsystem:SetDeathSystemDisabled(source, true)
```

Death processing is suppressed for that player until re-enabled. Useful for admin godmode or cutscenes.

**How do I revive a player from another script?**

```lua
-- Server side
exports.ml_healthsystem:RevivePlayer(source)
```

This fully revives the player and clears medical state per `Config.ReviveSettings` (`server/config_server.lua`).

## Database

**Which tables does the script create?**

Three, all created automatically on first start:

- `ml_healthsystem`: persisted per-character medical state (`identifier`, `health_data`).
- `ml_lifepoints`: Life Points balance per character.
- `ml_health_tents`: placed respawn tents.

Live in-session state (wounds, bleeding, diseases, death state) is synced in real time and is flushed to `ml_healthsystem` for persistence, there is no separate per-injury table.

**A player is stuck downed / desynced. How do I reset their state?**

Revive them with `exports.ml_healthsystem:RevivePlayer(source)` (server). For a full medical wipe, that export honors `Config.ReviveSettings`. The `ml_healthsystem` row is keyed by identifier; clearing it resets persisted state on the next load, but a live revive is the correct first step.

## Updates

**How do I update the script?**

1. Download the latest build from the CFX keymaster / Tebex portal.
2. Back up your config: `shared/config.lua`, `shared/config/*.lua`, `server/config_server.lua`, and the `open/` folder.
3. Replace all files except your config and `open/` edits.
4. Restart the resource.

Medical state, Life Points, and tents live in the database (`ml_healthsystem`, `ml_lifepoints`, `ml_health_tents`) and survive updates.

**Will my balance edits survive an update?**

The balance files (`internal/balance/*.lua`) are escrowed and ship inside the encrypted build, so there is nothing to back up or merge there, they are replaced wholesale on update. Your editable config (`shared/config/*.lua`, `server/config_server.lua`) and `open/` changes are yours to preserve across updates.