> For the complete documentation index, see [llms.txt](https://ccfivem.gitbook.io/ccfivem-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ccfivem.gitbook.io/ccfivem-docs/player-and-ui/basic-needs-cc_status.md).

# Basic Needs (cc\_status)

Hunger, thirst, stress and intoxication per character – calculated on the server only, ready for HUD and inventory.

**Frameworks:** ESX Legacy, QBCore, QBox

## Features

* Four values with configurable decay per minute
* Calculated exclusively on the server; the client only displays, applies health instructions from the server and reports sprinting or swimming
* Faster hunger/thirst while sprinting or swimming
* Starvation damage and warnings at configurable thresholds
* Intoxication with three stages (walk style, camera shake, screen filter, stumbling)
* `Apply` export for food, drinks and other consumables (including healing over time and armour)
* Saved on logout, character switch, disconnect, resource stop and every 5 minutes (changes only)
* Protection against values being reset to full on database errors
* Admin command to view and reset values
* State bags for any HUD, including mirrored `hunger`/`thirst` for third-party HUDs

## Values

| Value    | 100 means   | 0 means    | Default decay       |
| -------- | ----------- | ---------- | ------------------- |
| `hunger` | full        | starving   | drops 0.6 %/min     |
| `thirst` | not thirsty | dehydrated | drops 0.8 %/min     |
| `stress` | maxed out   | relaxed    | drops 1 %/min       |
| `drunk`  | wasted      | sober      | wears off 2.5 %/min |

{% hint style="info" %}
The code is protected by Cfx asset escrow. `config/config.lua`, `locales/de.json`, `locales/en.json` and `shared/cc_framework.lua` stay editable.
{% endhint %}

## Works well with

* cc\_hud/00%20Overview\.md) – rings for hunger, thirst and stress
* cc\_inventory/00%20Overview\.md) – food and drinks call `Apply`
* cc\_ambulance/00%20Overview\.md) – down state and revive rule
* cc\_lib/00%20Overview\.md) – CrankChaos-style notifications

## Pages

* Installation
* Configuration
* API
* FAQ

## Installation

See also the general installation guide, dependencies and the framework bridge.

### Requirements

| Resource                               | Required | Notes                                                                                        |
| -------------------------------------- | -------- | -------------------------------------------------------------------------------------------- |
| `oxmysql`                              | yes      | declared as `dependency`                                                                     |
| `es_extended`, `qb-core` or `qbx_core` | yes      | one framework                                                                                |
| `cc_lib`                               | optional | CrankChaos notifications; GTA notifications otherwise                                        |
| `cc_inventory`                         | optional | food and drinks call `Apply`                                                                 |
| `cc_hud`                               | optional | rings for hunger, thirst and stress                                                          |
| `cc_ambulance`                         | optional | down state (`ccDown`) and `cc_ambulance:revived`; without it only the revive rule is missing |

{% hint style="warning" %}
`esx_status` is **not** needed. If both run, two systems calculate the same values – remove one.
{% endhint %}

### 1. Copy the resource

Copy the folder to `resources/[crankchaos]/cc_status`.

### 2. server.cfg

```cfg
ensure oxmysql
ensure es_extended   # or qb-core / qbx_core
ensure cc_lib        # optional
ensure cc_status
ensure cc_hud        # optional
ensure cc_inventory  # optional
```

### 3. ACE permissions

```cfg
add_ace group.admin cc_status.admin allow
```

The ACE name can be changed with `Config.Admin.ace`. The server console is always allowed.

### 4. Database

No SQL file. The `cc_status` table is created automatically on first start.

A new character starts full. If the database cannot be read, the character does **not** start full – hunger is paused for 30 seconds and loading is retried.

### Framework notes

No framework-specific steps.

## Configuration

All options are in `config/config.lua`. All values are **percent (0–100)**.

### Timing

```lua
Config.Locale = 'de'
Config.Tick = 30           -- seconds per tick (10–120), one tick for all players
Config.SaveInterval = 300  -- seconds between save runs
```

### Decay

```lua
Config.Decay = { hunger = 0.6, thirst = 0.8, stress = 1.0, drunk = 2.5 }  -- percent per minute
```

### Activity

```lua
Config.Activity = { sprint = 1.5, swim = 1.75, max = 2.0, valid = 45, check = 5000, report = 15000 }
```

Multiplier on hunger/thirst decay while the client reports sprinting or swimming, capped at `max`.

### Starvation and warnings

```lua
Config.Starve = { interval = 60, damage = 5, canKill = true }
Config.Warn = { 25, 10 }
```

At 0 hunger or thirst the player takes `damage` HP every `interval` seconds (double if both are empty). `Warn` shows a notification once when falling below each threshold.

### Exemptions

```lua
Config.Exempt = { down = true, noclip = true, godmode = true, jailed = false }
```

Players in these states do not starve (state bags `ccDown`, `ccAdminNoclip`, `ccAdminGod`, `ccJailed`).

