Status - Exports

Server and client status system for hunger, thirst, stress, and custom statuses

The Status component manages player statuses like hunger, thirst, stress, and drunkenness. It has both server and client components — the server tracks persistence while the client handles visual display and effects.

Overview

Access via Status on both server and client.

Built-in Statuses

Hunger, Thirst, Stress, Drunk

Custom Statuses

Register your own status types

Visual Effects

HUD display, blur, shake effects

Persistence

Saved to character data

---

Server-Side Methods

Server-side Status methods manage data persistence. The client handles visual display and modification logic. Use Execute:Client or events to trigger client-side changes from the server.

Status:Register (Server)

Register a status type on the server.

Status:Register(name, max, icon, tick, modify)

name · string · required

Status identifier (e.g., 'PLAYER_HUNGER')

max · number · required

Maximum value

icon · string · required

Icon identifier

tick · function

Callback for tick logic

modify · function

Callback for modification logic

---

Status.Get:All (Server)

Get all registered status definitions.

Status.Get:All()

statuses · table

All registered status definitions

---

Status.Get:Single (Server)

Get a single status definition.

Status.Get:Single(name)

name · string · required

Status name

---

Status:Set (Server)

Set a status value for a player and sync to client.

Status:Set(source, name, value)

source · number · required

Player server ID

name · string · required

Status name

value · number · required

New value

Example:

-- Reset a player's hunger to full
Status:Set(source, 'PLAYER_HUNGER', 100)

-- Set stress to zero
Status:Set(source, 'PLAYER_STRESS', 0)

---

Status.Modify:Add (Server)

Add to a status value via client callback.

Status.Modify:Add(source, name, value, addCd, isForced)

source · number · required

Player server ID

name · string · required

Status name

value · number · required

Amount to add

addCd · boolean

Add cooldown after modification

isForced · boolean

Force the modification (bypass checks)

Example:

-- Feed the player (restore hunger)
Status.Modify:Add(source, 'PLAYER_HUNGER', 25)

-- Hydrate the player
Status.Modify:Add(source, 'PLAYER_THIRST', 30)

---

Status.Modify:Remove (Server)

Remove from a status value via client callback.

Status.Modify:Remove(source, name, value, addCd, isForced)

Example:

-- Add stress
Status.Modify:Remove(source, 'PLAYER_STRESS', 15)

-- Sober up
Status.Modify:Remove(source, 'PLAYER_DRUNK', 20)

For inverted statuses like Stress and Drunk (where higher = worse), Remove decreases the value and Add increases it. Use Remove to reduce these statuses.

---

Client-Side Methods

Status:Register (Client)

Register a status with visual properties for the HUD.

Status:Register(name, max, icon, color, flash, modify, options)

name · string · required

Status identifier

max · number · required

Maximum value

icon · string · required

FontAwesome icon name

color · string · required

Hex color code for HUD display

flash · boolean · required

Enable flash animation when low

modify · function · required

Callback for value changes: function(change, force)

options · table · required

Display options (see Options below)

---

Status.Get:All (Client)

Get all statuses with their current values.

Status.Get:All()

statuses · table

All statuses with current values from LocalPlayer.state

---

Status.Get:Single (Client)

Get a single status with current value.

Status.Get:Single(name)

---

Status.Set:All (Client)

Set all statuses to a specific value.

Status.Set:All(entity, value)

---

Status.Set:Single (Client)

Set a single status to a specific value.

Status.Set:Single(name, value)

Example:

-- Client-side: Set hunger to full
Status.Set:Single('PLAYER_HUNGER', 100)

---

Status.Modify:Add (Client)

Add to a status value on the client.

Status.Modify:Add(status, value, addCd, force)

---

Status.Modify:Remove (Client)

Remove from a status value on the client.

Status.Modify:Remove(status, value, force)

---

Status:Reset

Reset all resettable statuses to their maximum value.

Status:Reset(entity, value)

Statuses with noReset = true (like Stress and Drunk) are not affected by Reset.

---

Status:Toggle

Toggle the status system on or off.

Status:Toggle()

---

Status:Check

Check if the status system is currently enabled.

Status:Check()

enabled · boolean

true if status system is active

---

Options Structure

{
    id = 1,            -- HUD position priority (lower = further left)
    hideHigh = false,  -- Hide the status icon when at max value
    hideZero = false,  -- Hide the status icon when at zero
    inverted = false,  -- Inverted display (fills right to left, higher = worse)
    noReset = false    -- Won't reset when Status:Reset is called
}

---

Status Storage

• Character Data: Character:SetData("Status", { PLAYER_HUNGER = 100, ... })
• State Variables: LocalPlayer.state["status:PLAYER_HUNGER"]
• HUD Display: Registered via Hud:RegisterStatus()

---

Best Practices

Use Server Methods for Persistence

-- ✅ Good: Server sets status (persists and syncs)
Status:Set(source, 'PLAYER_HUNGER', 100)

-- ❌ Bad: Client-only change (won't persist on disconnect)
-- Only use client methods for temporary visual effects

Understand Inverted Statuses

-- Hunger/Thirst: 100 = full, 0 = starving (normal)
-- Stress/Drunk: 0 = sober, 100 = max (inverted)

-- To feed a player:
Status.Modify:Add(source, 'PLAYER_HUNGER', 25)

-- To reduce stress:
Status.Modify:Remove(source, 'PLAYER_STRESS', 10)

---

Next Steps

Status - Defaults

Built-in status types and effects

HUD API

HUD display system

Characters API

Character data access