# F.A.Q

> Frequently asked questions for ML HealthSystem

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

## 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'
```

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

If optional zombie transformation is enabled, the configured trigger stage transforms the player instead of applying that disease's terminal last stand and delayed death. The default trigger is VX-9's terminal stage. Other diseases and medical damage still apply.

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

## Zombie transformation

**How do I enable it, and when does a player transform?**

Set `Config.ZombieTransformation.Enabled = true` in `shared/config/zombie.lua`. The default trigger is the terminal stage of `patogeno_vx_9`, which is used by the bite integration. You can map other diseases and stages to profiles or call the server `TransformPlayer` export directly. Keep it disabled to retain the ordinary disease behavior.

**Does it replace the player character?**

The default profile keeps the original ped, face and clothes. It changes movement and freemode eye color, adds a local screen effect and applies the configured restrictions. Optional model mode uses a model installed on your server and a registered appearance provider; no addon skin is included. That provider must capture and restore the complete original character.

**Can players use weapons, inventory or vehicles?**

The default profile blocks weapons, inventory access where supported, sprinting, jumping, climbing and vehicle entry. Unarmed attacks remain available. Each restriction has its own profile switch. Weapons and items stay in the inventory. ox_inventory has a built-in lock integration; other inventories need a provider if they do not honor its flags. Death continues to use its own restrictions.

**How does a transformed player recover?**

By default, there is no recovery timer or health decay. Death suspends the transformation effects; an authorized respawn cures it, while a revive preserves it according to `Lifecycle`. Configure a duration with `ExpiryAction = 'cure'` or `'death'`, enable health decay, offer the optional special antidote, or call `CureZombie` from a trusted server resource. Disconnecting does not cure the character or renew its timer. Offline progression is disabled by default.

The normal VX-9 cure still respects `maxCurableStage`. The optional zombie antidote is a separate treatment and ships disabled. Enabling it requires its inventory item and the configured medic/self-treatment policy.

**Can my NPC zombies ignore transformed players?**

Yes, when the NPC resource checks `ShouldZombiesIgnorePlayer`. This setting does not control another script's AI automatically. Use the server export for target selection and check again before an attack. Subscribe to the state change event to drop protected targets. Client-driven AI must handle unknown or stale state and refresh visible players. The Developer guide includes both integration examples.

**Can transformed players infect other players?**

Unarmed attacks are allowed by the default profile, but melee infection ships disabled. Enable `MeleeInfection.Enabled` to roll the configured infection chance after a confirmed unarmed hit. The server checks proximity, routing bucket, cooldown and matching damage reports. Custom combat resources may need an adapter if they do not produce the expected damage events.

**Are changes synchronized for nearby players?**

The server owns transformation state and sends it to clients in scope. Clients apply the configured presentation to nearby player peds, including after they return to scope. Movement and screen effects apply to the transformed player; observers render scoped cosmetics. Custom inventory and appearance providers must implement their documented contracts. Check the chosen providers, scope changes and recovery flows on your server before enabling optional model mode.

## 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 settings 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/` 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`) provides a contact-infection API that only runs when 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
local ok, reason = exports.ml_healthsystem:RevivePlayer(source, { ClearDiseases = false })
```

`ClearDiseases = false` keeps diseases for this revive. Include only the fields to change; omitted fields inherit `Config.ReviveSettings` in `server/config_server.lua`. The global settings and the supplied table are not changed. The player is revived in place, with no hospital teleport, inventory wipe, or Life Points penalty. Alive players are also accepted. Use `HospitalRespawn` for the hospital flow.

To use the global revive settings, omit the table:

```lua
local ok, reason = exports.ml_healthsystem:RevivePlayer(source)
```

The target must be an online player with a positive integer server ID. Success returns `true` after the server reset and client event dispatch. Invalid targets return `false, 'invalid_player'`; invalid tables, unknown fields, or non-boolean values return `false, 'invalid_options'`. Both exports accept the eight reset fields documented in the Developer reference.

**How do I respawn a downed player after NPC treatment without curing diseases?**

Call the server export after the NPC treatment progress completes and the server has validated treatment authorization, NPC proximity, payment, and any EMS availability rule:

```lua
local ok, reason = exports.ml_healthsystem:HospitalRespawn(source, { ClearDiseases = false })
```

`ClearDiseases = false` keeps diseases for this respawn. Omitted fields inherit `Config.HospitalReset`; the global configuration is not changed. All eight reset fields accept per-call boolean values: `RestoreHealth`, `RestoreBlood`, `ResetBleeding`, `ClearInjuries`, `ClearFractures`, `ClearCasts`, `ClearDiseases`, and `ResetHungerThirst`. Unknown keys or non-boolean values return `false, 'invalid_options'`.

The player must be `dead` or `last_stand`. The export bypasses the death timer and spawn selector and uses the normal hospital respawn flow, including inventory wipe and Life Points penalties when enabled. These two features still use their own global settings. A `true` result confirms the server reset and client event dispatch, not the end of the client animation.

When `RestoreHealth = false`, pre-reset health is preserved within 101 and `Config.MaxHealth` so the player can return alive. Preserved diseases, low blood volume, and bleeding still apply their normal effects and damage.

To select a configured hospital, pass its exact `Config.StartSpawn` key as the third argument:

```lua
local ok, reason = exports.ml_healthsystem:HospitalRespawn(source, { ClearDiseases = false }, 'prison')
```

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