🛠️ zobyeteam_wrapper

เขียนสคริปต์ FiveM ครั้งเดียว รันได้ทุกระบบ!
zobyeteam_wrapper คือเครื่องมือประเภท Abstraction Layer (ตัวกลางเชื่อมต่อ) แบบ Open Source สำหรับนักพัฒนา FiveM ที่ต้องการให้สคริปต์ของตัวเองรองรับการทำงานกับเซิร์ฟเวอร์ทั้ง ESX และ QBCore ได้พร้อมกัน โดยไม่ต้องแก้ไขโค้ดสำหรับแต่ละ Framework แยกกันให้ปวดหัว!

---

🎯 ทำไมสคริปต์นี้ถึงช่วยชีวิตนักพัฒนา?

ปกติแล้วหากคุณเป็นคนเขียนสคริปต์ขายหรือต้องการปล่อยฟรีในชุมชน FiveM ปัญหาหลักคือลูกค้าหรือผู้ใช้อาจใช้ Framework ที่แตกต่างกัน:

• กลุ่มหนึ่งใช้ ESX (บางคนใช้เวอร์ชันใหม่ บางคนใช้เวอร์ชันเก่าแบบ legacy)
• อีกกลุ่มหนึ่งใช้ QBCore

การต้องมานั่งสร้างโค้ดแยกสาขา (Branch) หรือใส่เงื่อนไขดึงข้อมูลผู้เล่นสลับไปมาทำให้นักพัฒนาปวดหัวและดูแลรักษาโค้ดได้ยาก
zobyeteam_wrapper เข้ามาทำหน้าที่เป็นสะพานเชื่อม ปรับความสามารถและชุดคำสั่ง (API) ของทุก Framework ให้เป็นรูปแบบมาตรฐานเดียวกันหมด ทำให้คุณเขียนสคริปต์ได้สนุกและจบงานได้เร็วขึ้นอย่างมาก!

---

✨ ฟีเจอร์หลัก (Features)

• 🔍 Auto-detection: ตรวจจับว่าเซิร์ฟเวอร์ใช้งาน Framework อะไรอยู่โดยอัตโนมัติ ไม่จำเป็นต้องสลับค่าสวิตช์เปิดปิด
• 💼 Unified Player API: จัดระบบคำสั่งดึงข้อมูลตัวละคร (เงิน, ไอเทม, งาน, ข้อมูลประจำตัว) ให้อยู่ภายใต้ API เดียวกัน
• 📡 Promise-based Callback System (RPC): ระบบส่ง-รับข้อมูลระหว่าง Client และ Server ที่ใช้ง่ายที่สุด ทำงานแบบ Promise/Await ไม่พึ่งพาฟังก์ชันภายนอก
• 🔌 Zero-configuration: ติดตั้ง ปล่อยรัน แล้วเรียกใช้ได้เลยทันที ไม่ยุ่งยาก
• 🔄 Support Legacy & Modern ESX: รองรับการโหลด Shared Object ของ ESX ทั้งเวอร์ชันดั้งเดิม (Event-based) และเวอร์ชันใหม่ (Export-based)

---

📦 วิธีการติดตั้งสำหรับเซิร์ฟเวอร์

1. ดาวน์โหลดและคัดลอกโฟลเดอร์ zobyeteam_wrapper ไปวางในโฟลเดอร์ resources/ ของเซิร์ฟเวอร์คุณ
2. เปิดไฟล์ server.cfg แล้วใส่คำสั่งสำหรับเปิดสคริปต์:

   ensure zobyeteam_wrapper

   (⚠️ ข้อสำคัญ: ต้องเรียกใช้ zobyeteam_wrapper ก่อนสคริปต์อื่น ๆ ที่จะใช้ Library นี้)
3. ตั้งค่าชื่อโฟลเดอร์ Framework หากต้องการในไฟล์ config.lua

---

⚙️ การตั้งค่า (config.lua)

ตัวแปร	ค่าเริ่มต้น	คำอธิบาย
Config.ESXResourceName	'es_extended'	ชื่อทรัพยากรหลักของ ESX
Config.QBCoreResourceName	'qb-core'	ชื่อทรัพยากรหลักของ QBCore
Config.UseESXImportVersion	true	true = โหลดด้วย exports[...]:getSharedObject(), false = ใช้ Event ดั้งเดิม
Config.ESXEvents	{ getSharedObject = 'esx:getSharedObject' }	แผนที่ Event สำหรับการดึง Shared Object ของ ESX
Config.AutoFrameworkDetected	true	ค้นหาและตั้งค่าตามระบบที่เปิดใช้งานในเซิร์ฟเวอร์ทันที
Config.FrameworkUsing	'esx'	เลือกบังคับใช้ Framework (จะทำงานเมื่อปิด AutoFrameworkDetected) เลือกระหว่าง 'esx' หรือ 'qbcore'

---

🚀 วิธีนำไปเชื่อมต่อกับสคริปต์ของคุณ (Integration Guide)

หากต้องการนำไปเป็น Dependency ในสคริปต์ของคุณ สามารถประกาศตัวแปรเพื่อใช้งาน Wrapper ได้สองวิธี:

1. เรียกผ่าน global table ZBT (แนะนำที่สุด 👍)

เมื่อรันสคริปต์ ตัวแปร ZBT จะถูกสร้างเป็น Global Table ให้เรียกใช้ได้ทันทีจากสคริปต์ใดๆ บนตัวเซิร์ฟเวอร์:

-- เรียกใช้ฟังก์ชันผ่าน ZBT ได้เลยโดยไม่ต้องประกาศ export ใหม่
ZBT.Callback.Await('getSomething')

2. เรียกรับ Library ผ่าน Exports

