> For the complete documentation index, see [llms.txt](https://docs.vames-store.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vames-store.com/assets/vms_needs/developer-api/client-state-bags.md).

# Client State Bags

### Getting Current Status

Returns the player's current status directly from the client state bag.\
These values are automatically synchronized by VMS Needs and are available at any time on the client.

```lua
LocalPlayer.state.STATUS_NAME
```

<details>

<summary><strong>Example Usage</strong></summary>

```lua
local hunger = LocalPlayer.state.hunger
print('My hunger level is ' .. hunger .. '%')

local thirst = LocalPlayer.state.thirst
print('My thirst level is ' .. thirst .. '%')

local stress = LocalPlayer.state.stress
print('My stress level is ' .. stress .. '%')
```

</details>

***

### Listening for Status Changes

Registers a callback that is automatically executed whenever the selected state bag value changes.\
Recommended for HUDs, UI elements, and any system that needs to react to status changes in real time.

```lua
local serverId = GetPlayerServerId(PlayerId())
AddStateBagChangeHandler(STATUS_NAME, ("player:%s"):format(serverId), function(_, _, percentage)
    print('Updated status to ' .. percentage .. '%')
end)
```

<details>

<summary><strong>Example Usage</strong></summary>

```lua
local serverId = GetPlayerServerId(PlayerId())

AddStateBagChangeHandler("hunger", ("player:%s"):format(serverId), function(_, _, percentage)
     -- Update HUD
end)

AddStateBagChangeHandler("thirst", ("player:%s"):format(serverId), function(_, _, percentage)
    -- Update HUD
end)

AddStateBagChangeHandler("stress", ("player:%s"):format(serverId), function(_, _, percentage)
    -- Update HUD
end)
```

</details>