Extending Framework

ภาพรวมแนวทางขยาย NC Core ด้วย Player Class Functions, Modules และ Functions พร้อมลิงก์ไปยังหน้ารายละเอียด

Extending Framework

NC Core รองรับการขยายความสามารถแบบ “เพิ่มไฟล์ใหม่” โดยไม่แก้ไฟล์หลัก

แนวทางนี้ช่วยลดความเสี่ยงเวลาต้องอัปเดต Framework และทำให้ดูแลโค้ดง่ายขึ้น

หลีกเลี่ยงการแก้ไฟล์ core โดยตรง ให้เพิ่มความสามารถผ่าน Player Class Functions, Modules หรือ Functions แทน

เลือกแนวทางให้เหมาะกับงาน

Player Class Functions

เพิ่ม Method ให้ xPlayer เช่น xPlayer.addExperience() ใช้ได้เฉพาะฝั่ง Server และ โหลดอัตโนมัติ (ไม่ต้องเปิดใน config)

Modules

ฟังก์ชันเสริมที่แยกตามฝั่ง client/server/shared เปิด/ปิดได้ใน config/config.modules.lua

Functions

ฟังก์ชันส่วนกลางของ Framework (ESX.*) เปิด/ปิดได้ใน config/config.functions.lua

โครงสร้างโฟลเดอร์

Player Class Functions: server/classes/player/functions/
Modules: modules/client/, modules/server/, modules/shared/
Functions: functions/client/, functions/server/, functions/shared/

Quick start

เลือกประเภทการขยาย

ถ้าต้องการเรียกผ่าน xPlayer.* ให้ใช้ Player Class Functions
ถ้าต้องการเรียกผ่าน ESX.* ให้ใช้ Modules หรือ Functions

สร้างไฟล์ และตั้งชื่อให้ตรงกับสิ่งที่จะเรียก

Player Class Functions: ชื่อไฟล์ = ชื่อ Method (เช่น addExperience.lua)
Modules/Functions: ชื่อไฟล์ PascalCase (เช่น ShowCustomNotification.lua)

เปิดใช้งาน และทดสอบ

Player Class Functions: ทดสอบได้ทันทีหลัง restart resource
Modules: เพิ่มรายการใน config/config.modules.lua
Functions: เพิ่มรายการใน config/config.functions.lua

อ่านต่อ (หน้ารายละเอียด)

หัวข้อที่มักใช้ร่วมกัน

Transaction: ดูใน Shared Functions
Status API: ดูใน Player Class — Status

Checklist (สรุป)

เนื้อหาเพิ่มเติม (ตัวอย่างและรายละเอียดแบบเต็ม)

เกี่ยวกับ Player Class Functions

Player Class Functions คือฟังก์ชันที่ทำงานกับ xPlayer object โดยตรง ใช้งานเฉพาะฝั่ง Server-side เท่านั้น

📁 ตำแหน่ง: server/classes/player/functions/
⚙️ Config: ไม่ต้องระบุใน config (โหลดอัตโนมัติ)
🎯 จุดประสงค์: เพิ่มฟังก์ชันใหม่ให้ xPlayer object

โครงสร้างพื้นฐาน

-- server/classes/player/functions/yourFunction.lua
return function(player, param1, param2)
    -- player คือ xPlayer object
    -- เขียนโค้ดของคุณที่นี่
    
    return result
end

ตัวอย่างที่ 1: ฟังก์ชันเพิ่มแต้มประสบการณ์

ไฟล์: server/classes/player/functions/addExperience.lua

-- ========================================
-- ฟังก์ชัน: addExperience
-- คำอธิบาย: เพิ่มแต้มประสบการณ์ให้ผู้เล่น
-- Parameters:
--   @param amount (number) - จำนวน EXP ที่ต้องการเพิ่ม
--   @param reason (string) - เหตุผล (สำหรับ log)
-- Returns:
--   @return (number) - EXP ปัจจุบันหลังเพิ่ม
-- ========================================
return function(player, amount, reason)
    -- ตรวจสอบ parameter
    amount = amount or 0
    reason = reason or 'Unknown'
    
    if amount <= 0 then
        print('[ERROR] addExperience: amount must be positive')
        return player.getMeta('experience') or 0
    end
    
    -- ดึง EXP ปัจจุบัน
    local currentExp = player.getMeta('experience') or 0
    local newExp = currentExp + amount
    
    -- บันทึก EXP ใหม่
    player.setMeta('experience', newExp)
    
    -- แจ้งเตือนผู้เล่น
    player.showNotification(string.format('~g~+%d EXP~s~ (%s)', amount, reason))
    
    -- Log
    print(string.format('[EXP] %s gained %d EXP (Reason: %s) - Total: %d', 
        player.getName(), amount, reason, newExp))
    
    -- ตรวจสอบเลเวลอัพ
    local currentLevel = player.getMeta('level') or 1
    local requiredExp = currentLevel * 1000  -- ต้องการ 1000 EXP ต่อเลเวล
    
    if newExp >= requiredExp then
        -- เลเวลอัพ!
        local newLevel = currentLevel + 1
        player.setMeta('level', newLevel)
        player.setMeta('experience', newExp - requiredExp)  -- EXP เหลือ
        
        player.showNotification(string.format('~y~🎉 Level Up!~s~ Level %d', newLevel))
        
        -- ให้รางวัล
        player.addMoney(newLevel * 1000, 'Level Up Reward')
    end
    
    return newExp