### Revive

```lua
Config.Revive = { reset = false, atLeast = 20 }
```

After a revive (`cc_ambulance:revived`), hunger/thirst are raised to at least 20 %.

### Apply limits

```lua
Config.Apply = { cooldown = 1000, maxHeal = 100, maxHealSeconds = 300, maxArmor = 100, maxEnergySeconds = 180, notifyFull = true }
```

### Intoxication

```lua
Config.Drunk = {
    { from = 10, clipset = 'move_m@drunk@slightlydrunk', shake = 0.3, strength = 0.2, stumble = 0 },
    { from = 40, clipset = 'move_m@drunk@moderatedrunk', shake = 0.9, strength = 0.5, stumble = 0 },
    { from = 70, clipset = 'move_m@drunk@verydrunk',     shake = 1.8, strength = 0.85, stumble = 0.03 },
}
```

### Third-party HUDs

```lua
Config.MirrorBags = true
```

Also writes `state.hunger` and `state.thirst` for HUDs that read those state bags.

### Admin

```lua
Config.Admin = { command = 'status', ace = 'cc_status.admin' }
```

### Items

Effects used when `Apply` only receives an item name:

```lua
Config.Items = {
    bread = { hunger = 15 },
    burger = { hunger = 30, stress = -3 },
    water = { thirst = 25 },
    coffee = { thirst = 15, stress = -3 },
    beer = { thirst = 12, drunk = 15, stress = -5 },
    whiskey = { thirst = 8, drunk = 40, stress = -10 },
    ...
}
```

## Exports, Events & Commands

### Commands

| Command                         | Effect                                        | Permission        |
| ------------------------------- | --------------------------------------------- | ----------------- |
| `/status <id>`                  | shows hunger, thirst, stress and intoxication | `cc_status.admin` |
| `/status <id> full` (or `voll`) | resets everything to a new character's state  | `cc_status.admin` |

The command name is `Config.Admin.command`. Always allowed from the server console.

### Server exports

| Export                           | Returns                                      | Effect                                      |
| -------------------------------- | -------------------------------------------- | ------------------------------------------- |
| `Apply(src, effects, itemName?)` | `ok, reason?`                                | apply an item effect                        |
| `Get(src)`                       | `{ hunger, thirst, stress, drunk }` or `nil` | current values                              |
| `Set(src, key, value)`           | `boolean`                                    | set `hunger`, `thirst`, `stress` or `drunk` |
| `Add(src, key, delta)`           | `boolean`                                    | change a value by `delta`                   |
| `Reset(src)`                     | `boolean`                                    | reset to a new character's state            |

```lua
local ok, reason = exports.cc_status:Apply(src, {
    hunger = 25, thirst = 10, stress = -5, drunk = 15,
    health = 20, heal = { amount = 40, seconds = 20 }, armor = 50,
}, 'burger')
```

* Values are clamped; an item never kills (negative `health` stops at 101 HP).
* If `effects` is `nil`, `Config.Items[itemName]` is used.
* `reason`: `'invalid'`, `'notready'`, `'down'`, `'cooldown'`, `'full'`.

### Client exports

None.

### Events

| Event                  | Side   | Direction                 | Payload                                               |
| ---------------------- | ------ | ------------------------- | ----------------------------------------------------- |
| `cc_status:applied`    | server | outgoing (`TriggerEvent`) | `src, effects, itemName` after every successful apply |
| `cc:characterChanged`  | server | incoming                  | `src, identifier` – loads the character's values      |
| `cc_ambulance:revived` | server | incoming                  | `src` – applies `Config.Revive`                       |

### State bags

`Player(src).state.ccStatus` / `LocalPlayer.state.ccStatus` = `{ hunger, thirst, stress, drunk }` in whole percent, `nil` while no character is loaded. With `Config.MirrorBags = true` also `state.hunger` and `state.thirst`.

## FAQ & Troubleshooting

**Food takes effect twice.** `esx_status` is running in parallel. Remove it – cc\_status replaces it.

**Stress never rises.** cc\_status has no stress triggers of its own. Stress only rises through `Apply` or `Add` from other scripts.

**A player spawned with empty values after a database hiccup.** That is the protection at work: if values cannot be read, the character does not start full. Hunger pauses for 30 seconds and loading is retried.

**My HUD does not show hunger and thirst.** Use cc\_hud/00%20Overview\.md), read `state.ccStatus`, or keep `Config.MirrorBags = true` so `state.hunger`/`state.thirst` are written.

**Players do not starve while down or in noclip.** Intended – see `Config.Exempt`.

**A limp from cc\_ambulance disappears while drunk.** The drunk walk style overrides it; the limp returns with the next injury change.

**`/status` says I have no permission.** Add `add_ace group.admin cc_status.admin allow` to `server.cfg`.

Still stuck? See Support.


---

# 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://ccfivem.gitbook.io/ccfivem-docs/player-and-ui/basic-needs-cc_status.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.