Client Exports

GetStatus

Returns a status controller for the specified player and status.

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

Example Usage

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

hunger.Set(300)

print(hunger.GetPercentage())

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

Returned Functions

{
    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,
}

---

GetStatuses

Returns a list of all registered player statuses.

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

Example Returned Data

{
    ["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",
    },
}

---

GetPercentageStatus

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

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

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

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

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

exports['vms_needs']:CleanupOptionalStatuses()

---

GetServerTemperature

Returns the current ambient server temperature.

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

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

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

Example

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

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

Available States

The following thermal states may be returned by this export.

State	Description	Temperature Range
NORMAL	Normal body temperature	36.0 - 37.5 °C
WARM	Slightly elevated body temperature	37.5 - 38.0 °C
HOT	Elevated body temperature	38.0 - 39.0 °C
OVERHEATED	Dangerously high body temperature	> 39.0 °C
CHILLED	Slightly reduced body temperature	35.2 - 36.0 °C
COLD	Low body temperature	34.0 - 35.2 °C
HYPOTHERMIA	Dangerously low body temperature	< 34.0 °C

---

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.

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

Example

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

---

GetPlayerCold

Returns the player's current cold factor.

The returned value is normalized between 0.0 and 1.0 and can be used to scale custom gameplay effects.

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

---

GetPlayerHeat

Returns the player's current heat factor.

The returned value is normalized between 0.0 and 1.0 and can be used to scale custom gameplay effects.

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

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

Example

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

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

---

CancelItemUsage

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

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.

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

Example

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

---

GetBreathalyzerReading

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

Note: The returned values are calculated using the current drunk status and the settings defined in Config.Alcohol.

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

Example Returned Data

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

Returned Fields

Field	Description
drunkPercent	Current drunk status as a percentage (0–100).
permille	Calculated blood alcohol concentration (‰).
mgL	Calculated breath alcohol concentration (mg/L).

---

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.

exports['vms_needs']:ReloadVisualEffect()

---

GetConfig

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