end

วิธีเรียกใช้งาน:

-- ใน resource อื่นๆ (server-side)
RegisterNetEvent('mission:complete', function(missionId)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    -- เรียกใช้ฟังก์ชันที่สร้างขึ้น
    local newExp = xPlayer.addExperience(500, 'ทำภารกิจสำเร็จ')
    print('EXP ปัจจุบัน:', newExp)
end)

-- ตัวอย่าง: ให้ EXP เมื่อฆ่า NPC
AddEventHandler('gameEventTriggered', function(name, args)
    if name == 'CEventNetworkEntityDamage' then
        local victim = args[1]
        local attacker = args[2]
        
        if IsEntityDead(victim) and IsPedAPlayer(attacker) then
            local playerId = NetworkGetPlayerIndexFromPed(attacker)
            local xPlayer = ESX.GetPlayerFromId(GetPlayerServerId(playerId))
            
            if xPlayer then
                xPlayer.addExperience(10, 'ฆ่า NPC')
            end
        end
    end
end)

ตัวอย่างที่ 2: ฟังก์ชันตรวจสอบระยะห่าง

ไฟล์: server/classes/player/functions/isNearPlayer.lua

-- ========================================
-- ฟังก์ชัน: isNearPlayer
-- คำอธิบาย: ตรวจสอบว่าผู้เล่นอยู่ใกล้ผู้เล่นคนอื่นหรือไม่
-- Parameters:
--   @param targetPlayer (table) - xPlayer object ของเป้าหมาย
--   @param maxDistance (number) - ระยะสูงสุด (เมตร)
-- Returns:
--   @return (boolean) - true ถ้าอยู่ใกล้
--   @return (number) - ระยะห่างจริง
-- ========================================
return function(player, targetPlayer, maxDistance)
    maxDistance = maxDistance or 3.0
    
    -- ตรวจสอบ parameter
    if not targetPlayer then
        print('[ERROR] isNearPlayer: targetPlayer is nil')
        return false, 0
    end
    
    -- ดึงตำแหน่งของทั้งสองคน
    local playerCoords = player.getCoords(true)  -- true = vector3
    local targetCoords = targetPlayer.getCoords(true)
    
    -- คำนวณระยะห่าง
    local distance = #(playerCoords - targetCoords)
    
    -- เปรียบเทียบกับระยะสูงสุด
    return distance <= maxDistance, distance
end

วิธีเรียกใช้งาน:

-- ตัวอย่าง: ระบบแลกเปลี่ยน Item ระหว่างผู้เล่น
RegisterNetEvent('trade:requestTrade', function(targetId)
    local xPlayer = ESX.GetPlayerFromId(source)
    local xTarget = ESX.GetPlayerFromId(targetId)
    
    if not xTarget then
        xPlayer.showNotification('~r~ไม่พบผู้เล่น!')
        return
    end
    
    -- ตรวจสอบระยะห่าง
    local isNear, distance = xPlayer.isNearPlayer(xTarget, 3.0)
    
    if isNear then
        -- เปิดหน้าต่างแลกเปลี่ยน
        TriggerClientEvent('trade:openUI', source, targetId)
        xPlayer.showNotification('~g~เริ่มการแลกเปลี่ยน')
    else
        xPlayer.showNotification(string.format('~r~อยู่ไกลเกินไป! (%.1fm)', distance))
    end
end)

-- ตัวอย่าง: ระบบโจรกรรม
RegisterNetEvent('robbery:startRob', function(targetId)
    local xRobber = ESX.GetPlayerFromId(source)
    local xVictim = ESX.GetPlayerFromId(targetId)
    
    if not xVictim then return end
    
    -- ต้องอยู่ใกล้มากๆ (1.5 เมตร)
    local isNear, distance = xRobber.isNearPlayer(xVictim, 1.5)
    
    if isNear then
        -- เริ่มโจรกรรม
        local stolenMoney = math.floor(xVictim.getMoney() * 0.5)
        xVictim.removeMoney(stolenMoney, 'ถูกปล้น')
        xRobber.addMoney(stolenMoney, 'ปล้นผู้เล่น')
        
        xRobber.showNotification('~g~ปล้นสำเร็จ! +$' .. stolenMoney)
        xVictim.showNotification('~r~คุณถูกปล้น! -$' .. stolenMoney)
    else
        xRobber.showNotification('~r~ต้องอยู่ใกล้มากกว่านี้!')
    end
end)

ตัวอย่างที่ 3: ฟังก์ชันจัดการสกิล

ไฟล์: server/classes/player/functions/addSkillExp.lua

