> 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-exports.md).

# Client Exports

### GetStatus

Returns a status controller for the specified player and status.

```lua
---@param {statusName: string}: Status name defined in Config.Statuses
---@return {status: table}: Status controller with Set, GetPercentage, Add and Remove functions
local status = exports['vms_needs']:GetStatus(statusName)
```

<details>

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

```lua
local hunger = exports['vms_needs']:GetStatus('hunger')

hunger.Set(300)

print(hunger.GetPercentage())

hunger.Add(50)
hunger.Remove(25)
```

</details>

<details>

<summary><strong>Returned Functions</strong></summary>

```lua
{
    Set = function(value)
        -- Sets the raw status value.
    end,

    GetPercentage = function()
        -- Returns the current status value as a percentage from 0 to 100.
    end,

    Add = function(value)
        -- Adds the specified value to the status.
    end,

    Remove = function(value)
        -- Removes the specified value from the status.
    end,
}
```

</details>

***

### GetStatuses

Returns a list of all registered player statuses.

```lua
---@return {statuses: table}: Status data indexed by status name
local statuses = exports['vms_needs']:GetStatuses()
```

<details>

<summary><strong>Example Returned Data</strong></summary>

```lua
{
    ["hunger"] = {
        max = 500,
        value = 154.0,
        percentage = 30.8,
        name = "hunger",
    },
    ["thirst"] = {
        max = 500,
        value = 106.0,
        percentage = 21.2,
        name = "thirst",
    },
    ["stress"] = {
        max = 500,
        value = 0.0,
        percentage = 0.0,
        name = "stress",
    },
}
```

</details>

***

### GetPercentageStatus

Returns the current status value as a percentage (0-100).

```lua
---@param {statusName: string}: Status name defined in Config.Statuses
---@return {statusPercentage: number}: Current status value as a percentage (0-100)
local statusPercentage = exports['vms_needs']:GetPercentageStatus(statusName)
```

***

### SetStatus

Sets the raw value of the status.

```lua
---@param {statusName: string}: Status name defined in Config.Statuses
---@param {value: number}: New raw status value
exports['vms_needs']:SetStatus(statusName, value)
```

***

### AddStatus

Adds a raw value to the status.

```lua
---@param {statusName: string}: Status name defined in Config.Statuses
---@param {value: number}: Raw status value to add
exports['vms_needs']:AddStatus(statusName, value)
```

***

### RemoveStatus

Removes a raw value from the status.

```lua
---@param {statusName: string}: Status name defined in Config.Statuses
---@param {value: number}: Raw status value to remove
exports['vms_needs']:RemoveStatus(statusName, value)
```

***

### CleanupOptionalStatuses

Clear all statuses if they are marked as `isOptional` in `Config.Statuses`.

```lua
exports['vms_needs']:CleanupOptionalStatuses()
```

***

### GetServerTemperature

Returns the current ambient server temperature.

```lua
---@param {unit: string | nil}: Temperature unit ("fahrenheit"). Defaults to Celsius if nil.
---@return {temperature: number}: Current ambient temperature
local temperature = exports['vms_needs']:GetServerTemperature(unit)
```

***

### GetServerFeelsLikeTemperature

Returns the current perceived temperature based on weather conditions.

```lua
---@param {unit: string | nil}: Temperature unit ("fahrenheit"). Defaults to Celsius if nil.
---@return {temperature: number}: Current perceived temperature
local temperature = exports['vms_needs']:GetServerFeelsLikeTemperature(unit)
```

***

### GetPlayerBodyTemperature

Returns the player's current body temperature and thermal state.

```lua
---@param {unit: string | nil}: Temperature unit ("fahrenheit"). Defaults to Celsius if nil.
---@return {temperature: number}: Current player body temperature
---@return {state: string}: Current thermal state (NORMAL, WARM, HOT, OVERHEATED, CHILLED, COLD or HYPOTHERMIA)
local temperature, state = exports['vms_needs']:GetPlayerBodyTemperature(unit)
```

<details>

<summary>Example</summary>

```lua
local temperature, state = exports['vms_needs']:GetPlayerBodyTemperature()

print(temperature) -- 36.8
print(state)       -- NORMAL
```

</details>

<details>

<summary>Available States</summary>

The following thermal states may be returned by this export.

<table><thead><tr><th width="206.6363525390625">State</th><th width="302.636474609375">Description</th><th>Temperature Range</th></tr></thead><tbody><tr><td>NORMAL</td><td>Normal body temperature</td><td>36.0 - 37.5 °C</td></tr><tr><td>WARM</td><td>Slightly elevated body temperature</td><td>37.5 - 38.0 °C</td></tr><tr><td>HOT</td><td>Elevated body temperature</td><td>38.0 - 39.0 °C</td></tr><tr><td>OVERHEATED</td><td>Dangerously high body temperature</td><td>> 39.0 °C</td></tr><tr><td>CHILLED</td><td>Slightly reduced body temperature</td><td>35.2 - 36.0 °C</td></tr><tr><td>COLD</td><td>Low body temperature</td><td>34.0 - 35.2 °C</td></tr><tr><td>HYPOTHERMIA</td><td>Dangerously low body temperature</td><td>&#x3C; 34.0 °C</td></tr></tbody></table>

