xPlayer overview

ภาพรวม Player Object (xPlayer), Properties ที่พบบ่อย และหมวดหมู่ของ Methods ที่ใช้งานบ่อย

ภาพรวม xPlayer

xPlayer คือ Object ของผู้เล่นฝั่ง Server

ใช้สำหรับจัดการข้อมูลและการกระทำของผู้เล่นแบบรวมศูนย์

คุณสามารถดึงข้อมูล xPlayer ได้จาก ESX.GetPlayerFromId(source)

หรือใช้ ESX.GetPlayerFromIdentifier(identifier)

จากนั้นสามารถเรียก Methods ผ่าน Object นี้ได้โดยตรง

xPlayer สามารถใช้งานได้ในสคริปต์ฝั่ง Server เท่านั้น

ข้อสำคัญด้านความปลอดภัย

ห้ามเชื่อข้อมูลจาก Client โดยตรง (เช่น amount, itemName, weaponName, grade) ให้ตรวจสอบสิทธิ์และตรวจสอบความถูกต้อง (Validate) ฝั่ง Server เสมอ

แนะนำให้ทำ "รายการที่อนุญาต (Allowlist)" สำหรับค่าที่สำคัญ เช่น ชื่อ Item และอาวุธ

การดึงข้อมูล xPlayer

examples.lua

-- จาก server ID (source)
local xPlayer = ESX.GetPlayerFromId(source)

-- จาก identifier
local xPlayerByIdentifier = ESX.GetPlayerFromIdentifier('license:abc123')

ESX.GetPlayerFromId() เป็นรูปแบบที่ใช้งานบ่อยที่สุด เมื่อคุณมี source จาก event/command อยู่แล้ว

Properties ที่พบบ่อย

ด้านล่างคือ properties ที่พบบ่อย

รายการจริงขึ้นกับเวอร์ชันและการปรับแต่งของเซิร์ฟเวอร์

Property	Type	Description
source	number	Server ID ของผู้เล่น
identifier	string	Identifier ของผู้เล่น
name	string	ชื่อตัวละคร
group	string	กลุ่มสิทธิ์ (เช่น 'user', 'admin')
job	table	ข้อมูลงานปัจจุบัน
accounts	table	ข้อมูลบัญชีเงิน
inventory	table	รายการ Item
loadout	table	รายการอาวุธ (loadout)
coords	table	พิกัดล่าสุด
weight	number	น้ำหนักปัจจุบัน
maxWeight	number	น้ำหนักสูงสุดที่ถือได้
metadata	table	พื้นที่เก็บ metadata
variables	table	พื้นที่เก็บตัวแปรชั่วคราว
health	number	เลือด/HP
armor	number	เกราะ

หมวดหมู่ Methods (Method categories)

• Accounts — จัดการบัญชีเงิน

• Inventory — จัดการ Item และน้ำหนัก

• Weapons — จัดการอาวุธ (loadout)

• Job — จัดการอาชีพและยศ

• Status — จัดการสถานะ (hunger/thirst ฯลฯ)

• General — Methods ทั่วไปของผู้เล่น

Usage Examples

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

example.lua

RegisterCommand('example', function(source)
    local xPlayer = ESX.GetPlayerFromId(source)
    if not xPlayer then return end

    -- ตรวจสอบเงินสด
    local money = xPlayer.getMoney()
    print('Player money: ' .. money)

    -- ให้ Item (ตรวจสอบน้ำหนักก่อน)
    if xPlayer.canCarryItem('bread', 5) then
        xPlayer.addInventoryItem('bread', 5, 'admin command: give bread')
    end

    -- เปลี่ยนอาชีพ
    xPlayer.setJob('police', 3)

    -- ทำหลายคำสั่งแบบเป็นชุด
    xPlayer.transaction({
        { name = 'addMoney', values = { 1000 } },
        { name = 'addInventoryItem', values = { 'bread', 5 } }
    })
end, true)

แนะนำให้ตั้งชื่อเป็น xPlayer ในทุกสคริปต์ เพื่อให้สอดคล้องกับเอกสารและอ่านโค้ดง่ายขึ้น