-- ========================================
-- ฟังก์ชัน: addSkillExp
-- คำอธิบาย: เพิ่ม EXP ให้กับสกิลเฉพาะ
-- Parameters:
--   @param skillName (string) - ชื่อสกิล (mining, fishing, crafting)
--   @param amount (number) - จำนวน EXP
-- Returns:
--   @return (table) - {level, currentExp, maxExp, leveledUp}
-- ========================================
return function(player, skillName, amount)
    -- ตรวจสอบ parameter
    if type(skillName) ~= 'string' or amount <= 0 then
        return nil
    end
    
    -- ดึงข้อมูลสกิล
    local skills = player.getMeta('skills') or {}
    local skill = skills[skillName] or {level = 1, exp = 0}
    
    -- เพิ่ม EXP
    skill.exp = skill.exp + amount
    
    -- คำนวณ level และ exp ที่ต้องการ
    local maxExp = skill.level * 500  -- ต้องการ 500 EXP/Level
    local leveledUp = false
    
    -- ตรวจสอบ Level Up
    while skill.exp >= maxExp do
        skill.level = skill.level + 1
        skill.exp = skill.exp - maxExp
        maxExp = skill.level * 500
        leveledUp = true
    end
    
    -- บันทึกข้อมูล
    skills[skillName] = skill
    player.setMeta('skills', skills)
    
    -- แจ้งเตือน
    if leveledUp then
        player.showNotification(string.format('~y~%s Level Up!~s~ Level %d', 
            skillName:upper(), skill.level))
    else
        player.showNotification(string.format('~g~+%d %s EXP', amount, skillName))
    end
    
    return {
        level = skill.level,
        currentExp = skill.exp,
        maxExp = maxExp,
        leveledUp = leveledUp
    }
end

ไฟล์: server/classes/player/functions/getSkillLevel.lua

-- ========================================
-- ฟังก์ชัน: getSkillLevel
-- คำอธิบาย: ดึงเลเวลของสกิล
-- ========================================
return function(player, skillName)
    local skills = player.getMeta('skills') or {}
    local skill = skills[skillName] or {level = 1, exp = 0}
    return skill.level
end

วิธีเรียกใช้งาน:

-- ระบบขุดแร่
RegisterNetEvent('mining:finishMining', function(oreType)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    -- ให้ของ
    xPlayer.addInventoryItem(oreType, 1)
    
    -- เพิ่ม EXP mining
    local skillData = xPlayer.addSkillExp('mining', 50)
    
    print('Mining Level:', skillData.level)
    print('EXP:', skillData.currentExp, '/', skillData.maxExp)
end)

-- ตรวจสอบเลเวลก่อนทำภารกิจ
RegisterNetEvent('quest:checkRequirement', function(questId)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    -- ภารกิจนี้ต้องมี Mining Level 5
    local miningLevel = xPlayer.getSkillLevel('mining')
    
    if miningLevel >= 5 then
        xPlayer.showNotification('~g~คุณมีคุณสมบัติรับภารกิจ!')
        -- เริ่มภารกิจ
    else
        xPlayer.showNotification(string.format('~r~ต้องการ Mining Level 5 (คุณมี Level %d)', miningLevel))
    end
end)

-- ระบบตกปลา
RegisterNetEvent('fishing:caught', function(fishType)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    -- เช็ค Fishing Level สำหรับปลาหายาก
    local fishingLevel = xPlayer.getSkillLevel('fishing')
    
    if fishType == 'rare_fish' and fishingLevel < 10 then
        xPlayer.showNotification('~r~ปลาหนีไป! ต้องการ Fishing Level 10')
        return
    end
    
    xPlayer.addInventoryItem(fishType, 1)
    xPlayer.addSkillExp('fishing', 30)
end)

2. Modules (โมดูลเสริม)

เกี่ยวกับ Modules

Modules คือฟังก์ชันเสริมที่ทำงานอิสระ สามารถสร้างได้ทั้งฝั่ง Client และ Server

📁 ตำแหน่ง: modules/client/ หรือ modules/server/ หรือ modules/shared/
⚙️ Config: ต้องระบุใน config/config.modules.lua
🎯 จุดประสงค์: เพิ่มฟังก์ชันเสริมที่ใช้งานทั่วไป

โครงสร้างพื้นฐาน

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

ขั้นตอนการเพิ่ม Module

ตัวอย่างที่อัปเดตและอ่านง่ายกว่าอยู่ในหน้า Extending Modules

ตัวอย่าง Server Module

ไฟล์: modules/server/BroadcastToJob.lua

-- ========================================
-- Module: BroadcastToJob
-- คำอธิบาย: ส่งข้อความไปยังทุกคนในอาชีพเดียวกัน
-- Parameters:
--   @param jobName (string) - ชื่ออาชีพ
--   @param message (string) - ข้อความ
--   @param minGrade (number) - เกรดขั้นต่ำ (optional)
-- ========================================
return function(jobName, message, minGrade)
    -- ตรวจสอบ parameter
    if type(jobName) ~= 'string' or type(message) ~= 'string' then
        print('[ERROR] BroadcastToJob: invalid parameters')
        return 0
    end
    
    minGrade = minGrade or 0
    local count = 0
    
    -- ดึงผู้เล่นทั้งหมด
    local xPlayers = ESX.GetExtendedPlayers()
    
    for _, xPlayer in pairs(xPlayers) do
        -- ตรวจสอบอาชีพและเกรด
        if xPlayer.job.name == jobName and xPlayer.job.grade >= minGrade then
            xPlayer.showNotification(message)
            count = count + 1
        end
    end
    
    print(string.format('[BroadcastToJob] Sent to %d %s members', count, jobName))
    return count
