Extending Functions

แนวทางเพิ่ม Functions ให้ NC Core พร้อมโครงสร้างไฟล์ การเปิดใช้งานผ่าน config และตัวอย่าง Client/Server

การเพิ่ม Functions

หน้านี้อธิบายแนวทางเพิ่ม Functions ให้ NC Core เนื้อหาเน้นโครงสร้างไฟล์ การเปิดใช้งานผ่าน config และรูปแบบการเขียนที่ดูแลง่าย

Functions คืออะไร

Functions คือฟังก์ชันส่วนกลางของ Framework ออกแบบให้เรียกใช้ซ้ำได้บ่อย และใช้งานได้หลาย resource

โฟลเดอร์ที่เกี่ยวข้อง

• functions/client/ สำหรับฝั่ง Client

• functions/server/ สำหรับฝั่ง Server

• functions/shared/ สำหรับโค้ดที่ใช้ร่วมกัน

การเปิดใช้งาน (สำคัญ)

ต้องเปิดใช้งานใน config/config.functions.lua หากไม่เพิ่มใน config ฟังก์ชันจะไม่ถูกโหลด

Functions vs Modules vs Player Class

• Player Class Functions เหมาะกับเมธอดที่ผูกกับ xPlayer และทำงานรายผู้เล่น

• Modules เหมาะกับเครื่องมือเสริม เปิด/ปิดได้ และไม่ได้เป็นแกนหลักของ Framework

• Functions เหมาะกับฟังก์ชันส่วนกลางที่เรียกใช้บ่อย และเป็นส่วนขยายของ Framework หลัก

โครงสร้างไฟล์ (ขั้นต่ำ)

-- functions/client/YourFunction.lua หรือ functions/server/YourFunction.lua
return function(param1, param2)
    -- เขียนโค้ดของคุณที่นี่
    return result
end

