Extending Modules

แนวทางสร้าง Modules ฝั่ง Client/Server/Shared พร้อมการเปิดใช้งานผ่าน config และตัวอย่างการเรียกใช้

Extending Modules

Modules คือฟังก์ชันเสริมของ NC Core ที่ทำงานแบบแยกไฟล์

เหมาะสำหรับ utility หรือฟังก์ชันที่ต้องเรียกซ้ำหลายจุด และต้องการควบคุมการโหลดผ่าน config

ข้อกำหนด

• สร้างได้ทั้งฝั่ง Client/Server/Shared

• ต้องเปิดใช้งานใน config/config.modules.lua

• แนะนำให้เขียนแบบ “ทำหน้าที่เดียว” และรับพารามิเตอร์ชัดเจน

ตำแหน่งไฟล์

• modules/client/

• modules/server/

• modules/shared/

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

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

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

1

สร้างไฟล์ Module

ตัวอย่าง Client Module

ไฟล์: modules/client/ShowCustomNotification.lua

-- ========================================
-- Module: ShowCustomNotification
-- คำอธิบาย: แสดงการแจ้งเตือนแบบกำหนดเอง
-- Parameters:
--   @param options (table) - {type, title, message, duration}
--        - type: 'success', 'error', 'warning', 'info'
--        - title: หัวข้อ
--        - message: ข้อความ
--        - duration: ระยะเวลา (milliseconds)
-- ========================================
return function(options)
    -- ตรวจสอบ parameter
    if type(options) ~= 'table' then
        print('[ERROR] ShowCustomNotification: options must be a table')
        return
    end
    
    -- ค่า default
    local notifType = options.type or 'info'
    local title = options.title or 'แจ้งเตือน'
    local message = options.message or ''
    local duration = options.duration or 5000
    
    -- สี HUD ตามประเภท
    local colors = {
        success = {r = 46, g = 204, b = 113},   -- เขียว
        error = {r = 231, g = 76, b = 60},      -- แดง
        warning = {r = 241, g = 196, b = 15},   -- เหลือง
        info = {r = 52, g = 152, b = 219}       -- น้ำเงิน
    }
    
    local color = colors[notifType] or colors.info
    
    -- แสดง Notification ด้วย Native
    BeginTextCommandThefeedPost('STRING')
    AddTextComponentSubstringPlayerName(message)
    SetNotificationBackgroundColor(color.r)
    SetNotificationTextEntry('STRING')
    ThefeedSetNextPostBackgroundColor(color.r)
    EndTextCommandThefeedPostTicker(false, true)
    
    -- แสดงบน Chat (สำหรับ record)
    TriggerEvent('chat:addMessage', {
        color = {color.r, color.g, color.b},
        multiline = true,
        args = {title, message}
    })
    
    -- เล่นเสียง
    PlaySoundFrontend(-1, 'CHECKPOINT_PERFECT', 'HUD_MINI_GAME_SOUNDSET', true)
end

2

ระบุใน Config

ไฟล์: config/config.modules.lua

Config.Modules.Client = {
    -- Modules เดิม...
    ['ShowNotification'] = true,
    ['ShowAdvancedNotification'] = true,
    
    -- เพิ่ม Module ใหม่
    ['ShowCustomNotification'] = true,
}

3

ใช้งาน

-- ใช้งานใน resource อื่นๆ (client-side)

-- แจ้งเตือนสำเร็จ
ESX.ShowCustomNotification({
    type = 'success',
    title = 'สำเร็จ',
    message = 'ซื้อสินค้าเรียบร้อยแล้ว',
    duration = 5000
})

-- แจ้งเตือนข้อผิดพลาด
ESX.ShowCustomNotification({
    type = 'error',
    title = 'ผิดพลาด',
    message = 'เงินไม่พอสำหรับการซื้อ',
    duration = 3000
})

-- แจ้งเตือนคำเตือน
ESX.ShowCustomNotification({
    type = 'warning',
    title = 'คำเตือน',
    message = 'HP ของคุณเหลือน้อย!',
    duration = 4000
})

-- แจ้งเตือนข้อมูล
ESX.ShowCustomNotification({
    type = 'info',
    title = 'ข้อมูล',
    message = 'ยินดีต้อนรับสู่เซิร์ฟเวอร์',
    duration = 6000
})

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

-- ส่งข้อความถึงช่างทั้งหมด
ESX.BroadcastToJob('mechanic', 'มีลูกค้ารอที่อู่ซ่อม')

-- ตัวอย่างใช้กับระบบเรียกตำรวจ
RegisterNetEvent('dispatch:callPolice', function(location, reason)
    local xPlayer = ESX.GetPlayerFromId(source)
    
    local message = string.format('%s เรียกตำรวจ: %s (พิกัด: %s)', 
        xPlayer.getName(), reason, location)
    
    local count = ESX.BroadcastToJob('police', message)
    
    if count > 0 then
        xPlayer.showNotification('~g~เรียกตำรวจสำเร็จ!')
    else
        xPlayer.showNotification('~r~ไม่มีตำรวจออนไลน์')
    end
end)

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

-- Server: ตรวจสอบระยะระหว่างผู้เล่น 2 คน
RegisterNetEvent('trade:request', function(targetId)
    local xPlayer = ESX.GetPlayerFromId(source)
    local xTarget = ESX.GetPlayerFromId(targetId)
    
    local playerCoords = xPlayer.getCoords(true)
    local targetCoords = xTarget.getCoords(true)
    
    local distance = ESX.CalculateDistance3D(playerCoords, targetCoords)
    
    if distance <= 3.0 then
        -- เริ่มแลกเปลี่ยน
    else
        xPlayer.showNotification(string.format('~r~อยู่ไกลเกินไป! (%.1fm)', distance))
    end
end)

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

การตั้งชื่อ

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

-- ✅ ดี
function ShowCustomNotification()
function BroadcastToJob()
function CalculateDistance3D()

การจัดการ Config

-- ✅ ดี: แยก Client/Server/Shared ชัดเจน
Config.Modules.Client = {
    ['ShowCustomNotification'] = true,
}

Config.Modules.Server = {
    ['BroadcastToJob'] = true,
}

Config.Modules.Shared = {
    ['CalculateDistance3D'] = true,
}

การตรวจสอบพารามิเตอร์

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

Checklist การเพิ่ม Module

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

• ตั้งชื่อไฟล์เป็น PascalCase (เช่น ShowCustomNotification.lua)

• ระบุพารามิเตอร์/ค่าที่คืนกลับใน comment ให้ครบ

• เพิ่มรายการเปิดใช้งานใน config/config.modules.lua

Config.Modules.Client = {
    ['YourModuleName'] = true,
}

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

สรุป

Modules เหมาะสำหรับ:

• ฟังก์ชันเสริมที่ไม่เกี่ยวกับผู้เล่นโดยตรง

• เป็น utility ทั่วไป

• ต้องการเปิด/ปิดได้ผ่าน config

ตัวอย่าง: ESX.ShowCustomNotification(), ESX.BroadcastToJob(), ESX.CalculateDistance3D()

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