> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/police-and-medical/cuxial-diseases/configuration.md). # Configuration Every option of Cuxial Diseases explained: config, the disease catalog, how to add a disease and pregnancy. Everything you can adjust lives in three files: `shared/config.lua` for behaviour, `data/diseases.lua` for the disease catalog and `data/pregnancy.lua` for pregnancy. Restart the resource after any change. {% hint style="info" %} Stage, treatment, vaccine and immunity times are **real hours** and keep counting while the player is offline. Symptom intervals are **minutes of play**: they only count while the player is connected. {% endhint %} ## General | Option | Type | Default | What it does | | ------- | ------- | ------- | ------------------------------------------------------------------------------------------------ | | `debug` | boolean | `false` | Prints traces to the console. Also enabled by setting the convar `cuxial_diseases_debug` to `1`. | ## Proximity contagion · `proximity` Only affects diseases that have `contagion.proximity` in the catalog. | Option | Type | Default | What it does | | ------------------ | ------------- | ------------- | ------------------------------------------------------------------------------------------------- | | `enabled` | boolean | `false` | `true` lets sick players infect whoever is near. `false` disables proximity contagion completely. | | `tickSeconds` | number | `30` | Seconds between contagion checks. | | `maskItem` | string \| nil | `'face_mask'` | Item that protects whoever carries it in the inventory. `nil` = nothing protects. | | `maskProtection` | number | `85` | Percentage of the risk removed by the mask, from 0 to 100. | | `indoorMultiplier` | number | `1.5` | Multiplier of the risk when the exposed player is inside an interior. | ## Symptoms · `symptoms` | Option | Type | Default | What it does | | -------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `enabled` | boolean | `true` | `true` makes players feel the symptoms. `false` keeps diseases, stages and treatments, with no effect in game, health loss included. | | `skipWhenDead` | boolean | `true` | `true` pauses symptoms while the player is dead or unconscious. `false` keeps them going. | | `sounds` | boolean | `true` | `true` plays a voice groan with cough and vomiting. `false` = silent. | ## Collapse · `collapse` | Option | Type | Default | What it does | | -------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------- | | `graceMinutes` | number | `15` | Minutes of margin given to a player who logs in with a collapse already overdue, so they can look for medical care first. | ## Schedules · `cron` Cron format: minute, hour, day, month, day of the week. | Option | Type | Default | What it does | | ------------- | ------ | --------------- | ---------------------------------------------------------------- | | `progression` | string | `'*/5 * * * *'` | Stage changes, treatments running out and broken dose routines. | | `pregnancy` | string | `'*/5 * * * *'` | Pregnancy months, start of labour and automatic birth. | | `onboarding` | string | `'*/5 * * * *'` | Expired vaccination deadlines and the last reminder. | | `cleanup` | string | `'0 4 * * *'` | Deletes old cured cases, expired immunities and old log entries. | ## Retention · `retention` | Option | Type | Default | What it does | | ---------------- | ------ | ------- | --------------------------------------------- | | `curedCasesDays` | number | `90` | Days that cured cases and their log are kept. | ## Immunity · `immunity` | Option | Type | Default | What it does | | -------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------- | | `defaultHours` | number | `24` | Hours of immunity after being cured, for diseases that do not set `cure.immunityHours`. `0` = no immunity. | ## Vaccination deadline · `onboarding` With `enabled = true`, each character gets a deadline to be vaccinated against one disease. When it expires without a vaccine, they catch it. | Option | Type | Default | What it does | | --------------------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | `false` | `true` applies the deadline. `false` = no deadline. | | `hours` | number | `24` | Hours given to characters created after the script was installed. | | `applyToExisting` | boolean | `false` | `true` also gives a deadline to characters that already existed. `false` leaves them exempt. | | `hoursExisting` | number | `72` | Hours given to characters that already existed, counted from their first login. | | `disease` | string | example id | Disease caught when the deadline expires. An `id` from `data/diseases.lua`. If the id does not exist, the deadline is disabled. | | `vaccineItem` | string | example item | Vaccine item shown to the player in the Health app. | | `reminderHoursBefore` | number | `2` | Hours before the deadline at which the last reminder is sent. | How it behaves: * On first start the script stores the highest character id of your server. Characters above it count as new; the rest count as existing. * The player is told the deadline when it is created and reminded at every login. * Any vaccine for `disease` fulfils the deadline. A character who is already immune or already sick is exempt. * If the deadline expires while the player is offline, they are infected anyway and the stage starts counting at their next login. ## Diagnosis · `diagnosis` | Option | Type | Default | What it does | | ----------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `revealToPatient` | boolean | `false` | `false` hides the name of the disease from the patient until it is diagnosed; they only feel the symptoms. `true` shows it from the start. | A case becomes diagnosed with a positive test, from the MDT of Cuxial Police, with `/disease diagnose` or with the `Diagnose` export. ## Staff · `admin` | Option | Type | Default | What it does | | ------------ | ------ | --------------- | ---------------------------------------------------------------------------- | | `permission` | string | `'admin'` | Framework permission checked through `cuxial_bridge` when a command is used. | | `restricted` | string | `'group.admin'` | ACE group that the commands `/disease` and `/pregnancy` are limited to. | ## Phone app · `app` Only used when `lb-phone` is running. | Option | Type | Default | What it does | | ------------- | --------- | ----------------- | ------------------------------------------------------------------------------------ | | `enabled` | boolean | `true` | `true` registers the app on the phone. `false` = no app. | | `identifier` | string | `'cuxial-salud'` | Internal identifier of the app. | | `name` | string | text | Name shown on the phone. | | `description` | string | text | Description in the app store. | | `developer` | string | text | Developer shown in the app store. | | `defaultApp` | boolean | `false` | `true` = installed on every phone. `false` = players download it from the app store. | | `categories` | string\[] | `{ 'Lifestyle' }` | Categories in the app store. | ## The disease catalog · `data/diseases.lua` The file returns a table where each key is the `id` of a disease. The script knows no disease by name: everything comes from this file. The included diseases are a starting point to edit, replace or delete. {% hint style="info" %} Names, stage labels and descriptions are free text in this file. Write them in the language of your server. {% endhint %} ### Disease | Field | Type | What it does | | ----------------- | ------------ | ----------------------------------------------------------------------------------------------------------- | | `label` | string | Name of the disease. | | `category` | string | Group used for display, such as `'respiratory'` or `'digestive'`. | | `icon` | string | Font Awesome icon, with the `fa-` prefix. | | `color` | string (hex) | Colour of the disease in the interfaces. | | `description` | string | Text for the doctor. | | `contagion` | table | How it is caught. See below. | | `incubationHours` | number | Hours after infection during which a test can come back inconclusive. `0` = detected from the first moment. | | `stages` | list | Stages in order. Required, at least one. | | `test` | table | `{ item, inconclusiveChance, external }`. Optional. | | `vaccine` | table | `{ item, immunityHours }` or `{ item, permanent = true }`. Optional. | | `treatment` | table | Doses that control the disease. Optional. | | `cure` | table | `{ steps, immunityHours }`. Cure plan applied by a doctor. Optional. | ### `contagion` | Field | What it does | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `proximity = { radius, chance, stages }` | Caught by being near a sick player. `radius` in metres, `chance` as a percentage per check, `stages` is the list of stage ids that are contagious. Needs `proximity.enabled = true` in the config. | | `sexual = { chance, condomProtection }` | Caught in an encounter between two characters, through the `RollContagion` export. Both are percentages. | | `manual = true` | Only caught through an export, a command or the vaccination deadline. | ### `stages` | Field | Type | What it does | | ------------------ | ------- | ------------------------------------------------------------------------- | | `id` | string | Identifier of the stage. Unique inside the disease. | | `label` | string | Name of the stage. | | `severity` | string | `'mild'`, `'moderate'`, `'severe'` or `'critical'`. | | `durationHours` | number | Real hours until the next stage. Without it, the stage does not advance. | | `lethal` | boolean | `true` = lethal stage. See [Lethal stages](#lethal-stages). | | `lethalAfterHours` | number | Hours between collapses in a last stage that is lethal. `6` when omitted. | | `symptoms` | table | Symptoms of the stage. `{}` = none. | ### `symptoms` `min` and `max` are the minutes between two episodes; each interval is picked at random between them. | Symptom | Shape | Effect | | ------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | `cough` | `{ min, max }` | Cough animation with voice. Not played inside a vehicle. | | `dizziness` | `{ min, max }` | Stumble and a short screen distortion. Not played inside a vehicle. | | `vomit` | `{ min, max }` | Vomiting animation with voice. Not played inside a vehicle. | | `fatigue` | `{ min, max }` | Out of breath animation. Does not change the movement speed. Not played inside a vehicle. | | `blur` | `{ min, max }` | Blurred vision for 2.5 seconds. | | `shake` | `{ min, max }` | Camera shake for 2.5 seconds. | | `healthDrain` | `{ min, max, minDamage, maxDamage }` | Removes between `minDamage` and `maxDamage` health points. Never kills on its own: health stops at the minimum. | A symptom that cannot play because the player is in a vehicle or in the middle of another animation is tried again 30 to 60 seconds later. ### `test` | Field | Type | What it does | | -------------------- | ------- | -------------------------------------------------------------------------------------- | | `item` | string | Item that tests for this disease. One item can test several diseases at once. | | `inconclusiveChance` | number | Percentage of inconclusive results. Only applies during `incubationHours`. | | `external` | boolean | `true` = the item is handled by another resource and this script does not register it. | A positive result marks the case as diagnosed. ### `vaccine` | Field | Type | What it does | | --------------- | ------- | -------------------------------------- | | `item` | string | Vaccine item. | | `immunityHours` | number | Hours of immunity. `168` when omitted. | | `permanent` | boolean | `true` = immune for good. | A vaccine has no effect on a character who already has that disease. ### `treatment` | Field | Type | What it does | | ----------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `item` | string | Item of one dose. | | `effectHours` | number | Hours that one dose lasts. `6` when omitted. | | `preventsProgression` | boolean | `true` = while a dose is active the stage does not advance; each dose pushes the stage deadline back by the time it covers. | | `suppressSymptoms` | boolean | `true` = no symptoms while a dose is active. | | `reducesSymptoms` | number \| boolean | With a dose active, cough and vomiting appear that fraction of the time (`0.5` = half as often) and every other symptom stops. `0.33` when omitted. `false` = symptoms are not reduced. | | `minIntervalHours` | number | Minimum hours between two doses. Without it, the next dose is only accepted when the previous one has run out. | | `curesAfterDoses` | number | Doses that cure the disease. Without it the disease is chronic: it is controlled, never cured by doses. | | `resetAfterHours` | number | Hours since the last dose after which the routine counts as broken and the dose count goes back to zero. Twice `effectHours` when omitted. `0` = never. Only with `curesAfterDoses`. | | `box = { item, count }` | table | A box item that gives `count` units of `item` when opened. `count` is `7` when omitted. | ### `cure` A plan of steps that a doctor completes one by one. The last step cures the patient. | Field | Type | What it does | | --------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `steps[n].id` | string | Identifier of the step. | | `steps[n].label` | string | Name of the step. | | `steps[n].kind` | string | `'item'`, `'procedure'` or `'appointment'`. An `'item'` step also counts as one dose of the treatment. | | `steps[n].item` | string | Item spent by the step. It is removed by the resource that applies the step. | | `steps[n].hours` | number | Real hours to wait before this step, counted from the previous step, or from the diagnosis for the first one. | | `steps[n].minigame` | string | Minigame used by EMS to apply the step in Cuxial Police, for example `'injection'`. Without it, the step is completed from the patient file or the appointment. | | `steps[n].difficulty` | number | Difficulty of the minigame: `1` easy, `2` normal, `3` hard. | | `immunityHours` | number | Hours of immunity when cured. `immunity.defaultHours` when omitted, `0` = none. It never shortens a longer or permanent immunity. | {% hint style="info" %} The cure plan is applied from the MDT of Cuxial Police, or from your own resource with the `AdvanceCureStep` export. Diseases with `treatment.curesAfterDoses` are also cured by taking the doses. {% endhint %} ### Lethal stages A stage with `lethal = true` can make the patient collapse in two ways: * **By health.** When `healthDrain` leaves the patient at minimum health, they collapse. At most once every five minutes. * **By time.** Only in the last stage of the disease. Every `lethalAfterHours` without an active treatment, the patient collapses if they are online. A collapse knocks the patient down through `cuxial_medical`. Without that resource the script only sends the `collapse` event, for you to handle from your own ambulance script. See [Exports & events](/scripts/police-and-medical/cuxial-diseases/developers.md#hooks). ## Add your own disease {% stepper %} {% step %} ### Add the entry Open `data/diseases.lua` and add a new key inside the returned table. The key is the `id`: one word without spaces, 40 characters at most. {% code title="data/diseases.lua" %} ```lua bronchitis = { label = 'Bronchitis', category = 'respiratory', icon = 'fa-lungs', color = '#38bdf8', description = 'Inflammation of the airways. Syrup every eight hours and a review.', contagion = { proximity = { radius = 2.5, chance = 3, stages = { 'acute' } }, }, incubationHours = 3, stages = { { id = 'early', label = 'Early', severity = 'mild', durationHours = 6, symptoms = {} }, { id = 'acute', label = 'Acute', severity = 'moderate', durationHours = 36, symptoms = { cough = { min = 4, max = 9 }, fatigue = { min = 5, max = 10 }, }, }, { id = 'chronic', label = 'Chronic', severity = 'severe', symptoms = { cough = { min = 2, max = 5 }, healthDrain = { min = 10, max = 20, minDamage = 1, maxDamage = 2 }, }, }, }, test = { item = 'rapid_test', inconclusiveChance = 25 }, treatment = { item = 'bronchitis_syrup', effectHours = 8, preventsProgression = true, reducesSymptoms = 0.5, curesAfterDoses = 4, }, cure = { steps = { { id = 'nebulizer', label = 'Nebulizer session', kind = 'procedure' }, { id = 'review', label = 'Review', kind = 'appointment', hours = 24 }, }, immunityHours = 48, }, }, ``` {% endcode %} This disease spreads by proximity during its `acute` stage, shows up on the rapid test, is controlled with a syrup and is cured after four doses. The last stage has no `durationHours`, so it stays there until treated. {% endstep %} {% step %} ### Create its items Every new item named in the entry needs a definition in your inventory. Here only the syrup is new: {% code title="ox\_inventory/data/items.lua" %} ```lua ['bronchitis_syrup'] = { label = 'Bronchitis syrup', weight = 100, stack = true, close = true, description = 'One dose every eight hours.', server = { export = 'cuxial_diseases.bronchitis_syrup', }, }, ``` {% endcode %} {% endstep %} {% step %} ### Restart and test Restart the server so the inventory loads the new item. Check the new disease with the staff commands: ``` /disease list /disease infect bronchitis /disease stage bronchitis acute /disease status ``` {% endstep %} {% endstepper %} {% hint style="warning" %} Do not rename or delete the `id` of a disease that players already have. Their cases stay in the database but stop being processed. {% endhint %} ## Common changes **Turn on proximity contagion** ```lua proximity = { enabled = true, -- ... }, ``` **Let the patient see what they have without a diagnosis** ```lua diagnosis = { revealToPatient = true, }, ``` **Make a disease slower.** Raise `durationHours` in each stage of `data/diseases.lua`. **Make a disease chronic.** Remove `curesAfterDoses` from its `treatment`. **Diseases without effects in game.** Set `symptoms.enabled = false`. ## Pregnancy · `data/pregnancy.lua` Pregnancy is followed like one more medical state. Conception is decided by another resource through the exports, or by staff with `/pregnancy`. ### Presentation and time | Option | Type | Default | What it does | | ------------------------ | ------ | ------------------------------- | -------------------------------------------- | | `label`, `icon`, `color` | string | text, `'fa-baby'`, configurable | How the pregnancy appears in the interfaces. | | `time.daysPerMonth` | number | `3` | Real days that one month of pregnancy lasts. | | `time.months` | number | `9` | Months until birth. | ### Fertility · `fertility` Used by the `RollPregnancy` export. | Option | Type | Default | What it does | | ---------------------------------------- | ------ | ---------- | ----------------------------------------------------------------- | | `baseChance` | number | `5` | Base percentage per unprotected encounter. | | `fertileMultiplier` | number | `3.0` | Multiplier inside the fertile window. | | `cycleLength` | number | `28` | Days of the cycle. | | `fertileWindowStart`, `fertileWindowEnd` | number | `12`, `16` | First and last day of the fertile window. | | `frequencyBonus` | number | `0.1` | Increase per recent encounter (`0.1` = +10 %). | | `frequencyMultMax` | number | `1.5` | Highest multiplier that recent encounters can reach. | | `recentCooldownHours` | number | `1` | Hours since the last encounter below which the chance is reduced. | | `recentReduction` | number | `0.5` | Multiplier applied in that case. | | `maxChance` | number | `60` | Highest percentage after everything is applied. | ### Test · `test` | Option | Type | Default | What it does | | --------------------- | ------ | ------- | --------------------------------------------------------- | | `falsePositiveChance` | number | `8` | Percentage of false positives when there is no pregnancy. | | `minHoursToDetect` | number | `12` | Hours since conception from which the test detects it. | ### Belly · `belly` | Option | Type | Default | What it does | | ----------- | --------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | `enabled` | boolean | `false` | `true` swaps a clothing piece for a belly as the months go by and restores it after birth. `false` = no clothing change. | | `component` | number | `11` | Clothing component replaced: `11` torso, `8` undershirt, `3` arms. | | `models` | string\[] | `{ 'mp_f_freemode_01' }` | Character models it applies to. | | `stages` | list | four entries | `{ fromMonth, drawable, texture }`: clothing piece used from that month on. | {% hint style="warning" %} Before setting `belly.enabled = true`, put the belly clothing of your server in the `drawable` and `texture` values of `belly.stages`. {% endhint %} ### Months · `months` One entry per month, from `[1]` to `[9]`. | Field | Type | What it does | | ---------- | ------- | -------------------------------------------------------------------------------------------------------- | | `label` | string | Name of the month. | | `symptoms` | table | Symptoms of the month, same shape as in the diseases. | | `message` | string | Notice sent to the mother when the month starts. A locale key or a literal text. | | `checkup` | boolean | `true` = schedules a check-up appointment that month. Needs Cuxial Police and a pregnancy already known. | ### Check-ups · `checkups` Only with Cuxial Police running. | Option | Type | Default | What it does | | ---------------------- | ------- | ------- | --------------------------------------------------------------------------------------- | | `enabled` | boolean | `true` | `true` creates the appointments automatically. `false` = the doctor books them by hand. | | `kind`, `subtype` | string | text | Type and subtype of the appointment in the MDT agenda. | | `hoursAfterMonthStart` | number | `6` | Hours after the month change at which the appointment is set. | | `durationMin` | number | `20` | Length of the appointment in minutes. | ### Labour · `labor` | Option | Type | Default | What it does | | -------------------- | ------- | ---------------------- | ---------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | `true` | `true` = when the date arrives, contractions start. `false` = the baby is born on its own on the due date. | | `durationMin` | number | `30` | Minutes to be attended before the birth happens outside the hospital. | | `contractionsEvery` | table | `{ min = 2, max = 4 }` | Minutes between contractions. | | `contractionSeconds` | number | `4` | Seconds that each contraction lasts. | | `notifyFather` | boolean | `true` | `true` also notifies the father. `false` = only the mother. | | `alertEms` | boolean | `true` | `true` sends an alert to EMS when labour starts. Needs Cuxial Police. | | `appointment` | boolean | `true` | `true` creates the birth appointment in the agenda. Needs Cuxial Police and a pregnancy already known. | Labour only starts while the mother is connected. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.cuxial.com/scripts/police-and-medical/cuxial-diseases/configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.