Status

ฟังก์ชันฝั่ง Server สำหรับอ่าน/ปรับสถานะผู้เล่น (เช่น hunger, thirst) ผ่าน xPlayer รวมถึงการตั้งค่า update rate และการ freeze/unfreeze

Status (xPlayer)

ฟังก์ชันสำหรับจัดการ "สถานะ" ของผู้เล่น เช่น hunger, thirst และสถานะอื่น ๆ ที่เซิร์ฟเวอร์กำหนด

ใช้งานผ่านออบเจกต์ผู้เล่น xPlayer และทำงานฝั่ง Server-side เท่านั้น

ก่อนเริ่ม (แนะนำ)

• แนะนำให้ตั้งค่าการเรียกใช้ Framework ให้ถูกต้องตาม Framework Usage

• ดึง xPlayer จาก source ก่อนเรียกใช้งาน:

local xPlayer = ESX.GetPlayerFromId(source)

Status ส่วนใหญ่เก็บเป็นตัวเลขช่วง 0 ถึง 1,000,000 โดย 1,000,000 มักเทียบเท่า “เต็ม 100%”

ค่าที่รับมาจาก Client (เช่น statusName, value) ต้องตรวจสอบสิทธิ์และตรวจสอบความถูกต้อง (validate) เสมอ แนะนำให้ทำ allowlist ของชื่อสถานะที่อนุญาต เพื่อป้องกันการแก้สถานะที่ไม่ควรแก้

---

xPlayer.getStatus

คืนค่าปัจจุบันของสถานะที่ระบุ

รูปแบบการใช้งาน (Syntax)

xPlayer.getStatus(name)

พารามิเตอร์ (Parameters)

Name	Type	Description
name	string	ชื่อสถานะ (เช่น 'hunger', 'thirst')

ค่าที่ส่งคืน (Returns)

Type	Description
number	ค่าสถานะปัจจุบัน (โดยทั่วไป 0-1,000,000)

ตัวอย่างการใช้งาน (Example)

local xPlayer = ESX.GetPlayerFromId(source)
local hunger = xPlayer.getStatus('hunger')

if hunger < 200000 then
    xPlayer.showNotification('~r~คุณหิวมาก!')
elseif hunger < 500000 then
    xPlayer.showNotification('~y~คุณหิวนิดหน่อย')
end

ตัวอย่างเพิ่มเติม (ขยายดู)

RegisterNetEvent('restaurant:buyFood')
AddEventHandler('restaurant:buyFood', function(foodItem)
    local xPlayer = ESX.GetPlayerFromId(source)
    local hunger = xPlayer.getStatus('hunger')
    
    if hunger >= 950000 then
        xPlayer.showNotification('~y~คุณอิ่มแล้ว ไม่ต้องกินหรอก')
        return
    end
    
    if xPlayer.getMoney() >= 50 then
        xPlayer.removeMoney(50, 'ซื้ออาหาร')
        xPlayer.addStatus('hunger', 200000)
        xPlayer.showNotification('~g~รับประทานอาหารแล้ว')
    end
end)

กรณีการใช้งาน (Use cases)

• ตรวจสอบเงื่อนไขก่อนให้ทำกิจกรรม (เช่น หิวมากห้ามวิ่ง)

• ตรวจสอบก่อนอนุญาตให้ซื้อ/กิน/ดื่ม

---

xPlayer.getAllStatus

คืนค่าสถานะทั้งหมด

รูปแบบการใช้งาน (Syntax)

xPlayer.getAllStatus(minimal)

พารามิเตอร์ (Parameters)

Name	Type	Description
minimal	boolean	(ไม่บังคับ) ถ้าเป็น true จะคืนค่าแบบย่อ {[name] = value}

ค่าที่ส่งคืน (Returns)

Type	Description
table	รายการสถานะทั้งหมด (รูปแบบขึ้นกับ minimal)

ตัวอย่างการใช้งาน (Example)

local xPlayer = ESX.GetPlayerFromId(source)
local allStatus = xPlayer.getAllStatus(false)

for i=1, #allStatus do
    print(allStatus[i].name .. ': ' .. allStatus[i].val)
end

local minimalStatus = xPlayer.getAllStatus(true)
TriggerClientEvent('hud:updateStatus', source, minimalStatus)

กรณีการใช้งาน (Use cases)

