# Needs add system

{% hint style="info" %}
Our HUD is already compatible with several needs systems: `esx_basicneeds`, `esx_status`, `okokNeeds`, `qb-hud`, and `renewed-lib`.
{% endhint %}

## Custom Needs System Integration Guide

This guide explains how to integrate your own needs system (hunger/thirst) with PHUD.

### 📋 Table of Contents

* How It Works
* Method 1: Using Event Handlers
* Method 2: Using Polling Loop
* Available Exports
* Real Examples
* Configuration
* Troubleshooting

***

### How It Works

PHUD needs to receive hunger and thirst values (0-100 scale) from your needs system:

* **0** = empty/dead
* **100** = full/satisfied

The HUD will automatically update when values change.

***

### Method 1: Using Event Handlers (Recommended)

This method listens to events triggered by your needs system.

#### Step 1: Create Your Integration File

Create a new file in this folder: `your-system-name.lua`

#### Step 2: Use This Template

```lua
-- Listen to events from your needs system
RegisterNetEvent('your_needs_system:onUpdate')
AddEventHandler('your_needs_system:onUpdate', function(data)
    local hunger, thirst = nil, nil

    -- Extract hunger and thirst from your system's data
    -- Adapt this to match your system's data structure
    for i = 1, #data do
        if data[i].name == 'hunger' then
            hunger = math.floor(data[i].percent) -- Convert to 0-100 if needed
        elseif data[i].name == 'thirst' then
            thirst = math.floor(data[i].percent)
        end
    end

    -- Update the HUD
    if hunger or thirst then
        UpdateNeeds(hunger, thirst)
    end
end)
```

#### Real Example: ESX Status

```lua
RegisterNetEvent('esx_status:onTick')
AddEventHandler('esx_status:onTick', function(data)
    local hunger, thirst = nil, nil

    for i = 1, #data do
        if data[i].name == 'hunger' then
            hunger = math.floor(data[i].percent)
        elseif data[i].name == 'thirst' then
            thirst = math.floor(data[i].percent)
        end
    end

    if hunger or thirst then
        UpdateNeeds(hunger, thirst)
    end
end)

-- Also listen to other events for real-time updates
RegisterNetEvent('esx_status:update')
AddEventHandler('esx_status:update', function(data)
    -- Same logic as above
end)

RegisterNetEvent('esx_status:set')
AddEventHandler('esx_status:set', function(name, val)
    if name == 'hunger' then
        local percent = math.floor((val / 1000000) * 100)
        UpdateHunger(percent)
    elseif name == 'thirst' then
        local percent = math.floor((val / 1000000) * 100)
        UpdateThirst(percent)
    end
end)
```

***

### Method 2: Using Polling Loop

This method actively checks your needs system at regular intervals.

#### Template

```lua
Citizen.CreateThread(function()
    while true do
        Wait(1000) -- Update every 1 second (adjust as needed)

        -- Get values from your needs system
        -- Replace these with your actual functions/exports
        local hunger = exports['your-needs-system']:GetHunger() -- Should return 0-100
        local thirst = exports['your-needs-system']:GetThirst() -- Should return 0-100

        -- Update the HUD
        if hunger and thirst then
            UpdateNeeds(hunger, thirst)
        end
    end
end)
```

#### Real Example: QB-Core HUD

```lua
CreateThread(function()
    while true do
        Wait(1000)

        local player = PlayerPedId()
        if player and player > 0 then
            -- Get player metadata
            local PlayerData = QBCore.Functions.GetPlayerData()
            if PlayerData and PlayerData.metadata then
                local hunger = PlayerData.metadata['hunger'] or 100
                local thirst = PlayerData.metadata['thirst'] or 100

                UpdateNeeds(hunger, thirst)
            end
        end
    end
end)
```

***

### Available Exports

Use these functions in your integration file:

#### Update Functions

```lua
-- Update both hunger and thirst at once
UpdateNeeds(hunger, thirst)

-- Update only hunger
UpdateHunger(hunger)

-- Update only thirst
UpdateThirst(thirst)
```

