> For the complete documentation index, see [llms.txt](https://code-after-sex.gitbook.io/script-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://code-after-sex.gitbook.io/script-documentation/cas-metabolism/cas-metabolism.md).

# CAS Metabolism

A complete survival and HUD system for **RedM** (`cas-metabolism`). It layers hunger, thirst, stress, sleep, cleanliness, temperature and intoxication onto a themeable HUD, with an XP/level system and a rich exports API for other resources.

## Highlights

* **Needs** — hunger and thirst with activity-based decay (idle/walk/run/sprint/mounted/swim)
* **Starvation & dehydration** damage with configurable delay and ticks
* **Stress system** — speed/shooting stress, screen shake, ragdoll and optional damage
* **Sleep system** — drowsiness, microsleep, knockout and beds/bedrolls
* **Cleanliness, temperature** (campfire warmth, interiors) and **intoxication** (drunk walking, vomiting, overconsume)
* **Themeable HUD** — themes, color presets, minimap styles and configurable colors
* **XP / level system** with client and server exports
* **Database persistence** with per-character support

## At a glance

|               |                                                                                    |
| ------------- | ---------------------------------------------------------------------------------- |
| Platform      | RedM                                                                               |
| Notifications | `cas-simplenotify`, `cas-notification`, `vorp` or `rsg`                            |
| Voice display | `pma`, `salty`, `mumble` or `auto`                                                 |
| Resource name | `cas-metabolism`                                                                   |
| Config files  | `config/client_config.lua`, `config/server_config.lua`, `config/shared_config.lua` |

## Installation

1. Place `cas-metabolism` in your `resources` directory.
2. Add `ensure cas-metabolism` to your `server.cfg`.
3. Configure the three config files (below) and restart.

## Configuration

### Client — `config/client_config.lua`

Commands (`hudsettings`, `hudvisible`, `hudshowsprint`), `VoiceSystem`, `Notification`, `MaxHealth`, `DefaultHudTheme` (`western` / `minimal` / `wave`), plus every subsystem:

```lua
Config.HungerDecreaseTimer = 10    -- every 10s
Config.HungerDecreaseAmount = 0.4  -- -0.4%
Config.ThirstDecreaseTimer = 15
Config.ThirstDecreaseAmount = 0.4
Config.Running = { HungerDecreaseTimer = 5, HungerDecreaseAmount = 0.8, ThirstDecreaseTimer = 7, ThirstDecreaseAmount = 0.8 }
Config.ActivityMultipliers = { idle = {}, walk = {}, run = {}, sprint = {}, mounted = {} }
```

Further blocks control starvation (`StarvationDamageDelay` / `Interval` / `Amount`), the stress system (`StressSettings`), the sleep system (`SleepSettings` — drowsy / microsleep / knockout / beds), cleanliness, temperature (`CampfireWarmth`, `InteriorTempBalance`), intoxication (`Vomit`, `OverConsume`, drunk walking styles), HUD colors, color presets and minimap styles.

### Server — `config/server_config.lua`

```lua
Config.Database = {
    Enabled = true,
    Table = "cas_metabolism",
    SaveIntervalMs = 60000,
    AlsoSyncFramework = true,
    UseCharacterIdentifier = true,
}
```

### Items — `config/shared_config.lua` → `Config.ItemsToUse`

Each consumable defines what it restores plus its animation and effects:

```lua
{
    Name = "bread", Thirst = 50, Hunger = 300, Metabolism = 150, Stamina = 50,
    InnerCoreHealth = 20, OuterCoreHealth = 10, PropName = "p_bread01x",
    stress = { mode = "decrease", value = 5 }, drunk = { mode = "decrease", value = 0 },
    Animation = "eat",          -- eat, drink, coffee, stew, smoke, chew, bandage, syringe
    GiveBackItem = "", GiveBackItemAmount = 1,
    coffeeBuff = { enabled = false, durationMinutes = 15, sleepReduction = 20 }
}
```

Animations, effects, prop models, gold cores, give-back items and coffee buffs are all per-item. Tobacco prompt keys live in `Config.Prompts`.

## Exports (selected)

Called as `exports['cas-metabolism']:Fn(...)`.

* **Client, generic:** `Get(keyPath)`, `Set(keyPath, value, opts)`, `Add(keyPath, delta, opts)`, `getAllMetabolismValues()`, `ApplyVitalsFromValues()`
* **Client, specific:** `GetHunger` / `SetHunger` / `AddHunger` (and the same for Thirst, Stress, Drunk, Sleep), plus `Get`/`SetHealthInner`/`Outer` and `Get`/`SetStaminaInner`/`Outer`
* **Server, levels:** `getXP(id)`, `addXP(amount, id, source)`, `removeXP(amount, id, source)`, `getLevel(id)`, `getPlayerLevelData(id)` — 100 XP = 1 level

```lua
if exports['cas-metabolism']:GetHunger() < 20 then return end
exports['cas-metabolism']:AddHunger(-15)
```

## Support

Join the [CAS Discord](https://discord.gg/X8bTK9Stwk) or use the support channel on your product page.