Custom functions

เพิ่มฟังก์ชันกลางให้ NC Core โดยไม่แก้ไฟล์หลัก และไม่กระทบการอัปเดต

Custom Functions

วิธีการสร้าง Custom Functions

หน้านี้อธิบายวิธีเพิ่ม “ฟังก์ชันส่วนกลาง” ให้ NC Core โดยไม่แก้ไฟล์หลัก

ฟังก์ชันที่เพิ่มจะถูกโหลดพร้อม es_extended และเรียกใช้ผ่าน ESX ได้ทันที

เหมาะสำหรับกรณีใด

• ฟังก์ชันที่ต้องเรียกใช้ซ้ำในหลายทรัพยากร (resource)

• ฟังก์ชันช่วย เช่น notification, logging, validation

• ตรรกะธุรกิจที่ต้องการมาตรฐานเดียวกันทั้งเซิร์ฟเวอร์

ประโยชน์หลัก

• ลดโอกาสโค้ดชนกับการอัปเดตของ NC Core

• ใช้งานซ้ำได้จากหลายทรัพยากร ผ่านจุดอ้างอิงเดียว (ESX)

• รวมตรรกะไว้ที่เดียว ลดโค้ดซ้ำ และดูแลง่าย

ตำแหน่งไฟล์

NC Core เตรียมไฟล์สำหรับ custom functions ไว้ 2 จุด:

• lib/cl.custom.lua สำหรับฟังก์ชันฝั่ง Client

• lib/sv.custom.lua สำหรับฟังก์ชันฝั่ง Server

ไฟล์เหล่านี้ถูกโหลดพร้อม NC Core ฟังก์ชันที่ประกาศไว้จะพร้อมใช้งานผ่าน ESX โดยตรง

ขั้นตอนการเพิ่มฟังก์ชัน (แนะนำ)

1

เลือกฝั่งที่เหมาะสม

• งานที่เกี่ยวข้องกับเงิน Item สิทธิ์ และความปลอดภัย ให้ทำบน Server

• งานที่เกี่ยวกับ UI/เอฟเฟกต์/การควบคุมตัวละคร ให้ทำบน Client

2

เพิ่มเมทอดในไฟล์ *.custom.lua

• เพิ่มฟังก์ชันใน lib/sv.custom.lua หรือ lib/cl.custom.lua

• ตั้งชื่อเป็นกริยา และสื่อหน้าที่ชัดเจน เช่น ESX.GivePackage, ESX.RevivePlayer

3

ทดสอบการโหลดและการเรียกใช้งาน

• รีสตาร์ท es_extended หรือรีสตาร์ทเซิร์ฟเวอร์ 1 รอบ

• ตรวจ error ที่ Console/F8 เพื่อยืนยันว่าเมทอดถูกผูกกับ ESX แล้ว

โครงสร้างพื้นฐาน (Template)

กำหนดรูปแบบพารามิเตอร์และการคืนค่าให้สม่ำเสมอ

ใส่คำอธิบายสั้น ๆ เพื่อให้ทีมอ่านโค้ดได้เร็วขึ้น

-- lib/sv.custom.lua
-- name: ESX.MyCustomFunction
-- desc: คำอธิบายสั้น ๆ ว่าฟังก์ชันนี้ทำอะไร
-- params:
--   - playerId (number)
--   - value (any)
-- returns:
--   - success (boolean)
--   - message (string)
function ESX.MyCustomFunction(playerId, value)
    value = value or 0

    local xPlayer = ESX.GetPlayerFromId(playerId)
    if not xPlayer then
        return false, 'ไม่พบผู้เล่น'
    end

    -- TODO: logic ของคุณ

    return true, 'สำเร็จ'
end

การเรียกใช้งานจาก resource อื่น

Custom functions ถูกผูกกับ ESX จึงเรียกใช้ได้เหมือนเมทอดทั่วไป

• ฝั่ง Client: เรียก ESX.YourFunction() ใน client script

• ฝั่ง Server: เรียก ESX.YourFunction() ใน server script

หาก resource ของคุณยังไม่ได้ import Framework ให้ตั้งค่าตามหน้า Framework usage

ตัวอย่างการเรียกใช้งาน (ขยายดู)

-- server/main.lua
local ok, msg = ESX.GivePackage(source, 'starter', 'admin:give starter')
print(ok, msg)

-- client/main.lua
ESX.TeleportPlayer('hospital')

---

