Extending Player Class

แนวทางเพิ่ม Methods ให้ xPlayer (Server-side) ด้วย Player Class Functions พร้อมตัวอย่างและแนวปฏิบัติที่แนะนำ

Extending Player Class Functions

Player Class Functions คือ Methods ที่เพิ่มให้ xPlayer โดยตรง

สามารถใช้งานได้เฉพาะฝั่ง Server และถูกออกแบบให้โหลดอัตโนมัติ

ตำแหน่งไฟล์

• server/classes/player/functions/

การโหลด

• โหลดอัตโนมัติเมื่อเริ่ม resource

• ไม่ต้องเปิดใช้งานผ่าน config

---

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

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

Function ต้องรับ player (xPlayer) เป็นพารามิเตอร์ตัวแรกเสมอ เพื่อให้เรียกใช้ผ่าน xPlayer.yourFunction(...) ได้

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

1

สร้างไฟล์ในโฟลเดอร์ Player Class

สร้างไฟล์ใน server/classes/player/functions/

ตั้งชื่อไฟล์ให้ตรงกับชื่อ Method ที่จะเรียก (เช่น addExperience.lua)

2

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

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

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

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

• ค่าที่ return

3

เรียกใช้ผ่าน xPlayer และทดสอบ

เรียกใช้จาก resource อื่นแบบ server-side

ตรวจสอบ error log และกรณี input ผิด

ตัวอย่าง: เพิ่มแต้มประสบการณ์ (addExperience)

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

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)

---

ตัวอย่าง: ตรวจสอบระยะห่าง (isNearPlayer)

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

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)

---

ตัวอย่าง: จัดการสกิล (addSkillExp / getSkillLevel)

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

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

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)

---

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

การตั้งชื่อ

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

-- ✅ ดี
function addExperience()
function isNearPlayer()
function getSkillLevel()

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

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

การ return ค่า

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

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

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

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

---

Checklist การเพิ่ม Player Class Function

• สร้างไฟล์ใน server/classes/player/functions/yourFunction.lua

• Function รับ player เป็น parameter แรก

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

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

• ไม่ต้องเพิ่มใน config (โหลดอัตโนมัติ)

---

สรุป

Player Class Functions เหมาะสำหรับ:

• ต้องการเพิ่มเมธอดให้ xPlayer

• ทำงานเฉพาะผู้เล่นคนเดียว

• ต้องการเรียกใช้แบบ xPlayer.yourFunction()

ตัวอย่าง: xPlayer.addExperience(), xPlayer.isNearPlayer(), xPlayer.getSkillLevel()

เพิ่ม Player Class Function เรียบร้อยแล้ว

หากเรียกใช้งานไม่เจอ ให้ตรวจตำแหน่งไฟล์และชื่อไฟล์ก่อน