Framework usage

วิธีนำ NC Core ไปใช้ใน resource ของคุณ พร้อมข้อควรระวังเรื่องลำดับ ensure และ performance

วิธีการใช้งาน Framework

หน้านี้อธิบายวิธีนำ NC Core ไปใช้งานในทรัพยากร (resource) ของคุณ

เนื้อหาเน้นการเรียกใช้ ESX ให้ถูกลำดับ และลดความเสี่ยงเรื่องการโหลดไม่ทัน

ข้อกำหนดด้านลำดับการโหลด

ต้อง ensure es_extended ก่อน resource ใด ๆ ที่เรียกใช้งาน Framework เสมอ

หากลำดับ ensure ไม่ถูกต้อง มักพบ error เช่น ESX is nil หรือ attempt to index a nil value (global 'ESX')

ตัวอย่างลำดับที่แนะนำใน server.cfg:

ensure es_extended

# resource อื่น ๆ ที่เรียกใช้งาน Framework ต้องอยู่หลังจากนี้
ensure my_resource
ensure my_resource_2

เลือกวิธีนำ Framework ไปใช้

1. ใช้ @es_extended/imports.lua (แนะนำสำหรับ resource ใหม่)

2. ใช้ TriggerEvent('esx:getSharedObject', ...) (รองรับ resource เก่า)

3. ใช้ exports['es_extended']:getSharedObject() (รองรับ resource เก่า)

หากเป้าหมายคือความเสถียรและประสิทธิภาพ ให้เริ่มจาก @es_extended/imports.lua

วิธีที่ 1: ใช้ @es_extended/imports.lua (แนะนำ)

ข้อดีของการใช้ imports.lua

1. แต่ละ Resource มี Instance ของตัวเอง

เมื่อใช้ @es_extended/imports.lua แต่ละ resource จะได้ ESX instance แยกกัน

ไม่เหมือนการใช้ TriggerEvent หรือ exports ที่ทุก resource ชี้ไปที่ instance เดียวกัน

2. ลดปัญหา "คอขวด" ที่ es_extended

การใช้ ESX.RegisterServerCallback และ ESX.TriggerClientCallback จากแต่ละ resource:

• วิธีเดิม (TriggerEvent/exports): Callback ทุกตัวรวมศูนย์ที่ es_extended → เกิดคิวรอและ bottleneck

• วิธีใหม่ (imports.lua): Callback แยกทำงานใน resource ของตัวเอง → ไม่มีการรอคิว ทำงานได้ทันที

3. ไม่ต้องเขียนโค้ดรอโหลด

ไม่ต้องมี while ESX == nil do Wait(0) end หรือ callback function

Framework พร้อมใช้ทันทีที่ resource เริ่มทำงาน

4. เหมาะกับ Server ที่มีผู้เล่นเยอะ

ยิ่ง resource มีการใช้ Callback บ่อย ยิ่งเห็นความแตกต่างชัดเจน

ระบบจะไม่ค้างหรือช้าเมื่อหลาย resource เรียก Callback พร้อมกัน

กรณีการใช้งาน

• สร้าง resource ใหม่

• ปรับปรุง (refactor) resource เดิม

• ต้องการลดปัญหาเรื่องการโหลดไม่ทัน และลดโค้ดซ้ำซ้อน

ตั้งค่าใน fxmanifest.lua

เลือก 1 รูปแบบให้เหมาะกับ resource ของคุณ:

-- fxmanifest.lua
shared_script '@es_extended/imports.lua'

หรือแยกตามฝั่งที่ใช้งาน:

-- fxmanifest.lua
server_script '@es_extended/imports.lua'
-- หรือ
client_script '@es_extended/imports.lua'

แนะนำให้ระบุ imports.lua เฉพาะฝั่งที่มีการใช้งานจริง หาก resource ใช้งาน ESX ทั้ง Client และ Server ค่อยใช้ shared_script

การใช้งานตัวแปร NCCore/ESX หลังจาก import

เมื่อ import @es_extended/imports.lua แล้ว สามารถใช้งานตัวแปร NCCore หรือ ESX ได้ทันที

ชื่อตัวแปรสามารถปรับเปลี่ยนได้ผ่าน Config ของ NC Core

ใช้งาน ESX.on สำหรับรอการโหลดผู้เล่น (Client)

NC Core มี ESX.on function ที่ช่วยลดโค้ดซ้ำซ้อนในการรอผู้เล่นโหลด

-- วิธีเดิม (ESX)
CreateThread(function()
    while not ESX.PlayerLoaded do
        Wait(300)
    end
    -- DO SOMETHING
end)

-- วิธีใหม่ (NC Core)
ESX.on('PlayerLoaded', function()
    -- DO SOMETHING
end)

การใช้ ESX.on('PlayerLoaded') ช่วยให้โค้ดอ่านง่ายและลดการใช้ loop ที่ไม่จำเป็น

ตัวอย่าง (ขยายดู)

-- fxmanifest.lua
fx_version 'cerulean'
game 'gta5'

shared_script '@es_extended/imports.lua'
shared_script 'config.lua'
client_script 'client/main.lua'
server_script 'server/main.lua'

