Inventory

ฟังก์ชันฝั่ง Server สำหรับจัดการ Item, น้ำหนักกระเป๋า, และข้อจำกัดการถือของของผู้เล่น ผ่าน xPlayer

Inventory (xPlayer)

กลุ่มฟังก์ชันสำหรับจัดการ Item ในกระเป๋าของผู้เล่น รวมถึงระบบน้ำหนัก, limit และการตรวจสอบการถือของ

ใช้งานผ่าน Object ผู้เล่น xPlayer และทำงานฝั่ง Server-side เท่านั้น

ก่อนเริ่ม (แนะนำ)

• แนะนำให้ตั้งค่าการเรียกใช้ Framework ให้ถูกต้องตาม Framework Usage

• ดึง xPlayer จาก source ก่อนเรียกใช้งาน:

local xPlayer = ESX.GetPlayerFromId(source)

ฟังก์ชันในหน้านี้ใช้ได้เฉพาะสคริปต์ฝั่ง Server เท่านั้น

ค่าที่รับมาจาก Client (เช่น itemName, count) ต้องตรวจสอบสิทธิ์และตรวจสอบความถูกต้อง (validate) เสมอ โดยเฉพาะ event ที่เกี่ยวกับการ "เพิ่ม Item" หรือ "ล้างกระเป๋า"

โครงสร้างข้อมูล Item (Item Object)

Item ใน inventory มักมีฟิลด์สำคัญดังนี้:

• name ชื่อ Item (สำหรับอ้างอิงในระบบ)

• label ชื่อแสดง

• count จำนวนที่มี

• weight น้ำหนักต่อชิ้น

• limit จำนวนสูงสุดที่ถือได้ (ต่อ Item)

• rare ความหายาก (แล้วแต่การตั้งค่า)

Inventory เปรียบเหมือน “กระเป๋า” ที่มีข้อจำกัดหลัก 2 แบบ:

• limit ต่อ Item

• น้ำหนักรวมสูงสุด (maxWeight)

---

xPlayer.getInventory

ดึงข้อมูล Item ทั้งหมดในกระเป๋าของผู้เล่น

รูปแบบการใช้งาน (Syntax)

xPlayer.getInventory(minimal)

พารามิเตอร์ (Parameters)

Name	Type	Description
minimal	boolean	(ไม่บังคับ) ถ้าเป็น true จะคืนค่าเป็น {[name] = count}

ค่าที่ส่งคืน (Returns)

Type	Description
table	Array ของ item object หรือ {name = count} เมื่อใช้ minimal = true

ตัวอย่างการใช้งาน (Example)

local xPlayer = ESX.GetPlayerFromId(source)
local inventory = xPlayer.getInventory()

for i = 1, #inventory do
    local item = inventory[i]
    if item.count > 0 then
        print(('%s: %d'):format(item.label, item.count))
    end
end

ตัวอย่างเพิ่มเติม (ขยายดู)

-- ดึงแบบย่อ
local xPlayer = ESX.GetPlayerFromId(source)
local minimal = xPlayer.getInventory(true)

print('bread:', minimal.bread or 0)
print('water:', minimal.water or 0)

-- ส่งข้อมูลไป UI (ตัวอย่าง)
RegisterNetEvent('inventory:open', function()
    local xPlayer = ESX.GetPlayerFromId(source)

    TriggerClientEvent('inventory:show', source, {
        items = xPlayer.getInventory(),
        weight = xPlayer.getWeight(),
        maxWeight = xPlayer.getMaxWeight()
    })
end)

กรณีการใช้งาน (Use cases)

• แสดงรายการ Item ใน UI

• สร้างรายการวัตถุดิบสำหรับ crafting

• ส่งข้อมูล Item ให้ระบบอื่น (เช่น log/analytics)

ใช้ minimal = true เมื่อต้องการข้อมูลแบบเบาและอ่านง่าย

---

xPlayer.getInventoryItem

ดึงข้อมูล Item ตามชื่อที่ระบุ

รูปแบบการใช้งาน (Syntax)

xPlayer.getInventoryItem(name)

พารามิเตอร์ (Parameters)

Name	Type	Description
name	string	ชื่อ Item

ค่าที่ส่งคืน (Returns)

