Server

ฟังก์ชันฝั่ง Server ที่เรียกผ่าน ESX.* สำหรับจัดการผู้เล่น Item คำสั่ง และการบันทึกข้อมูล

ฟังก์ชันฝั่ง Server (ESX.*)

หน้านี้รวบรวมฟังก์ชันหลักฝั่ง Server-side ที่เรียกผ่าน ESX.*

ใช้สำหรับอ่าน/แก้ไขข้อมูลผู้เล่น, ตรวจสอบสิทธิ์, จัดการ Item/เงิน, และทำงานกับระบบฐานข้อมูล

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

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

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

• แยกไฟล์ server.lua / client.lua ให้ชัดเจน แล้วเรียกใช้งานให้ถูกฝั่ง

• ตรวจสอบและบังคับใช้กฎทุกอย่างที่ฝั่ง Server เสมอ (เงิน/Item/สิทธิ์)

อย่าเชื่อข้อมูลจาก Client โดยตรง ให้ validate และตรวจสอบสิทธิ์ที่ฝั่ง Server ทุกครั้ง

รูปแบบ Trigger (Event) ที่แนะนำ

ตั้งชื่อ event ให้ “ไม่ชน” กับ resource อื่น และอ่านแล้วรู้ฝั่ง/หน้าที่

• รูปแบบชื่อที่แนะนำ: <resource>:<action>

• ใช้ server / client เพื่อบอกทิศทางการรับ event

• หลีกเลี่ยงชื่อสั้น ๆ เช่น buy, open, update (ชนง่าย)

ตัวอย่างฝั่ง Server (รับจาก Client):

RegisterNetEvent('my_resource:buyItem', function(itemName, price)
    local src = source

    -- แนะนำ: validate ทุก input
    if type(itemName) ~= 'string' then return end
    if type(price) ~= 'number' or price <= 0 then return end

    local xPlayer = ESX.GetPlayerFromId(src)
    if not xPlayer then return end

    -- ทำธุรกรรม...
end)

ตัวอย่างฝั่ง Server (ส่งไป Client เฉพาะคน):

TriggerClientEvent('my_resource:notify', targetId, 'Hello')

ถ้าต้อง “ขอข้อมูล” จากอีกฝั่ง แนะนำใช้ callback มากกว่า event เพราะควบคุม flow และการคืนค่าได้ชัดเจนกว่า

รูปแบบ Exports ที่แนะนำ

ใช้ exports เมื่อต้องการ “เรียกใช้ฟังก์ชันแบบตรง ๆ” ระหว่าง resource ในฝั่งเดียวกัน

• exports เป็น synchronous call

• Server exports เรียกได้จาก Server เท่านั้น

• Client exports เรียกได้จาก Client เท่านั้น

ตัวอย่างประกาศ export (Server):

exports('GetPlayerJobName', function(playerId)
    local xPlayer = ESX.GetPlayerFromId(playerId, { 'job' })
    return xPlayer and xPlayer.job and xPlayer.job.name or nil
end)

ตัวอย่างเรียกใช้งาน export (Server):

local jobName = exports['my_resource']:GetPlayerJobName(source)

อย่า export “xPlayer object ทั้งก้อน” ออกไปให้ resource อื่นแบบไม่จำเป็น ให้คืนค่าเท่าที่ต้องใช้ เช่น identifier, job, group หรือผลลัพธ์ที่ประมวลแล้ว

---

ESX.GetPlayerFromId

คืนค่า xPlayer จาก Server ID ที่ระบุ

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

ESX.GetPlayerFromId(playerId, filter)

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

ชื่อ	ประเภท	คำอธิบาย
playerId	number	Server ID ของผู้เล่น
filter	table	(ไม่บังคับ) Array ของ xPlayer members (methods/fields) ที่จะใช้งาน

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

ประเภท	คำอธิบาย
table หรือ nil	xPlayer หรือ nil ถ้าไม่พบผู้เล่น

การใช้งาน filter (แนะนำให้ใส่เสมอ)

filter ใช้บอกว่า “คุณจะเรียก/แตะอะไรบน xPlayer บ้าง” ในโค้ดส่วนนั้น

ใส่ชื่อ Method/ฟิลด์ที่คุณใช้จริง เช่น getMoney, removeMoney, job, identifier

แนวทางนี้ช่วยลดภาระฝั่ง Server และทำให้โค้ดอ่านง่ายขึ้น