วิธีที่ 2: ใช้ TriggerEvent('esx:getSharedObject', ...)

กรณีการใช้งาน (วิธีที่ 2)

• ต้องการคงโครงสร้าง resource เดิมเพื่อความเข้ากันได้

• มีโค้ดเดิมที่อิงรูปแบบการดึง ESX ด้วย trigger

ตั้งค่าด้วย TriggerEvent

ฝั่ง Server:

ESX = nil
TriggerEvent('esx:getSharedObject', function(obj) ESX = obj end)

ฝั่ง Client:

ESX = nil
CreateThread(function()
    while ESX == nil do
        TriggerEvent('esx:getSharedObject', function(obj) ESX = obj end)
        Wait(0)
    end
end)

เมื่อใช้วิธีที่ 2 ให้กำหนด filter ทุกครั้งที่เรียก ESX.GetPlayerFromId() เพื่อจำกัดข้อมูลให้ตรงกับการใช้งาน และลดภาระของระบบ

ตัวอย่างการกำหนด filter (ขยายดู)

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

วิธีที่ 3: ใช้ exports['es_extended']:getSharedObject()

กรณีการใช้งาน (วิธีที่ 3)

• ต้องการคงโครงสร้าง resource เดิม

• ใช้ exports เป็นมาตรฐานภายในโปรเจกต์อยู่แล้ว

ตั้งค่าด้วย Exports

ESX = exports['es_extended']:getSharedObject()

วิธีนี้ต้องมั่นใจว่า es_extended โหลดก่อน resource ของคุณ (ลำดับ ensure ถูกต้อง)

เมื่อใช้วิธีที่ 3 ให้กำหนด filter ทุกครั้งที่เรียก ESX.GetPlayerFromId()

การกำหนด Filter สำหรับ ESX.GetPlayerFromId() (สำหรับวิธีที่ 2 และ 3)

การกำหนด filter คือการระบุ “คุณจะเรียก/แตะอะไรบน xPlayer บ้าง” ในแต่ละจุดที่เรียก ESX.GetPlayerFromId()

แนวทางนี้ช่วยลดภาระด้านหน่วยความจำ และทำให้พฤติกรรมของโค้ดชัดเจน

รายการ filter ที่ใช้บ่อย

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

แนวทางที่แนะนำคือ “ใส่เท่าที่เรียกจริง” ตัวอย่าง: ระบบร้านค้าใส่แค่ getMoney/removeMoney/addInventoryItem

เปิด debug เพื่อช่วยตรวจการใช้งาน

-- config.general.lua
Config.EnableDebug = true

ภาคผนวก: ตัวอย่างเพิ่มเติม (ขยายดู)

ตัวอย่าง: 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)

ตัวอย่าง: filter สำหรับตรวจสอบอาชีพ

RegisterNetEvent('police:checkPermission', function()
    local xPlayer = ESX.GetPlayerFromId(source, {'job'})
    if not xPlayer then return end

    if xPlayer.job.name == 'police' then
        -- อนุญาตให้ทำงานต่อ
    end
end)

---

Event Callbacks ของ NC Core

NC Core มี Event Callbacks ที่ช่วยให้ resource ของคุณรับรู้เมื่อมีการเปลี่ยนแปลงสำคัญ

OnPlayerData

เรียกเมื่อมีการเปลี่ยนแปลงค่าใน ESX.PlayerData (ฝั่ง Client)

function OnPlayerData(key, val, last)
    print('PlayerData changed:', key, val, last)
end

OnUpdateOnlineCount

เรียกเมื่อจำนวนผู้เล่น Online เปลี่ยนแปลง (ทั้งฝั่ง Server และ Client)

function OnUpdateOnlineCount(count)
    print('Online players:', count)
end

OnUpdateJobCount

เรียกเมื่อจำนวนผู้เล่นในอาชีพเปลี่ยนแปลง (ทั้งฝั่ง Server และ Client)

function OnUpdateJobCount(name, count)
    print('Job count:', name, count)
end

OnUpdateGroupCount

เรียกเมื่อจำนวนผู้เล่นใน Permission Group เปลี่ยนแปลง (ทั้งฝั่ง Server และ Client)

function OnUpdateGroupCount(name, count)
    print('Group count:', name, count)
end

Event Callbacks เหล่านี้เหมาะสำหรับอัปเดต UI/HUD แบบ Real-time สำหรับการดึงข้อมูลแบบครั้งเดียว ใช้ ESX.CountOnline(), ESX.CountJob(), ESX.CountGroup() แทน

อ่านเพิ่มเติม: Common (Count Functions)

หากใช้ Event Callbacks เพื่อตรวจสอบสิทธิ์หรือเงื่อนไขสำคัญ ควรยืนยันผลฝั่ง Server เสมอเพื่อความปลอดภัย

Support

ติดต่อทีมงานผ่าน Ticket บน Discord ทางการ

• Discord: https://discord.gg/ncdeveloper

เพื่อความเร็ว โปรดแนบรูปภาพ ตอนบูตเซิร์ฟเวอร์ + error ที่พบ (Server console/F8)