Needs add system

Our HUD is already compatible with several needs systems: esx_basicneeds, esx_status, okokNeeds, qb-hud, and renewed-lib.

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

-- 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

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

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

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

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

-- Update only hunger
UpdateHunger(hunger)

-- Update only thirst
UpdateThirst(thirst)

Get Functions

-- 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

-- 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

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

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

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:

-- 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

   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()