ถ้าคุณเปิด Max Player Optimization (Beta) ด้วย Config.Player.UseMaxOptimization = true การไม่ใส่ filter อาจทำให้ได้ข้อมูลผู้เล่น “ไม่ครบ” ตามที่โค้ดคุณต้องใช้

ถ้า resource ของคุณประกาศ @es_extended/imports.lua ไว้ใน fxmanifest.lua บาง flow ภายใน Framework จะช่วยจัดการเรื่อง filter ให้อัตโนมัติ

แต่ถ้าเรียก ESX.GetPlayerFromId() จาก flow ที่เป็น TriggerEvent/exports ข้าม resource แนะนำให้ใส่ filter ทุกครั้ง เพื่อคุมข้อมูลให้แน่นอน

ตัวอย่าง filter (ตาม member ที่เรียกใช้)

local xPlayer = ESX.GetPlayerFromId(source, {
    'getMoney',
    'removeMoney',
    'addInventoryItem',
    'showNotification',
})

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

1

1) ดึง xPlayer พร้อม filter (แนะนำ)

RegisterNetEvent('shop:buyItem')
AddEventHandler('shop:buyItem', function(itemName, price)
    local xPlayer = ESX.GetPlayerFromId(source, { 'getMoney', 'removeMoney', 'addInventoryItem', 'showNotification' })
    if not xPlayer then return end
    
    if xPlayer.getMoney() >= price then
        xPlayer.removeMoney(price, 'ซื้อของ')
        xPlayer.addInventoryItem(itemName, 1)
        xPlayer.showNotification('~g~ซื้อสำเร็จ')
    else
        xPlayer.showNotification('~r~เงินไม่พอ')
    end
end)

2

2) ดึงเฉพาะ field ที่ต้องใช้ด้วย filter

-- อ่านข้อมูลเท่าที่ต้องใช้
local xPlayer = ESX.GetPlayerFromId(source, { 'name', 'job', 'identifier' })
if not xPlayer then return end

print(('ชื่อ: %s'):format(xPlayer.name))
print(('งาน: %s'):format(xPlayer.job.label))
print(('identifier: %s'):format(xPlayer.identifier))

3

3) ตรวจสอบว่าเป้าหมายออนไลน์ก่อนทำงาน

RegisterCommand('pay', function(source, args)
    local xPlayer = ESX.GetPlayerFromId(source, { 'getMoney', 'removeMoney', 'showNotification' })
    if not xPlayer then return end

    local targetId = tonumber(args[1])
    local amount = tonumber(args[2])
    
    local xTarget = ESX.GetPlayerFromId(targetId, { 'addMoney', 'showNotification' })
    if not xTarget then
        xPlayer.showNotification('~r~ผู้เล่นนี้ไม่ออนไลน์')
        return
    end
    
    if xPlayer.getMoney() >= amount then
        xPlayer.removeMoney(amount, 'โอนเงิน')
        xTarget.addMoney(amount, 'รับเงินโอน')
        xPlayer.showNotification('~g~โอนเงิน $' .. amount .. ' สำเร็จ')
        xTarget.showNotification('~g~ได้รับเงิน $' .. amount)
    end
end)

---

ESX.GetPlayerFromIdentifier

คืนค่า xPlayer จาก identifier ที่ระบุ (เช่น license:)

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

ESX.GetPlayerFromIdentifier(identifier, filter)

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

ชื่อ	ประเภท	คำอธิบาย
identifier	string	Identifier ของผู้เล่น (เช่น license, steam, etc.)
filter	table	(ไม่บังคับ) Array ของ xPlayer members (methods/fields) ที่จะใช้งาน

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

ประเภท	คำอธิบาย
table หรือ nil	xPlayer หรือ nil ถ้าไม่พบ

ฟังก์ชันนี้จะหาได้เฉพาะ “ผู้เล่นที่ออนไลน์อยู่” เท่านั้น ถ้าต้องการข้อมูลผู้เล่นออฟไลน์ ให้ query จากฐานข้อมูลด้วย identifier แทน

การใช้งาน filter

แนวคิดเดียวกับ ESX.GetPlayerFromId()

ใส่ filter ให้ตรง member ที่คุณจะอ่าน/เรียกใช้จริงเสมอ

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

-- ค้นหาผู้เล่นด้วย identifier
local xPlayer = ESX.GetPlayerFromIdentifier('license:abc123def456')

if xPlayer then
    print('พบผู้เล่น: ' .. xPlayer.getName())
    xPlayer.addMoney(1000, 'โบนัส')
else
    print('ไม่พบผู้เล่นที่ออนไลน์')
end

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

