> 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/es/policia-y-medico/cuxial-diseases/developers.md).

# Exports y eventos

API pública de Cuxial Diseases: exports, hooks y eventos para infectar, hacer pruebas, tratar y curar desde otros recursos.

Lee el estado médico de un personaje, cámbialo y reacciona a lo que le ocurre desde tus propios recursos.

Todos los exports de servidor reciben un `target` que puede ser un **id de servidor** (number) o un **citizenid** (string). Con un citizenid el export funciona también con el jugador desconectado.

## Leer casos

| Export                                 | Devuelve                                                                                                                                                                      |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GetCatalog()`                         | `table<string, table>`. Resumen de cada enfermedad: `id`, `label`, `category`, `icon`, `color`, `description`, `stages`, `testItem`, `treatmentItem`, `curable`, `cureSteps`. |
| `GetDiseaseDef(disease)`               | table \| nil. La entrada completa de `data/diseases.lua`.                                                                                                                     |
| `GetCases(target)`                     | `table[]`. Casos activos del personaje.                                                                                                                                       |
| `GetCase(target, disease)`             | table \| nil. Un caso activo. Sin `disease`, el más reciente.                                                                                                                 |
| `IsInfected(target, disease)`          | `boolean`. Sin `disease`, comprueba cualquier enfermedad.                                                                                                                     |
| `IsImmune(target, disease)`            | `boolean`.                                                                                                                                                                    |
| `GetHistory(target, limit)`            | `table[]`. Casos del personaje, curados incluidos. `limit` vale 50 por defecto, 200 como máximo.                                                                              |
| `GetLog(target, limit)`                | `table[]`. Registro del personaje: `caseId`, `event`, `detail`, `actor`, `at`. `limit` vale 50 por defecto, 200 como máximo.                                                  |
| `GetActiveCases(limit, onlyDiagnosed)` | `table[]`. Casos activos de todo el servidor. `limit` vale 100 por defecto, 500 como máximo. `onlyDiagnosed = true` devuelve solo los diagnosticados.                         |

```lua
if exports.cuxial_diseases:IsInfected(source, 'gripe') then
    local case = exports.cuxial_diseases:GetCase(source, 'gripe')
    print(case.stageLabel, case.treatmentActive)