end

เพิ่มใน Config:

-- config/config.modules.lua
Config.Modules.Server = {
    -- Modules เดิม...
    ['RegisterServerCallback'] = true,
    
    -- เพิ่ม Module ใหม่
    ['BroadcastToJob'] = true,  -- ⬅️ เพิ่มบรรทัดนี้
}

วิธีใช้งาน:

-- server-side

-- ส่งข้อความถึงตำรวจทั้งหมด
ESX.BroadcastToJob('police', '🚨 มีการปล้นธนาคาร! ไปช่วยด่วน!')

-- ส่งข้อความถึงแพทย์เกรด 3 ขึ้นไป
ESX.BroadcastToJob('ambulance', '🏥 มีฉุกเฉิน! ต้องการหัวหน้าทีม', 3)

ตัวอย่าง Shared Module

ไฟล์: modules/shared/CalculateDistance3D.lua

-- ========================================
-- Module: CalculateDistance3D
-- คำอธิบาย: คำนวณระยะห่าง 3 มิติ
-- Parameters:
--   @param coords1 (vector3 หรือ table) - ตำแหน่งที่ 1
--   @param coords2 (vector3 หรือ table) - ตำแหน่งที่ 2
-- Returns:
--   @return (number) - ระยะห่าง (เมตร)
-- ========================================
return function(coords1, coords2)
    -- แปลง table เป็น vector3
    if type(coords1) == 'table' and not coords1.x then
        coords1 = vector3(coords1[1] or 0, coords1[2] or 0, coords1[3] or 0)
    end
    if type(coords2) == 'table' and not coords2.x then
        coords2 = vector3(coords2[1] or 0, coords2[2] or 0, coords2[3] or 0)
    end
    
    -- คำนวณระยะห่าง
    return #(coords1 - coords2)
end

เพิ่มใน Config:

-- config/config.modules.lua
Config.Modules.Shared = {
    -- Modules เดิม...
    ['DumpTable'] = true,
    
    -- เพิ่ม Module ใหม่
    ['CalculateDistance3D'] = true,  -- ⬅️ เพิ่มบรรทัดนี้
}

วิธีใช้งาน:

-- ใช้ได้ทั้ง Client และ Server

-- Client: ตรวจสอบระยะจากผู้เล่นถึงจุดหมาย
local playerCoords = GetEntityCoords(PlayerPedId())
local targetCoords = vector3(100.0, 200.0, 30.0)
local distance = ESX.CalculateDistance3D(playerCoords, targetCoords)

if distance <= 5.0 then
    print('ใกล้จุดหมายแล้ว!')
end

3. Functions (ฟังก์ชันหลัก)

เกี่ยวกับ Functions

Functions คือฟังก์ชันหลักของ NC Core ที่ใช้งานทั่วไป แยกตามฝั่ง Client, Server และ Shared

📁 ตำแหน่ง: functions/client/ หรือ functions/server/ หรือ functions/shared/
⚙️ Config: ต้องระบุใน config/config.functions.lua
🎯 จุดประสงค์: ฟังก์ชันหลักที่ใช้บ่อย

ความแตกต่างระหว่าง Modules และ Functions:

Modules = ฟังก์ชันเสริมเพิ่มเติม
Functions = ฟังก์ชันหลักของ Framework

ในทางปฏิบัติ ทั้งสองทำงานคล้ายกัน แต่แยกเพื่อความเป็นระเบียบ

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

ตัวอย่าง Client Function

ไฟล์: 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

เพิ่มใน Config:

-- config/config.functions.lua
Config.Functions.Client = {
    -- Functions เดิม...
    ['GetPlayerData'] = true,
    ['SetPlayerData'] = true,
    
    -- เพิ่ม Function ใหม่
    ['PlayAnimationSync'] = true,  -- ⬅️ เพิ่มบรรทัดนี้
}

วิธีใช้งาน:

-- client-side

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

ตัวอย่าง Server Function

ไฟล์: 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

เพิ่มใน Config:

-- config/config.functions.lua
Config.Functions.Server = {
    -- Functions เดิม...
    ['GetPlayers'] = true,
    ['GetExtendedPlayers'] = true,
    
    -- เพิ่ม Function ใหม่
    ['GetPlayersInRadius'] = true,  -- ⬅️ เพิ่มบรรทัดนี้
}

วิธีใช้งาน:

-- server-side

-- ตัวอย่าง: ระบบระเบิด
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)

สรุปและ 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

คำแนะนำการเลือกใช้

ใช้ Player Class Functions เมื่อ:

✅ ต้องการเพิ่มฟังก์ชันให้ xPlayer object
✅ ทำงานเฉพาะผู้เล่นคนหนึ่ง
✅ ต้องการเรียกผ่าน xPlayer.yourFunction()

ใช้ Modules เมื่อ:

✅ ฟังก์ชันเสริมที่ไม่เกี่ยวกับผู้เล่นโดยตรง
✅ เป็นเครื่องมือหรือ utility ทั่วไป
✅ ต้องการเปิด/ปิดได้ผ่าน config

ใช้ Functions เมื่อ:

✅ เป็นฟังก์ชันหลักที่สำคัญต่อ Framework
✅ ใช้งานบ่อยมากและทั่วทั้งระบบ
✅ เป็นส่วนขยายของ 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}