{#esx-getplayerfromidentifier-more-examples}

ตัวอย่าง 2: ใช้ filter เพื่ออ่านข้อมูลสำคัญแบบสั้น ๆ

local xPlayer = ESX.GetPlayerFromIdentifier('license:abc123def456', { 'name', 'group' })
if not xPlayer then return end

print(('name=%s, group=%s'):format(xPlayer.name, xPlayer.group))

ตัวอย่าง 3: ใช้กับระบบแอดมิน (แนะนำให้บันทึกลง DB ด้วย)

RegisterCommand('banplayer', function(source, args)
    local xAdmin = ESX.GetPlayerFromId(source)
    if not xAdmin then return end

    if xAdmin.getGroup() ~= 'admin' then return end

    local targetIdentifier = args[1]
    if type(targetIdentifier) ~= 'string' or targetIdentifier == '' then return end

    local xTarget = ESX.GetPlayerFromIdentifier(targetIdentifier)
    if xTarget then
        xTarget.kick('คุณถูกแบนจากเซิร์ฟเวอร์')
    end

    -- แนะนำ: บันทึกลง banlist database ที่นี่
end, true)

---

ESX.GetPlayers

คืนค่ารายการ server ID ของผู้เล่นที่เชื่อมต่ออยู่ทั้งหมด

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

ESX.GetPlayers()

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

ประเภท	คำอธิบาย
table	Array ของ server IDs (ตัวเลข)

Examples

1

นับจำนวนผู้เล่น

local players = ESX.GetPlayers()
print('ผู้เล่นออนไลน์: ' .. #players .. ' คน')

2

ส่งข้อความถึงทุกคน

RegisterCommand('announce', function(source, args)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    if xPlayer.getGroup() == 'admin' then
        local message = table.concat(args, ' ')
        local players = ESX.GetPlayers()
        
        for i=1, #players do
            local xTarget = ESX.GetPlayerFromId(players[i])
            xTarget.showNotification('~b~ประกาศ: ~s~' .. message)
        end
    end
end, true)

3

ให้รางวัลทุกคน

RegisterCommand('giveallmoney', function(source, args)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    if xPlayer.getGroup() == 'admin' then
        local amount = tonumber(args[1]) or 1000
        local players = ESX.GetPlayers()
        
        for i=1, #players do
            local xTarget = ESX.GetPlayerFromId(players[i])
            xTarget.addMoney(amount, 'Admin bonus')
        end
        
        xPlayer.showNotification('~g~ให้เงินทุกคนสำเร็จ')
    end
end, true)

---

ESX.GetExtendedPlayers

คืนค่า player objects โดยสามารถกรองด้วย key/value ได้

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

ESX.GetExtendedPlayers(key, val)

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

ชื่อ	ประเภท	คำอธิบาย
key	string	(ไม่บังคับ) Key สำหรับกรอง (เช่น 'job', 'group')
val	any	(ไม่บังคับ) ค่าที่ต้องการกรอง (เช่น 'police', 'admin')

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

ประเภท	คำอธิบาย
table	Array ของ player objects ที่ตรงตามเงื่อนไข

Examples

1

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

local allPlayers = ESX.GetExtendedPlayers()
print('ผู้เล่นออนไลน์: ' .. #allPlayers .. ' คน')

for i=1, #allPlayers do
    print(allPlayers[i].getName() .. ' - ' .. allPlayers[i].getJob().label)
end

2

นับตำรวจออนไลน์

RegisterCommand('countpolice', function(source, args)
    local cops = ESX.GetExtendedPlayers('job', 'police')
    local count = #cops
    
    TriggerClientEvent('chat:addMessage', source, {
        args = { 'ระบบ', 'ตำรวจออนไลน์: ' .. count .. ' คน' }
    })
end)

3

ส่งข้อความถึง Admin ทั้งหมด

function NotifyAdmins(message)
    local admins = ESX.GetExtendedPlayers('group', 'admin')
    
    for i=1, #admins do
        admins[i].showNotification('~r~[ADMIN] ~s~' .. message)
    end
end

-- ใช้งาน
RegisterNetEvent('report:send')
AddEventHandler('report:send', function(message)
    local xPlayer = ESX.GetPlayerFromId(source)
    NotifyAdmins(xPlayer.getName() .. ' รายงาน: ' .. message)
end)

4

เรียกหมอทั้งหมด

RegisterNetEvent('ambulance:callAll')
AddEventHandler('ambulance:callAll', function(coords, message)
    local xPlayer = ESX.GetPlayerFromId(source)
    local medics = ESX.GetExtendedPlayers('job', 'ambulance')
    
    if #medics > 0 then
        for i=1, #medics do
            medics[i].showNotification('~r~[ฉุกเฉิน] ~s~' .. message)
            medics[i].triggerEvent('ambulance:setBlip', coords)
        end
        xPlayer.showNotification('~g~เรียกหมอสำเร็จ (' .. #medics .. ' คน)')
    else
        xPlayer.showNotification('~r~ไม่มีหมอออนไลน์')
    end
end)

---

ESX.GetJobs

คืนค่าตารางงานทั้งหมดพร้อมยศต่างๆ

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

ESX.GetJobs()

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

ประเภท	คำอธิบาย
table	ตารางงานทั้งหมด indexed ด้วยชื่องาน

Examples

-- แสดงงานทั้งหมด
local jobs = ESX.GetJobs()

for jobName, jobData in pairs(jobs) do
    print('งาน: ' .. jobName .. ' - ' .. jobData.label)
    
    -- แสดงยศทั้งหมด
    for grade, gradeData in pairs(jobData.grades) do
        print('  ยศ ' .. grade .. ': ' .. gradeData.label .. ' (เงินเดือน: $' .. gradeData.salary .. ')')
    end
end

-- สร้างเมนูเลือกงาน
RegisterNetEvent('jobcenter:showMenu')
AddEventHandler('jobcenter:showMenu', function()
    local jobs = ESX.GetJobs()
    local elements = {}
    
    for jobName, jobData in pairs(jobs) do
        -- ไม่แสดงงานพิเศษ
        if jobName ~= 'unemployed' and jobName ~= 'police' and jobName ~= 'ambulance' then
            table.insert(elements, {
                label = jobData.label,
                value = jobName
            })
        end
    end
    
    TriggerClientEvent('jobcenter:openMenu', source, elements)
end)

---

ESX.DoesJobExist

ตรวจสอบว่างานและยศที่ระบุมีอยู่จริงหรือไม่

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

ESX.DoesJobExist(job, grade)

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

ชื่อ	ประเภท	คำอธิบาย
job	string	ชื่องาน
grade	string|number	เลขยศ

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

ประเภท	คำอธิบาย
boolean	true ถ้างานและยศมีอยู่จริง

Examples

-- ตรวจสอบก่อนเปลี่ยนงาน
RegisterCommand('setjob', function(source, args)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    if xPlayer.getGroup() == 'admin' then
        local targetId = tonumber(args[1])
        local jobName = args[2]
        local jobGrade = tonumber(args[3]) or 0
        
        if ESX.DoesJobExist(jobName, jobGrade) then
            local xTarget = ESX.GetPlayerFromId(targetId)
            if xTarget then
                xTarget.setJob(jobName, jobGrade)
                xPlayer.showNotification('~g~เปลี่ยนงานสำเร็จ')
            end
        else
            xPlayer.showNotification('~r~งานหรือยศนี้ไม่มีอยู่')
        end
    end
end, true)

---

ESX.GetIdentifier

คืนค่า identifier ของผู้เล่นตามที่ตั้งค่าไว้ (license, steam, etc.)

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

ESX.GetIdentifier(playerId)

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

ชื่อ	ประเภท	คำอธิบาย
playerId	number	Server ID ของผู้เล่น

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

ประเภท	คำอธิบาย
string	Identifier string ของผู้เล่น

Examples

-- บันทึกข้อมูลลง database
RegisterNetEvent('player:saveCustomData')
AddEventHandler('player:saveCustomData', function(data)
    local identifier = ESX.GetIdentifier(source)
    
    MySQL.Async.execute('INSERT INTO player_data (identifier, data) VALUES (@id, @data) ON DUPLICATE KEY UPDATE data = @data', {
        ['@id'] = identifier,
        ['@data'] = json.encode(data)
    })
end)

-- ตรวจสอบ Ban
AddEventHandler('playerConnecting', function(playerName, setKickReason)
    local identifier = ESX.GetIdentifier(source)
    
    MySQL.Async.fetchScalar('SELECT COUNT(1) FROM banlist WHERE identifier = @id', {
        ['@id'] = identifier
    }, function(count)
        if count > 0 then
            setKickReason('คุณถูก Ban จากเซิร์ฟเวอร์')
            CancelEvent()
        end
    end)
end)

---

ESX.RegisterCommand

ลงทะเบียนคำสั่งแชทพร้อมกลุ่มสิทธิ์, การตรวจสอบ arguments, และ auto-completion

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

ESX.RegisterCommand(name, group, cb, allowConsole, suggestion)

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

ชื่อ	ประเภท	คำอธิบาย
name	string|table	ชื่อคำสั่ง หรือ array ของชื่อ (aliases)
group	string|table	กลุ่มสิทธิ์ (เช่น 'admin', {'admin', 'mod'})
cb	function	Callback function(player, args, showError)
allowConsole	boolean	อนุญาตให้รันจาก console หรือไม่
suggestion	table	(ไม่บังคับ) ตารางสำหรับ auto-completion

โครงสร้างตาราง Suggestion

ฟิลด์	ประเภท	คำอธิบาย
help	string	ข้อความช่วยเหลือที่แสดงในแชท
validate	boolean	ตรวจสอบจำนวน arguments หรือไม่
arguments	table	Array ของ argument definitions

โครงสร้าง Argument Definition

ฟิลด์	ประเภท	คำอธิบาย
name	string	ชื่อ argument
type	string	ประเภท: 'number', 'string', 'player', 'playerId', 'item', 'weapon', 'any'
help	string	ข้อความช่วยเหลือ
validate	boolean	ตั้งเป็น false เพื่อข้ามการตรวจสอบ argument นี้

Examples

1

คำสั่งเปลี่ยนงาน

ESX.RegisterCommand('setjob', 'admin', function(xPlayer, args, showError)
    if not args.target then 
        return showError('ไม่พบผู้เล่น')
    end
    
    args.target.setJob(args.job, args.grade)
    xPlayer.showNotification('~g~เปลี่ยนงานสำเร็จ')
    args.target.showNotification('~g~คุณได้รับงาน ' .. args.job)
end, true, {
    help = 'เปลี่ยนงานของผู้เล่น',
    validate = true,
    arguments = {
        { name = 'target', help = 'ID ผู้เล่น', type = 'player' },
        { name = 'job',    help = 'ชื่องาน',  type = 'string'  },
        { name = 'grade',  help = 'ยศ',     type = 'number'  }
    }
})

2

คำสั่งให้เงิน

ESX.RegisterCommand({'givemoney', 'gm'}, 'admin', function(xPlayer, args, showError)
    if not args.target then 
        return showError('ระบุ ID ผู้เล่น')
    end
    
    local amount = args.amount or 1000
    args.target.addMoney(amount, 'Admin give')
    
    xPlayer.showNotification('~g~ให้เงิน $' .. amount .. ' แล้ว')
    args.target.showNotification('~g~ได้รับเงิน $' .. amount)
end, false, {
    help = 'ให้เงินผู้เล่น',
    validate = true,
    arguments = {
        { name = 'target', help = 'ID ผู้เล่น', type = 'player' },
        { name = 'amount', help = 'จำนวนเงิน', type = 'number' }
    }
})

3

คำสั่งให้ Item

ESX.RegisterCommand('giveitem', {'admin', 'mod'}, function(xPlayer, args, showError)
    if not args.target then 
        return showError('ไม่พบผู้เล่น')
    end
    
    if not args.itemName then
        return showError('ระบุชื่อ Item')
    end
    
    local count = args.count or 1
    
    if args.target.canCarryItem(args.itemName, count) then
        args.target.addInventoryItem(args.itemName, count)
        xPlayer.showNotification('~g~ให้ Item สำเร็จ')
        args.target.showNotification('~g~ได้รับ ' .. args.itemName .. ' x' .. count)
    else
        showError('กระเป๋าของผู้เล่นเต็ม')
    end
end, true, {
    help = 'ให้ Item ผู้เล่น',
    validate = true,
    arguments = {
        { name = 'target',   help = 'ID ผู้เล่น',   type = 'player' },
        { name = 'itemName', help = 'ชื่อ Item', type = 'item' },
        { name = 'count',    help = 'จำนวน',    type = 'number', validate = false }
    }
})

4

คำสั่ง Teleport

ESX.RegisterCommand({'tp', 'teleport'}, 'admin', function(xPlayer, args, showError)
    if not args.target then 
        return showError('ไม่พบผู้เล่น')
    end
    
    local coords = xPlayer.getCoords()
    args.target.setCoords(coords)
    
    xPlayer.showNotification('~g~Teleport ผู้เล่นมาหาคุณ')
    args.target.showNotification('~g~ถูก Teleport โดย Admin')
end, false, {
    help = 'Teleport ผู้เล่นมาหาตัวเอง',
    validate = true,
    arguments = {
        { name = 'target', help = 'ID ผู้เล่น', type = 'player' }
    }
})

คำแนะนำ: ใช้ type = 'player' เพื่อแปลง ID เป็น xPlayer object อัตโนมัติ ทำให้ไม่ต้อง GetPlayerFromId เอง

---

ESX.RegisterUsableItem

ลงทะเบียน Item ให้สามารถใช้งานได้พร้อม callback function

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

ESX.RegisterUsableItem(itemName, cb)

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

ชื่อ	ประเภท	คำอธิบาย
itemName	string	ชื่อ Item ที่ต้องการลงทะเบียน
cb	function	Callback function(playerId, itemName, ...)

Examples

1

Item กินได้

ESX.RegisterUsableItem('bread', function(source, itemName)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    if xPlayer.getInventoryItem(itemName).count > 0 then
        xPlayer.removeInventoryItem(itemName, 1)
        
        -- เพิ่มความหิว
        TriggerClientEvent('esx_status:add', source, 'hunger', 200000)
        TriggerClientEvent('esx:useItem', source, itemName)
        
        xPlayer.showNotification('~g~คุณกินขนมปัง')
    end
end)

2

Item ดื่มได้

ESX.RegisterUsableItem('water', function(source, itemName)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    if xPlayer.getInventoryItem(itemName).count > 0 then
        xPlayer.removeInventoryItem(itemName, 1)
        
        -- เพิ่มความกระหาย
        TriggerClientEvent('esx_status:add', source, 'thirst', 250000)
        TriggerClientEvent('esx:useItem', source, itemName)
        
        xPlayer.showNotification('~g~คุณดื่มน้ำ')
    end
end)

3

Item พิเศษ

ESX.RegisterUsableItem('lockpick', function(source, itemName)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    -- ลบ Item
    xPlayer.removeInventoryItem(itemName, 1)
    
    -- เริ่มการงัดล็อค
    TriggerClientEvent('lockpick:start', source)
    
    xPlayer.showNotification('~y~กำลังงัดล็อค...')
end)

ESX.RegisterUsableItem('bandage', function(source, itemName)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    xPlayer.removeInventoryItem(itemName, 1)
    
    -- ฟื้นเลือด
    TriggerClientEvent('ambulance:heal', source, 50)
    
    xPlayer.showNotification('~g~ใช้ผ้าพันแผล')
end)

4

Item ที่มี Cooldown

local itemCooldowns = {}

ESX.RegisterUsableItem('energy_drink', function(source, itemName)
    local xPlayer = ESX.GetPlayerFromId(source)
    local identifier = xPlayer.getIdentifier()
    
    -- ตรวจสอบ cooldown
    if itemCooldowns[identifier] and itemCooldowns[identifier] > GetGameTimer() then
        local remaining = math.ceil((itemCooldowns[identifier] - GetGameTimer()) / 1000)
        xPlayer.showNotification('~r~รอ ' .. remaining .. ' วินาที')
        return
    end
    
    xPlayer.removeInventoryItem(itemName, 1)
    
    -- เพิ่มพลัง
    TriggerClientEvent('esx_status:add', source, 'thirst', 200000)
    TriggerClientEvent('player:addSpeed', source, 1.2, 30000) -- เร็วขึ้น 30 วินาที
    
    -- ตั้ง cooldown 60 วินาที
    itemCooldowns[identifier] = GetGameTimer() + 60000
    
    xPlayer.showNotification('~g~รู้สึกมีพลัง!')
end)

---

ESX.UseItem

Trigger การใช้งานของ usable item ที่ลงทะเบียนไว้

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

ESX.UseItem(playerId, itemName, ...)

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

ชื่อ	ประเภท	คำอธิบาย
playerId	number	Server ID ของผู้เล่น
itemName	string	ชื่อ Item ที่จะใช้
...	any	ตัวแปรเพิ่มเติมที่ส่งไปยัง callback

{% hint style="warning" %} คำเตือน: ฟังก์ชั่นนี้จะตรวจสอบว่าผู้เล่นเกินลิมิตการใช้ Item หรือไม่ก่อน trigger callback Item ต้องลงทะเบียนด้วย RegisterUsableItem ก่อน {% endhint %}

---

ESX.GetUsableItems

คืนค่าตารางชื่อ usable items ทั้งหมดที่ลงทะเบียนไว้

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

ESX.GetUsableItems()

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

ประเภท	คำอธิบาย
table	ตารางที่มีชื่อ Item เป็น keys และค่าเป็น true

Examples

-- ตรวจสอบว่า Item สามารถใช้งานได้หรือไม่
local usables = ESX.GetUsableItems()

if usables['bread'] then
    print('Bread เป็น Item ที่ใช้งานได้')
end

-- แสดงรายการ Item ที่ใช้ได้ทั้งหมด
print('Item ที่ใช้งานได้:')
for itemName, _ in pairs(usables) do
    print('- ' .. itemName)
end

---

ESX.CreatePickup

สร้าง Item ที่ตกใน world ตรงตำแหน่งผู้เล่น

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

ESX.CreatePickup(itemType, itemName, itemCount, itemLabel, playerId, components, tintIndex)

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

ชื่อ	ประเภท	คำอธิบาย
itemType	string	ประเภท Item ('item_standard', 'item_weapon', etc.)
itemName	string	ชื่อ Item/อาวุธ
itemCount	number	จำนวน
itemLabel	string	ชื่อแสดง
playerId	number	Server ID (กำหนดตำแหน่งที่ drop)
components	table	(ไม่บังคับ) อุปกรณ์เสริมอาวุธ (สำหรับ 'item_weapon')
tintIndex	number	(ไม่บังคับ) สีอาวุธ (สำหรับ 'item_weapon')

Examples

{% stepper %} {% step %}

ทิ้ง Item ปกติ

RegisterNetEvent('player:dropItem')
AddEventHandler('player:dropItem', function(itemName, count)
    local xPlayer = ESX.GetPlayerFromId(source)
    local item = xPlayer.getInventoryItem(itemName)
    
    if item.count >= count then
        xPlayer.removeInventoryItem(itemName, count)
        ESX.CreatePickup('item_standard', itemName, count, item.label, source)
        
        xPlayer.showNotification('~y~ทิ้ง ' .. item.label .. ' x' .. count)
    end
end)

{% endstep %}

{% step %}

ทิ้งอาวุธ

RegisterNetEvent('player:dropWeapon')
AddEventHandler('player:dropWeapon', function(weaponName)
    local xPlayer = ESX.GetPlayerFromId(source)
    local index, weapon = xPlayer.getWeapon(weaponName)
    
    if weapon then
        xPlayer.removeWeapon(weaponName, 'ทิ้ง')
        
        ESX.CreatePickup('item_weapon', weaponName, weapon.ammo, weapon.label, source, weapon.components, weapon.tintIndex)
        
        xPlayer.showNotification('~y~ทิ้ง ' .. weapon.label)
    end
end)

{% endstep %}

{% step %}

Loot จากศพ

RegisterNetEvent('player:lootBody')
AddEventHandler('player:lootBody', function(targetServerId)
    local xPlayer = ESX.GetPlayerFromId(source)
    local xTarget = ESX.GetPlayerFromId(targetServerId)
    
    if xTarget and xTarget.isDead then
        -- ทิ้ง Item ทั้งหมดของเป้า
        local inventory = xTarget.getInventory()
        for i=1, #inventory do
            if inventory[i].count > 0 then
                ESX.CreatePickup('item_standard', inventory[i].name, inventory[i].count, inventory[i].label, targetServerId)
                xTarget.removeInventoryItem(inventory[i].name, inventory[i].count)
            end
        end
        
        -- ทิ้งอาวุธทั้งหมด
        local loadout = xTarget.getLoadout()
        for i=1, #loadout do
            ESX.CreatePickup('item_weapon', loadout[i].name, loadout[i].ammo, loadout[i].label, targetServerId, loadout[i].components, loadout[i].tintIndex)
        end
        xTarget.clearLoadout('ถูก loot')
        
        xPlayer.showNotification('~g~Loot สำเร็จ')
    end
end)

{% endstep %} {% endstepper %}

---

ESX.SavePlayer

บันทึกข้อมูลผู้เล่นคนเดียวลง database

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

ESX.SavePlayer(player, cb)

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

ชื่อ	ประเภท	คำอธิบาย
player	table	Player object
cb	function	(ไม่บังคับ) Callback เมื่อบันทึกเสร็จ

Examples

-- บันทึกผู้เล่นก่อน kick
RegisterCommand('kicksave', function(source, args)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    if xPlayer.getGroup() == 'admin' then
        local targetId = tonumber(args[1])
        local xTarget = ESX.GetPlayerFromId(targetId)
        
        if xTarget then
            ESX.SavePlayer(xTarget, function()
                xTarget.kick('Kicked by admin')
                xPlayer.showNotification('~g~Kick และบันทึกข้อมูลแล้ว')
            end)
        end
    end
end, true)

-- บันทึกอัตโนมัติทุก 10 นาที
CreateThread(function()
    while true do
        Wait(600000) -- 10 minutes
        
        local xPlayers = ESX.GetExtendedPlayers()
        for i=1, #xPlayers do
            ESX.SavePlayer(xPlayers[i])
        end
        
        print('[Auto-Save] บันทึกผู้เล่น ' .. #xPlayers .. ' คน')
    end
end)

---

ESX.SavePlayers

บันทึกข้อมูลผู้เล่นทั้งหมดที่เชื่อมต่ออยู่ลง database

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

ESX.SavePlayers(cb)

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

ชื่อ	ประเภท	คำอธิบาย
cb	function	(ไม่บังคับ) Callback เมื่อบันทึกเสร็จ

Examples

-- บันทึกทุกคนก่อนรีสตาร์ทเซิร์ฟเวอร์
RegisterCommand('saveall', function(source, args)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    if xPlayer.getGroup() == 'admin' then
        ESX.SavePlayers(function()
            xPlayer.showNotification('~g~บันทึกผู้เล่นทั้งหมดเรียบร้อย')
            print('[Admin] บันทึกผู้เล่นทั้งหมดแล้ว')
        end)
    end
end, true)

-- บันทึกก่อน shutdown
AddEventHandler('txAdmin:events:serverShuttingDown', function()
    print('[Shutdown] กำลังบันทึกผู้เล่นทั้งหมด...')
    ESX.SavePlayers(function()
        print('[Shutdown] บันทึกเสร็จสมบูรณ์')
    end)
end)

---

ESX.SetItemIgnoreSaving

กำหนดให้ Item ถูกข้าม (หรือไม่) เมื่อบันทึก inventory ของผู้เล่น

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

ESX.SetItemIgnoreSaving(name, state)

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

ชื่อ	ประเภท	คำอธิบาย
name	string	ชื่อ Item
state	boolean	true เพื่อข้ามการบันทึก, false เพื่อบันทึก

Examples

-- ป้องกัน Item ชั่วคราวจากการบันทึก
ESX.SetItemIgnoreSaving('temp_badge', true)
ESX.SetItemIgnoreSaving('event_ticket', true)
ESX.SetItemIgnoreSaving('tutorial_item', true)

-- ตัวอย่าง: Item อีเว้นท์
RegisterNetEvent('event:start')
AddEventHandler('event:start', function()
    local xPlayers = ESX.GetExtendedPlayers()
    
    -- ให้ Item พิเศษทุกคน (ไม่บันทึก)
    for i=1, #xPlayers do
        xPlayers[i].addInventoryItem('event_weapon', 1)
    end
end)

RegisterNetEvent('event:end')
AddEventHandler('event:end', function()
    local xPlayers = ESX.GetExtendedPlayers()
    
    -- เอา Item พิเศษคืน
    for i=1, #xPlayers do
        xPlayers[i].removeInventoryItem('event_weapon', 999)
    end
end)

{% hint style="info" %} หมายเหตุ: มีประโยชน์สำหรับ Item ชั่วคราวที่ใช้ในอีเว้นท์หรือภารกิจ {% endhint %}

---

ESX.Trace

พิมพ์ข้อความ debug ไปยัง console ของเซิร์ฟเวอร์ แสดงผลเฉพาะเมื่อเปิด Debug mode ใน config

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

ESX.Trace(msg)

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

ชื่อ	ประเภท	คำอธิบาย
msg	string	ข้อความที่ต้องการพิมพ์

Examples

-- Debug การโหลดผู้เล่น
RegisterNetEvent('esx:playerLoaded')
AddEventHandler('esx:playerLoaded', function(playerId)
    local xPlayer = ESX.GetPlayerFromId(playerId)
    ESX.Trace('Player loaded: ' .. xPlayer.getName() .. ' (' .. xPlayer.getIdentifier() .. ')')
end)

-- Debug ระบบร้านค้า
RegisterNetEvent('shop:purchase')
AddEventHandler('shop:purchase', function(itemName, price)
    local xPlayer = ESX.GetPlayerFromId(source)
    ESX.Trace('[Shop] ' .. xPlayer.getName() .. ' ซื้อ ' .. itemName .. ' ราคา $' .. price)
    
    -- ทำธุรกรรม...
end)

{% hint style="success" %} คำแนะนำ: ใช้ ESX.Trace แทน print เพื่อ debug เพราะจะแสดงผลเฉพาะเมื่อเปิด Debug mode ช่วยลด spam ใน console

คำเตือน: อย่าลืมปิด Debug mode ใน production server เพื่อลด spam และเพิ่ม performance