แนวทางการออกแบบ (แนะนำ)

• ตรวจสอบอินพุตทุกครั้ง โดยเฉพาะค่าที่มาจาก client

• ระบุผลลัพธ์ให้ตรวจสอบได้ เช่น success (boolean) และ message (string)

• แยกตรรกะ Client/Server ให้ชัดเจน และให้ Server เป็นแหล่งข้อมูลจริง (source of truth)

• หลีกเลี่ยง side-effect ที่คาดเดายาก เช่น แก้ state หลายจุดในฟังก์ชันเดียว

หลีกเลี่ยงการวาง logic ที่ “เชื่อถือไม่ได้” ไว้ฝั่ง Client งานด้านเศรษฐกิจ สิทธิ์ Item และความปลอดภัย ควรทำบน Server เป็นหลัก

ตัวอย่างเพิ่มเติม

ตัวอย่าง (Client): ฟังก์ชันชุบชีพ (Revive)

-- lib/cl.custom.lua
function ESX.RevivePlayer()
    local playerPed = PlayerPedId()
    local coords = GetEntityCoords(playerPed)

    if IsEntityDead(playerPed) then
        NetworkResurrectLocalPlayer(coords.x, coords.y, coords.z, GetEntityHeading(playerPed), true, false)
        Wait(100)

        SetEntityHealth(playerPed, 200)
        SetPedArmour(playerPed, 100)

        ClearPedTasksImmediately(playerPed)
        ClearPedBloodDamage(playerPed)
        ResetPedVisibleDamage(playerPed)
        ResetPedMovementClipset(playerPed, 0)

        ESX.ShowNotification('คุณได้รับการชุบชีพแล้ว')
        return true
    end

    ESX.ShowNotification('ไม่สามารถชุบชีพได้ เนื่องจากผู้เล่นยังไม่ตาย')
    return false
end

ตัวอย่าง (Client): ฟังก์ชันเทเลพอร์ต (Teleport)

-- lib/cl.custom.lua
ESX.TeleportLocations = {
    hospital = vector3(298.72, -584.90, 43.26),
    police = vector3(425.13, -979.56, 30.71),
    bank = vector3(149.46, -1040.53, 29.37),
}

function ESX.TeleportPlayer(coords, heading)
    local playerPed = PlayerPedId()

    DoScreenFadeOut(500)
    Wait(500)

    if type(coords) == 'string' then
        coords = ESX.TeleportLocations[coords:lower()]
        if not coords then
            DoScreenFadeIn(500)
            ESX.ShowNotification('ไม่พบสถานที่ที่ระบุ')
            return false
        end
    end

    SetEntityCoords(playerPed, coords.x, coords.y, coords.z, false, false, false, false)
    if heading then SetEntityHeading(playerPed, heading) end

    Wait(100)
    DoScreenFadeIn(500)
    return true
end

ตัวอย่าง (Server): ให้แพ็คเกจ Item/เงิน (GivePackage)

-- lib/sv.custom.lua
ESX.PackageTypes = {
    starter = {
        name = 'แพ็คเกจผู้เริ่มต้น',
        items = {
            {name = 'bread', count = 5},
            {name = 'water', count = 5},
        },
        money = 5000,
        bank = 25000
    }
}

function ESX.GivePackage(playerId, packageType, reason)
    local xPlayer = ESX.GetPlayerFromId(playerId)
    if not xPlayer then return false, 'ไม่พบผู้เล่น' end

    local package = ESX.PackageTypes[packageType]
    if not package then return false, 'ไม่พบแพ็คเกจนี้' end

    reason = reason or ('รับแพ็คเกจ: ' .. package.name)

    if package.items then
        for _, item in ipairs(package.items) do
            if xPlayer.canCarryItem(item.name, item.count) then
                xPlayer.addInventoryItem(item.name, item.count)
            end
        end
    end

    if package.money then
        xPlayer.addMoney(package.money, reason)
    end

    if package.bank then
        xPlayer.addAccountMoney('bank', package.bank, reason)
    end

    return true, 'สำเร็จ'
end

การทดสอบและการดีบัก (แนะนำ)

ทดสอบแยกตามฝั่ง เพื่อแยกสาเหตุได้ชัดเจน

• ทดสอบฝั่ง Server ด้วย command/event ที่ควบคุมได้

• ทดสอบฝั่ง Client หลัง spawn แล้ว และตรวจสอบ error ใน F8

Support

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

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

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