General

ฟังก์ชันฝั่ง Server สำหรับจัดการข้อมูลทั่วไปของผู้เล่นผ่าน xPlayer (variables, identity, coords, bucket, metadata, notifications, transactions)

General (xPlayer)

ฟังก์ชันทั่วไปสำหรับจัดการข้อมูลผู้เล่นฝั่ง Server-side ผ่านออบเจกต์ xPlayer

ครอบคลุมการจัดการตัวแปรชั่วคราว, ข้อมูลตัวตน, สิทธิ์, พิกัด, routing bucket, metadata และ utility อื่น ๆ

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

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

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

local xPlayer = ESX.GetPlayerFromId(source)

ฟังก์ชันในหน้านี้ใช้ได้เฉพาะสคริปต์ฝั่ง Server เท่านั้น

ค่าที่รับมาจาก Client ต้องตรวจสอบสิทธิ์และ validate เสมอ โดยเฉพาะคำสั่งที่เปลี่ยนชื่อ, เปลี่ยนกลุ่มสิทธิ์, teleport, kick หรือเปลี่ยน metadata

แนวคิด: Variables vs Metadata

• xPlayer.get/set(key, value) เหมาะกับ “ตัวแปรชั่วคราว” ระหว่างเล่น เช่น สถานะเข้าเวร, ใส่กุญแจมือ, อยู่ในโซนพิเศษ

• xPlayer.getMetadata/setMetadata(...) เหมาะกับ “ข้อมูลประกอบ” ที่ระบบต้องใช้งานร่วมกัน เช่น เบอร์โทร, licenses, flags เฉพาะตัว

พฤติกรรมการ persist ของ metadata ขึ้นกับการติดตั้ง/การตั้งค่าของเซิร์ฟเวอร์

---

Variables (Custom per-player variables)

xPlayer.get

ดึงค่าตัวแปรที่กำหนดเองที่เก็บไว้กับผู้เล่น

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

xPlayer.get(key)

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

Name	Type	Description
key	string	ชื่อตัวแปรที่ต้องการอ่าน

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

Type	Description
any	ค่าที่เก็บไว้ หรือ nil หากไม่พบ

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

local xPlayer = ESX.GetPlayerFromId(source)
local isHandcuffed = xPlayer.get('isHandcuffed')

if isHandcuffed then
    xPlayer.showNotification('~r~คุณถูกใส่กุญแจมือ')
end

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

local xPlayer = ESX.GetPlayerFromId(source)
local inSafeZone = xPlayer.get('inSafeZone')
if inSafeZone then
    print('player is in safe zone')
end

---

xPlayer.set

กำหนดค่าตัวแปรที่กำหนดเองให้กับผู้เล่น และ trigger event เมื่อค่าเปลี่ยน

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

xPlayer.set(key, value)

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

Name	Type	Description
key	string	ชื่อตัวแปร
value	any	ค่าที่ต้องการตั้ง

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

Type	Description
boolean	true หากสำเร็จ, false หากค่าไม่เปลี่ยนแปลง

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

local xPlayer = ESX.GetPlayerFromId(source)
xPlayer.set('isHandcuffed', true)

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

xPlayer.set('jailTime', 300) -- 300 วินาที

RegisterNetEvent('safezone:enter')
AddEventHandler('safezone:enter', function()
    local xPlayer = ESX.GetPlayerFromId(source)
    xPlayer.set('inSafeZone', true)
end)

Events ที่ถูก trigger

Event	Parameters
NCCore:onSetVariable (server)	source, key, value, lastValue

---

Identity & Permissions

xPlayer.getName

คืนค่าชื่อตัวละครของผู้เล่น

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

xPlayer.getName()

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

Type	Description
string	ชื่อผู้เล่น

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

local xPlayer = ESX.GetPlayerFromId(source)
print('ชื่อผู้เล่น: ' .. xPlayer.getName())

---

xPlayer.setName

เปลี่ยนชื่อตัวละครของผู้เล่น

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

xPlayer.setName(name)

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

Name	Type	Description
name	string	ชื่อใหม่

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

