Server

ฟังก์ชันฝั่ง Server สำหรับ callback และการค้นหา player ผ่าน `ESX.*`

Server (Server-side)

หน้านี้รวมฟังก์ชัน ESX.* สำหรับใช้งานฝั่ง Server

ครอบคลุมการทำ server callback, การเรียก client callback, และการดึงข้อมูลผู้เล่น

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

• เรียกใช้งานฝั่ง Server เท่านั้น (เช่น server.lua)

• ตรวจสอบว่า ESX ถูกโหลดแล้วก่อนเรียกใช้

• ระวังการเรียกกับ playerId ที่ไม่อยู่ในเซิร์ฟเวอร์

API ในหน้านี้ออกแบบมาสำหรับงานฝั่ง Server โดยตรง

---

ESX.RegisterServerCallback

ลงทะเบียน server callback เพื่อให้ฝั่ง Client เรียกใช้งานได้

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

ESX.RegisterServerCallback(name, cb)

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

Name	Type	Description
name	string	ชื่อ callback ที่ต้องการลงทะเบียน
cb	function	ฟังก์ชัน function(playerId, respond, ...) โดย respond(...) ใช้ส่งผลลัพธ์กลับไป Client

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

ESX.RegisterServerCallback('myResource:getPlayerMoney', function(playerId, respond)
    local player = ESX.GetPlayerFromId(playerId)
    respond(player.getMoney())
end)

callback จะถูกล้างอัตโนมัติ เมื่อ resource ที่ลงทะเบียนถูกหยุดทำงาน

---

ESX.TriggerClientCallback

เรียก client callback ที่ลงทะเบียนไว้ จากฝั่ง Server

รองรับทั้งแบบ callback และแบบคืนค่า (promise style)

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

-- Callback style
ESX.TriggerClientCallback(playerId, name, cb, ...)

-- Promise style (no callback)
local result = ESX.TriggerClientCallback(playerId, name, nil, ...)

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

Name	Type	Description
playerId	number	Server ID ของผู้เล่นเป้าหมาย
name	string	ชื่อ client callback ที่ลงทะเบียนไว้
cb	function	function(...) หรือ nil เมื่อใช้ promise style
...	any	อาร์กิวเมนต์เพิ่มเติมที่ส่งไปให้ client callback

ตัวอย่าง — Callback style

ESX.TriggerClientCallback(source, 'myResource:getClientData', function(data)
    print('Client data: ', data)
end, someArg)

ตัวอย่าง — Promise style

CreateThread(function()
    local data = ESX.TriggerClientCallback(source, 'myResource:getClientData', nil, someArg)
    print('Client data: ', data)
end)

หาก playerId ไม่พบ ระบบจะ throw error

หากใช้ promise style ต้องเรียกภายใน CreateThread เท่านั้น

---

ESX.GetPlayerFromId

ดึง player object จาก server ID

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

ESX.GetPlayerFromId(playerId, filter)

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

Name	Type	Description
playerId	number	Server ID ของผู้เล่น
filter	table	(ไม่บังคับ) array ของ xPlayer members (methods/fields) ที่จะใช้งาน

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

Type	Description
table	xPlayer หรือ nil

การใช้งาน filter (สำคัญ)

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

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

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

ตัวอย่างการเปิด Max Player Optimization (ขยายดู)

-- config/config.player.lua
Config.Player.UseMaxOptimization = true
-- เปิดใช้งานการ Optimize ขั้นสูงสุดเกี่ยวกับข้อมูลผู้เล่น (Beta)
-- จำเป็นต้องเรียกใช้ไฟล์ imports.lua เสมอ
-- ต้องการ NC Addons v1.0.1+ (https://github.com/NC-Developer-FiveM/nc-addons/releases)

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

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

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

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

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

local player = ESX.GetPlayerFromId(source)
if player then
    print(player.getName())
end

ตัวอย่าง — ใช้ filter เพื่อจำกัดข้อมูล

RegisterNetEvent('shop:buy', function(item, price)
    local xPlayer = ESX.GetPlayerFromId(source, {'getMoney', 'removeMoney', 'addInventoryItem'})
    if not xPlayer then return end

    if xPlayer.getMoney() >= price then
        xPlayer.removeMoney(price)
        xPlayer.addInventoryItem(item, 1)
    end
end)

---

ESX.GetPlayerFromIdentifier

ดึง player object จาก identifier (เช่น license)

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

ESX.GetPlayerFromIdentifier(identifier, filter)

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

Name	Type	Description
identifier	string	identifier ของผู้เล่น
filter	table	(ไม่บังคับ) array ของ xPlayer members (methods/fields) ที่จะใช้งาน

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

Type	Description
table	xPlayer หรือ nil

การใช้งาน filter (กรณีค้นหาจาก identifier)

แนวคิดเหมือน ESX.GetPlayerFromId() ทุกประการ

• ใส่ filter ให้ตรงกับ member ที่คุณเรียกใช้

• สำคัญมากเมื่อเปิด Config.Player.UseMaxOptimization = true

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

local player = ESX.GetPlayerFromIdentifier('license:abc123def456')
if player then
    print(player.getName())
end

ตัวอย่าง — ค้นหาแล้วใช้งานเฉพาะ job

local xPlayer = ESX.GetPlayerFromIdentifier('license:abc123def456', {'job'})
if xPlayer then
    print(xPlayer.job.name)
end

---

ESX.GetIdentifier

คืนค่า identifier ของผู้เล่นตาม IdentifierType ใน config

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

ESX.GetIdentifier(playerId)

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

Name	Type	Description
playerId	number	Server ID ของผู้เล่น

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

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

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

local identifier = ESX.GetIdentifier(source)
print('Player identifier: ' .. identifier)

ในโหมดพัฒนา FxDK ฟังก์ชันนี้จะคืนค่า 'NCCORE-DEBUG-LICENCE' ให้ผู้เล่นทุกคน