end
```

### Caso

Forma de cada caso que devuelven los exports anteriores. Las fechas son marcas de tiempo Unix en segundos.

| Campo                                           | Tipo                    | Descripción                                                                                           |
| ----------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- |
| `id`                                            | number                  | Id del caso.                                                                                          |
| `citizenid`                                     | string                  | Personaje.                                                                                            |
| `disease`, `label`, `category`, `icon`, `color` | string                  | Enfermedad y cómo se presenta.                                                                        |
| `stage`, `stageLabel`                           | string                  | Etapa actual.                                                                                         |
| `stageIndex`, `stageCount`                      | number                  | Posición de la etapa y número de etapas.                                                              |
| `severity`                                      | string                  | `'mild'`, `'moderate'`, `'severe'` o `'critical'`.                                                    |
| `lethal`                                        | boolean                 | Si la etapa actual es letal.                                                                          |
| `status`                                        | string                  | `'active'`, `'controlled'` (hay una dosis activa) o `'cured'`.                                        |
| `diagnosed`, `diagnosedAt`, `diagnosedBy`       | boolean, number, string | Diagnóstico.                                                                                          |
| `infectedAt`, `infectedBy`                      | number, string          | Cuándo y por quién.                                                                                   |
| `stageSince`, `progressesAt`                    | number                  | Inicio de la etapa y cuándo cambia.                                                                   |
| `lastTreatment`, `treatmentUntil`               | number                  | Última dosis y fin de su efecto.                                                                      |
| `treatmentActive`                               | boolean                 | Si hay una dosis en efecto ahora.                                                                     |
| `treatmentDoses`                                | number                  | Dosis contadas hasta ahora.                                                                           |
| `cureStep`, `cureSteps`                         | number, table           | Pasos del plan de cura ya hechos, y el plan.                                                          |
| `cureStepAt`, `nextStepAt`                      | number                  | Cuándo se hizo el último paso, y desde cuándo se puede hacer el siguiente (`nil` si no tiene espera). |
| `curedAt`, `curedBy`                            | number, string          | Cura.                                                                                                 |
| `notes`                                         | string                  | Notas del médico.                                                                                     |

## Cambiar casos

### Infect

Da una enfermedad a un personaje.

```lua
exports.cuxial_diseases:Infect(target, disease, infectedBy, opts)
```

| Parámetro             | Tipo             | Descripción                                                                                    |
| --------------------- | ---------------- | ---------------------------------------------------------------------------------------------- |
| `target`              | number \| string | Id de servidor o citizenid.                                                                    |
| `disease`             | string           | `id` de `data/diseases.lua`.                                                                   |
| `infectedBy`          | string           | Origen, que se guarda con el caso. Opcional.                                                   |
| `opts.stage`          | string           | Etapa en la que empieza. La primera por defecto.                                               |
| `opts.ignoreImmunity` | boolean          | `true` infecta aunque el personaje sea inmune.                                                 |
| `opts.actor`          | number \| string | Quién lo hizo, para el registro.                                                               |
| `opts.deferStage`     | boolean          | `true` = si el personaje está desconectado, la etapa empieza a contar en su siguiente entrada. |

**Devuelve:** `boolean, string`. `true`, o `false` y un motivo: `'invalid_target'`, `'unknown_disease'`, `'already_infected'`, `'immune'` o `'db_error'`.

```lua
-- Comida en mal estado
local ok, reason = exports.cuxial_diseases:Infect(source, 'gastroenteritis', 'bad_food')
```

### RollContagion

Tira el contagio entre dos personajes cuando exactamente uno de ellos tiene la enfermedad. Usa `contagion.sexual` del catálogo.

```lua
exports.cuxial_diseases:RollContagion(first, second, disease, mods)
```

| Parámetro              | Tipo             | Descripción                                      |
| ---------------------- | ---------------- | ------------------------------------------------ |
| `first`, `second`      | number \| string | Los dos personajes.                              |
| `disease`              | string           | Enfermedad que se tira.                          |
| `mods.condomUsed`      | boolean          | Aplica `condomProtection`.                       |
| `mods.condomSabotaged` | boolean          | Anula la protección.                             |
| `mods.chanceOverride`  | number           | Porcentaje que se usa en lugar del del catálogo. |

**Devuelve:** `boolean, string`. Si alguien se ha infectado, y el motivo: `'infected'`, `'no_roll'`, `'protected'`, `'none_infected'`, `'both_infected'`, `'immune'`, `'no_sexual_contagion'` o `'invalid_target'`.

```lua
local infected = exports.cuxial_diseases:RollContagion(srcA, srcB, 'vih', { condomUsed = true })
```

### RunTest

Hace a un personaje la prueba de una enfermedad. Un resultado positivo marca el caso como diagnosticado.

```lua
exports.cuxial_diseases:RunTest(target, disease, actor, opts)
```

| Parámetro       | Tipo             | Descripción                                                                            |
| --------------- | ---------------- | -------------------------------------------------------------------------------------- |
| `target`        | number \| string | Id de servidor o citizenid.                                                            |
| `disease`       | string           | Enfermedad que se comprueba.                                                           |
| `actor`         | number \| string | Quién hace la prueba, para el registro. Opcional.                                      |
| `opts.accuracy` | number           | De 0 a 100. Por debajo de 70 añade probabilidad de resultado no concluyente. Opcional. |

**Devuelve:** `string`. `'negative'`, `'inconclusive'` o `'positive'`.

```lua
local result = exports.cuxial_diseases:RunTest(patient, 'neumonia', source)
```

### ApplyItem

Aplica un ítem que se ha consumido: una dosis por cada caso activo que trate, y la vacuna si es un `vaccine.item`. Úsalo cuando sea tu propio recurso el que gestiona el uso del ítem.

```lua
exports.cuxial_diseases:ApplyItem(target, item, actor)
```

**Devuelve:** `table[]`. Una entrada por efecto: `{ disease, label, effect }`, donde `effect` es `'dose'`, `'cured'` o `'vaccine'`. Las vacunas añaden `permanent` y `hours`. Vacía si el ítem no hizo nada.

```lua
local effects = exports.cuxial_diseases:ApplyItem(source, 'paracetamol', source)
```

### Diagnose

Marca un caso como diagnosticado.

```lua
exports.cuxial_diseases:Diagnose(target, disease, actor)
```

**Devuelve:** `boolean, string`. `false, 'not_infected'` si no hay caso.

```lua
exports.cuxial_diseases:Diagnose(patient, 'gripe', source)
```

### Treat

Aplica una dosis del tratamiento de una enfermedad.

```lua
exports.cuxial_diseases:Treat(target, disease, actor)
```

**Devuelve:** `boolean, string, boolean`. Si va bien: `true`, la etapa actual y si esa dosis ha curado la enfermedad. Si falla: `false` y `'not_infected'`, `'no_treatment'`, `'too_soon'` o `'invalid_target'`.

```lua
local ok, stage, cured = exports.cuxial_diseases:Treat(patient, 'gripe', source)
```

### AdvanceCureStep

Completa el paso actual del plan de cura. El último paso cura al paciente.

```lua
exports.cuxial_diseases:AdvanceCureStep(target, disease, actor)
```

**Devuelve:** `boolean, string, boolean, number`. Si va bien: `true`, el `id` del paso y si el paciente queda curado. Si falla: `false` y `'not_infected'`, `'no_cure_plan'` o `'too_soon'`; con `'too_soon'` el cuarto valor son los segundos que faltan.

```lua
local ok, step, cured, wait = exports.cuxial_diseases:AdvanceCureStep(citizenid, 'neumonia', source)
if not ok and step == 'too_soon' then
    print(('Siguiente paso en %d minutos'):format(math.ceil(wait / 60)))
