# corex-survival

> Three survival tracks (hunger, thirst, infection). Items auto-restore stats. Infection progresses through stages with escalating effects.

{% hint style="info" %}
**Depends on:** `corex-core` · **Version:** `1.0.0`
{% endhint %}

## Quick Facts

| Dependencies | Server Exports | Client Exports | Events |
| ------------ | -------------- | -------------- | ------ |
| `corex-core` | 7              | —              | 3      |

## Overview

Three independent tracks:

* **Hunger** drains over time, damages the player at critical levels
* **Thirst** same mechanism, different drain/damage rates
* **Infection** grows when bitten by zombies; progresses through 4 stages with increasing debuffs, ends at death

Items automatically restore the appropriate stat when used — the mapping lives in `Config.Items`.

## Quick Start

```cfg
ensure corex-core
ensure corex-survival
```

```lua
-- server: read / set
local h = exports['corex-survival']:GetPlayerHunger(source)
exports['corex-survival']:SetPlayerHunger(source, 100)
```

## Configuration

### Debug

`Config.Debug = false` — enables verbose survival-tick logging.

### Hunger / Thirst

Live in `Config.Hunger` and `Config.Thirst` respectively. Same schema for both:

| Field             | Hunger default | Thirst default | Description                                   |
| ----------------- | -------------- | -------------- | --------------------------------------------- |
| `maxValue`        | `100`          | `100`          | Cap                                           |
| `drainRate`       | `0.15`         | `0.20`         | Points lost per tick                          |
| `tickInterval`    | `30000`        | `30000`        | Ms between ticks                              |
| `effectThreshold` | `25`           | `25`           | Below this, debuffs kick in (shake, slowness) |
| `damageThreshold` | `5`            | `5`            | Below this, player takes HP damage            |
| `damageAmount`    | `3`            | `4`            | HP per damage tick                            |

### Infection

```lua
Config.Infection = {
    enabled = true,
    biteChance = 0.15,          -- 15% chance per zombie bite
    growthRate = 0.5,           -- points added per growth tick
    growthInterval = 60000,     -- ms between growth ticks
    stages = {
        { threshold = 25,  effects = {'shake'} },
        { threshold = 50,  effects = {'shake', 'slowness'} },
        { threshold = 75,  effects = {'shake', 'slowness', 'cough', 'screenDistort'} },
        { threshold = 100, effects = {'death'} },
    },
}
```

Stages activate when infection meets or exceeds their `threshold`.

### Effects

`Config.Effects` tunes the visual/audio strength of each debuff:

| Field                   | Default                | Description                                 |
| ----------------------- | ---------------------- | ------------------------------------------- |
| `shakeIntensity`        | `0.3`                  | Camera shake strength                       |
| `slowMultiplier`        | `0.7`                  | Movement speed reduction (0.7 = 30% slower) |
| `screenDistortStrength` | `0.3`                  | Distort shader intensity                    |
| `coughDict`             | `'mp_player_intdrink'` | Cough animation dict                        |
| `coughAnim`             | `'loop_bottle'`        | Cough animation name                        |
| `coughDuration`         | `2000`                 | Ms per cough                                |
| `coughCooldown`         | `15000`                | Ms between coughs                           |

### Items

`Config.Items` maps item names to their survival effect:

```lua
Config.Items = {
    ['canned_food']   = { stat = 'hunger',    amount = 35 },
    ['raw_meat']      = { stat = 'hunger',    amount = 15, infectionRisk = 0.10 },
    ['cooked_meat']   = { stat = 'hunger',    amount = 50 },
    ['clean_water']   = { stat = 'thirst',    amount = 40 },
    ['dirty_water']   = { stat = 'thirst',    amount = 20, infectionRisk = 0.10 },
    ['energy_drink']  = { stat = 'thirst',    amount = 25 },
    ['bread']         = { stat = 'hunger',    amount = 20 },
    ['water']         = { stat = 'thirst',    amount = 25 },
    ['antidote']      = { stat = 'infection', cure = true },
    ['painkillers']   = { stat = 'infection', pause = 300000 },  -- 5 min
    ['antibiotics']   = { stat = 'infection', reduce = 25 },
    ['bandage']       = { stat = 'health',    amount = 25 },
    ['medkit']        = { stat = 'health',    amount = 100, fullHeal = true },
}
```