• ส่งสถานะไป HUD/UI

• สร้าง debug/log เพื่อเช็กสถานะผู้เล่น

---

xPlayer.setStatus

ตั้งค่าสถานะเป็นตัวเลขที่กำหนด

รูปแบบการใช้งาน (Syntax)

xPlayer.setStatus(name, value)

พารามิเตอร์ (Parameters)

Name	Type	Description
name	string	ชื่อสถานะ
value	number	ค่าใหม่ (แนะนำให้ clamp ให้อยู่ในช่วง 0-1,000,000)

ตัวอย่างการใช้งาน (Example)

local xPlayer = ESX.GetPlayerFromId(source)
xPlayer.setStatus('hunger', 1000000)

ตัวอย่างเพิ่มเติม (ขยายดู)

RegisterNetEvent('character:firstSpawn')
AddEventHandler('character:firstSpawn', function()
    local xPlayer = ESX.GetPlayerFromId(source)
    xPlayer.setStatus('hunger', 1000000)
    xPlayer.setStatus('thirst', 1000000)
end)

กรณีการใช้งาน (Use cases)

• ตั้งค่าเริ่มต้นหลังสร้างตัวละคร/เข้าเกม

• แก้ไขสถานะผิดปกติ (เครื่องมือแอดมิน)

xPlayer.setStatus() เป็นการ “เขียนทับค่า” ถ้าต้องการเพิ่ม/ลดตามจำนวน แนะนำให้ใช้ xPlayer.addStatus() หรือ xPlayer.removeStatus()

---

xPlayer.addStatus

เพิ่มค่าให้กับสถานะ

รูปแบบการใช้งาน (Syntax)

xPlayer.addStatus(name, value)

พารามิเตอร์ (Parameters)

Name	Type	Description
name	string	ชื่อสถานะ
value	number	จำนวนที่เพิ่ม

ตัวอย่างการใช้งาน (Example)

ESX.RegisterUsableItem('bread', function(source)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    xPlayer.removeInventoryItem('bread', 1)
    xPlayer.addStatus('hunger', 200000) -- เพิ่มความหิว 20%
    
    TriggerClientEvent('esx_status:onUse', source, 'bread')
    xPlayer.showNotification('~g~คุณกินขนมปัง')
end)

ตัวอย่างเพิ่มเติม (ขยายดู)

ESX.RegisterUsableItem('water', function(source)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    xPlayer.removeInventoryItem('water', 1)
    xPlayer.addStatus('thirst', 250000) -- เพิ่มความกระหาย 25%
    
    TriggerClientEvent('esx_status:onUse', source, 'water')
    xPlayer.showNotification('~g~คุณดื่มน้ำ')
end)

ESX.RegisterUsableItem('energy_drink', function(source)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    xPlayer.removeInventoryItem('energy_drink', 1)
    xPlayer.addStatus('thirst', 200000)
    xPlayer.addStatus('stamina', 300000) -- เพิ่มพลัง
    
    xPlayer.showNotification('~g~รู้สึกมีแรง!')
end)

กรณีการใช้งาน (Use cases)

• ระบบกิน/ดื่ม เพิ่มสถานะตาม Item

• บัฟจาก Item พิเศษหรือกิจกรรม

---

xPlayer.removeStatus

ลดค่าจากสถานะ

รูปแบบการใช้งาน (Syntax)

xPlayer.removeStatus(name, value)

พารามิเตอร์ (Parameters)

Name	Type	Description
name	string	ชื่อสถานะ
value	number	จำนวนที่ลด

ตัวอย่างการใช้งาน (Example)

-- ลดความหิวเมื่อวิ่ง
RegisterNetEvent('player:running')
AddEventHandler('player:running', function()
    local xPlayer = ESX.GetPlayerFromId(source)
    xPlayer.removeStatus('hunger', 5000) -- ลดความหิว
    xPlayer.removeStatus('thirst', 3000) -- ลดความกระหาย
end)

กรณีการใช้งาน (Use cases)

• ลดสถานเตามกิจกรรม (วิ่ง, ต่อสู้, ออกกำลังกาย)

---

xPlayer.getStatusUpdate

ดึง “อัตราการเปลี่ยนแปลงอัตโนมัติ” ของสถานะต่อรอบอัปเดต

รูปแบบการใช้งาน (Syntax)