Type	Description
boolean	true หากสำเร็จ, false หากชื่อไม่เปลี่ยนแปลง

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

RegisterNetEvent('admin:changeName')
AddEventHandler('admin:changeName', function(targetId, newName)
    local xPlayer = ESX.GetPlayerFromId(source)
    local xTarget = ESX.GetPlayerFromId(targetId)

    if xPlayer.getGroup() ~= 'admin' then return end
    if not xTarget then return end

    xTarget.setName(newName)
    xTarget.showNotification('~g~ชื่อของคุณถูกเปลี่ยนเป็น ' .. newName)
end)

ควรจำกัดการใช้งาน setName() เฉพาะแอดมินหรือ flow ที่ยืนยันตัวตนแล้ว

---

xPlayer.getIdentifier

คืนค่า identifier ของผู้เล่น

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

xPlayer.getIdentifier()

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

Type	Description
string	Identifier string ของผู้เล่น

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

local xPlayer = ESX.GetPlayerFromId(source)
local identifier = xPlayer.getIdentifier()
print('identifier:', identifier)

---

xPlayer.getGroup

คืนค่ากลุ่มสิทธิ์ของผู้เล่น

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

xPlayer.getGroup()

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

Type	Description
string	ชื่อกลุ่ม (เช่น 'user', 'admin', 'superadmin')

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

RegisterCommand('tpwaypoint', function(source)
    local xPlayer = ESX.GetPlayerFromId(source)
    local group = xPlayer.getGroup()

    if group == 'admin' or group == 'superadmin' then
        TriggerClientEvent('admin:tpToWaypoint', source)
    else
        xPlayer.showNotification('~r~คุณไม่มีสิทธิ์')
    end
end)

---

xPlayer.setGroup

เปลี่ยนกลุ่มสิทธิ์ของผู้เล่น และอัปเดต ACE permissions อัตโนมัติ

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

xPlayer.setGroup(group)

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

Name	Type	Description
group	string	ชื่อกลุ่มใหม่

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

Type	Description
boolean	true หากสำเร็จ, false หากกลุ่มไม่เปลี่ยนแปลง

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

RegisterCommand('setadmin', function(source, args)
    local xPlayer = ESX.GetPlayerFromId(source)
    if xPlayer.getGroup() ~= 'superadmin' then return end

    local targetId = tonumber(args[1])
    local xTarget = ESX.GetPlayerFromId(targetId)
    if not xTarget then return end

    xTarget.setGroup('admin')
    xTarget.showNotification('~g~คุณได้รับยศ Admin')
    xPlayer.showNotification('~g~ให้ยศ Admin สำเร็จ')
end, true)

ฟังก์ชันนี้จะลบ ACE principal เดิม และเพิ่ม principal ใหม่โดยอัตโนมัติ

---

Position & Status

xPlayer.getCoords

คืนค่าพิกัดล่าสุดของผู้เล่น

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

xPlayer.getCoords(vector)

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

Name	Type	Description
vector	boolean	(ไม่บังคับ) ถ้าเป็น true จะคืนค่าเป็น vector3

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

Type	Description
table|vector3	พิกัดพร้อม fields x, y, z, heading หรือ vector3

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

local xPlayer = ESX.GetPlayerFromId(source)
local coords = xPlayer.getCoords(true)
print('ตำแหน่ง:', coords)

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

local xPlayer = ESX.GetPlayerFromId(source)
local coordsTable = xPlayer.getCoords(false)
print(string.format('X: %.2f, Y: %.2f, Z: %.2f', coordsTable.x, coordsTable.y, coordsTable.z))

RegisterCommand('checkdistance', function(source, args)
    local xPlayer = ESX.GetPlayerFromId(source)
    local targetId = tonumber(args[1])
    local xTarget = ESX.GetPlayerFromId(targetId)
    if not xTarget then return end

    local d = #(xPlayer.getCoords(true) - xTarget.getCoords(true))
    xPlayer.showNotification(('ระยะห่าง: %dm'):format(math.floor(d)))
end)

---

xPlayer.setCoords