Effect shapes:

| Shape                                 | Meaning                                    |
| ------------------------------------- | ------------------------------------------ |
| `{ stat, amount }`                    | Adds `amount` to the named stat            |
| `{ stat, amount, infectionRisk }`     | Same, but with a chance to raise infection |
| `{ stat='infection', cure=true }`     | Full cure                                  |
| `{ stat='infection', pause=ms }`      | Pauses infection growth for N ms           |
| `{ stat='infection', reduce=N }`      | Reduces infection by N                     |
| `{ stat='health', amount, fullHeal }` | Restores HP; `fullHeal` overrides amount   |

When a player uses an item that appears in `Config.Items`, `corex-survival` applies the effect. Integration works via `corex-inventory`'s `corex-inventory:server:itemUsed` event.

## Server Exports

* `GetPlayerHunger(source)` → `number`
* `GetPlayerThirst(source)` → `number`
* `GetPlayerInfection(source)` → `number`
* `SetPlayerHunger(source, value)` → `boolean`
* `SetPlayerThirst(source, value)` → `boolean`
* `SetPlayerInfection(source, value)` → `boolean`
* `IsInfectionPaused(source)` → `boolean` (true while a painkiller timer is active)

## Events

Server-side:

* `corex-survival:server:drainTick` — internal tick between client and server
* `corex-survival:server:useItem` — item consumption gated through survival
* `corex-survival:server:zombieHit` — bite-infection resolution

Client-side:

* `corex-survival:client:applyHealthDelta(delta)` — server pushes an HP delta to apply
* `corex-survival:client:zombieHit` — client-side hook for bite effect (fired by `corex-zombies`)

### Listens to

* `corex-inventory:client:useItem` — detect food/water/medicine use via the `Config.Items` map
* `corex-survival:client:zombieHit` — from corex-zombies

{% hint style="info" %}
If you want to observe survival state changes, poll via the exports (`GetPlayerHunger/Thirst/Infection`) or subscribe to the metadata StateBag. There's no "stat crossed threshold" event — watch the values yourself.
{% endhint %}

## Troubleshooting

**Stats don't appear on the HUD.** → `corex-hud` isn't ensured, or its flags (`Config.ShowHunger`, `Config.ShowThirst`) are false.

**Infection doesn't pause with painkillers.** → `Config.Items['painkillers']` has `pause = 300000` (5 minutes). If infection keeps climbing, verify `corex-inventory` is firing `itemUsed` for painkillers, and that `IsInfectionPaused(source)` returns true after use.

**Infection stays at 0 despite bites.** → `biteChance = 0.15` means only \~1 in 7 bites infect. Raise for easier testing: `Config.Infection.biteChance = 1.0`.

**Stats reset on reconnect.** → Persistence broken. Verify `metadata.hunger / thirst / infection` exists: `SELECT JSON_EXTRACT(metadata, '$.hunger') FROM players WHERE identifier = ?`.

**Adding a new food item.** → 1) add the item to `corex-inventory/shared/items.lua`, 2) add it to `Config.Items` in `corex-survival/config.lua` with the appropriate `stat` and `amount`.

## Further reading

* [Resources → corex-inventory](https://corex-zombies.gitbook.io/corex-docs/resources/systems/corex-inventory) — `itemUsed` event
* [Resources → corex-hud](https://corex-zombies.gitbook.io/corex-docs/resources/player/corex-hud) — the bars these stats drive


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://corex-zombies.gitbook.io/corex-docs/resources/player/corex-survival.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.