หากสคริปต์ของคุณต้องการเรียกใช้งานในรูปแบบ Local สามารถดึง library มาเก็บไว้ได้ดังนี้:

local ZBT = exports.zobyeteam_wrapper:GetLib()

---

💻 ตัวอย่างการเขียนโค้ด (Code Examples)

การจัดการผู้เล่นฝั่ง Server-side (Server Exports)

-- ค้นหาและสร้าง Object ผู้เล่นขึ้นมาจัดการ
local player = exports.zobyeteam_wrapper:GetPlayer(source)

-- ➕ การเพิ่มไอเทม
player.AddItem('bread', 5) -- เพิ่มขนมปัง 5 ชิ้น

-- ➖ การลบไอเทม
player.RemoveItem('water', 1) -- ลบน้ำออก 1 ชิ้น

-- 💵 การเพิ่มเงิน
player.AddMoney('bank', 1000) -- เพิ่มเงินเข้าธนาคาร $1,000

-- 💸 การหักเงิน
player.RemoveMoney('cash', 500) -- หักเงินสด $500

-- 💰 ตรวจสอบยอดเงินในบัญชี
local balance = player.GetAccount('bank')

-- 💼 ดึงข้อมูลอาชีพปัจจุบันของผู้เล่น (จะคืนข้อมูลเป็น Table)
local job = player.GetJob()
print("ชื่ออาชีพ: " .. job.name .. " | ตำแหน่งงาน: " .. job.grade_name)

-- 🆔 ดึงรหัสประจำตัว (Identifier / citizenid)
local identifier = player.GetIdentifier()

การดึงข้อมูลฝั่ง Client-side (Client Exports)

-- ดึงเงินในกระเป๋า/บัญชีของผู้เล่นที่กำลังเล่นอยู่
local cash = exports.zobyeteam_wrapper:GetPlayerAccount('money')

-- ดึงป้ายแสดงชื่อของไอเทม (Item Label) เช่น bread -> ขนมปัง
local label = exports.zobyeteam_wrapper:GetItemLabel('bread')

-- ดึงข้อมูลอาชีพปัจจุบันของผู้เล่น
local job = exports.zobyeteam_wrapper:GetPlayerJob()

-- ดึงชื่อแสดงตัวละครในเกม
local name = exports.zobyeteam_wrapper:GetPlayerName()

ระบบเรียกรับข้อมูลแบบทันที (Callback RPC)

ฝั่ง Server (ลงทะเบียน Callback):

exports.zobyeteam_wrapper:CallbackRegister('getUserMoney', function(playerId)
    local player = exports.zobyeteam_wrapper:GetPlayer(playerId)
    return player.GetAccount('bank')
end)

ฝั่ง Client (ดึงข้อมูลมาใช้งาน):

local ZBT = exports.zobyeteam_wrapper:GetLib()

-- ใช้คำสั่ง Await โค้ดจะหยุดรอข้อมูลจาก Server โดยไม่ทำลาย Thread
local bankMoney = ZBT.Callback.Await('getUserMoney')
print("ยอดเงินธนาคารคือ: " .. bankMoney)

---

📊 ตารางการรองรับระบบ (Compatibility)

Framework	ระบบดึงข้อมูล	สถานะการทำงาน
ESX (Modern)	Export (exports.es_extended:getSharedObject())	✅ เสถียรพร้อมใช้
ESX (Legacy)	Event (TriggerEvent('esx:getSharedObject', ...))	✅ เสถียรพร้อมใช้
QBCore	Standard Resource API (qb-core)	✅ เสถียรพร้อมใช้

---

🤝 การมีส่วนร่วมพัฒนา (Contributing)

ยินดีต้อนรับนักพัฒนาทุกท่านมาร่วมสร้างสรรค์สคริปต์นี้ให้ครอบคลุมยิ่งขึ้น! คุณสามารถช่วยเหลือพวกเราได้หลายวิธี:

1. รายงานปัญหา (Bug Report): หากพบข้อผิดพลาดขณะรันกับสคริปต์ของคุณ สามารถเปิด Issue ชี้แจงรายละเอียดพร้อมแนบ Log ข้อผิดพลาดได้ตลอดเวลา
2. ส่ง Pull Request (PR): หากคุณอยากเพิ่มความสามารถใหม่ ๆ หรือปรับปรุงระบบ เช่น:
   • เพิ่มการรองรับ Framework อื่น ๆ (เช่น Ox Core, VRP, หรือ ND Framework)
   • ปรับแต่งชุดคำสั่งจัดการสิ่งของ/เงินให้ยืดหยุ่นขึ้น
3. ส่งคำเสนอแนะ: ร่วมพูดคุย แนะนำฟังก์ชันหรือแนวทางใหม่ ๆ ที่อยากให้มีในโปรเจกต์นี้

---

📄 สัญญาอนุญาต (License)

โปรเจกต์นี้เผยแพร่ภายใต้สัญญาอนุญาต MIT License
นั่นหมายความว่าคุณมีสิทธิ์เต็มที่ในการนำไปประยุกต์ใช้, แก้ไขดัดแปลง, ทำซ้ำ หรือแจกจ่ายต่อร่วมกับสคริปต์ของคุณเองได้อย่างอิสระ ไม่ว่าจะนำไปใช้ในสคริปต์ฟรีหรือสคริปต์เชิงพาณิชย์ก็ตาม!

---

ℹ️ ข้อมูลทีมพัฒนา

• 👨‍💻 ผู้พัฒนา: ZOBYETEAM (TAK)
• 🎮 เกม: Grand Theft Auto V (FiveM Platform)
• 📧 ติดต่อ: [ZOBYETEAM Official] หรือทาง GitHub Repository