การตรวจสอบ Parameters

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

4. Transaction System

เกี่ยวกับ Transaction

Transaction คือระบบที่ใช้ในการทำหลายๆ การเปลี่ยนแปลง (เงิน/Item/อาวุธ) พร้อมกันในครั้งเดียว แทนการเรียกฟังก์ชันทีละตัว

ข้อดีของ Transaction:

⚡ Performance ดีกว่า - ทำหลายอย่างในครั้งเดียว แทนการเรียก function ทีละตัว
🔒 ความปลอดภัย - ถ้าทำไม่สำเร็จ ทั้งหมดจะถูก rollback (ไม่มีการเปลี่ยนแปลง)
📝 Log ครบถ้วน - บันทึกทุกการเปลี่ยนแปลงในครั้งเดียว
💾 Save ครั้งเดียว - บันทึกฐานข้อมูลรอบเดียว ไม่ซ้ำซ้อน

เปรียบเทียบวิธีการ

❌ แบบเดิม (ไม่แนะนำ)

-- เรียกฟังก์ชันทีละตัว (ช้า, save DB หลายครั้ง)
xPlayer.addMoney(5000, 'รางวัลภารกิจ')
xPlayer.addAccountMoney('bank', 10000, 'รางวัลภารกิจ')
xPlayer.addInventoryItem('bread', 5)
xPlayer.addInventoryItem('water', 10)
xPlayer.addWeapon('WEAPON_PISTOL', 50)

✅ แบบใหม่ (แนะนำ) - Transaction

-- ทำทั้งหมดในครั้งเดียว (เร็ว, save DB ครั้งเดียว)
xPlayer.transaction({
    { name = 'addMoney', values = { 5000, 'รางวัลภารกิจ' } },
    { name = 'addAccountMoney', values = { 'bank', 10000, 'รางวัลภารกิจ' } },
    { name = 'addInventoryItem', values = { 'bread', 5 } },
    { name = 'addInventoryItem', values = { 'water', 10 } },
    { name = 'addWeapon', values = { 'WEAPON_PISTOL', 50 } },
})

xPlayer.transaction() - Player Transaction

ใช้สำหรับทำหลายๆ การเปลี่ยนแปลงกับผู้เล่น 1 คน พร้อมกัน

Syntax:

xPlayer.transaction(transactions)

Parameters:

transactions (table): Array ของ transaction objects
- name (string): ชื่อฟังก์ชัน (addMoney, removeMoney, addInventoryItem, etc.)
- values (table): Array ของ parameters

ฟังก์ชันที่รองรับ:

addMoney / removeMoney
addAccountMoney / removeAccountMoney
addInventoryItem / removeInventoryItem
addWeapon / removeWeapon
setJob / setJob2
setMeta

ตัวอย่างที่ 1: ระบบให้รางวัลภารกิจ (แบบง่าย)

-- server-side
RegisterNetEvent('mission:complete', function(missionId)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    -- กำหนดรางวัล
    local rewards = {
        { type = 'money', amount = 5000 },
        { type = 'bank', amount = 10000 },
        { type = 'item', name = 'bread', quantity = 5 },
        { type = 'item', name = 'water', quantity = 10 },
        { type = 'weapon', name = 'WEAPON_PISTOL', ammo = 50 }
    }
    
    -- สร้าง transactions
    local transactions = {}
    
    for _, reward in ipairs(rewards) do
        if reward.type == 'money' then
            table.insert(transactions, {
                name = 'addMoney',
                values = { reward.amount, 'รางวัลภารกิจ ' .. missionId }
            })
        elseif reward.type == 'bank' then
            table.insert(transactions, {
                name = 'addAccountMoney',
                values = { 'bank', reward.amount, 'รางวัลภารกิจ ' .. missionId }
            })
        elseif reward.type == 'item' then
            table.insert(transactions, {
                name = 'addInventoryItem',
                values = { reward.name, reward.quantity }
            })
        elseif reward.type == 'weapon' then
            table.insert(transactions, {
                name = 'addWeapon',
                values = { reward.name, reward.ammo }
            })
        end
    end
    
    -- Execute transaction
    if #transactions > 0 then
        local success = xPlayer.transaction(transactions)
        
        if success then
            xPlayer.showNotification('~g~ได้รับรางวัล!')
        else
            xPlayer.showNotification('~r~เกิดข้อผิดพลาด!')
        end
    end
end)

ESX.Transaction() - Multi-Player Transaction

ใช้สำหรับทำการเปลี่ยนแปลงกับ หลายคน พร้อมกัน

Syntax:

ESX.Transaction(playerTransactions)

Parameters:

playerTransactions (table): Object ที่มี key เป็น source/identifier ของผู้เล่น

{
    [source1] = { transactions },
    [source2] = { transactions },
    [identifier1] = { transactions }
}

ตัวอย่างที่ 5: ระบบแลกเปลี่ยนระหว่างผู้เล่น