xPlayer.getStatusUpdate(name)

พารามิเตอร์ (Parameters)

Name	Type	Description
name	string	ชื่อสถานะ

ค่าที่ส่งคืน (Returns)

Type	Description
number	ค่า update ต่อรอบ (ค่าลบ = ลดลง)

---

xPlayer.setStatusUpdate

ตั้ง “อัตราการเปลี่ยนแปลงอัตโนมัติ” ของสถานะต่อรอบอัปเดต

รูปแบบการใช้งาน (Syntax)

xPlayer.setStatusUpdate(name, value)

พารามิเตอร์ (Parameters)

Name	Type	Description
name	string	ชื่อสถานะ
value	number	อัตรา update ต่อรอบ (ค่าลบ = ลดลง)

ตัวอย่างการใช้งาน (Example)

-- ลดความหิวเร็วขึ้นเมื่อออกกำลังกาย
RegisterNetEvent('gym:enter')
AddEventHandler('gym:enter', function()
    local xPlayer = ESX.GetPlayerFromId(source)
    xPlayer.setStatusUpdate('hunger', -500) -- ลดเร็วกว่าปกติ
    xPlayer.showNotification('~y~คุณกำลังออกกำลังกาย หิวเร็วขึ้น')
end)

-- กลับสู่ปกติ
RegisterNetEvent('gym:leave')
AddEventHandler('gym:leave', function()
    local xPlayer = ESX.GetPlayerFromId(source)
    xPlayer.setStatusUpdate('hunger', -200) -- กลับสู่ค่าปกติ
end)

---

xPlayer.freezeStatus

หยุดการอัปเดตอัตโนมัติของสถานะที่ระบุ

รูปแบบการใช้งาน (Syntax)

xPlayer.freezeStatus(name)

พารามิเตอร์ (Parameters)

Name	Type	Description
name	string	ชื่อสถานะ

ตัวอย่างการใช้งาน (Example)

RegisterNetEvent('safezone:enter')
AddEventHandler('safezone:enter', function()
    local xPlayer = ESX.GetPlayerFromId(source)
    
    xPlayer.freezeStatus('hunger')
    xPlayer.freezeStatus('thirst')
    
    xPlayer.showNotification('~g~เข้าสู่พื้นที่ปลอดภัย สถานะหยุดลดลง')
end)

ตัวอย่างเพิ่มเติม (ขยายดู)

RegisterNetEvent('event:start')
AddEventHandler('event:start', function()
    local xPlayer = ESX.GetPlayerFromId(source)
    
    xPlayer.freezeStatus('hunger')
    xPlayer.freezeStatus('thirst')
    
    xPlayer.showNotification('~b~สถานะถูกหยุดระหว่างอีเว้นท์')
end)

---

xPlayer.unfreezeStatus

เปิดการอัปเดตอัตโนมัติของสถานะที่ระบุอีกครั้ง

รูปแบบการใช้งาน (Syntax)

xPlayer.unfreezeStatus(name)

พารามิเตอร์ (Parameters)

Name	Type	Description
name	string	ชื่อสถานะ

ตัวอย่างการใช้งาน (Example)

RegisterNetEvent('safezone:leave')
AddEventHandler('safezone:leave', function()
    local xPlayer = ESX.GetPlayerFromId(source)
    
    xPlayer.unfreezeStatus('hunger')
    xPlayer.unfreezeStatus('thirst')
    
    xPlayer.showNotification('~y~ออกจากพื้นที่ปลอดภัย สถานะเริ่มลดอีกครั้ง')
end)

---

xPlayer.freezeAllStatus

หยุดการอัปเดตสถานะทั้งหมด

รูปแบบการใช้งาน (Syntax)

xPlayer.freezeAllStatus()

ตัวอย่างการใช้งาน (Example)

-- หยุดสถานะทั้งหมดเมื่อเข้าอีเว้นท์
RegisterNetEvent('arena:enter')
AddEventHandler('arena:enter', function()
    local xPlayer = ESX.GetPlayerFromId(source)
    
    xPlayer.freezeAllStatus()
    xPlayer.showNotification('~g~สถานะทั้งหมดถูกหยุด')
end)

---

xPlayer.unfreezeAllStatus

เปิดการอัปเดตสถานะทั้งหมด

รูปแบบการใช้งาน (Syntax)

xPlayer.unfreezeAllStatus()