Type	Description
table	item object หรือ nil หากไม่พบ

ตัวอย่างการใช้งาน (Example)

local xPlayer = ESX.GetPlayerFromId(source)
local item = xPlayer.getInventoryItem('bread')

if item and item.count > 0 then
    print(('bread: %d'):format(item.count))
else
    print('ไม่พบ bread ในกระเป๋า')
end

ตัวอย่างเพิ่มเติม (ขยายดู)

{#xplayer-getinventoryitem-more-examples}

-- ตรวจสอบก่อนใช้ Item
RegisterNetEvent('item:use', function(itemName)
    local xPlayer = ESX.GetPlayerFromId(source)
    local item = xPlayer.getInventoryItem(itemName)

    if item and item.count > 0 then
        xPlayer.removeInventoryItem(itemName, 1, 'use item')
        return
    end

    xPlayer.showNotification('คุณไม่มี Item นี้')
end)

กรณีการใช้งาน (Use cases)

• ตรวจสอบจำนวน Item ก่อนทำธุรกรรม

• ใช้ในระบบ crafting / quest / shop

ควรตรวจสอบ item.count > 0 ก่อนใช้งานเสมอ

---

xPlayer.addInventoryItem

เพิ่ม Item ให้ผู้เล่น

รูปแบบการใช้งาน (Syntax)

xPlayer.addInventoryItem(name, count, reason)

พารามิเตอร์ (Parameters)

Name	Type	Description
name	string	ชื่อ Item
count	number	จำนวนที่ต้องการเพิ่ม (ต้องเป็นบวก)
reason	string	(ไม่บังคับ) เหตุผล (ใช้สำหรับ log)

ค่าที่ส่งคืน (Returns)

Type	Description
boolean	true หากสำเร็จ

ตัวอย่างการใช้งาน (Example)

local xPlayer = ESX.GetPlayerFromId(source)
if xPlayer.canCarryItem('bread', 5) then
    xPlayer.addInventoryItem('bread', 5, 'shop purchase')
end

ตัวอย่างเพิ่มเติม (ขยายดู)

{#xplayer-addinventoryitem-more-examples}

-- ซื้อของ (ตัวอย่าง)
RegisterNetEvent('shop:buyItem', function(itemName, count, price)
    local xPlayer = ESX.GetPlayerFromId(source)

    count = tonumber(count) or 0
    price = tonumber(price) or 0
    if count <= 0 or price < 0 then return end

    local total = price * count
    if xPlayer.getMoney() < total then
        return xPlayer.showNotification('เงินไม่พอ')
    end

    if not xPlayer.canCarryItem(itemName, count) then
        return xPlayer.showNotification('กระเป๋าเต็ม')
    end

    xPlayer.removeMoney(total, 'shop purchase')
    xPlayer.addInventoryItem(itemName, count, 'shop purchase')
end)

กรณีการใช้งาน (Use cases)

• ให้ Item จากร้านค้า/รางวัล/กิจกรรม

• ให้ Item ผลลัพธ์จาก crafting

แนะนำให้ตรวจด้วย xPlayer.canCarryItem() ก่อนเพิ่ม Item เสมอ

---

xPlayer.removeInventoryItem

หัก Item ออกจากกระเป๋าผู้เล่น

รูปแบบการใช้งาน (Syntax)

xPlayer.removeInventoryItem(name, count, reason)

พารามิเตอร์ (Parameters)

Name	Type	Description
name	string	ชื่อ Item
count	number	จำนวนที่ต้องการหัก (ต้องเป็นบวก)
reason	string	(ไม่บังคับ) เหตุผล (ใช้สำหรับ log)

ค่าที่ส่งคืน (Returns)

Type	Description
boolean	true หากสำเร็จ

ตัวอย่างการใช้งาน (Example)

local xPlayer = ESX.GetPlayerFromId(source)
local item = xPlayer.getInventoryItem('bread')

if item and item.count >= 1 then
    xPlayer.removeInventoryItem('bread', 1, 'consume')
end

ตัวอย่างเพิ่มเติม (ขยายดู)

{#xplayer-removeinventoryitem-more-examples}

-- หักวัตถุดิบ crafting (ตัวอย่าง)
RegisterNetEvent('crafting:create', function(recipeId)
    local xPlayer = ESX.GetPlayerFromId(source)
    local recipe = Config.Recipes and Config.Recipes[recipeId]
    if not recipe then return end

    for _, ing in ipairs(recipe.ingredients) do
        local it = xPlayer.getInventoryItem(ing.name)
        if not it or it.count < ing.count then
            return xPlayer.showNotification('วัตถุดิบไม่พอ')
        end
    end

    for _, ing in ipairs(recipe.ingredients) do
        xPlayer.removeInventoryItem(ing.name, ing.count, 'crafting')
    end

    if xPlayer.canCarryItem(recipe.result, recipe.resultCount) then
        xPlayer.addInventoryItem(recipe.result, recipe.resultCount, 'crafting')
    end
end)

กรณีการใช้งาน (Use cases)

• ใช้ Item (consume)

• หักวัตถุดิบ

• ขาย/แลกเปลี่ยน

ควรตรวจสอบจำนวนด้วย xPlayer.getInventoryItem() ก่อนหักเสมอ

---

xPlayer.setInventoryItem

กำหนดยอด Item เป็นค่าที่แน่นอน (เขียนทับจำนวนเดิม)

รูปแบบการใช้งาน (Syntax)

xPlayer.setInventoryItem(name, count, reason)

พารามิเตอร์ (Parameters)

Name	Type	Description
name	string	ชื่อ Item
count	number	จำนวนใหม่
reason	string	(ไม่บังคับ) เหตุผล (ใช้สำหรับ log)

ค่าที่ส่งคืน (Returns)

Type	Description
boolean	true หากสำเร็จ

ตัวอย่างการใช้งาน (Example)

local xPlayer = ESX.GetPlayerFromId(source)
xPlayer.setInventoryItem('bread', 10, 'admin fix')

กรณีการใช้งาน (Use cases)

• เครื่องมือแอดมิน (แก้ไข/รีเซ็ตจำนวน Item)

• ซ่อมข้อมูลที่ผิดปกติ

ฟังก์ชันนี้จะ เขียนทับจำนวนเดิมทั้งหมด หากต้องการเพิ่ม/ลด ให้ใช้ xPlayer.addInventoryItem() หรือ xPlayer.removeInventoryItem()

---

xPlayer.hasItem

ตรวจสอบว่าผู้เล่นมี Item หรือไม่ และคืนค่า item พร้อมจำนวน

รูปแบบการใช้งาน (Syntax)

local item, count = xPlayer.hasItem(name)

พารามิเตอร์ (Parameters)

Name	Type	Description
name	string	ชื่อ Item

ค่าที่ส่งคืน (Returns)

Type	Description
table	item object หรือ nil หากไม่พบ
number	จำนวน Item

ตัวอย่างการใช้งาน (Example)

local xPlayer = ESX.GetPlayerFromId(source)
local item, count = xPlayer.hasItem('bread')

if item and count > 0 then
    print(('bread: %d'):format(count))
end

กรณีการใช้งาน (Use cases)

• ตรวจสอบเงื่อนไข quest/mission

• ตรวจสอบก่อนเข้าโซนพิเศษ

xPlayer.hasItem() เหมาะกับกรณีที่ต้องการ “item + count” ทันทีในบรรทัดเดียว

---

xPlayer.canCarryItem

ตรวจสอบว่าสามารถเพิ่ม Item ได้หรือไม่ โดยพิจารณาทั้ง limit และ maxWeight

รูปแบบการใช้งาน (Syntax)

xPlayer.canCarryItem(name, count)

พารามิเตอร์ (Parameters)

Name	Type	Description
name	string	ชื่อ Item
count	number	จำนวนที่ต้องการตรวจสอบ

ค่าที่ส่งคืน (Returns)

Type	Description
boolean	true หากสามารถถือได้

ตัวอย่างการใช้งาน (Example)

local xPlayer = ESX.GetPlayerFromId(source)
if xPlayer.canCarryItem('water', 2) then
    xPlayer.addInventoryItem('water', 2, 'reward')
end

กรณีการใช้งาน (Use cases)

• ตรวจสอบก่อนให้ของรางวัล

• ตรวจสอบก่อนซื้อของ/เก็บของจากพื้น/loot

ฟังก์ชันนี้ตรวจสอบทั้ง limit และน้ำหนักรวม (maxWeight)

---

xPlayer.canSwapItem

ตรวจสอบว่าสามารถ "หัก Item A" แล้ว "เพิ่ม Item B" ได้หรือไม่ ในธุรกรรมเดียว

รูปแบบการใช้งาน (Syntax)

xPlayer.canSwapItem(name, count, testName, testCount)

พารามิเตอร์ (Parameters)

Name	Type	Description
name	string	ชื่อ Item ที่จะหัก
nameCount	number	จำนวนที่จะหัก
testName	string	ชื่อ Item ที่จะเพิ่ม
testCount	number	จำนวนที่จะเพิ่ม

ค่าที่ส่งคืน (Returns)

Type	Description
boolean	true หาก swap ได้

ตัวอย่างการใช้งาน (Example)

local xPlayer = ESX.GetPlayerFromId(source)
if xPlayer.canSwapItem('water', 1, 'bread', 2) then
    xPlayer.removeInventoryItem('water', 1, 'exchange')
    xPlayer.addInventoryItem('bread', 2, 'exchange')
end

กรณีการใช้งาน (Use cases)

• crafting (หักวัตถุดิบ + เพิ่มผลลัพธ์)

• แลกเปลี่ยนสินค้า/อัปเกรด Item

ช่วยลดงานคำนวณน้ำหนัก/limit เองก่อนทำการแลกเปลี่ยน

---

xPlayer.clearInventory

ลบ Item ทั้งหมดในกระเป๋า และรีเซ็ตน้ำหนัก

รูปแบบการใช้งาน (Syntax)

xPlayer.clearInventory(reason)

พารามิเตอร์ (Parameters)

Name	Type	Description
reason	string	(ไม่บังคับ) เหตุผล (ใช้สำหรับ log)

ค่าที่ส่งคืน (Returns)

Type	Description
boolean	true หากสำเร็จ

ตัวอย่างการใช้งาน (Example)

local xPlayer = ESX.GetPlayerFromId(source)
xPlayer.clearInventory('admin reset')

กรณีการใช้งาน (Use cases)

• ลงโทษ/รีเซ็ตกระเป๋า

• ระบบ character wipe

• โหมด hardcore (ตายแล้วเสียของ)

ฟังก์ชันนี้จะ ลบของทั้งหมด ในกระเป๋า ควรทำ confirmation และตรวจสอบสิทธิ์ก่อนใช้งานเสมอ

---

xPlayer.getWeight

อ่านน้ำหนักกระเป๋าปัจจุบันของผู้เล่น

รูปแบบการใช้งาน (Syntax)

xPlayer.getWeight()

ค่าที่ส่งคืน (Returns)

Type	Description
number	น้ำหนักปัจจุบัน

ตัวอย่างการใช้งาน (Example)

local xPlayer = ESX.GetPlayerFromId(source)
print(('weight: %s / %s'):format(xPlayer.getWeight(), xPlayer.getMaxWeight()))

กรณีการใช้งาน (Use cases)

• แสดงน้ำหนักใน UI

• คำนวณพื้นที่ว่าง

น้ำหนักจะอัปเดตอัตโนมัติเมื่อมีการเพิ่ม/ลด Item

---

xPlayer.getMaxWeight

อ่านน้ำหนักสูงสุดที่ผู้เล่นสามารถถือได้

รูปแบบการใช้งาน (Syntax)

xPlayer.getMaxWeight()

ค่าที่ส่งคืน (Returns)

Type	Description
number	น้ำหนักสูงสุด

ตัวอย่างการใช้งาน (Example)

local xPlayer = ESX.GetPlayerFromId(source)
local space = xPlayer.getMaxWeight() - xPlayer.getWeight()
print(('free space: %s'):format(space))

กรณีการใช้งาน (Use cases)

• UI แสดง max weight

• ระบบ backpack / VIP

---

xPlayer.setMaxWeight

ตั้งค่าน้ำหนักสูงสุดของผู้เล่น

รูปแบบการใช้งาน (Syntax)

xPlayer.setMaxWeight(maxWeight)

พารามิเตอร์ (Parameters)

Name	Type	Description
maxWeight	number	น้ำหนักสูงสุดใหม่

ค่าที่ส่งคืน (Returns)

Type	Description
boolean	true หากสำเร็จ

ตัวอย่างการใช้งาน (Example)

local xPlayer = ESX.GetPlayerFromId(source)
xPlayer.setMaxWeight(100)

ตัวอย่างเพิ่มเติม (ขยายดู)

{#xplayer-setmaxweight-more-examples}

-- VIP ตั้งน้ำหนักสูงสุด (ตัวอย่าง)
RegisterNetEvent('vip:activate', function(vipType)
    local xPlayer = ESX.GetPlayerFromId(source)

    local weights = {
        vip = 75,
        vvip = 100,
        mvp = 150
    }

    local w = weights[vipType]
    if not w then return end

    xPlayer.setMaxWeight(w)
    xPlayer.showNotification(('ปรับน้ำหนักสูงสุดเป็น %d'):format(w))
end)

กรณีการใช้งาน (Use cases)

• ระบบ backpack / item เพิ่มช่องกระเป๋า

• ระบบ VIP

• เครื่องมือแอดมิน

การเปลี่ยน maxWeight ไม่ได้บังคับให้ทิ้งของทันที หากน้ำหนักปัจจุบันเกินค่าใหม่ หากต้องการบังคับใช้กติกา ให้เพิ่มตรรกะ (logic) ในระบบของคุณ

---

สรุปฟังก์ชันใน Inventory

ฟังก์ชันต่อไปนี้เป็น method บน xPlayer

Function	Description	Use Case
getInventory()	ดึง Item ทั้งหมด	แสดงใน UI
getInventoryItem()	ดึง Item ที่ระบุ	ตรวจสอบ Item
addInventoryItem()	เพิ่ม Item	ให้รางวัล, ซื้อของ
removeInventoryItem()	หัก Item	ใช้ Item, Crafting
setInventoryItem()	ตั้งจำนวน Item	Admin Tools
hasItem()	ตรวจสอบมี Item ไหม	Quest, เงื่อนไข
canCarryItem()	เช็คว่าเก็บได้ไหม	ก่อนให้ Item
canSwapItem()	เช็คแลกได้ไหม	Crafting, Trade
clearInventory()	ลบของทั้งหมด	Reset, Punishment
getWeight()	ดูน้ำหนักปัจจุบัน	แสดง UI
getMaxWeight()	ดูน้ำหนักสูงสุด	คำนวณพื้นที่
setMaxWeight()	ตั้งน้ำหนักสูงสุด	VIP, Backpack

---

แนวทางสำหรับนักพัฒนา

1

ตรวจสอบก่อนเพิ่ม

ใช้ xPlayer.canCarryItem() ก่อน xPlayer.addInventoryItem() เพื่อป้องกันการเพิ่ม Item เมื่อกระเป๋าเต็มหรือเกิน limit

2

ตรวจสอบจำนวน

ใช้ xPlayer.getInventoryItem() เพื่อตรวจจำนวนก่อนหักหรือใช้งาน Item

3

ระบุ Reason

ระบุ reason เมื่อมีการเปลี่ยนแปลง Item เพื่อช่วยตรวจสอบ log และ debug

4

ระวังน้ำหนัก

Item ที่น้ำหนักสูงจะทำให้กระเป๋าเต็มเร็ว ควรตรวจสอบน้ำหนักก่อนให้/รับ Item

5

Validate Input

ตรวจสอบ input ก่อนเปลี่ยนแปลงกระเป๋าเสมอ (ชนิดข้อมูล, ค่าเป็นบวก, รายการที่อนุญาต (allowlist) ของ Item)

6

Sync Client

ระบบจะ sync ไปที่ client อัตโนมัติ แต่ควรออกแบบ event ให้สอดคล้องกับการเปลี่ยนแปลงบน server

การทำงานของระบบน้ำหนัก:

• น้ำหนักรวม = ผลรวมของ (จำนวน Item × น้ำหนักต่อชิ้น)

• ถ้าน้ำหนักรวม > maxWeight จะไม่สามารถเพิ่ม Item ได้

• แต่ละ Item มี limit จำกัดจำนวนที่เก็บได้ และ xPlayer.canCarryItem() จะตรวจทั้ง weight และ limit