-- server-side
RegisterNetEvent('trade:execute', function(targetId, myOffer, theirOffer)
    local xPlayer = ESX.GetPlayerFromId(source)
    local xTarget = ESX.GetPlayerFromId(targetId)
    
    if not xTarget then
        xPlayer.showNotification('~r~ไม่พบผู้เล่น!')
        return
    end
    
    -- 1. ตรวจสอบว่าทั้ง 2 คนมีของจริง
    for _, item in ipairs(myOffer) do
        local invItem = xPlayer.getInventoryItem(item.name)
        if not invItem or invItem.count < item.quantity then
            xPlayer.showNotification('~r~คุณไม่มี ' .. item.name)
            return
        end
    end
    
    for _, item in ipairs(theirOffer) do
        local invItem = xTarget.getInventoryItem(item.name)
        if not invItem or invItem.count < item.quantity then
            xPlayer.showNotification('~r~อีกฝ่ายไม่มี ' .. item.name)
            return
        end
    end
    
    -- 2. สร้าง Multi-Player Transaction
    local playerTransactions = {}
    
    -- Player 1: ลบของตัวเอง + รับของอีกฝ่าย
    playerTransactions[source] = {}
    for _, item in ipairs(myOffer) do
        table.insert(playerTransactions[source], {
            name = 'removeInventoryItem',
            values = { item.name, item.quantity }
        })
    end
    for _, item in ipairs(theirOffer) do
        table.insert(playerTransactions[source], {
            name = 'addInventoryItem',
            values = { item.name, item.quantity }
        })
    end
    
    -- Player 2: ลบของตัวเอง + รับของอีกฝ่าย
    playerTransactions[targetId] = {}
    for _, item in ipairs(theirOffer) do
        table.insert(playerTransactions[targetId], {
            name = 'removeInventoryItem',
            values = { item.name, item.quantity }
        })
    end
    for _, item in ipairs(myOffer) do
        table.insert(playerTransactions[targetId], {
            name = 'addInventoryItem',
            values = { item.name, item.quantity }
        })
    end
    
    -- 3. Execute Multi-Player Transaction
    local success = ESX.Transaction(playerTransactions)
    
    if success then
        xPlayer.showNotification('~g~แลกเปลี่ยนสำเร็จ!')
        xTarget.showNotification('~g~แลกเปลี่ยนสำเร็จ!')
    else
        xPlayer.showNotification('~r~แลกเปลี่ยนล้มเหลว!')
        xTarget.showNotification('~r~แลกเปลี่ยนล้มเหลว!')
    end
end)

สรุปความแตกต่าง

Feature

xPlayer.transaction()

ESX.Transaction()

ผู้เล่น

1 คน

หลายคน

Use Case

ให้รางวัล, ซื้อของ, คราฟ

แลกเปลี่ยน, แจกของหลายคน

Performance

⚡ เร็ว (save 1 คน)

⚡⚡ เร็วมาก (save หลายคนพร้อมกัน)

Rollback

✅ ถ้าล้มเหลว rollback

✅ ถ้าล้มเหลว rollback ทุกคน

ข้อควรระวัง:

⚠️ Transaction จะ rollback ทั้งหมด ถ้าทำไม่สำเร็จ
⚠️ ต้องตรวจสอบ เงิน, ช่องเก็บของ, น้ำหนัก ก่อนทำ transaction
⚠️ ESX.Transaction() จะล้มเหลว ทั้งหมด ถ้าผู้เล่นคนใดคนหนึ่งล้มเหลว

5. Performance Optimization - เรียกค่าโดยตรง

ปัญหา: เรียกฟังก์ชัน Reference ซ้ำซ้อน

ปัญหาที่พบบ่อย:

เรียก xPlayer.getName() ทั้งที่มีค่าใน xPlayer.name อยู่แล้ว
เรียก xPlayer.getJob() ทั้งที่มีค่าใน xPlayer.job อยู่แล้ว
เรียก xPlayer.getInventoryItem('item').count ทั้งที่เข้าถึงได้โดยตรงจาก xPlayer.inventory['item']

ผลกระทบ:

🐌 ช้าลง (เรียก function ซ้ำเปล่าๆ)
💾 ใช้ memory มากขึ้น
🔄 โหลดของเดิมซ้ำๆ

Auto-Filter จาก imports.lua

เมื่อใช้งาน NC Core มี 2 รูปแบบ:

1. ใช้ imports.lua (แนะนำ) - มี Auto-Filter

ไฟล์: fxmanifest.lua

fx_version 'cerulean'
game 'gta5'

-- เพิ่มบรรทัดนี้
shared_script '@es_extended/imports.lua'

client_scripts {
    'client.lua'
}

server_scripts {
    'server.lua'
}

ผลลัพธ์: เมื่อใช้ imports.lua จะส่งข้อมูลพื้นฐานของ xPlayer และโหลดฟังก์ชันตามที่เรียกใช้จริง (Auto-Filter)

ข้อดีของ Auto-Filter:

✅ Performance ดีกว่า - ส่งข้อมูลเฉพาะที่ต้องใช้
✅ โหลดฟังก์ชันตามต้องการ - ถ้าไม่ได้เรียกใช้ ก็ไม่โหลด
✅ ลด Bandwidth - ส่งข้อมูลน้อยลง
✅ ใช้งานง่าย - เหมือนเดิมทุกประการ

2. ไม่ใช้ imports.lua - ไม่มี Auto-Filter