ย้ายผู้เล่น (teleport) ไปยังพิกัดที่ระบุ

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

xPlayer.setCoords(coords)

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

Name	Type	Description
coords	vector3|vector4|table	พิกัดปลายทาง

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

Type	Description
boolean	true หากสำเร็จ, false หาก ped ไม่มีอยู่จริง

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

local xPlayer = ESX.GetPlayerFromId(source)
xPlayer.setCoords(vector3(307.7, -1433.5, 29.9))

ควรจำกัดการใช้งาน setCoords() เฉพาะแอดมิน หรือระบบที่ตรวจสอบสิทธิ์แล้ว

---

xPlayer.updateCoords

ซิงค์พิกัดจากเกมไปยัง xPlayer (ใช้งานภายใน)

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

xPlayer.updateCoords()

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

Type	Description
boolean	true หากสำเร็จ

ฟังก์ชันนี้ถูกเรียกโดย framework อัตโนมัติ โดยทั่วไปไม่จำเป็นต้องเรียกเอง

---

xPlayer.getHealth

คืนค่า HP ของผู้เล่น

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

xPlayer.getHealth()

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

Type	Description
number	ค่าเลือด (0-200)

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

local xPlayer = ESX.GetPlayerFromId(source)
if xPlayer.getHealth() < 100 then
    print('ผู้เล่น HP ต่ำ')
end

---

xPlayer.getArmor

คืนค่าเกราะของผู้เล่น

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

xPlayer.getArmor()

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

Type	Description
number	ค่าเกราะ (0-100)

---

Routing buckets

xPlayer.getBucket

คืนค่า routing bucket ปัจจุบันของผู้เล่น

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

xPlayer.getBucket()

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

Type	Description
number	Routing bucket ID

Routing bucket ใช้แยก “โลก” ของผู้เล่น ผู้เล่นที่อยู่คนละ bucket จะไม่เห็นกันและกัน

---

xPlayer.setBucket

เปลี่ยน routing bucket ของผู้เล่น

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

xPlayer.setBucket(bucket)

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

Name	Type	Description
bucket	number	Routing bucket ใหม่

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

Type	Description
boolean	true หากสำเร็จ, false หาก bucket ไม่เปลี่ยนแปลง

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

RegisterNetEvent('housing:enter')
AddEventHandler('housing:enter', function(houseId)
    local xPlayer = ESX.GetPlayerFromId(source)
    local bucket = 1000 + houseId

    xPlayer.setBucket(bucket)
    xPlayer.setCoords(Config.HouseInteriors[houseId])
end)

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

RegisterNetEvent('housing:exit')
AddEventHandler('housing:exit', function()
    local xPlayer = ESX.GetPlayerFromId(source)
    xPlayer.setBucket(0) -- bucket 0 = โลกหลัก
end)

---

Metadata

xPlayer.getMetadata

ดึงค่า metadata ตาม key ที่ระบุ

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

xPlayer.getMetadata(key)

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

Name	Type	Description
key	string	Metadata key

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

Type	Description
any	ค่า metadata

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

local xPlayer = ESX.GetPlayerFromId(source)
local phoneNumber = xPlayer.getMetadata('phone_number')

---

xPlayer.getAllMetadata

ดึง metadata ทั้งหมดของผู้เล่น

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

xPlayer.getAllMetadata()

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

Type	Description
table	ตาราง metadata ทั้งหมด

---

xPlayer.setMetadata

ตั้งค่า metadata ตาม key ที่ระบุ

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

xPlayer.setMetadata(key, value)

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

Name	Type	Description
key	string	Metadata key
value	any	ค่าที่ต้องการตั้ง

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

Type	Description
boolean	true หากสำเร็จ, false หากค่าไม่เปลี่ยนแปลง

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

local xPlayer = ESX.GetPlayerFromId(source)
xPlayer.setMetadata('phone_number', '555-0123')

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