#### Get Functions

```lua
-- Get current hunger value
local hunger = exports['PHud']:GetHunger()

-- Get current thirst value
local thirst = exports['PHud']:GetThirst()

-- Get both values
local needs = exports['PHud']:GetNeeds()
-- Returns: { hunger = 75, thirst = 80 }
```

#### Force Set Functions

```lua
-- Force set hunger without checking for changes
exports['PHud']:SetHunger(75)

-- Force set thirst without checking for changes
exports['PHud']:SetThirst(80)
```

***

### Real Examples

#### ESX Basic Needs

```lua
RegisterNetEvent('esx_basicneeds:onTick')
AddEventHandler('esx_basicneeds:onTick', function(data)
    local hunger, thirst = nil, nil

    for i = 1, #data do
        if data[i].name == 'hunger' then
            hunger = math.floor(data[i].percent)
        elseif data[i].name == 'thirst' then
            thirst = math.floor(data[i].percent)
        end
    end

    if hunger or thirst then
        UpdateNeeds(hunger, thirst)
    end
end)
```

#### OkOk Needs

```lua
CreateThread(function()
    while true do
        Wait(1000)

        if exports['okokNeeds'] then
            local hunger = exports['okokNeeds']:GetHunger()
            local thirst = exports['okokNeeds']:GetThirst()

            if hunger and thirst then
                UpdateNeeds(hunger, thirst)
            end
        end
    end
end)
```

#### Renewed Library

```lua
CreateThread(function()
    while true do
        Wait(1000)

        local needs = exports['Renewed-Lib']:getPlayerNeeds()

        if needs then
            local hunger = needs.hunger or 100
            local thirst = needs.thirst or 100

            UpdateNeeds(hunger, thirst)
        end
    end
end)
```

***

### Configuration

#### Step 1: Create Your Integration File

Create a new `.lua` file in the `phud/editable/needs/` folder.

**Example:**

* Create the file: `phud/editable/needs/custom.lua`
* In config.lua: `Config.NeedsSystem = "custom"`

**Important:** The filename (without `.lua`) must EXACTLY match the value you set in `Config.NeedsSystem`.

#### Step 2: Enable Your System in Config

Open `phud/config.lua` and set:

```lua
-- Use your specific system
Config.NeedsSystem = "custom" -- Filename without .lua extension
```

Available systems:

* `esx_status` - ESX Status (default version)
* `esx_basicneeds` - ESX Basic Needs
* `qb-hud` - QB-Core HUD
* `okokNeeds` - OkOk Needs
* `renewed-lib` - Renewed Library
* `Metabolic` - Metabolic system
* Or your custom filename

#### Step 3: Restart Resource

```
ensure phud
```

***

### Troubleshooting

#### HUD Not Updating

1. **Check if your file is loaded**
   * Make sure the filename matches `Config.NeedsSystem`
   * File should be in `phud/editable/needs/` folder
2. **Check console for errors**
   * Look for Lua errors in F8 console
   * Check server console for warnings
3. **Verify data format**
   * Hunger/thirst should be numbers between 0-100
   * Use `print()` to debug values
4. **Check events are triggering**

   ```lua
   RegisterNetEvent('your_event')
   AddEventHandler('your_event', function(data)
       print("Event received:", json.encode(data))
       -- Your code here
   end)
   ```

#### Values Not Correct

* Check if you need to convert values (e.g., from 0-1000000 to 0-100)
* Ensure you're using `math.floor()` to convert to integers
* Verify your needs system is actually running

#### Auto-Detection Not Working

* Set specific system name instead of "auto"
* Check if your needs resource is started before PHUD
* Ensure your needs system resource name matches

***

### Need Help?

If your needs system is not listed here:

1. Find out what events your system triggers
2. Or find out what exports your system provides
3. Use one of the methods above to integrate it
4. Check your system's documentation for available functions

Common event patterns:

* `system_name:onTick`
* `system_name:update`
* `system_name:onChange`

Common export patterns:

* `exports['system_name']:GetHunger()`
* `exports['system_name']:GetNeeds()`