</details>

***

### OverwriteTemperature

Overrides the ambient temperature for the local player until disabled. Useful for interiors or controlled environments where the perceived temperature should differ from the outside world.

The player's body temperature will not change instantly. It will gradually adjust toward the overridden ambient temperature according to the configured temperature system.

```lua
---@param {toggle: boolean}: Enables or disables the local ambient temperature override.
---@param {temperature: number | nil}: Ambient temperature to use while the override is enabled. Ignored when toggle is false.
exports['vms_needs']:OverwriteTemperature(toggle, temperature)
```

<details>

<summary>Example</summary>

```lua
-- Entering a heated interior
exports['vms_needs']:OverwriteTemperature(true, 40.0)

-- Entering a comfortable interior
exports['vms_needs']:OverwriteTemperature(true, 20.0)

-- Leaving the interior
exports['vms_needs']:OverwriteTemperature(false)
```

</details>

***

### GetPlayerCold

Returns the player's current cold factor.

{% hint style="info" %}
The returned value is normalized between 0.0 and 1.0 and can be used to scale custom gameplay effects.
{% endhint %}

```lua
---@return {cold: number}: Cold intensity (0.0-1.0)
local cold = exports['vms_needs']:GetPlayerCold()
```

***

### GetPlayerHeat

Returns the player's current heat factor.

{% hint style="info" %}
The returned value is normalized between 0.0 and 1.0 and can be used to scale custom gameplay effects.
{% endhint %}

```lua
---@return {heat: number}: Heat intensity (0.0-1.0)
local heat = exports['vms_needs']:GetPlayerHeat()
```

***

### GetUsingItem

Returns the currently active item, including its name, metadata and configured type.

```lua
---@return {name: string | nil}: Current item name
---@return {metadata: table | nil}: Current item metadata
---@return {type: string | nil}: Item type defined in Config.Items
local name, metadata, type = exports['vms_needs']:GetUsingItem()
```

<details>

<summary>Example</summary>

```lua
local name, metadata, type = exports['vms_needs']:GetUsingItem()

if name then
    print("Name:", name)
    print("Metadata:", json.encode(metadata))
    print("Type:", type)
end
```

</details>

***

### CancelItemUsage

Cancels the current item usage by either hiding or dropping the item, depending on the specified action and item behavior.

{% hint style="info" %}
**Note:** Not all items support both actions. For example, lit cigarettes cannot be returned to the inventory, while some items (such as a breathalyzer) cannot be dropped. In these cases, the item's configured behavior is applied automatically.
{% endhint %}

```lua
---@param {action: string | nil}: "drop" to drop the current item, or "cancel"/nil to hide it if possible.
exports['vms_needs']:CancelItemUsage(action)
```

<details>

<summary>Example</summary>

```lua
-- Hide the current item (default behavior)
exports['vms_needs']:CancelItemUsage()

-- Explicitly hide the current item
exports['vms_needs']:CancelItemUsage('cancel')

-- Attempt to drop the current item
exports['vms_needs']:CancelItemUsage('drop')
```

</details>

***

### GetBreathalyzerReading

Calculates and returns the current breathalyzer reading using the player's drunk status and the configured alcohol settings.

{% hint style="info" %}
**Note:** The returned values are calculated using the current `drunk` status and the settings defined in `Config.Alcohol`.
{% endhint %}

```lua
---@return {data: table}: Current breathalyzer reading
local data = exports['vms_needs']:GetBreathalyzerReading()
```

<details>

<summary>Example Returned Data</summary>

```lua
{
    drunkPercent = 42.5,
    permille = 1.28,
    mgL = 0.61
}
```

</details>

<details>

<summary>Returned Fields</summary>

<table><thead><tr><th width="234.8182373046875">Field</th><th>Description</th></tr></thead><tbody><tr><td>drunkPercent</td><td>Current <code>drunk</code> status as a percentage (0–100).</td></tr><tr><td>permille</td><td>Calculated blood alcohol concentration (‰).</td></tr><tr><td>mgL</td><td>Calculated breath alcohol concentration (mg/L).</td></tr></tbody></table>

</details>

***

### ReloadVisualEffect

Reapplies the active VMS Needs visual effect after another resource overrides or clears the current timecycle modifier.

Use this export after reviving a player or whenever another resource temporarily applies its own screen effect.

```lua
exports['vms_needs']:ReloadVisualEffect()
```

***

### GetConfig

```lua
local config = exports['vms_needs']:GetConfig()
```