end
```

{% hint style="info" %}
Retira el `item` del paso del inventario en tu recurso antes de llamar al export.
{% endhint %}

### Regress

Recaída: retrocede un paso en el plan de cura y anula el tratamiento activo. Pensado para el paciente que falta a una cita.

```lua
exports.cuxial_diseases:Regress(target, disease, actor)
```

**Devuelve:** `boolean, number | string`. `true` y el paso en el que queda el plan, o `false, 'not_infected'`.

```lua
exports.cuxial_diseases:Regress(citizenid, 'neumonia', 'no_show')
```

### Cure

Cura una enfermedad y aplica la inmunidad indicada en el catálogo.

```lua
exports.cuxial_diseases:Cure(target, disease, actor, reason)
```

| Parámetro | Tipo             | Descripción                                           |
| --------- | ---------------- | ----------------------------------------------------- |
| `target`  | number \| string | Id de servidor o citizenid.                           |
| `disease` | string           | Enfermedad que se cura. Sin él, el caso más reciente. |
| `actor`   | number \| string | Quién cura, para el registro. Opcional.               |
| `reason`  | string           | Se guarda en el registro. `'manual'` por defecto.     |

**Devuelve:** `boolean, string`. `false, 'not_infected'` si no hay caso.

```lua
exports.cuxial_diseases:Cure(source, 'gripe', 'hospital_bed', 'bed_rest')
```

### GrantImmunity

Hace a un personaje inmune a una enfermedad. Nunca acorta una inmunidad más larga.

```lua
exports.cuxial_diseases:GrantImmunity(target, disease, hours, source)
```

| Parámetro | Tipo             | Descripción                                                      |
| --------- | ---------------- | ---------------------------------------------------------------- |
| `hours`   | number \| string | Horas de inmunidad, o `'permanent'`.                             |
| `source`  | string           | Origen, que se guarda con la inmunidad. `'vaccine'` por defecto. |

**Devuelve:** `boolean`. `false` si la enfermedad no existe.

```lua
exports.cuxial_diseases:GrantImmunity(source, 'gripe', 72, 'event_reward')
```

### SetNotes

Guarda las notas del médico sobre un caso. Se cortan a 2000 caracteres.

```lua
exports.cuxial_diseases:SetNotes(target, disease, notes)
```

**Devuelve:** `boolean`.

## Hooks

Ejecuta tu código cuando le ocurre algo a un caso.

### onDisease

```lua
local handle = exports.cuxial_diseases:onDisease(event, fn)
```

**Devuelve:** `number`. Un identificador para quitar el hook más adelante.

### offDisease

```lua
exports.cuxial_diseases:offDisease(handle)
```

**Devuelve:** `boolean`.

```lua
local handle = exports.cuxial_diseases:onDisease('collapse', function(e)
    -- e.source es el id de servidor del paciente
    if e.source then TriggerEvent('my_ambulance:knockDown', e.source) end
end)
```

Cada hook se envía también como evento de servidor con el nombre `cuxial_diseases:<evento>`, con la misma tabla:

```lua
AddEventHandler('cuxial_diseases:cure', function(e)
    print(e.citizenid, e.disease, e.reason)
end)
```

| Evento               | Cuándo                             | Campos                                                      |
| -------------------- | ---------------------------------- | ----------------------------------------------------------- |
| `infect`             | Se crea un caso                    | `caseId`, `citizenid`, `disease`, `stage`, `infectedBy`     |
| `progress`           | Cambia la etapa                    | `caseId`, `citizenid`, `disease`, `from`, `stage`, `lethal` |
| `diagnose`           | Se diagnostica un caso             | `caseId`, `citizenid`, `disease`, `stage`, `by`             |
| `treat`              | Se aplica una dosis                | `caseId`, `citizenid`, `disease`, `stage`, `doses`          |
| `expire`             | Termina el efecto de una dosis     | `caseId`, `citizenid`, `disease`, `stage`                   |
| `routine_reset`      | El contador de dosis vuelve a cero | `caseId`, `citizenid`, `disease`, `stage`, `doses`          |
| `step`               | Se completa un paso de cura        | `caseId`, `citizenid`, `disease`, `step`, `total`, `stepId` |
| `regress`            | Una recaída                        | `caseId`, `citizenid`, `disease`, `stage`, `step`           |
| `cure`               | Se cura un caso                    | `caseId`, `citizenid`, `disease`, `stage`, `reason`         |
| `collapse`           | Colapsa una etapa letal            | `caseId`, `citizenid`, `disease`, `stage`, `source`         |
| `vaccine`            | Se aplica una vacuna               | `citizenid`, `disease`, `permanent`                         |
| `conceive`           | Empieza un embarazo                | `id`, `mother`, `father`                                    |
| `pregnancy_revealed` | Un embarazo pasa a ser conocido    | `id`, `mother`                                              |
| `pregnancy_month`    | Empieza un mes nuevo               | `id`, `mother`, `month`                                     |
| `labor`              | Empieza el parto                   | `id`, `mother`, `father`                                    |
| `birth`              | Nacimiento                         | `id`, `mother`, `father`, `reason`, `by`                    |
| `terminate`          | Se termina un embarazo             | `id`, `mother`, `reason`                                    |

## Embarazo

| Export                                      | Devuelve                                                                                                                                                                                                                                                           |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GetPregnancy(target)`                      | table \| nil. Embarazo activo: `id`, `mother`, `father`, `status`, `revealed`, `conceivedAt`, `dueDate`, `month`, `months`, `monthLabel`, `week`, `trimester`, `trimesterLabel`, `daysToBirth`, `secondsToBirth`, `labor`, `laborSince`, `laborDeadline`, `notes`. |
| `IsPregnant(target)`                        | `boolean`.                                                                                                                                                                                                                                                         |
| `IsFertile(target)`                         | `boolean`. Si el personaje está hoy dentro de la ventana fértil.                                                                                                                                                                                                   |
| `GetPregnancyHistory(target, limit)`        | `table[]`. Embarazos del personaje, con la misma forma. `limit` vale 20 por defecto, 100 como máximo.                                                                                                                                                              |
| `RollPregnancy(mother, father, stats)`      | boolean, number \| string. Tira un embarazo con las reglas de `fertility`. `stats` es opcional: `recentCount`, `lastEncounterAt`, `encounterRef`. Devuelve `true` y el id, o `false` y `'already_pregnant'` o `'no_roll'`.                                         |
| `Conceive(mother, father, opts)`            | boolean, number \| string. Inicia un embarazo sin tirada. `opts.encounterRef`, `opts.actor`. Falla con `'invalid_mother'` o `'already_pregnant'`.                                                                                                                  |
| `SetPregnancyEncounter(mother, ref)`        | `boolean`. Guarda en el embarazo una referencia numérica tuya.                                                                                                                                                                                                     |
| `PregnancyTest(target, actor)`              | `string`. `'positive'`, `'false_positive'` o `'negative'`. Un positivo marca el embarazo como conocido.                                                                                                                                                            |
| `RevealPregnancy(target, actor)`            | `boolean`. Marca el embarazo como conocido.                                                                                                                                                                                                                        |
| `StartLabor(target)`                        | `boolean`. Empieza el parto ahora.                                                                                                                                                                                                                                 |
| `DeliverBaby(target, actor, reason)`        | `boolean, string`. Registra el nacimiento. `false, 'not_pregnant'` si no hay embarazo.                                                                                                                                                                             |
| `TerminatePregnancy(target, actor, reason)` | `boolean, string`. Termina el embarazo.                                                                                                                                                                                                                            |
| `SetPregnancyNotes(target, notes)`          | `boolean`. Notas del médico.                                                                                                                                                                                                                                       |

