# esx_basicneeds (/docs/addons/esx_basicneeds)

esx_basicneeds adds hunger and thirst to ESX Legacy. It registers both as statuses in [esx_status](/docs/addons/esx_status), drains them over time, damages the player when one hits zero, and turns food and drink items (bread and water by default) into usable items with an eating or drinking animation.

## Overview [#overview]

| | |
| --- | --- |
| Resource | `esx_basicneeds` (version 1.0) |
| Side | client + server |
| Dependencies | `esx_lib`, `es_extended`, `esx_status` (also loads `@oxmysql`) |
| Items | `bread`, `water` |
| Command | `/heal` (admin) |

How it behaves in-game:

- Hunger and thirst have a max of `1000000`. Hunger drains `100` and thirst `75` per esx_status tick.
- At `0` the player takes damage each tick (1 HP, or 5 HP when health is at or below 150).
- After death and respawn both statuses are reset to `500000`.
- Using an item adds `status` to hunger (`food`) or thirst (`drink`), plays a 3 second animation with an attached prop and optionally removes the item.

## Installation [#installation]

<Steps>
<Step>

### Import the items [#import-the-items]

Run `esx_basicneeds.sql` (or a translated file from `localization/`). It inserts `bread` and `water` into `items`.

</Step>
<Step>

### Ensure the resource [#ensure-the-resource]

```bash title="server.cfg"
ensure esx_lib
ensure es_extended
ensure esx_status
ensure esx_basicneeds
```

</Step>
</Steps>

## Configuration [#configuration]

| Key | Default | Description |
| --- | --- | --- |
| `Config.Locale` | `GetConvar('esx:locale', 'en')` | Language. |
| `Config.Visible` | `true` | Whether the hunger and thirst bars are visible in the esx_status HUD. |
| `Config.Items` | `bread`, `water` | Usable consumables, keyed by item name. |

### Config.Items fields [#configitems-fields]

| Field | Type | Description |
| --- | --- | --- |
| `type` | `'food' \| 'drink'` | `food` adds to hunger, `drink` adds to thirst. Any other value logs an error. |
| `prop` | `string` | Prop model attached to the right hand. |
| `status` | `number` | Amount added (out of `1000000`). Default bread `200000`, water `100000`. |
| `remove` | `boolean` | Remove one item on use. |
| `anim` | `{ dict, name, settings }` | Animation. `settings` holds the 8 extra `TaskPlayAnim` arguments. |
| `pos` | `vector3` | Prop offset on the hand bone. |
| `rot` | `vector3` | Prop rotation. |

```lua title="config.lua"
Config.Items['sandwich'] = {
    type = 'food',
    prop = 'prop_sandwich_01',
    status = 350000,
    remove = true,
    anim = { dict = 'mp_player_inteat@burger', name = 'mp_player_int_eat_burger_fp', settings = { 8.0, -8, -1, 49, 0, 0, 0, 0 } },
    pos = vector3(0.15, 0.03, 0.0),
    rot = vector3(15.0, 175.0, 5.0),
}
```

Remember to add `sandwich` to the `items` table as well.

## Commands [#commands]

### /heal [#heal]

```txt
/heal <playerId>
```

Admin only (`admin` group). Sets hunger and thirst to the maximum, restores full health and notifies the player. The `playerId` argument is required, so to heal yourself pass your own ID. Healing a player through the txAdmin menu triggers the same logic.

## Events [#events]

### esx_basicneeds:healPlayer (client) [#esx_basicneedshealplayer-client]

```lua
TriggerClientEvent('esx_basicneeds:healPlayer', playerId)
```

Sets hunger and thirst to `1000000` and health to max on that client. Net event, so trigger it from the server.

### esx_basicneeds:resetStatus (client, local) [#esx_basicneedsresetstatus-client-local]

```lua
TriggerEvent('esx_basicneeds:resetStatus')
```

Sets hunger and thirst to `500000`. Local only, use it from client scripts (for example after a custom respawn).

### esx_basicneeds:onUse (client) [#esx_basicneedsonuse-client]

```lua
TriggerClientEvent('esx_basicneeds:onUse', playerId, itemType, propName, anim, pos, rot)
```

| Name | Type | Description |
| --- | --- | --- |
| `itemType` | `'food' \| 'drink'` | Picks the default animation and prop. |
| `propName` | `string?` | Prop model. Defaults to `prop_cs_burger_01` or `prop_ld_flow_bottle`. |
| `anim` | `table?` | `{ dict, name, settings }`. |
| `pos`, `rot` | `vector3?` | Prop offset and rotation. |

Plays only the animation; it does not change any status. Useful when your own script handles the item logic. Arguments are validated and a second call is ignored while an animation is running.

### esx_basicneeds:isEating (client, local) [#esx_basicneedsiseating-client-local]

```lua
TriggerEvent('esx_basicneeds:isEating', function(isEating)
    print('Eating or drinking:', isEating)
end)
```

Returns whether the eat or drink animation is currently playing.

<Callout type="info" title="Deprecated">
`esx_basicneeds:onEat` and `esx_basicneeds:onDrink` still work but print a warning and forward to `esx_basicneeds:onUse`.
</Callout>

## Integration tips [#integration-tips]

- Change statuses from the server through esx_status. The server side only has `esx_status:set` and `esx_status:add`; to subtract, send the client event:

  ```lua title="server/main.lua"
  TriggerEvent('esx_status:add', source, 'hunger', 100000)
  TriggerClientEvent('esx_status:remove', source, 'thirst', 100000)
  ```

- Read the current value on the client:

  ```lua title="client/main.lua"
  TriggerEvent('esx_status:getStatus', 'hunger', function(status)
      print(status.percent)
  end)
  ```

- [esx_optionalneeds](/docs/addons/esx_optionalneeds) adds a `drunk` status on top of these two.

## Common issues [#common-issues]

- **Bars not showing**: esx_status must start before esx_basicneeds, and `Config.Visible` must be `true`.
- **Item does nothing**: the item is missing from the `items` table, or `type` is not `food` or `drink`.
- **Values reset on reconnect**: esx_status saves statuses to the `users.status` column. Make sure that column exists.

## Related [#related]

- [esx_status](/docs/addons/esx_status)
- [esx_optionalneeds](/docs/addons/esx_optionalneeds)
- [esx_hud](/docs/addons/esx_hud)
- [Add items](/docs/guides/add-items)