ตัวอย่างการใช้งาน (Example)

-- เปิดสถานะทั้งหมดเมื่อออกจากอีเว้นท์
RegisterNetEvent('arena:leave')
AddEventHandler('arena:leave', function()
    local xPlayer = ESX.GetPlayerFromId(source)
    
    xPlayer.unfreezeAllStatus()
    xPlayer.showNotification('~g~สถานะกลับมาทำงานปกติ')
end)

---

xPlayer.setUpdateInterval

ตั้งช่วงเวลา (interval) สำหรับการอัปเดตสถานะอัตโนมัติ

รูปแบบการใช้งาน (Syntax)

xPlayer.setUpdateInterval(duration)

พารามิเตอร์ (Parameters)

Name	Type	Description
duration	number	ช่วงเวลาอัปเดต (มิลลิวินาที)

ตัวอย่างการใช้งาน (Example)

-- เปลี่ยนความถี่ในการอัปเดต
local xPlayer = ESX.GetPlayerFromId(source)
xPlayer.setUpdateInterval(30000) -- อัปเดตทุก 30 วินาที

ค่าเริ่มต้นมักเป็น 10,000 ms (10 วินาที) ไม่แนะนำให้ตั้งต่ำเกินไป เพราะทำให้ฝั่ง Server ทำงานถี่และเกิดภาระเพิ่ม

---

กรณีการใช้งาน (Use cases)

• ระบบอาหาร/น้ำ: เพิ่ม hunger / thirst เมื่อกิน/ดื่ม

• Safe zone: หยุดสถานะในพื้นที่ปลอดภัย

• Event/Arena: หยุดสถานะระหว่างกิจกรรม

• Gym/Exercise: ปรับอัตราการลดลงของสถานะให้เร็วขึ้น/ช้าลง

• ตรวจสอบสถานะก่อนอนุญาตให้ทำกิจกรรม

ควรตรวจสอบสถานะก่อนอนุญาตให้ผู้เล่นทำกิจกรรมบางอย่าง เช่น ห้ามวิ่งถ้าหิวมาก

การใช้ freezeStatus() ควรใช้เฉพาะเมื่อจำเป็น อย่าลืม unfreezeStatus() เมื่อออกจากสถานการณ์

---

สรุปฟังก์ชันใน Status

ฟังก์ชันต่อไปนี้เป็น method บน xPlayer

Function	Description
getStatus(name)	อ่านค่าสถานะ
getAllStatus(minimal)	อ่านสถานะทั้งหมด
setStatus(name, value)	เขียนทับค่าสถานะ
addStatus(name, value)	เพิ่มค่าสถานะ
removeStatus(name, value)	ลดค่าสถานะ
getStatusUpdate(name)	อ่านค่า update ต่อรอบ
setStatusUpdate(name, value)	ตั้งค่า update ต่อรอบ
freezeStatus(name)	หยุดอัปเดตสถานะรายตัว
unfreezeStatus(name)	เปิดอัปเดตสถานะรายตัว
freezeAllStatus()	หยุดอัปเดตสถานะทั้งหมด
unfreezeAllStatus()	เปิดอัปเดตสถานะทั้งหมด
setUpdateInterval(duration)	ตั้ง interval ของการอัปเดต

---

แนวทางสำหรับนักพัฒนา {#best-practices}

1

ควบคุมชื่อสถานะ (allowlist)

กำหนดรายการสถานะที่อนุญาต เช่น hunger, thirst, stamina และปฏิเสธชื่ออื่นที่ส่งมาจาก Client

2

Clamp ค่าให้อยู่ในช่วง

ก่อน setStatus/addStatus/removeStatus แนะนำให้ clamp ค่าให้อยู่ในช่วง 0-1,000,000 เพื่อป้องกันค่าหลุดช่วงจาก input ผิดหรือการโกง

3

อย่าตั้ง interval ถี่เกินไป

การตั้ง interval ถี่เกินไปทำให้ Server ทำงานหนักขึ้น ควรเริ่มจากค่าเริ่มต้น และปรับเฉพาะเมื่อมีเหตุผลชัดเจน

4

Freeze แล้วต้อง Unfreeze

ทุก flow ที่เรียก freezeStatus() หรือ freezeAllStatus() ควรมีจุดคืนค่าด้วย unfreeze...() เสมอ