ไฟล์ใน functions/* ต้อง return function(...) เสมอ อย่าสร้างเป็น function YourFunction() แบบ global

Steps to Add New Function

ขั้นตอนการเพิ่ม Function ใหม่

1

สร้างไฟล์ Function

เลือกตำแหน่งให้ถูกฝั่ง:

• Client: functions/client/

• Server: functions/server/

• Shared: functions/shared/

2

เขียนฟังก์ชัน และใส่ comment ให้ครบ

แนะนำให้ระบุ:

• วัตถุประสงค์

• พารามิเตอร์ และชนิดข้อมูล

• ค่าที่ return

3

เปิดใช้งานใน config/config.functions.lua

เพิ่มชื่อไฟล์ (ไม่ต้องใส่นามสกุล .lua) ลงในฝั่งที่เกี่ยวข้อง

4

ทดสอบการเรียกใช้งาน

ทดสอบในจุดใช้งานจริง และตรวจ error log

ตัวอย่าง: Client Function

ไฟล์: functions/client/PlayAnimationSync.lua

functions/client/PlayAnimationSync.lua

-- ========================================
-- Function: PlayAnimationSync
-- คำอธิบาย: เล่นแอนิเมชันแบบ Synchronized
-- Parameters:
--   @param dict (string) - ชื่อ Animation Dictionary
--   @param anim (string) - ชื่อ Animation
--   @param duration (number) - ระยะเวลา (ms) หรือ -1 = วนลูป
--   @param flag (number) - Animation Flag (default: 49)
-- Returns:
--   @return (boolean) - สำเร็จหรือไม่
-- ========================================
return function(dict, anim, duration, flag)
    -- ตรวจสอบ parameter
    if type(dict) ~= 'string' or type(anim) ~= 'string' then
        print('[ERROR] PlayAnimationSync: invalid parameters')
        return false
    end
    
    duration = duration or 5000
    flag = flag or 49
    
    -- โหลด Animation Dictionary
    RequestAnimDict(dict)
    local timeout = 0
    while not HasAnimDictLoaded(dict) and timeout < 5000 do
        Wait(10)
        timeout = timeout + 10
    end
    
    if not HasAnimDictLoaded(dict) then
        print('[ERROR] PlayAnimationSync: failed to load dict:', dict)
        return false
    end
    
    -- เล่นแอนิเมชัน
    local playerPed = PlayerPedId()
    TaskPlayAnim(playerPed, dict, anim, 8.0, -8.0, duration, flag, 0, false, false, false)
    
    -- ลบ dictionary หลังใช้งาน
    if duration > 0 then
        SetTimeout(duration + 1000, function()
            RemoveAnimDict(dict)
        end)
    end
    
    return true
end

Enable in Config

เปิดใช้งานใน Config

-- config/config.functions.lua
Config.Functions.Client = {
    -- Functions เดิม...
    ['GetPlayerData'] = true,
    ['SetPlayerData'] = true,
    
    -- เพิ่ม Function ใหม่
    ['PlayAnimationSync'] = true,
}

วิธีใช้งาน (Client)

-- เล่นแอนิเมชันกำลังดื่ม
RegisterCommand('drink', function()
    ESX.PlayAnimationSync('mp_player_intdrink', 'loop_bottle', 5000)
    
    -- ส่งคำสั่งไปยัง Server
    SetTimeout(5000, function()
        TriggerServerEvent('consumable:drink', 'water')
    end)
end)

-- เล่นแอนิเมชันกำลังซ่อม
RegisterNetEvent('mechanic:startRepair', function()
    ESX.PlayAnimationSync('mini@repair', 'fixing_a_player', 10000)
    
    SetTimeout(10000, function()
        TriggerServerEvent('mechanic:finishRepair')
    end)
end)

-- เล่นแอนิเมชันวนลูป (ยกมือขึ้น)
RegisterCommand('handsup', function()
    ESX.PlayAnimationSync('missminuteman_1ig_2', 'handsup_base', -1, 49)
end)

ตัวอย่าง: Server Function

ไฟล์: functions/server/GetPlayersInRadius.lua

functions/server/GetPlayersInRadius.lua

-- ========================================
-- Function: GetPlayersInRadius
-- คำอธิบาย: ดึงผู้เล่นทั้งหมดในรัศมี
-- Parameters:
--   @param coords (vector3) - ตำแหน่งกึ่งกลาง
--   @param radius (number) - รัศมี (เมตร)
--   @param includeXPlayer (boolean) - รวม xPlayer object หรือไม่
-- Returns:
--   @return (table) - array ของ {source, xPlayer, distance, coords}
-- ========================================
return function(coords, radius, includeXPlayer)
    -- ตรวจสอบ parameter
    if type(coords) == 'table' and not coords.x then
        coords = vector3(coords.x or coords[1], coords.y or coords[2], coords.z or coords[3])
    end
    
    radius = radius or 10.0
    includeXPlayer = includeXPlayer or false
    
    local playersInRadius = {}
    local xPlayers = ESX.GetExtendedPlayers()
    
    for _, xPlayer in pairs(xPlayers) do
        local playerCoords = xPlayer.getCoords(true)
        local distance = #(coords - playerCoords)
        
        if distance <= radius then
            table.insert(playersInRadius, {
                source = xPlayer.source,
                xPlayer = includeXPlayer and xPlayer or nil,
                distance = distance,
                coords = playerCoords
            })
        end
    end
    
    -- เรียงตามระยะใกล้-ไกล
    table.sort(playersInRadius, function(a, b)
        return a.distance < b.distance
    end)
    
    return playersInRadius
end

Enable in Config

เปิดใช้งานใน Config

-- config/config.functions.lua
Config.Functions.Server = {
    -- Functions เดิม...
    ['GetPlayers'] = true,
    ['GetExtendedPlayers'] = true,
    
    -- เพิ่ม Function ใหม่
    ['GetPlayersInRadius'] = true,
}

วิธีใช้งาน (Server)

-- ตัวอย่าง: ระบบระเบิด
RegisterNetEvent('bomb:explode', function(bombCoords)
    -- หาผู้เล่นในรัศมี 50 เมตร
    local players = ESX.GetPlayersInRadius(bombCoords, 50.0, true)
    
    for _, data in ipairs(players) do
        local xPlayer = data.xPlayer
        local distance = data.distance
        
        -- คำนวณความเสียหาย (ใกล้ = เสียหายมาก)
        local damage = math.max(0, 100 - (distance * 2))
        
        -- ส่งคำสั่งไปยัง Client
        TriggerClientEvent('bomb:takeDamage', xPlayer.source, damage)
        
        xPlayer.showNotification(string.format('~r~ระเบิด! ได้รับความเสียหาย %d', math.floor(damage)))
    end
    
    print(string.format('[Bomb] Affected %d players', #players))
end)

-- ตัวอย่าง: ระบบประกาศในพื้นที่
RegisterNetEvent('announce:local', function(message)
    local xPlayer = ESX.GetPlayerFromId(source)
    local playerCoords = xPlayer.getCoords(true)
    
    -- หาผู้เล่นในรัศมี 20 เมตร
    local nearbyPlayers = ESX.GetPlayersInRadius(playerCoords, 20.0, false)
    
    for _, data in ipairs(nearbyPlayers) do
        TriggerClientEvent('chat:addMessage', data.source, {
            color = {255, 194, 14},
            args = {'📢 ' .. xPlayer.getName(), message}
        })
    end
end)

-- ตัวอย่าง: ระบบกิจกรรมในพื้นที่
RegisterCommand('startevent', function(source, args)
    local xPlayer = ESX.GetPlayerFromId(source)
    if xPlayer.getGroup() ~= 'admin' then return end
    
    local eventCoords = vector3(100.0, 200.0, 30.0)
    local players = ESX.GetPlayersInRadius(eventCoords, 100.0, true)
    
    for _, data in ipairs(players) do
        -- ให้รางวัล
        data.xPlayer.addMoney(5000, 'Event Reward')
        data.xPlayer.showNotification('~g~Event Started! +$5000')
    end
    
    print(string.format('[Event] Started with %d players', #players))
end, true)

แนวทางการเขียน (Best Practices)

เลือกประเภทให้ถูกงาน

ประเภท	ตำแหน่ง	Config	Object Context	Use Case
Player Class	server/classes/player/functions/	❌ ไม่ต้อง	player (xPlayer)	ฟังก์ชันเฉพาะผู้เล่น
Modules	modules/*/	✅ config.modules.lua	ไม่มี	ฟังก์ชันเสริมทั่วไป
Functions	functions/*/	✅ config.functions.lua	ไม่มี	ฟังก์ชันหลักของ Framework

การตั้งชื่อ

ตั้งชื่อให้สื่อความหมาย และสอดคล้องกับการใช้งานจริง

-- ❌ ไม่ดี
function xyz()
function DoStuff()
function func1()

-- ✅ ดี
function addExperience()
function isNearPlayer()
function ShowCustomNotification()
function GetPlayersInRadius()

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

-- ========================================
-- ชื่อฟังก์ชัน
-- คำอธิบาย: ...
-- Parameters:
--   @param name (type) - description
-- Returns:
--   @return (type) - description
-- ========================================
return function(...)
    -- โค้ด
end

การ return ค่า

-- ✅ ดี: Return ค่าที่มีความหมาย
return true, 'สำเร็จ'
return false, 'เงินไม่พอ'
return {level = 5, exp = 250}

-- ❌ ไม่ดี: ไม่ return อะไรเลย
-- function(...)
--     -- ทำอะไรสักอย่าง
-- end

การตรวจสอบพารามิเตอร์ และ default value

return function(param1, param2)
    -- ✅ ตรวจสอบก่อนใช้
    if type(param1) ~= 'string' then
        print('[ERROR] param1 must be string')
        return false
    end
    
    -- ใช้ default value
    param2 = param2 or 100
    
    -- โค้ดหลัก...
end

Checklist การเพิ่ม Function

• สร้างไฟล์ใน functions/client/ หรือ functions/server/ หรือ functions/shared/

• ตั้งชื่อไฟล์เป็น PascalCase

• เขียน comment อธิบายฟังก์ชัน

• เพิ่มใน config/config.functions.lua

Config.Functions.Client = {
    ['YourFunctionName'] = true,
}

• ทดสอบการทำงาน

สรุป

Functions เหมาะเมื่อ:

• เป็นฟังก์ชันส่วนกลางที่ใช้ซ้ำหลายจุด

• ต้องการให้เรียกผ่าน ESX.YourFunction() ได้แบบมาตรฐาน

• ต้องการควบคุมการโหลดผ่าน config/config.functions.lua

ตัวอย่าง: ESX.GetPlayersInRadius(), ESX.PlayAnimationSync()

เพิ่ม Function เรียบร้อยแล้ว หากเรียกใช้งานไม่เจอ ให้ตรวจ config/config.functions.lua เป็นอันดับแรก