```lua
local ok, id = exports.cuxial_diseases:RollPregnancy(motherSrc, fatherSrc, { recentCount = 2 })

local result = exports.cuxial_diseases:PregnancyTest(source, source)
if result == 'positive' then
    local info = exports.cuxial_diseases:GetPregnancy(source)
    print(info.week, info.daysToBirth)
end
```

{% hint style="info" %}
Tu recurso decide qué personaje es la madre antes de llamar a `RollPregnancy` o `Conceive`.
{% endhint %}

## Exports de cliente

### GetMyState

Devuelve el estado médico del jugador local, con los síntomas que tiene en efecto ahora mismo.

```lua
local cases = exports.cuxial_diseases:GetMyState()
```

**Devuelve:** `table[]`. Cada entrada trae `id`, `disease`, `label`, `icon`, `color`, `stage`, `stageLabel`, `severity`, `lethal`, `symptoms`, `treatmentActive`, `treatmentUntil` y `diagnosed`. `label` es `nil` mientras el paciente no sabe lo que tiene. Un embarazo es una entrada más, con `disease = 'pregnancy'`.

### IsSick

```lua
local sick = exports.cuxial_diseases:IsSick()
```

**Devuelve:** `boolean`. `true` cuando el estado tiene al menos una entrada, embarazo incluido.

```lua
if exports.cuxial_diseases:IsSick() then
    -- recuperación de aguante más lenta, un icono en el HUD...
end
```

### GetPregnancyState

```lua
local pregnancy = exports.cuxial_diseases:GetPregnancyState()
```

**Devuelve:** `table | nil`. `month`, `months`, `week`, `belly` y `labor` del embarazo del jugador local.

## Eventos de cliente

Los dos son eventos locales: escúchalos con `AddEventHandler` en un script de cliente.

| Evento                                   | Parámetros      | Cuándo                                                                                                                              |
| ---------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `cuxial_diseases:client:StateChanged`    | `cases`         | Cambia el estado médico del jugador. Misma tabla que `GetMyState`.                                                                  |
| `cuxial_diseases:client:TestResultShown` | `item, results` | El jugador ha usado un ítem de prueba. `results` lista los resultados no negativos: `{ disease, label, result }`. Vacía = negativo. |

```lua
AddEventHandler('cuxial_diseases:client:StateChanged', function(cases)
    SendNUIMessage({ action = 'sick', value = #cases > 0 })
end)
```


---

# 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/es/policia-y-medico/cuxial-diseases/developers.md?ask=<question>&goal=<user_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.