ถ้าไม่ใส่ @es_extended/imports.lua ใน fxmanifest จะได้ xPlayer ที่มี function references ทั้งหมด ส่งผลให้ข้อมูลใหญ่และช้าลง

ข้อเสียของการไม่ใช้ imports.lua:

⚠️ ส่งข้อมูลมากเกินจำเป็น (ทั้งข้อมูล + functions)
⚠️ Performance แย่กว่า
⚠️ ใช้ Bandwidth มากขึ้น

เปรียบเทียบการเข้าถึงข้อมูล

ข้อมูล

❌ ช้า (เรียก Function)

✅ เร็ว (เข้าถึงโดยตรง)

ชื่อ

xPlayer.getName()

xPlayer.name

อาชีพ

xPlayer.getJob()

xPlayer.job

เงิน

xPlayer.getAccount('bank').money

xPlayer.accounts.bank

Item

xPlayer.getInventoryItem('bread').count

xPlayer.inventory.bread

ตัวอย่างการ Optimize

❌ แบบเดิม (ช้า - เรียก function ซ้ำซ้อน)

-- server-side
RegisterNetEvent('shop:buy', function(itemName, quantity)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    -- เรียก function ทุกครั้ง (ช้า!)
    local playerName = xPlayer.getName()  -- ❌
    local playerMoney = xPlayer.getMoney()  -- ❌
    local job = xPlayer.getJob()  -- ❌
    local jobName = job.name
    local jobGrade = job.grade
    
    -- ดึง Item
    local item = xPlayer.getInventoryItem(itemName)  -- ❌ เรียก function
    local currentCount = item and item.count or 0
    
    -- คำนวณราคา
    local itemData = ESX.Items[itemName]
    local price = itemData.price * quantity
    
    -- ตรวจสอบเงิน
    if playerMoney >= price then  -- ❌ ใช้ค่าจาก function
        xPlayer.removeMoney(price)
        xPlayer.addInventoryItem(itemName, quantity)
        
        -- Log
        print(string.format('%s (%s - Grade %d) bought %s x%d for $%d', 
            playerName, jobName, jobGrade, itemName, quantity, price))
    end
end)

✅ แบบใหม่ (เร็ว - เข้าถึงโดยตรง)

-- server-side
RegisterNetEvent('shop:buy', function(itemName, quantity)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    -- เข้าถึงโดยตรง (เร็วกว่ามาก!)
    local playerName = xPlayer.name  -- ✅
    local playerMoney = xPlayer.accounts.money or 0  -- ✅
    local jobName = xPlayer.job.name  -- ✅
    local jobGrade = xPlayer.job.grade  -- ✅
    
    -- เข้าถึง inventory โดยตรง
    local currentCount = xPlayer.inventory[itemName] or 0  -- ✅
    
    -- คำนวณราคา
    local itemData = ESX.Items[itemName]
    local price = itemData.price * quantity
    
    -- ตรวจสอบเงิน
    if playerMoney >= price then
        xPlayer.removeMoney(price)
        xPlayer.addInventoryItem(itemName, quantity)
        
        -- Log
        print(string.format('%s (%s - Grade %d) bought %s x%d for $%d', 
            playerName, jobName, jobGrade, itemName, quantity, price))
    end
end)

รายการ Properties ที่เข้าถึงได้โดยตรง

local xPlayer = ESX.GetPlayerFromId(source)

-- ข้อมูลพื้นฐาน
xPlayer.source
xPlayer.playerId
xPlayer.identifier
xPlayer.name
xPlayer.group
xPlayer.sex

-- ตัวแปร, บัญชี, คลัง, อาชีพ ฯลฯ
xPlayer.variables
xPlayer.accounts
xPlayer.inventory
xPlayer.loadout
xPlayer.job
xPlayer.job2
xPlayer.coords
xPlayer.weight
xPlayer.maxWeight
xPlayer.health
xPlayer.armor
xPlayer.metadata
xPlayer.fashions
xPlayer.bucket

Best Practices

เข้าถึงโดยตรงเสมอ (ถ้าเป็นไปได้)
Cache ค่าที่ใช้ซ้ำๆ
ใช้ @es_extended/imports.lua เสมอ
ถ้าไม่ใช้ imports.lua ให้สร้าง object ใหม่ที่มีเฉพาะข้อมูลที่ต้องการส่งไป client

สรุป:

✅ ใช้ @es_extended/imports.lua เสมอ (Auto-filter อัตโนมัติ)
✅ เข้าถึงค่าโดยตรง (xPlayer.name) แทนเรียก function (xPlayer.getName())
✅ Cache ค่าที่ใช้ซ้ำๆ
✅ ประหยัด Performance ได้ 50-95%!

6. Status System (Client-Side)

เกี่ยวกับ Status System

Status System คือระบบจัดการสถานะต่างๆ ของผู้เล่น เช่น ความหิว (hunger) และ ความเครียด (stress) ที่มีการอัพเดตแบบ Real-time

Status System ทำงานเฉพาะฝั่ง Client เท่านั้น เพื่อประสิทธิภาพและความลื่นไหล

✅ อัพเดตทุกๆ วินาที (ตาม config.status.lua)
✅ Sync กับ Server เมื่อมีการเปลี่ยนแปลงสำคัญ
✅ รองรับการ Freeze/Unfreeze