RegisterNetEvent('dmv:passTest')
AddEventHandler('dmv:passTest', function(licenseType)
    local xPlayer = ESX.GetPlayerFromId(source)
    local licenses = xPlayer.getMetadata('licenses') or {}

    table.insert(licenses, {
        type = licenseType,
        date = os.date('%Y-%m-%d')
    })

    xPlayer.setMetadata('licenses', licenses)
end)

---

Utilities

xPlayer.kick

เตะผู้เล่นออกจากเซิร์ฟเวอร์ พร้อมเหตุผล

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

xPlayer.kick(reason, args, ...)

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

Name	Type	Description
reason	string	เหตุผล (รองรับ string.format เมื่อส่ง args)
args	any	(ไม่บังคับ) ตัวแปรสำหรับ format
...	any	(ไม่บังคับ) ตัวแปรเพิ่มเติม

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

local xPlayer = ESX.GetPlayerFromId(source)
xPlayer.kick('คุณถูกเตะ: %s', 'ละเมิดกฎ')

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

RegisterCommand('kick', function(source, args)
    local xPlayer = ESX.GetPlayerFromId(source)
    if xPlayer.getGroup() ~= 'admin' then return end

    local targetId = tonumber(args[1])
    local reason = table.concat(args, ' ', 2)
    local xTarget = ESX.GetPlayerFromId(targetId)
    if not xTarget then return end

    xTarget.kick('คุณถูกเตะโดย Admin: %s', reason)
end, true)

---

xPlayer.showNotification

ส่งการแจ้งเตือนให้ผู้เล่น

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

xPlayer.showNotification(msg)

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

Name	Type	Description
msg	string|table	ข้อความ หรือ options สำหรับ notification

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

local xPlayer = ESX.GetPlayerFromId(source)
xPlayer.showNotification('~g~ยินดีต้อนรับ!')

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

xPlayer.showNotification({
    title = 'ยินดีต้อนรับ!',
    type = 'success',
    description = 'คุณเข้าสู่เซิร์ฟเวอร์แล้ว'
})

---

xPlayer.triggerEvent

trigger client event เฉพาะผู้เล่นคนนี้

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

xPlayer.triggerEvent(eventName, ...)

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

Name	Type	Description
eventName	string	ชื่อ event
...	any	arguments ที่ส่งให้ event

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

local xPlayer = ESX.GetPlayerFromId(source)

xPlayer.triggerEvent('myResource:updateUI', {
    score = 100,
    level = 5
})

---

Transactions

xPlayer.transaction

รันหลายคำสั่งบน xPlayer แบบมีลำดับ และคืนผลลัพธ์ของแต่ละ operation

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

xPlayer.transaction(transaction)

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

Name	Type	Description
transaction	table	Array ของ operations { name, values }

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

Type	Description
table	Array ผลลัพธ์ของแต่ละ method call

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

local xPlayer = ESX.GetPlayerFromId(source)
local results = xPlayer.transaction({
    { name = 'addMoney', values = { 5000 } },
    { name = 'addInventoryItem', values = { 'bread', 10 } }
})

if results[1] and results[1][1] then
    xPlayer.showNotification('~g~ทำรายการสำเร็จ')
end

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

RegisterNetEvent('character:firstJoin')
AddEventHandler('character:firstJoin', function()
    local xPlayer = ESX.GetPlayerFromId(source)

    xPlayer.transaction({
        { name = 'addMoney', values = { 5000 } },
        { name = 'addAccountMoney', values = { 'bank', 25000 } },
        { name = 'addInventoryItem', values = { 'bread', 5 } },
        { name = 'addInventoryItem', values = { 'water', 5 } },
        { name = 'addInventoryItem', values = { 'phone', 1 } },
        { name = 'setJob', values = { 'unemployed', 0 } }
    })
end)

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

• ให้รางวัลหลายอย่างพร้อมกัน (เงิน + Item)

• ตั้งค่าตัวละครใหม่แบบ batch

• ทำงานหลายขั้นตอนให้สั้นและอ่านง่าย

ใช้ xPlayer.transaction() เมื่อต้องทำหลายอย่างต่อเนื่องในจุดเดียว เพื่อให้อ่านง่ายและจัดการผลลัพธ์ได้เป็นชุด