# Configuration > Configuration reference for ML HealthSystem Category: HEALTH SYSTEM · Source: https://miciomods.it/docs/ml-healthsystem-configuration · Last updated: 2026-10-05 ## Overview Configuration is split by feature under `shared/config/`, plus a server-only file. There is no single `shared/config.lua` table; edit each value in its feature file. ```text shared/config/ ├── core.lua # Debug, Locale, Theme, native regen toggle ├── vitals.lua # MaxHealth, Blood, Armor, Wound levels, BloodTrails, Casts ├── bodyparts.lua # Single table for the 9 body parts ├── diseases.lua # Disease definitions, stages, contagion, treatments ├── items.lua # Medical items + XP cooldown ├── anim_presets.lua # Reusable animation presets referenced by items ├── masks.lua # Masks (item + drawable) and clothing protection ├── effects.lua # Visual effects, Voice, Flare, Vehicle crash, NPC behavior ├── fractures.lua # Fall-fracture chance + per-part fracture penalties ├── integrations.lua # Radiation, contact infection, LifePoints zones ├── item_diseases.lua # Food/item → disease map ├── lifecycle.lua # Last stand + Death ├── respawn.lua # Spawn points, cinematic cam, bed, respawn tent ├── security.lua # AntiBunnyHop (Enabled + Sensitivity preset) ├── ui.lua # Scan UI, Medic jobs, Commands ├── zombie.lua └── open.lua # Open-handler event toggles server/config_server.lua # Webhooks, LifePoints, inventory wipe, revive/hospital reset ``` > **WARNING:** Escrowed balance numbers are not editable > > `internal/balance/*.lua` is encrypted by the Cfx escrow and cannot be edited. It holds `Config.Performance` (tick intervals), `Config.DamageControl` (anti-exploit thresholds), `Config.Blood.Probabilities` / `Config.Blood.Compatibility`, the per-weapon LifePoints penalties, the AntiBunnyHop sensitivity presets, and the per-body-part balance numbers. `internal/engine/*.lua` (bone IDs, weapon hashes, cast prop offsets) is visible but is technical data, do not modify it. Everything documented below lives in `shared/config/*.lua` or `server/config_server.lua` and is freely editable. ## Core **shared/config/core.lua** ```lua Config.Debug = false Config.Locale = 'en' Config.Theme = 'default' Config.DisableHealthRegen = true ``` - `Debug`: enables console DebugLog output. Keep off in production. - `Locale`: language code. Default `'en'`. Use any file present in the `locales/` folder. - `Theme`: UI theme: `default`, `cyberpunk`, `wasteland`, `noir`, `fantasy`. - `DisableHealthRegen`: blocks GTA native health regeneration so wounds do not self-heal. ## Vitals **shared/config/vitals.lua** ```lua Config.MaxHealth = 200 Config.BleedRateMultiplier = 0.5 Config.ArmorDamageThreshold = 2 Config.ArmorSettings = { BleedReduction = 0.80, DamageReduction = 0.20, MinArmorForProtection = 5.0, } Config.Casts.Duration = 3600 ``` - `MaxHealth`: player max health ceiling (GTA caps usable health; 200 is the engine max). - `BleedRateMultiplier`: multiplier on blood lost per bleeding tick. `1.0` is the unscaled rate. - `ArmorDamageThreshold`: minimum incoming damage before armor degradation logic applies. - `ArmorSettings.BleedReduction`: fraction of bleed chance removed while armored. - `ArmorSettings.DamageReduction`: fraction of damage absorbed while armored. - `ArmorSettings.MinArmorForProtection`: minimum armor value before any protection counts. - `Casts.Duration`: fallback cast duration in seconds when a body part does not define its own. Per-part durations live in `bodyparts.lua`. ### Blood **shared/config/vitals.lua** ```lua Config.Blood.MaxVolume = 6.0 Config.Blood.WeaknessThreshold = 4.5 Config.Blood.CriticalLevel = 3.0 Config.Blood.DeathThreshold = 0.0 Config.Blood.DrawAmount = 0.25 Config.Blood.RegenRate = 0.05 Config.Blood.RegenBoost = 0.2 Config.Blood.BleedingRates = { [1] = 0.008, [2] = 0.017, [3] = 0.033, [4] = 0.067, } ``` - `MaxVolume`: maximum blood volume in liters. - `WeaknessThreshold`: below this liter level the player takes movement penalties. - `CriticalLevel`: below this level screen effects and severe debuffs apply. - `DeathThreshold`: blood level at which the player dies from blood loss. - `DrawAmount`: liters drawn per `empty_syringe` use. - `RegenRate`: liters regenerated per natural regen tick. - `RegenBoost`: liters regenerated per tick while a saline/regen buff is active. - `BleedingRates`: liters lost per tick at each bleeding level (1-4). > **INFO:** Blood types are escrowed > > Blood-type probabilities and donor/receiver compatibility live in `internal/balance/blood_groups.lua` and cannot be edited. The defaults are O 45%, A 40%, B 11%, AB 4%, with O universal donor and AB universal receiver. ### Wound levels and blood trails **shared/config/vitals.lua** ```lua Config.WoundLevels = { [1] = { movementRate = 0.98, label = 'Minor' }, [2] = { movementRate = 0.85, label = 'Painful' }, [3] = { movementRate = 0.72, label = 'Severe' }, [4] = { movementRate = 0.59, label = 'Critical' }, } Config.BloodTrails = { Enabled = true, Threshold = 2, } ``` - `WoundLevels[n].movementRate`: movement-speed multiplier at each wound severity. - `WoundLevels[n].label`: name shown for that severity. - `BloodTrails.Enabled`: leave blood decals on the ground while bleeding. - `BloodTrails.Threshold`: minimum bleeding level (1-4) before trails start. ## Body Parts **shared/config/bodyparts.lua** ```lua Config.BodyParts = { head = { armored = false, canFracture = false, fracture = { allowShoot = true, allowDrive = true, allowSprint = true }, }, } ``` A single table defines all 9 parts (`head`, `neck`, `chest`, `spine`, `pelvis`, `left_arm`, `right_arm`, `left_leg`, `right_leg`). - `armored`: whether worn armor reduces damage to this part. - `canFracture`: whether the part can fracture. Ships `false` on every part (fractures are disabled by default, see `fractures.lua`). - `fracture.allowShoot` / `allowDrive` / `allowSprint`: what the player may do while this part is fractured. - `cast.duration`: optional per-part cast duration (ms) overriding `Config.Casts.Duration`. > **INFO:** Per-part balance is escrowed > > `breakThreshold`, `fractureChance`, `staggerMult`, and `shakeIntensity` for each part live in `internal/balance/balance.lua` and cannot be edited. ## Lifecycle (Last Stand and Death) **shared/config/lifecycle.lua** ```lua Config.LastStand = { Duration = 60, InstantDeathOnDamage = false, MinimumDamageToKill = 50, Anim = { dict = 'move_injured_ground', name = 'front_loop' }, } Config.Death = { Duration = 600, AutoRespawnOnZero = false, AutoRespawnGracePeriod = 600, RespawnUITimeout = 60, Anim = { dict = 'dead', name = 'dead_a' }, AnimVeh = { dict = 'veh@low@front_ps@idle_duck', name = 'sit' }, } ``` - `LastStand.Duration`: seconds in last stand before death. - `LastStand.InstantDeathOnDamage`: `true` kills immediately if damaged while downed. - `LastStand.MinimumDamageToKill`: damage needed to kill during last stand when `InstantDeathOnDamage` is `false`. - `LastStand.Anim`: downed ground animation dict/name. - `Death.Duration`: seconds before the respawn UI opens. - `Death.AutoRespawnOnZero`: auto-respawn when the timer reaches zero. - `Death.AutoRespawnGracePeriod`: when `AutoRespawnOnZero` is `true`, seconds the "Hold E" prompt stays open before a forced respawn. `0` or `nil` = instant auto-respawn with no prompt. - `Death.RespawnUITimeout`: seconds before the respawn UI auto-selects. - `Death.Anim` / `Death.AnimVeh`: death animation on foot / in a vehicle. ## Effects **shared/config/effects.lua** ```lua Config.Effects = { CameraShake = true, ScreenEffects = true, WeaknessEffects = true, AimShake = true, ExternalRecoilScript = false, FlashOnFracture = true, Blackout = { Enabled = true, OnHeadShot = true, OnExplosion = true, Chance = 80, Duration = 4000, MinDamage = 20, }, } ``` - `CameraShake`: camera shake on injury. - `ScreenEffects`: screen post-FX at critical blood levels. - `WeaknessEffects`: movement penalties at low blood. - `AimShake`: weapon sway while injured. - `ExternalRecoilScript`: set `true` when a standalone recoil script is present, to avoid conflicts. - `FlashOnFracture`: screen flash on fracture. - `Blackout.Enabled`: knockout on headshot/explosion. - `Blackout.OnHeadShot` / `OnExplosion`: which events can trigger a blackout. - `Blackout.Chance`: percent chance to trigger. - `Blackout.Duration`: blackout length in ms. - `Blackout.MinDamage`: minimum damage that can trigger a blackout. ### NPC behavior and voice **shared/config/effects.lua** ```lua Config.NPCInteraction = { IgnoreOnDeath = true, IgnoreInLastStand = true, } Config.Voice = { Enable = true, System = 'pma-voice', MuteDead = true, MuteLastStand = false, } ``` - `NPCInteraction.IgnoreOnDeath` / `IgnoreInLastStand`: NPCs ignore the player while dead / downed. - `Voice.Enable`: enable voice muting integration. - `Voice.System`: voice resource name. - `Voice.MuteDead`: mute the player while dead. - `Voice.MuteLastStand`: mute the player while in last stand. ### Flare **shared/config/effects.lua** ```lua Config.Flare = { Enabled = true, RequireItem = true, VisualEffect = true, Item = 'WEAPON_FLARE', RemoveItem = true, Cooldown = 60000, Key = 47, AlertDispatch = { Enabled = false, Jobs = { 'ambulance', 'police' }, Code = '10-52', }, } ``` - `Enabled`: allow downed players to fire a flare for help. - `RequireItem`: require the flare item to use it. - `VisualEffect`: fire the visual flare into the sky. Off sends the alert with no flare shot and the death-screen prompt becomes a plain call for help. - `Item`: inventory weapon key. `WEAPON_FLARE` is the base-game flare weapon (case-sensitive). - `RemoveItem`: consume the flare on use. - `Cooldown`: ms between flare uses. - `Key`: control index that fires the flare. - `AlertDispatch.Enabled`: alert police and medics through your dispatch when a downed player uses the flare. - `AlertDispatch.Jobs`: jobs that receive the call. - `AlertDispatch.Code`: dispatch code sent with the alert. - `VisualEffect` and `AlertDispatch` both off hide the signal prompt on the death screen. ### Vehicle crash **shared/config/effects.lua** ```lua Config.VehicleCrash = { Enabled = true, Tiers = { { minSpeed = 100.0, damage = 15, bleedChance = 10, fractureChance = 0, stagger = true }, { minSpeed = 70.0, damage = 7, bleedChance = 5, fractureChance = 0, stagger = false }, { minSpeed = 40.0, damage = 3, bleedChance = 0, fractureChance = 0, stagger = false }, }, } ``` - `Enabled`: apply crash injuries from high-speed impacts. - `Tiers[n].minSpeed`: speed threshold for the tier. - `Tiers[n].damage`: health damage applied. - `Tiers[n].bleedChance` / `fractureChance`: percent chance to start bleeding / fracture. - `Tiers[n].stagger`: whether the impact staggers the player. Defaults are deliberately low to avoid random deaths from minor crashes. ## Security (Anti-Bunny Hop) **shared/config/security.lua** ```lua Config.AntiBunnyHop = { Enabled = true, Sensitivity = 'medium', Notify = true, Message = "Slow down! Don't jump so often.", } ``` - `Enabled`: toggle the anti-bunny-hop ragdoll. - `Sensitivity`: preset: `low` (only extreme hops), `medium` (recommended), `high` (aggressive), `extreme` (ragdoll almost always). - `Notify`: show a notification on a violation. - `Message`: notification text. > **INFO:** Sensitivity presets are escrowed > > The concrete cooldown, ragdoll duration, and trigger chance behind each preset live in `internal/balance/antibunnyhop.lua` and cannot be edited. Pick a preset; the numbers are fixed. ## Fractures **shared/config/fractures.lua** ```lua Config.Fractures = { enabled = false, Legs = { FallOnlyRunning = true, FallChanceRun = 10, FallChanceSprint = 15, FallChanceWalk = 5, }, } ``` - `enabled`: master kill switch. Ships `false`. Re-enabling also requires setting `canFracture = true` on the desired parts in `bodyparts.lua`. - `Legs.FallOnlyRunning`: only count fall fractures while moving. - `Legs.FallChanceRun` / `FallChanceSprint` / `FallChanceWalk`: percent chance of a leg fracture from a fall at each movement state. **shared/config/fractures.lua** ```lua Config.FracturePenalties = { ['left_arm'] = { allowShoot = true, aimShake = true, shakeIntensity = 2.5 }, ['right_arm'] = { allowShoot = false, allowDrive = true }, ['left_leg'] = { limp = true, sprint = false, allowDrive = true }, ['right_leg'] = { limp = true, sprint = false, allowDrive = false }, } ``` `Config.FracturePenalties` defines, per body part, what a fracture restricts: - `allowShoot`: whether the player can shoot with this part fractured. - `allowDrive`: whether the player can drive. - `aimShake` / `shakeIntensity`: add aim sway and how strong it is. - `limp` / `sprint`: apply a limp / block sprint. ## Masks **shared/config/masks.lua** ```lua Config.MaskSystem = { EnableItemMode = true, EnableClothingMode = true, Anim = { dict = 'mp_masks@on_foot', putOn = 'put_on_mask', takeOff = 'put_on_mask', flags = 49, }, } Config.Masks = { ['mask_surgical'] = { protection = 90, component = { id = 7, male = 38, female = 38, texture = 0 }, label = 'Surgical Mask' }, ['mask_n95'] = { protection = 99, component = { id = 7, male = 120, female = 120, texture = 0 }, label = 'N95 Mask' }, ['mask_dust_unisex'] = { protection = 30, component = { id = 7, male = 46, female = nil, texture = 0 }, label = 'Dust Mask', itemless = true }, ['helmet_full_male'] = { protection = 100, component = { id = 1, male = 36, female = 36, texture = 0 }, label = 'Full Helmet', itemless = true }, ['helmet_half_male'] = { protection = 50, component = { id = 1, male = 46, female = nil, texture = 0 }, label = 'Half Helmet', itemless = true }, } ``` - `MaskSystem.EnableItemMode`: mask items from inventory grant disease protection. - `MaskSystem.EnableClothingMode`: worn clothing components grant protection. - `MaskSystem.Anim`: put-on / take-off animation. - `Config.Masks`: single source of truth for masks. `Config.MaskItems` (per-item lookup) and the mask entries in `Config.ProtectiveClothing` are derived from this table at runtime. - `protection`: filtering percentage (0-100). - `component`: clothing slot `{ id, male, female, texture }`. Set `female = nil` if the drawable is male-only. - `label`: display name. - `itemless`: `true` means protection comes from the worn drawable only, with no dedicated inventory item. `Config.ProtectiveClothing` (also in `masks.lua`) maps individual male/female drawable IDs for component slot `[1]` to a protection value (40 or 80), letting plain clothing offer partial protection without a mask item. > **TIP:** Add a mask in one place > > Add or edit an entry in `Config.Masks` only. The item lookup and the clothing check are generated from it, no need to edit three tables. These are shipped defaults, not fixed values; add, remove, or rebalance them freely. ## Diseases Diseases live in `shared/config/diseases.lua`. They are shipped defaults, add, remove, or rebalance them freely. Each disease defines: - `severity`: `mild`, `moderate`, `severe`, or `critical`. - `contagious`: `enabled`, `distance`, `chance`, `interval`, `useMasks`. - `trigger`: optional auto-infect on injury (`type = 'injury'`, `parts`, `chance`). - `stages`: timed progression; each stage has `after`, `name`, and an `effects` list. - `treatment`: `cure` item, optional `maxCurableStage`, `tooLateMessage`, `suppressors`, `naturalRecovery`. The six shipped diseases: - `influenza` (Viral Flu), mild, contagious, 4 stages. Cure: `paracetamol`. Suppressors: `vitalex`, `vitamin_cocktail`. - `patogeno_vx_9` (VX-9 Pathogen), critical, 5 stages (stage 5 terminal). Cure: `retroxin` (max curable stage 4). - `radiazioni` (Radiation Sickness), severe, 4 stages (stage 4 terminal). Cure: `radiation_antidote` (max curable stage 3). Wired to the radiation integration. - `infezione` (Wound Infection), moderate, triggered by `cut`/`gunshot` injuries (30%), 5 stages (stage 5 terminal). Cure: `antibiotics`. - `intossicazione` (Food Poisoning), mild, 3 stages with natural recovery. Cure: `herbal_infusion`. - `tetano` (Tetanus), severe, triggered by `cut` injuries (25%), 4 stages (stage 4 terminal). Cure: `antibiotics`. Effect types usable in a stage: `cough`, `stumble`, `damage`, `bleed`, `fever`, `movePenalty`, `vomit`, `lastStand`, `death`, `notify`. Time format: `'30s'`, `'15m'`, `'2h'`, `'1d'`. Add `terminal = true` to a stage to make it fatal. ### Kill switch **shared/config/diseases.lua** ```lua Config.DiseasesEnabled = true Config.AlwaysEnabledDiseases = { 'radiazioni', } ``` - `DiseasesEnabled`: `false` disables every disease except those in `AlwaysEnabledDiseases`. - `AlwaysEnabledDiseases`: diseases that survive the kill switch. Keep `radiazioni` while the radiation integration is on, otherwise its silent terminal progression can cause "random" deaths. **Adding a custom disease** Add an entry to `Config.Diseases` in `shared/config/diseases.lua`: **shared/config/diseases.lua** ```lua ['my_disease'] = { label = 'My Disease', icon = 'fa-virus', severity = 'moderate', contagious = { enabled = false }, stages = { [1] = { after = '0s', name = 'disease_my_disease_s1', effects = {} }, [2] = { after = '30m', name = 'disease_my_disease_s2', effects = { { type = 'damage', amount = 2, interval = '10m' }, { type = 'notify', message = 'disease_my_disease_s2_msg' }, }}, }, treatment = { cure = 'antibiotics', }, } ``` `name` and `notify message` fields are locale keys. Add the matching keys to every file in `locales/`: a missing key renders on screen as the literal `MISSING: key`, not a fallback. The `cure` item must exist in `items.lua` with `type = 'cure_disease'` and `disease = 'my_disease'`. ### Item-triggered diseases **shared/config/item_diseases.lua** ```lua Config.ItemDiseases = { ['cibo_marcio'] = { disease = 'intossicazione', chance = 100 }, ['carne_rossa'] = { disease = 'intossicazione', chance = 50 }, ['carne_squalo'] = { disease = 'intossicazione', chance = 30 }, } ``` Maps inventory items (raw meat, spoiled food, undercooked fish) to a disease applied on consumption. `disease` must exist in `diseases.lua`; `chance` is rolled per use (0-100). The shipped entries map to `intossicazione`. Edit freely to match your server's food items. ## Zombie transformation Player zombie transformation is disabled by default. The default profile keeps the player's original ped and clothing, with zombie-like movement, optional restrictions and a local screen effect. **Default configuration** **shared/config/zombie.lua** ```lua Config.ZombieTransformation = { Enabled = false, DefaultProfile = 'default', TickInterval = 1000, ExportAllowlist = {}, Diseases = { ['patogeno_vx_9'] = { Stage = 'terminal', Profile = 'default', }, }, Lifecycle = { Respawn = 'cure', Revive = 'preserve', OfflineProgress = false, }, Cure = { Enabled = false, Item = 'zombie_antidote', MedicOnly = true, AllowSelf = false, TreatmentDuration = 6000, }, MeleeInfection = { Enabled = false, Chance = 35, Distance = 2.5, Cooldown = 3000, ConfirmationWindow = 1500, }, Profiles = { ['default'] = { Duration = 0, ExpiryAction = 'cure', IgnoreByZombies = true, Movement = { Clipset = 'move_m@drunk@verydrunk', Speed = 0.75, Transition = 0.5, }, Restrictions = { BlockWeapons = true, BlockInventory = true, BlockSprint = true, BlockJump = true, BlockVehicleEntry = true, BlockClimbing = true, BlockSwimming = false, BlockMelee = false, }, Appearance = { Mode = 'original', Model = 's_m_y_zombie_01', Provider = false, EyeColor = 31, }, Screen = { Modifier = 'NG_filmic01', Strength = 0.25, }, Decay = { Amount = 0, Interval = 30, }, }, }, } ``` ### Enable and permissions `Config.ZombieTransformation.Enabled` defaults to `false`. Set to true to enable player transformation. Disabled mode keeps the existing disease terminal behavior. `Config.ZombieTransformation.DefaultProfile` defaults to `'default'`. Name of the profile used when a transformation export does not select one. The name must exist in Profiles. `Config.ZombieTransformation.TickInterval` defaults to `1000`. Milliseconds between server checks for watched infections and transformed characters. The server clamps the interval to 250 to 10000 milliseconds. `Config.ZombieTransformation.ExportAllowlist` defaults to `{}`. Allowed callers of the mutating server exports. An empty table allows any server resource. Use a list of resource names or map names to true. This setting does not control read exports or validated medical item treatment. ### Disease triggers `Config.ZombieTransformation.Diseases.patogeno_vx_9.Stage` defaults to `'terminal'`. The 'terminal' option transforms at the first stage marked terminal in Config.Diseases. An integer from 1 to 100 transforms at that stage or later; choose a stage defined for the disease. Add other entries using existing disease names. Only configured diseases have their terminal effects replaced by transformation. `Config.ZombieTransformation.Diseases.patogeno_vx_9.Profile` defaults to `'default'`. Profile applied by this disease trigger. The profile name must exist in Profiles. ### Death, recovery and offline time `Config.ZombieTransformation.Lifecycle.Respawn` defaults to `'cure'`. Use 'cure' to remove the transformation and its trigger infections after an authorized respawn. Use 'preserve' to keep the transformation. `Config.ZombieTransformation.Lifecycle.Revive` defaults to `'preserve'`. Use 'preserve' to resume zombie behavior after a revive, or 'cure' to remove the transformation and its trigger infections. Death suspends zombie presentation and does not cure the character. A client external respawn reset does not clear the transformation. `Config.ZombieTransformation.Lifecycle.OfflineProgress` defaults to `false`. False pauses watched disease progression, transformation duration and the next decay deadline during offline time. True lets those timers continue. Health damage from missed decay intervals is not accumulated or replayed. ### Special cure item `Config.ZombieTransformation.Cure.Enabled` defaults to `false`. Enables a separate zombie antidote treatment in the medical interaction system. Ordinary cures for the configured trigger diseases do not clear an active transformation; other disease treatments remain available. `Config.ZombieTransformation.Cure.Item` defaults to `'zombie_antidote'`. Name of an item registered in the server inventory. This setting does not create the inventory item. When enabled, the script creates its medical treatment entry if Config.MedicalItems has no entry for that item. An existing entry must use type cure_zombie to route through the zombie treatment. `Config.ZombieTransformation.Cure.MedicOnly` defaults to `true`. Requires a job listed in Config.MedicJobs. False allows other players to use the treatment. `Config.ZombieTransformation.Cure.AllowSelf` defaults to `false`. Allows self treatment when true. The medic requirement still applies when MedicOnly is enabled. `Config.ZombieTransformation.Cure.TreatmentDuration` defaults to `6000`. Milliseconds for treatment progress and the medical animation. ### Melee infection `Config.ZombieTransformation.MeleeInfection.Enabled` defaults to `false`. Enables infection from a transformed player's confirmed unarmed attack. Config.ZombieBite.Enabled and Config.ContactInfection.Enabled must also be true. The disease comes from Config.ContactInfection.Disease. Weapon damage alone or a client damage report alone does not infect the victim. `Config.ZombieTransformation.MeleeInfection.Chance` defaults to `35`. Infection chance from 0 to 100 percent after a confirmed attack. `Config.ZombieTransformation.MeleeInfection.Distance` defaults to `2.5`. Maximum attacker-to-victim distance in meters. The server also requires both players to be in the same routing bucket. `Config.ZombieTransformation.MeleeInfection.Cooldown` defaults to `3000`. Milliseconds between infection attempts by the same attacker, including attempts that fail the chance roll. `Config.ZombieTransformation.MeleeInfection.ConfirmationWindow` defaults to `1500`. Milliseconds allowed to correlate server weapon damage with the victim's damage report. Keep this long enough for the server's expected network latency. ### Profiles and duration `Config.ZombieTransformation.Profiles.default.Duration` defaults to `0`. Transformation duration in seconds. Zero keeps it until a cure or a lifecycle recovery removes it. Positive values use ExpiryAction when the timer expires. Duration strings such as '5m' or '1h' are also accepted; the maximum is 31536000 seconds. Add named entries under Profiles for other server modes. `Config.ZombieTransformation.Profiles.default.ExpiryAction` defaults to `'cure'`. Use 'cure' for automatic recovery that also clears trigger infections. Use 'death' for a fatal timeout through the medical death system; the transformation remains until its recovery policy or a cure removes it. `Config.ZombieTransformation.Profiles.default.IgnoreByZombies` defaults to `true`. Marks an active transformed player as a target that cooperating zombie AI can ignore. The NPC resource must use the health system's server API when choosing and keeping targets. ### Movement `Config.ZombieTransformation.Profiles.default.Movement.Clipset` defaults to `'move_m@drunk@verydrunk'`. Movement animation set. False leaves the walking animation unchanged. `Config.ZombieTransformation.Profiles.default.Movement.Speed` defaults to `0.75`. Accepted range 0.1 to 2.0. The medical movement controller caps the resulting rate at normal speed and applies stronger medical movement penalties. `Config.ZombieTransformation.Profiles.default.Movement.Transition` defaults to `0.5`. Animation blend duration in seconds, from 0.0 to 5.0. ### Restrictions `Config.ZombieTransformation.Profiles.default.Restrictions.BlockWeapons` defaults to `true`. Prevents weapon equipment while transformed and rejects non-unarmed weapon damage on the server. `Config.ZombieTransformation.Profiles.default.Restrictions.BlockInventory` defaults to `true`. Locks the inventory through the built-in ox inventory adapter or a registered inventory provider. Other inventories require a provider for a complete lock; blocked keys alone do not prevent inventory commands or exports. `Config.ZombieTransformation.Profiles.default.Restrictions.BlockSprint` defaults to `true`. Blocks sprinting while zombie behavior is active. `Config.ZombieTransformation.Profiles.default.Restrictions.BlockJump` defaults to `true`. Blocks jumping while zombie behavior is active. `Config.ZombieTransformation.Profiles.default.Restrictions.BlockVehicleEntry` defaults to `true`. Blocks entering vehicles. It does not eject a player already inside a vehicle. `Config.ZombieTransformation.Profiles.default.Restrictions.BlockClimbing` defaults to `true`. Blocks climbing and vaulting. `Config.ZombieTransformation.Profiles.default.Restrictions.BlockSwimming` defaults to `false`. Blocks swimming controls when true. `Config.ZombieTransformation.Profiles.default.Restrictions.BlockMelee` defaults to `false`. Blocks unarmed melee attacks when true. Keep false to allow zombie attacks and optional melee infection. ### Appearance `Config.ZombieTransformation.Profiles.default.Appearance.Mode` defaults to `'original'`. Use 'original' to retain the player's ped, face and clothing. Use 'model' for a temporary ped model, with a complete appearance provider. `Config.ZombieTransformation.Profiles.default.Appearance.Model` defaults to `'s_m_y_zombie_01'`. Installed ped model name used only in model mode. No model is downloaded or installed by the health system. `Config.ZombieTransformation.Profiles.default.Appearance.Provider` defaults to `false`. Registered appearance provider name. False delegates provider selection to open/client/zombie_handlers.lua. Model mode requires Capture and Restore support for the original appearance. `Config.ZombieTransformation.Profiles.default.Appearance.EyeColor` defaults to `31`. Temporary freemode eye color from 0 to 31. False preserves the original color. When zombie presentation ends, the original color is restored only if the same freemode ped still has the color applied by this feature. Later changes made by other resources are preserved. ### Screen effect `Config.ZombieTransformation.Profiles.default.Screen.Modifier` defaults to `'NG_filmic01'`. Local timecycle effect name. False disables this zombie screen effect. Medical emergencies take priority. `Config.ZombieTransformation.Profiles.default.Screen.Strength` defaults to `0.25`. Effect strength from 0.0 to 1.0. ### Health decay `Config.ZombieTransformation.Profiles.default.Decay.Amount` defaults to `0`. Health lost per decay tick, from 0 to 100. Zero disables decay. Fatal decay uses the medical death system. `Config.ZombieTransformation.Profiles.default.Decay.Interval` defaults to `30`. Seconds between decay ticks, from 1 to 86400. Duration strings are also accepted. The saved deadline is preserved across reconnects. Model mode keeps the original ped if its provider is missing, capture fails or the requested model cannot load. Complete appearance recovery requires a provider that restores all captured appearance data, including the saved face. Its Restore handler must finish synchronously, including during resource stop. ## Medical Items Items live in `shared/config/items.lua` under `Config.MedicalItems`. The resource ships 28 medical items plus the `respawn_tent`. Item keys are English and must match the ox_inventory entries in `_INSTALL/ox_items.txt` exactly. **shared/config/items.lua** ```lua Config.XpCooldownSeconds = 1800 Config.MedicalItems = { ['field_dressing'] = { quickAccess = true, type = 'heal_wound', allowSelf = true, remove = true, target = { 'cut', 'gunshot' }, amount = 1, health = 20, anim = 'bandage_shirt', duration = 13000, xp = { medico = 5 }, client = { labelKey = 'item_field_dressing', descKey = 'item_field_dressing_desc', icon = 'bandage' }, }, } ``` - `Config.XpCooldownSeconds`: seconds between XP awards on the same `(healer, patient, treatmentType)` tuple. Treatment still applies during cooldown; only the XP is suppressed. `0` disables the anti-grind. Default `1800`. Per-item fields: - `type`: action: `heal_wound`, `fix_fracture`, `revive_player`, `cure_disease`, `boost_regen`, `draw_blood`, `transfuse_blood`, `relieve_pain`. - `allowSelf`: usable on self. - `remove`: consumed on use. `false` with `durabilityLoss` + `removeWhen0` makes a reusable item (the defibrillator). - `quickAccess`: appears in the quick-access panel. - `target`: wound types (cut, gunshot, blunt, burn, bite) or body parts the item treats. - `amount` / `health` / `stopBleeding`: wound severity reduced, health restored, and bleed-stop strength. - `job`: restricts use to a job (most advanced items require `medico`). - `disease`: for `cure_disease`, the disease(s) cured. - `anim`: references a preset in `anim_presets.lua` (`syringe`, `pill`, `bandage`, `cast_anim`, `cpr`, `bandage_shirt`, `medkit`, `pill_capsule`, `bottle_herbal`, `bottle_pills`, `syringe_morphine`). - `animSelf` / `animTarget`: explicit animations override the preset. - `xp`: XP awarded per category on a real success, integrating with `ml_skills` (e.g. `{ medico = 10 }`). Self-treatments grant nothing. - `requiredSkill`: lock the item until the player has unlocked a specific ml_skills skill. Needs Config.Skills.Enabled. Always set category: it lets the client block the item before the use animation and hide it from the medic panel. - `requiredLevel`: lock the item below a minimum ml_skills category level. Combine with requiredSkill; both must pass. - `client`: `labelKey`, `descKey` (locale keys) and `icon`. The shipped items, grouped by purpose: - Bandages / dressings: `crafted_gauze`, `field_dressing`, `elastic_bandage`, `packing_bandage`, `ifak`, `surgical_kit`, `improvised_tourniquet`, `tourniquet`, `suture_kit` - Casts: `arm_cast`, `leg_cast`, `neck_brace`, `body_cast` - Disease cures: `retroxin`, `herbal_infusion`, `paracetamol`, `radiation_antidote`, `antibiotics`, `vitalex`, `vitamin_cocktail` - Pain relief: `painkillers`, `morphine` - Blood: `empty_syringe`, `blood_bag_500`, `saline_500` - Revival: `revive_kit`, `ecg` (defibrillator, reusable), `epinephrine` - Survival: `respawn_tent` > **TIP:** Quick access > > Items with `quickAccess = true` appear in the HUD quick bar for fast use during combat. ### Skill lock (ml_skills) With ml_skills installed, an item can require an unlocked skill or a category level before it is usable. Locked items are stopped before the use animation starts and the message names the missing skill. The rule is enforced server-side and fails open, so a stopped ml_skills never locks players out of medical gear. requiredSkill and requiredLevel are optional fields in a medical item entry. **shared/config/items.lua** ```lua Config.Skills = { Enabled = false, FailOpen = true, XpOnSelfUse = false, HideLockedItems = false, } ['surgical_kit'] = { requiredSkill = { category = 'medico', skill = 'first_aid' }, requiredLevel = { category = 'medico', level = 5 }, } ``` - `Enabled`: turn the skill lock on. Off leaves every item usable (default). - `FailOpen`: if ml_skills is stopped or errors, allow the item anyway. - `XpOnSelfUse`: also grant item-use XP when a player treats themselves. - `HideLockedItems`: hide locked items from the medic panel. Off (default) keeps them listed and blocks them on use. ## Respawn **shared/config/respawn.lua** ```lua Config.RespawnSettings = { UISelection = true, GTAcam = true, ShowAllSpawns = true, RandomSpawn = false, FallbackSpawn = vector4(1651.01, 2543.6, 45.56, 53.03), CinematicCam = true, } ``` - `UISelection`: show the spawn-selection UI on death. - `GTAcam`: use the GTA selection camera. - `ShowAllSpawns`: show all spawn points instead of only the nearest. - `RandomSpawn`: pick a random spawn instead of showing the UI. - `FallbackSpawn`: fallback respawn coord. Replace the example with one valid on your map. - `CinematicCam`: enable the cinematic fly-in camera. `Config.StartSpawn` defines named spawn groups, each with a `label`, `center`, and a list of `spawns`. The shipped entry (`prison`, "Prison") is an example; replace its coordinates with your own hospitals or safe zones. `HospitalRespawn` selects this entry by its key, not its label. ### Bed respawn (hrs_base_building) **shared/config/respawn.lua** ```lua Config.HrsBase = { Enable = true, UseCinematicCam = false, Anim = { dict = 'switch@trevor@bed', name = 'trevor_bed_exit_f_trevor', duration = 8000, blendIn = 8.0, blendOut = -8.0, }, } ``` - `Enable`: offer "respawn in your own bed" when `hrs_base_building` is running. The option is gated by `GetResourceState`, so it is safe to leave enabled without the addon. - `UseCinematicCam`: cinematic camera on bed respawn. - `Anim`: bed exit animation. `Config.HrsBase.PropSettings` defines per-prop `zOffset` / `headingOffset`. ### Respawn tent **shared/config/respawn.lua** ```lua Config.RespawnTent = { Enabled = true, Item = 'respawn_tent', Model = `prop_skid_tent_01`, MaxPerPlayer = 2, PlacementRange = 50.0, InteractionDistance = 2.5, SpawnLOD = 200.0, Permissions = { Pickup = 'owner', Destroy = 'all', }, Placement = { RayCastDistance = 10.0, Anim = { dict = 'anim@narcotics@trash', name = 'drop_front', duration = 3000 }, }, SpawnOffset = vec3(0.0, 1.5, 1.0), } ``` - `Enabled`: `false` fully disables the tent feature. - `Item`: inventory item that starts placement (`respawn_tent`). - `Model`: tent prop. `prop_skid_tent_01` is a base-game GTA prop, no stream needed. - `MaxPerPlayer`: maximum active tents per player. - `PlacementRange`: max placement distance (m) and minimum distance between two tents. - `InteractionDistance`: distance (m) the target menu appears at. - `SpawnLOD`: distance (m) within which the prop renders. - `Permissions.Pickup` / `Destroy`: `'owner'` (only owner) or `'all'` (anyone nearby). Pickup returns the item; destroy does not. - `Placement.RayCastDistance`: aim range (m). - `Placement.Anim`: placement confirmation animation and progress-bar duration. - `SpawnOffset`: respawn offset from the tent so the player does not spawn inside the prop. Placed tents persist in the `ml_health_tents` table, created automatically. ## UI, Medic Jobs, Commands **shared/config/ui.lua** ```lua Config.MedicJobs = { 'medico', } Config.SelfAlwaysAdvanced = false Config.ScanUI = { Mode = 'modern', DragSensitivity = 1.0, CloseUpOnSelect = true, IntroDuration = 800, RevealMissingItems = true, } Config.Commands = { Revive = 'revive', ReviveRadius = 'reviveall', Debug = 'meddebug', } Config.HealthMenu = { Command = 'health', Keybind = false, } ``` - `MedicJobs`: jobs that get full medical info (exact BPM, blood liters, blood type, numeric severity, disease names). Non-medics see vague symptoms. Empty `{}` disables gating (everyone sees everything). - `SelfAlwaysAdvanced`: `true` gives every player full self-diagnosis even when not a medic. - `ScanUI.Mode`: `'modern'` (body labels + orbital camera) or `'classic'` (2D grid). - `ScanUI.DragSensitivity`: mouse drag sensitivity when rotating the camera. - `ScanUI.CloseUpOnSelect`: cinematic zoom when a body part is clicked. - `ScanUI.IntroDuration`: open-animation duration in ms (`0` instant). - `ScanUI.RevealMissingItems`: `true` shows valid-but-unowned items grayed out with a "MISSING" badge; `false` shows only owned items. - `Commands.Revive` / `ReviveRadius` / `Debug`: command names. Defaults are `/revive`, `/reviveall`, `/meddebug`. - `HealthMenu.Command`: chat command that opens the player's own health panel. `false` does not register it. - `HealthMenu.Keybind`: default key for that command, for example `'H'`. It is registered through the FiveM key mapping system, so players can rebind or clear it in the game settings. `false` leaves it unbound. Other resources can open the same panel with `exports.ml_healthsystem:OpenHealthPanel()`. ## Integrations **shared/config/integrations.lua** ```lua Config.RadiationIntegration = { Enabled = true, PollInterval = 5000, DiseaseName = 'radiazioni', CureThreshold = 2.0, EntryGrace = { Enabled = true, Duration = 15000, MaxRadiation = 15 }, RequireAntidoteForCure = true, Thresholds = { { level = 5, action = 'infect' }, { level = 250, action = 'accelerate', speedMult = 2 }, { level = 650, action = 'escalade', forceStage = 3 }, { level = 1000, action = 'escalade', forceStage = 4 }, }, CureItems = { ['radiation_antidote'] = 'all', }, } ``` - `Enabled`: connect to `ml_radiation`. - `PollInterval`: ms between radiation polls. - `DiseaseName`: disease applied (`radiazioni`). - `CureThreshold`: radiation level below which the disease may auto-cure. - `EntryGrace`: grace window on zone entry (`Duration` ms, `MaxRadiation`) before infect/accelerate/escalade fires. - `RequireAntidoteForCure`: `true` blocks natural-decay auto-cure; only the antidote cleans the player. - `Thresholds`: radiation levels that `infect`, `accelerate` (with `speedMult`), or `escalade` (with `forceStage`). - `CureItems`: items that also remove radiation. `'all'` clears it fully (recommended so the player is not re-infected on the next poll). **shared/config/integrations.lua** ```lua Config.ContactInfection = { Enabled = true, Disease = 'patogeno_vx_9', Chance = 35, SignalCooldown = 1000, } ``` - `Enabled`: master toggle for the contact-infection API. Inert until an external script calls it, so it is safe to ship enabled. - `Disease`: disease applied on contact (must exist in `diseases.lua`). - `Chance`: percent chance per contact. - `SignalCooldown`: minimum ms between client contact signals (anti-spam). **shared/config/integrations.lua** ```lua Config.ZombieBite = { Enabled = true, WeaponClass = 'ZOMBIE_BITE', Damage = 12, Infect = true, Chance = nil, Parts = { 'left_arm', 'right_arm', 'neck', 'chest', 'left_leg', 'right_leg' }, } ``` Bite wound for zombie and creature scripts, applied through `exports.ml_healthsystem:ApplyZombieBite`. Like the contact infection above, it stays inert until an external script calls it. - `Enabled`: master toggle for the bite API. - `WeaponClass`: entry in Config.WeaponClasses (shared/config/weapons.lua) that sets the bite bleeding and severity. - `Damage`: wound damage passed to the medical engine when the caller does not send its own. - `Infect`: also roll the contact infection on every bite. - `Chance`: infection chance in percent for a bite. `nil` uses the Chance of the contact infection above. - `Parts`: body zones a bite can land on when the caller does not pick one. **shared/config/integrations.lua** ```lua Config.LifePoints.Zones = { -- ['nuclear_plant'] = { -- type = 'sphere', coords = vec3(2700.0, 1500.0, 30.0), -- radius = 200.0, penalty = 25, label = 'Nuclear Plant', -- }, } ``` Geographic zones that apply an extra LifePoints penalty on death inside them. Each zone is `type = 'sphere'` (`coords` + `radius`) or `type = 'poly'` (`points` + `thickness`), plus a required `penalty` and a `label`. Ships empty (commented examples only). ## Open-Handler Events **shared/config/open.lua** ```lua Config.OpenHandlers = { EnableDeathEvent = true, EnableLastStandEvent = true, EnableRespawnEvent = true, } ``` - `EnableDeathEvent`: fire `ml_healthsystem:onPlayerDeath`. - `EnableLastStandEvent`: fire `ml_healthsystem:onPlayerLastStand`. - `EnableRespawnEvent`: fire `ml_healthsystem:onPlayerRespawned`. These hooks let the editable `open/` scripts react to lifecycle events. ## Server Config `server/config_server.lua` holds the server-only values: webhooks, LifePoints, inventory wipe, and reset behavior. A reference copy ships as `_INSTALL/config_server.example.lua`. ### Discord webhooks **server/config_server.lua** ```lua Config.Log = { AdminRevive = 'INSERT_WEBHOOK_LINK_HERE', AdminAction = 'INSERT_WEBHOOK_LINK_HERE', PlayerDeath = 'INSERT_WEBHOOK_LINK_HERE', PlayerRevive = 'INSERT_WEBHOOK_LINK_HERE', ItemUsed = 'INSERT_WEBHOOK_LINK_HERE', Treatment = 'INSERT_WEBHOOK_LINK_HERE', Disease = 'INSERT_WEBHOOK_LINK_HERE', Injury = 'INSERT_WEBHOOK_LINK_HERE', ExploitDetected = 'INSERT_WEBHOOK_LINK_HERE', LifePoints = 'INSERT_WEBHOOK_LINK_HERE', } ``` Each key logs one event category. Replace the placeholder with a webhook URL to enable that log; leave the placeholder (or set `false`) to disable it. ### Life Points **server/config_server.lua** ```lua Config.LifePoints.Enabled = true Config.LifePoints.StartingPoints = 100 Config.LifePoints.MinPoints = 0 Config.LifePoints.DefaultPenalty = 10 Config.LifePoints.PlayerKillPenalty = 3 Config.LifePoints.NPCOverrides = { [`Lurker`] = 7, [`Gasbag`] = 7, } Config.LifePoints.ExternalReasons = { ['radiazioni'] = 9, ['infezione'] = 5, ['patogeno_vx_9'] = 7, ['bleedout'] = 5, ['starvation'] = 2, ['dehydration'] = 2, ['overdose'] = 5, } Config.LifePoints.StaffPermissions = { 'god', 'admin', } Config.LifePoints.ExportAllowlist = {} ``` - `Enabled`: toggle the LifePoints system. - `StartingPoints`: points each character starts with. - `MinPoints`: floor (points cannot drop below this). - `DefaultPenalty`: points lost per death without a more specific rule. - `PlayerKillPenalty`: points lost when killed by another player. - `NPCOverrides`: per-NPC-model penalty overrides (hashed model names). - `ExternalReasons`: penalties for non-combat death causes. - `StaffPermissions`: ACE / framework group names exempt from penalties and allowed to call the modify exports. - `ExportAllowlist`: resources permitted to call `Set/Add/RemoveLifePoints`. Empty allows any server resource (still blocks non-staff player context); populate to restrict. > **WARNING:** Per-weapon penalties are escrowed > > `Config.LifePoints.PlayerKillWeapons` and per-weapon penalty values live in `internal/balance/weapon_penalties.lua` and cannot be edited. ### Inventory wipe **server/config_server.lua** ```lua Config.InventoryWipe = { Enabled = true, Whitelist = { ['water'] = true, ['id_card'] = true, ['driver_license'] = true, ['money'] = true, ['phone'] = true, }, } ``` - `Enabled`: wipe non-whitelisted inventory on respawn. - `Whitelist`: items kept on respawn; everything else is removed. The shipped list is a survival-server example, replace it with your server's protected items (IDs, licenses, owned weapons, blueprints). ### Revive and hospital reset **server/config_server.lua** ```lua Config.ReviveSettings = { RestoreHealth = true, RestoreBlood = true, ResetBleeding = true, ClearInjuries = true, ClearFractures = true, ClearCasts = true, ClearDiseases = true, ResetHungerThirst = true, } Config.HospitalReset = { RestoreHealth = true, RestoreBlood = true, ResetBleeding = true, ClearInjuries = true, ClearFractures = true, ClearCasts = true, ClearDiseases = true, ResetHungerThirst = true, } ``` - `ReviveSettings`: Defaults applied on admin revives and calls to `RevivePlayer`. The export accepts a partial settings table to override fields for one call. - `HospitalReset`: Defaults applied on hospital/safe-zone respawn and calls to `HospitalRespawn`. The export accepts a partial settings table to override fields for one call. Set `ClearFractures` / `ClearCasts` / `ClearDiseases` to `false` to keep fractures, casts, and diseases after hospital treatment. Medics can then treat fractures and diseases with casts and antibiotics. **server/config_server.lua** ```lua Config.ReviveSettings.ClearDiseases = false Config.HospitalReset.ClearDiseases = false ``` These set the global defaults for their respective flows. To keep diseases for a single call without changing the configuration, pass only the field to override: ```lua local ok, reason = exports.ml_healthsystem:RevivePlayer(source, { ClearDiseases = false }) ``` ```lua local ok, reason = exports.ml_healthsystem:HospitalRespawn(source, { ClearDiseases = false }) ``` Both exports accept the eight boolean fields listed above. Omitted fields inherit `Config.ReviveSettings` for `RevivePlayer` or `Config.HospitalReset` for `HospitalRespawn`. Neither export modifies the configuration or the supplied table. `RestoreHealth = false` keeps pre-reset health clamped between 101 and `Config.MaxHealth`. Preserved diseases, low blood volume, and bleeding continue their normal effects. > **WARNING:** Fracture/injury reset interaction > > `ClearFractures = false` with `ClearInjuries = true` causes a "ped slow after respawn / cannot sprint" bug because the leg fracture activates the limp clipset. Keep `ClearFractures = true` unless your medical workflow applies a cast post-respawn. ## Database Tables The resource creates three tables automatically on first start (no manual SQL): - `ml_healthsystem`: persisted per-character medical state (`identifier`, `health_data` LONGTEXT). Live in-session state runs on live states; this table is the save/load snapshot. - `ml_health_tents`: placed respawn tents bound to their owner. - `ml_lifepoints`: per-character life points.