รายละเอียดของ Status System, ฟังก์ชันหลัก, ตัวอย่างการใช้งาน (ดึงข้อมูล, HUD, Event, Freeze, ส่งข้อมูลไป Server) และ Config (config.status.lua) ถูกระบุไว้ในเนื้อหาเดิมด้านล่าง ซึ่งคุณสามารถคัดลอกไปใช้ได้ตามต้องการ (เนื้อหาเต็มประกอบด้วยตัวอย่างโค้ดและ Best Practices สำหรับการใช้งาน status system แบบ client-side)

สรุปหลัก:

ใช้ Event nc:onChangeStatus แทน Loop (ประหยัด Performance)
ใช้ Freeze/Unfreeze เมื่อเปิด Menu หรือ AFK
เช็คสถานะก่อนให้ผู้เล่นทำอะไร

7. Event System (Client-Side)

เกี่ยวกับ Event System

Event System คือระบบ Listener ที่ ฟังการเปลี่ยนแปลง ของค่าต่างๆ ใน NC Core โดยอัตโนมัติ โดยไม่ต้องใช้ Loop ตรวจสอบ

ข้อดีของ Event System:

⚡ ประหยัด Performance - ไม่ต้อง Loop ตรวจสอบทุกวินาที
🎯 ทำงานทันที - เมื่อมีการเปลี่ยนแปลงเท่านั้น
🔄 ทำงานเมื่อรีสคริปต์ - เหมาะสำหรับ Development
✅ เรียกครั้งแรกเสมอ - ไม่ต้องกังวลว่าพลาด

เนื้อหาเกี่ยวกับการใช้งาน ESX.on, ตัวอย่างการใช้ ESX.on('PlayerLoaded') และ ESX.on('PlayerReady'), ตัวอย่าง Initialize HUD/Blips/Markers, Resource Start/Restart, Debug & Logging, เปรียบเทียบ PlayerLoaded vs PlayerReady และ Best Practices ถูกจัดวางเป็นตัวอย่างโค้ดและคำอธิบายในเนื้อหาต้นฉบับที่ส่งมา คุณสามารถนำโค้ดตัวอย่างเหล่านั้นไปใช้หรือปรับแต่งตามความต้องการได้

สรุปสั้นๆ:

ใช้ ESX.on('PlayerLoaded') สำหรับ Init พื้นฐาน
ใช้ ESX.on('PlayerReady') สำหรับเริ่มระบบหนัก
เพิ่ม ['PlayerReady'] = true ใน config/config.functions.lua หากต้องการใช้งาน

Checklist การเพิ่มฟังก์ชัน (ซ้ำ)

Player Class Functions

สร้างไฟล์ใน server/classes/player/functions/yourFunction.lua
Function รับ player เป็น parameter แรก
เขียน comment อธิบายฟังก์ชัน
ทดสอบการทำงาน
✅ ไม่ต้องเพิ่มใน config (โหลดอัตโนมัติ)

Modules

สร้างไฟล์ใน modules/client/ หรือ modules/server/ หรือ modules/shared/
ตั้งชื่อไฟล์เป็น PascalCase (เช่น ShowCustomNotification.lua)
เขียน comment อธิบายฟังก์ชัน
เพิ่มใน config/config.modules.lua
ทดสอบการทำงาน

Functions

สร้างไฟล์ใน functions/client/ หรือ functions/server/ หรือ functions/shared/
ตั้งชื่อไฟล์เป็น PascalCase
เขียน comment อธิบายฟังก์ชัน
เพิ่มใน config/config.functions.lua
ทดสอบการทำงาน

พร้อมใช้งานแล้ว

เลือกหัวข้อที่ต้องใช้ และทดสอบใน resource ของคุณ

PreviousExtending Functions NextExtending Modules

Last updated 48 minutes ago

hashtagExtending Framework

hashtagเลือกแนวทางให้เหมาะกับงาน

hashtagPlayer Class Functions

hashtagModules

hashtagFunctions

hashtagโครงสร้างโฟลเดอร์

hashtagQuick start

hashtagอ่านต่อ (หน้ารายละเอียด)

hashtagหัวข้อที่มักใช้ร่วมกัน

hashtag2. Modules (โมดูลเสริม)

hashtag3. Functions (ฟังก์ชันหลัก)

hashtagสรุปและ Best Practices

hashtag4. Transaction System

hashtag5. Performance Optimization - เรียกค่าโดยตรง

hashtag6. Status System (Client-Side)

hashtag7. Event System (Client-Side)

hashtagChecklist การเพิ่มฟังก์ชัน (ซ้ำ)

Extending Framework

เลือกแนวทางให้เหมาะกับงาน

Player Class Functions

Modules

Functions

โครงสร้างโฟลเดอร์

Quick start

อ่านต่อ (หน้ารายละเอียด)

หัวข้อที่มักใช้ร่วมกัน

2. Modules (โมดูลเสริม)

3. Functions (ฟังก์ชันหลัก)

สรุปและ Best Practices

4. Transaction System

5. Performance Optimization - เรียกค่าโดยตรง

6. Status System (Client-Side)

7. Event System (Client-Side)

Checklist การเพิ่มฟังก์ชัน (ซ้ำ)