esx_status

esx_status is the engine behind player needs in ESX Legacy. It keeps a list of named values per player (for example hunger, thirst, drunk), saves them in users.status, decays them over time and broadcasts them to the client every tick. esx_basicneeds and esx_optionalneeds build on it, and HUDs such as esx_hud read from it.

OverviewCopy Anchor Link

Two kinds of statusesCopy Anchor Link

Since version 1.1 hunger and thirst are decided on the server. Change them with the server events. Client-side changes only last until the next sync.

InstallationCopy Anchor Link

ALTER TABLE `users` ADD COLUMN `status` LONGTEXT NULL;

ensure esx_status
ensure esx_basicneeds
ensure esx_optionalneeds

ConfigurationCopy Anchor Link

With the defaults, hunger drops from full to zero in about 2 hours 47 minutes (1,000,000 / 100 seconds) and thirst in about 3 hours 42 minutes.

Config.AuthoritativeStatuses = {
    hunger = { default = 1000000, decay = 100 },
    thirst = { default = 1000000, decay = 75 },
    stress = { default = 0, decay = 0 }, -- server-owned, changed only by your scripts
}

Status data shapeCopy Anchor Link

Every status entry sent between server and client looks like this:

A player can hold at most 64 statuses. The loaded list is also mirrored to ESX.PlayerData.variables.status on the client.

Server APICopy Anchor Link

All server events below are local (AddEventHandler). Only other server scripts can trigger them.

esx_status:setCopy Anchor Link

Sets a status to an exact value.

TriggerEvent('esx_status:set', playerId, name, value)

-- fill hunger and thirst after a revive
TriggerEvent('esx_status:set', source, 'hunger', 1000000)
TriggerEvent('esx_status:set', source, 'thirst', 1000000)

esx_status:addCopy Anchor Link

Adds to a status. Use a negative value to remove.

TriggerEvent('esx_status:add', playerId, name, value)

ESX.RegisterUsableItem('sandwich', function(source)
    local xPlayer = ESX.Player(source)
    xPlayer.removeInventoryItem('sandwich', 1)
    TriggerEvent('esx_status:add', source, 'hunger', 250000)
end)

set and add only change a status the player already has. After the change the server sends esx_status:sync to the client right away.

esx_status:getStatusCopy Anchor Link

Reads one status of a player.

TriggerEvent('esx_status:getStatus', playerId, name, cb)

TriggerEvent('esx_status:getStatus', source, 'thirst', function(status)
    if status.percent < 10 then
        TriggerClientEvent('esx:showNotification', source, 'You are very thirsty')
    end
end)

Client APICopy Anchor Link

esx_status:registerStatusCopy Anchor Link

Creates a status object on the client. Register custom statuses in a handler for esx_status:loaded so the saved value is applied.

TriggerEvent('esx_status:registerStatus', name, default, color, visible, tickCallback)

AddEventHandler('esx_status:loaded', function()
    TriggerEvent('esx_status:registerStatus', 'stress', 0, '#E74C3C',
        function(status) return status.val > 0 end,
        function(status) status.remove(500) end
    )
end)

If a status with the same name exists, the new object replaces it and keeps the current value.

Status objectCopy Anchor Link

esx_status:getStatus and esx_status:getAllStatus return status objects with these members:

esx_status:unregisterStatusCopy Anchor Link

TriggerEvent('esx_status:unregisterStatus', name)

Removes the status from the client list. It stops ticking and is no longer sent to the server.

esx_status:getStatus (client)Copy Anchor Link

TriggerEvent('esx_status:getStatus', name, cb)

TriggerEvent('esx_status:getStatus', 'hunger', function(status)
    print(('Hunger: %.1f%%'):format(status.getPercent()))
end)

esx_status:getAllStatusCopy Anchor Link

TriggerEvent('esx_status:getAllStatus', function(statuses)
    for i = 1, #statuses do
        print(statuses[i].name, statuses[i].val)
    end
end)

esx_status:set / add / remove (client)Copy Anchor Link

TriggerEvent('esx_status:set', name, val)
TriggerEvent('esx_status:add', name, val)
TriggerEvent('esx_status:remove', name, val)

These change the local status object. They are also net events, so the server can send them with TriggerClientEvent('esx_status:add', playerId, 'drunk', 250000). For custom statuses the new value reaches the server with the next update. For authoritative statuses (hunger, thirst) the change is overwritten by the next server sync, so use the server events instead.

esx_status:setDisplayCopy Anchor Link

TriggerEvent('esx_status:setDisplay', 0.5)

Sets the opacity of the built-in bars (0.0 hides them). Only useful with Config.Display = true.

Events you can listen toCopy Anchor Link

AddEventHandler('esx_status:onTick', function(statuses)
    for _, status in ipairs(statuses) do
        if status.name == 'thirst' then
            SendNUIMessage({ action = 'thirst', value = status.percent })
        end
    end
end)

Network events (client to server)Copy Anchor Link

SavingCopy Anchor Link

The server loads users.status on esx:playerLoaded and writes it back on esx:playerDropped. During the session values live in the xPlayer variable status. Authoritative values are advanced from elapsed time whenever they are read, synced or saved.

Common issuesCopy Anchor Link

• Hunger or thirst jumps back after eating: your item script changes them on the client. Use TriggerEvent('esx_status:add', source, 'hunger', amount) on the server.
• Status bars do not show: Config.Display is false by default. Enable it or use a HUD.
• Custom status always starts at the default: it was registered before esx_status:loaded fired and then never received the saved value, or the player never stayed long enough for an update. Register inside esx_status:loaded.
• users.status column missing: import esx_status.sql. Loading fails and is retried with backoff.
• Changing an unknown status on the server does nothing: set and add only touch statuses that already exist for the player.

RelatedCopy Anchor Link

• esx_basicneeds
• esx_optionalneeds
• esx_hud
• Add items

Frequently asked questions