Коротко
Зберігайте предмети кожного гравця в таблиці на сервері, усередині ModuleScript у ServerScriptService, і лише цей код може додавати, прибирати й складати їх у стаки. Опишіть предмети один раз у ModuleScript у ReplicatedStorage (id, назва, максимальний стак). Після кожної зміни сервер надсилає цьому гравцеві RemoteEvent з копією його інвентарю, а LocalScript малює його сіткою через ScrollingFrame і UIGridLayout.
- Клієнт ніколи не додає предмети. Він може лише попросити, наприклад "екіпіруй мій меч", і сервер перевіряє, що гравець його має, перш ніж щось робити.
- Предмети з'являються лише через серверний код, який ви контролюєте: підбирання, покупки в магазині після перевірки на сервері, нагороди.
- Зберігайте id предметів та їхню кількість, а не Tool, через DataStoreService, коли гравець виходить, коли сервер вимикається і раз на кілька хвилин. Ніколи не зберігайте гравця, чиї дані не завантажилися.
На цій сторінці
Як влаштований інвентар
Система складається з шести маленьких частин, у кожної одне завдання. Усі правила про предмети живуть в одному серверному модулі, тому коли щось ламається, шукати треба рівно в одному місці.
| Частина | Тип і місце | Завдання |
|---|---|---|
ItemCatalog | ModuleScript у ReplicatedStorage | Що являє собою кожен предмет: назва, опис, максимальний стак і чи можна його екіпірувати або використати. Його читають сервер і всі клієнти. |
InventoryService | ModuleScript у ServerScriptService | Зберігає слоти всіх гравців. Єдиний код, який додає, прибирає й складає предмети в стаки. |
InventoryData | Script у ServerScriptService | Завантажує предмети гравця під час входу і зберігає їх. |
InventoryActions | Script у ServerScriptService | Перевіряє і виконує запити на екіпірування та використання. |
ItemPickup | Script усередині Part | Видає предмет тому, хто його підібрав. |
InventoryClient | LocalScript у StarterPlayerScripts | Малює сітку і надсилає запити. Сам нічого не змінює. |
Дані йдуть в один бік. Сервер змінює інвентар, потім надсилає цьому гравцеві InventoryUpdated з усім інвентарем, і клієнт перемальовує його. Коли гравець клікає по слоту, клієнт надсилає EquipItem або UseItem з id предмета; сервер перевіряє запит, вносить зміну, і нова копія приходить тим самим шляхом. Надсилати весь інвентар простіше, ніж надсилати зміни, а для кількох десятків слотів повідомлення залишається маленьким.
Чому клієнт ніколи не додає предмети
Хочеться додати предмет просто в LocalScript, який його показує: гравець клікнув, слот заповнився. Це ламається двома способами.
- Ніхто інший цього не бачить. Зміна в LocalScript існує лише на пристрої цього гравця. Сервер про неї не дізнається, тому вона не зберігається, і жоден серверний скрипт не може її використати.
- Підробити може будь-хто. Якщо полагодити це ремоутом на кшталт
AddItem(itemId, amount), чітер зможе сам викликати цей івент, з будь-якими аргументами і скільки завгодно разів. У гайді Roblox з безпеки сказано, що сервер має перевіряти все, що надсилає клієнт, перш ніж це використовувати.
Тому в цьому гайді клієнт може лише просити щось зробити з предметами, які гравець уже має: "екіпіруй це" і "використай це". У кожному запиті один id предмета і жодних кількостей, і на сервері він проходить одну перевірку: це рядок, такий предмет існує, гравець має хоча б один, і гравець надсилає не більше чотирьох запитів на секунду. Потім сервер сам знаходить Tool за каталогом. Він ніколи не приймає від клієнта Tool, шлях чи інстанс, про що попереджає той самий гайд.
Предмети потрапляють в інвентар лише через серверний код: підбирання, яке перевірив сервер, покупку, за яку сервер списав гроші (її збирає гайд із магазину), нагороду за квест або дроп. Про ремоути загалом, з перевіркою інших видів аргументів, читайте в гайді з RemoteEvent.
Крок 1: підготуйте Explorer
Створіть ці об'єкти вручну. Скрипти з наступних кроків шукають їх за ім'ям, тому пишіть кожне ім'я точно як тут.
- У ReplicatedStorage вставте Folder з ім'ям
InventoryRemotes. Усередину вставте три RemoteEvent з іменамиInventoryUpdated,EquipItemіUseItem. - У ServerStorage вставте Folder з ім'ям
ItemTools. Усередину вставте Tool з ім'ямSword, а в Tool Part з ім'ямHandle(1 на 4 на 1 стад цілком підійде). Перевірте, що позначку Anchored у Handle знято: Roblox попереджає, що персонаж застрягає на місці, якщо тримає інструмент з анкерними партами. Підійде і Tool, який у вас уже є, якщо його ім'я збігається з каталогом із кроку 2. - Додавайте скрипти в міру проходження кроків. Дерево показує, куди йде кожен із них.
ReplicatedStorage
ItemCatalog ModuleScript new
InventoryRemotes Folder new
InventoryUpdated RemoteEvent new
EquipItem RemoteEvent new
UseItem RemoteEvent new
ServerScriptService
InventoryService ModuleScript new
InventoryData Script new
InventoryActions Script new
ServerStorage
ItemTools Folder new
Sword Tool new
Handle Part new
StarterPlayer
StarterPlayerScripts
InventoryClient LocalScript new
Workspace
Apple Part new
ItemPickup Script new
Крок 2: опишіть предмети в каталозі
Каталог описує кожен предмет, який може існувати, один раз. Інвентарі потім зберігають лише id предмета і кількість. Так збереження залишаються маленькими, і пізніше можна перейменувати предмет або переписати його опис, не чіпаючи нічиїх збережених даних.
Вставте ModuleScript у ReplicatedStorage, назвіть його ItemCatalog і замініть його вміст на це:
-- Усі предмети, які можуть бути в грі. Цей список читають сервер і всі
-- клієнти; лише сервер вирішує, у кого що є.
export type Item = {
id: string, -- має збігатися з ключем нижче
name: string,
description: string,
maxStack: number, -- скільки цього предмета вміщується в один слот
icon: string?, -- необов'язкова картинка: "rbxassetid://" плюс ID вашого зображення
toolName: string?, -- Tool у ServerStorage.ItemTools: предмет можна екіпірувати
heal: number?, -- скільки здоров'я відновлює: предмет витратний
}
local items: { [string]: Item } = {
sword = {
id = "sword",
name = "Sword",
description = "Equip it to put it in your hand.",
maxStack = 1,
toolName = "Sword",
},
apple = {
id = "apple",
name = "Apple",
description = "Use it to restore 25 health.",
maxStack = 10,
heal = 25,
},
wood = {
id = "wood",
name = "Wood",
description = "A building material.",
maxStack = 50,
},
}
local ItemCatalog = {}
-- Повертає предмет із цим id або nil, якщо такого предмета немає
function ItemCatalog.get(id: string): Item?
return items[id]
end
return ItemCatalog
Необов'язкові поля вирішують, що робить предмет. toolName робить його екіпірованим, heal робить його придатним до використання, а предмет без обох полів, як дерево, лежить в інвентарі, поки його не прибере інший серверний код (крафт, продаж).
Щоб додати предмет, додайте запис, у якого ключ і id збігаються. Id чутливі до регістру і саме вони зберігаються, тому ніколи не змінюйте id, коли предмет уже є в гравців: змінюйте його name.
Крок 3: зберігайте інвентарі на сервері
Цей ModuleScript володіє інвентарем кожного гравця. Кожен інвентар це список слотів, у кожному слоті id предмета і кількість, плюс місткість у 20 слотів. Інші серверні скрипти викликають його функції, і більше ніхто таблицю не редагує.
Вставте ModuleScript у ServerScriptService і назвіть його InventoryService:
-- Єдиний код, який змінює інвентарі. Він лежить у ServerScriptService,
-- де клієнти не можуть ні побачити, ні запустити його.
local ReplicatedStorage = game:GetService("ReplicatedStorage")
-- Strict-режим не бачить, що повертає require через WaitForChild, тому
-- описуємо ту частину модуля, яку використовує цей скрипт
type Item = { id: string, maxStack: number }
type Catalog = { get: (id: string) -> Item? }
local ItemCatalog = require(ReplicatedStorage:WaitForChild("ItemCatalog")) :: Catalog
local remotes = ReplicatedStorage:WaitForChild("InventoryRemotes")
local inventoryUpdated = remotes:WaitForChild("InventoryUpdated") :: RemoteEvent
export type Slot = { id: string, count: number }
type Inventory = { slots: { Slot }, capacity: number, equipped: string? }
local CAPACITY = 20 -- слотів на гравця
local STARTER_ITEMS: { Slot } = { -- з чим починає зовсім новий гравець
{ id = "sword", count = 1 },
{ id = "apple", count = 3 },
}
local inventories: { [Player]: Inventory } = {}
local InventoryService = {}
-- Надсилає власникові копію його інвентарю. Викликається після кожної зміни.
local function sync(player: Player)
local inventory = inventories[player]
if inventory then
inventoryUpdated:FireClient(player, {
capacity = inventory.capacity,
slots = inventory.slots,
equipped = inventory.equipped,
})
end
end
-- Правила стаків: спершу доливаємо неповні стаки, потім починаємо нові стаки
-- в порожніх слотах. Повертає, скільки додано, це може бути менше за запитане.
local function addToInventory(inventory: Inventory, item: Item, amount: number): number
local remaining = amount
for _, slot in inventory.slots do
if remaining == 0 then
break
end
if slot.id == item.id and slot.count < item.maxStack then
local moved = math.min(item.maxStack - slot.count, remaining)
slot.count += moved
remaining -= moved
end
end
while remaining > 0 and #inventory.slots < inventory.capacity do
local moved = math.min(item.maxStack, remaining)
table.insert(inventory.slots, { id = item.id, count = moved })
remaining -= moved
end
return amount - remaining
end
function InventoryService.count(player: Player, itemId: string): number
local inventory = inventories[player]
local total = 0
if inventory then
for _, slot in inventory.slots do
if slot.id == itemId then
total += slot.count
end
end
end
return total
end
-- Скільки ще предмета влізе: місце в його стаках плюс порожні слоти
function InventoryService.spaceFor(player: Player, itemId: string): number
local inventory = inventories[player]
local item = ItemCatalog.get(itemId)
if not inventory or not item then
return 0
end
local space = (inventory.capacity - #inventory.slots) * item.maxStack
for _, slot in inventory.slots do
if slot.id == itemId then
space += item.maxStack - slot.count
end
end
return space
end
-- Додає до amount штук предмета. Повертає, скільки додано (0, якщо
-- предмета немає, інвентар повний або ще не завантажився).
function InventoryService.add(player: Player, itemId: string, amount: number): number
local inventory = inventories[player]
local item = ItemCatalog.get(itemId)
local wanted = math.floor(amount)
if not inventory or not item or wanted < 1 then
return 0
end
local added = addToInventory(inventory, item, wanted)
if added > 0 then
sync(player)
end
return added
end
-- Прибирає рівно amount штук предмета, починаючи з останніх стаків.
-- Якщо в гравця менше, нічого не прибирає і повертає false.
function InventoryService.remove(player: Player, itemId: string, amount: number): boolean
local inventory = inventories[player]
local wanted = math.floor(amount)
if not inventory or wanted < 1 or InventoryService.count(player, itemId) < wanted then
return false
end
local remaining = wanted
-- Ідемо з кінця, щоб table.remove не пропускав слоти
for index = #inventory.slots, 1, -1 do
local slot = inventory.slots[index]
if slot.id == itemId then
local taken = math.min(slot.count, remaining)
slot.count -= taken
remaining -= taken
if slot.count == 0 then
table.remove(inventory.slots, index)
end
if remaining == 0 then
break
end
end
end
sync(player)
return true
end
function InventoryService.getEquipped(player: Player): string?
local inventory = inventories[player]
return if inventory then inventory.equipped else nil
end
function InventoryService.setEquipped(player: Player, itemId: string?)
local inventory = inventories[player]
if inventory then
inventory.equipped = itemId
sync(player)
end
end
-- Викликається, коли збережені дані гравця завантажилися. saved це те, що
-- повернув дата стор: nil для нового гравця. Кожен запис знову проходить через
-- правила стаків, тому видалені предмети і старі розміри стаків нічого не ламають.
function InventoryService.load(player: Player, saved: any)
local inventory: Inventory = { slots = {}, capacity = CAPACITY }
local entries: { Slot } = STARTER_ITEMS
if type(saved) == "table" and type(saved.slots) == "table" then
entries = {}
for _, entry in saved.slots do
if type(entry) == "table" and type(entry.id) == "string" and type(entry.count) == "number" then
table.insert(entries, { id = entry.id, count = math.floor(entry.count) })
end
end
end
for _, entry in entries do
local item = ItemCatalog.get(entry.id)
if item and entry.count > 0 then
addToInventory(inventory, item, entry.count)
end
end
inventories[player] = inventory
sync(player)
end
-- Проста копія для збереження або nil, якщо дані гравця так і не завантажилися
function InventoryService.serialize(player: Player): { version: number, slots: { Slot } }?
local inventory = inventories[player]
if not inventory then
return nil
end
local slots: { Slot } = {}
for index, slot in inventory.slots do
slots[index] = { id = slot.id, count = slot.count }
end
return { version = 1, slots = slots }
end
function InventoryService.unload(player: Player)
inventories[player] = nil
end
return InventoryService
Рядки type і приведення :: після require потрібні лише тайпчекеру Luau, який не бачить, що повертає модуль, знайдений через WaitForChild. Під час гри вони нічого не змінюють. Решта скриптів у цьому гайді роблять так само.
Як працюють правила стаків із каталогом вище, де яблука стакаються до 10:
- Якщо додати 15 яблук гравцеві зі стаком із 7, цей стак заповниться до 10, а потім почнеться новий стак із 5.
- Коли слоти закінчуються,
addдодає те, що влізло, і повертає це число. Викликайте спершуspaceFor, коли потрібно все або нічого, як робить підбирання в кроці 5. removeпрацює за принципом усе або нічого. Запит 3 яблук у гравця, який має 2, нічого не прибирає і повертаєfalse, тому перевіряйте результат, перш ніж щось давати натомість.- У слотах немає дірок: коли слот порожніє, решта зсуваються вгору. Так список простіше надсилати й зберігати. Про слоти, які тримають свою позицію, розказано в запитаннях наприкінці.
| Функція | Повертає | Для чого |
|---|---|---|
add(player, itemId, amount) | Скільки додано | Підбирання, нагороди, покупки |
remove(player, itemId, amount) | true, якщо прибрано все | Використання, продаж, крафт |
count(player, itemId) | Сума за всіма стаками | Перевірити, що є в гравця |
spaceFor(player, itemId) | Скільки ще влізе | Перевірка перед додаванням за принципом усе або нічого |
getEquipped, setEquipped | Id екіпірованого предмета або nil | Екіпірування, у кроці 6 |
load, serialize, unload | Копія, готова до збереження (serialize) | Завантаження і збереження, у кроці 4 |
Крок 4: завантажуйте і зберігайте кожен інвентар
Інвентарі живуть у пам'яті сервера, тому зникають, коли гравець виходить. Цей скрипт завантажує слоти гравця з дата стору, коли він заходить, і записує їх назад, коли він виходить, коли сервер вимикається і кожні три хвилини на випадок крашу сервера. Він зберігає лише id предметів і кількість: дата стори не вміють зберігати Instance, наприклад Tool.
Вставте Script у ServerScriptService і назвіть його InventoryData:
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
local RunService = game:GetService("RunService")
local ServerScriptService = game:GetService("ServerScriptService")
type InventoryApi = {
load: (player: Player, saved: any) -> (),
serialize: (player: Player) -> any,
unload: (player: Player) -> (),
}
local InventoryService = require(ServerScriptService:WaitForChild("InventoryService")) :: InventoryApi
local STORE_NAME = "PlayerInventory_v1"
local LOAD_ATTEMPTS = 3
local AUTOSAVE_SECONDS = 180
-- Зберігаються лише гравці, чиї дані завантажилися. Після невдалого завантаження
-- не можна зберігати, інакше порожній інвентар замінить справжній.
local canSave: { [Player]: boolean } = {}
local activeSaves = 0
local function keyFor(player: Player): string
return "User_" .. player.UserId
end
-- Один невдалий запит не має коштувати нікому предметів, тому пробуємо кілька разів.
-- GetDataStore теж усередині pcall, тому сесія Studio без доступу до дата
-- сторів отримує попередження, а не зупиняє цей скрипт.
local function loadSaved(player: Player): (boolean, any)
for attempt = 1, LOAD_ATTEMPTS do
local ok, result = pcall(function()
return DataStoreService:GetDataStore(STORE_NAME):GetAsync(keyFor(player))
end)
if ok then
return true, result
end
warn(`Inventory load failed for {player.Name} (attempt {attempt}): {result}`)
if attempt < LOAD_ATTEMPTS then
task.wait(attempt * 2)
end
end
return false, nil
end
local function onPlayerAdded(player: Player)
local ok, saved = loadSaved(player)
if player.Parent ~= Players then
return -- гравець вийшов, поки ми завантажували
end
if ok then
InventoryService.load(player, saved) -- saved дорівнює nil для нового гравця
canSave[player] = true
elseif RunService:IsStudio() then
-- Зазвичай означає, що доступ Studio до API services вимкнено. Граємо зі
-- стартовими предметами, щоб можна було тестувати, але ніколи їх не зберігаємо.
warn("Inventory not loaded: playing with starter items that will not be saved")
InventoryService.load(player, nil)
else
player:Kick("Your inventory could not be loaded. Please rejoin in a minute.")
end
end
local function save(player: Player)
if not canSave[player] then
return -- дані так і не завантажилися, безпечно записати нічого
end
local data = InventoryService.serialize(player)
if not data then
return
end
activeSaves += 1
local ok, err = pcall(function()
DataStoreService:GetDataStore(STORE_NAME):SetAsync(keyFor(player), data, { player.UserId })
end)
activeSaves -= 1
if not ok then
warn(`Inventory save failed for {player.Name}: {err}`)
end
end
Players.PlayerAdded:Connect(onPlayerAdded)
for _, player in Players:GetPlayers() do
task.spawn(onPlayerAdded, player)
end
Players.PlayerRemoving:Connect(function(player: Player)
save(player)
canSave[player] = nil
InventoryService.unload(player)
end)
-- Коли сервер вимикається, зберігаємо всіх, хто ще тут, і чекаємо кожне
-- поточне збереження, включно з тими, що запустив PlayerRemoving
game:BindToClose(function()
for _, player in Players:GetPlayers() do
task.spawn(save, player)
end
while activeSaves > 0 do
task.wait()
end
end)
-- Зберігаємо всіх раз на кілька хвилин, щоб краш сервера коштував хвилин, а не всієї сесії
while true do
task.wait(AUTOSAVE_SECONDS)
for _, player in Players:GetPlayers() do
task.spawn(save, player)
end
end
Що робить скрипт і навіщо:
- Завантаження зі значеннями за замовчуванням. Новий гравець не має збереженого значення, тому
GetAsyncповертає nil, і він отримує стартові предмети. Збережені слоти знову проходять через правила стаків, тому предмет, видалений із каталогу, або зменшений максимальний стак не зламають завантаження. Усе, що більше не влазить або чийого id більше немає в каталозі, відкидається, і наступне збереження робить це остаточним, тому тримайте в каталозі кожен id, який може бути в гравців. - Ніколи не зберігати після невдалого завантаження. Записуються лише гравці з
canSave. На живому сервері гравця, чиї дані не завантажилися і після трьох спроб, просять перезайти. У Studio він натомість отримує стартові предмети, що не зберігаються, на кілька секунд пізніше через повторні спроби. Так і буде, поки плейс не опубліковано з увімкненим доступом до API. - Збереження під час виходу і вимкнення.
BindToCloseзберігає всіх, хто ще на сервері, і чекає вже поточні збереження. Roblox дає прив'язаним функціям до 30 секунд. - Не виходити за ліміти. Один запис на гравця кожні три хвилини плюс один під час виходу це набагато менше за стандартний бюджет сервера в 60 записів на хвилину плюс 40 на кожного гравця (за документацією на 30 вересня 2026). Шаблон ключа
User_узято з рекомендацій Roblox, а передача user ID уSetAsyncпов'язує дані з цим гравцем, що Roblox наполегливо рекомендує для обробки запитів на видалення даних.
Для невеликої гри це надійна основа. Блокування сесії, яке не дає гравцеві, що швидко змінив сервер, завантажити дані раніше, ніж старий сервер їх зберіг, і коли використовувати UpdateAsync замість SetAsync, розібрано в туторіалі з DataStore.
Крок 5: видавайте предмети зі світу
Підбирання це найпростіший спосіб, яким предмети потрапляють в інвентар: парт із ProximityPrompt, який додає предмет, коли гравець його використовує. Скрипт слухає його подію Triggered на сервері, тому предмет додається там, де клієнт не може втрутитися.
- Додайте Part у Workspace, назвіть його
Appleі пофарбуйте в червоний. Увімкніть Anchored і вимкніть CanCollide, щоб ніхто не врізався в нього, поки він невидимий. Підказка показує ім'я парта. - Виділивши парт, прокрутіть вікно Properties до розділу Attributes і натисніть +. Додайте
ItemIdз типом string і натисніть Save, потім задайте значенняapple. Так само додайтеAmountтипу number зі значенням1. - Вставте Script у парт, назвіть його
ItemPickupі вставте цей код:
-- Покладіть цей Script усередину Part і дайте Part два атрибути:
-- ItemId (рядок, наприклад apple) і Amount (число, наприклад 1).
local ServerScriptService = game:GetService("ServerScriptService")
type InventoryApi = {
add: (player: Player, itemId: string, amount: number) -> number,
spaceFor: (player: Player, itemId: string) -> number,
}
local InventoryService = require(ServerScriptService:WaitForChild("InventoryService")) :: InventoryApi
local part = script.Parent :: BasePart
local RESPAWN_SECONDS = 15
local itemId = part:GetAttribute("ItemId")
local amount = part:GetAttribute("Amount")
if typeof(itemId) ~= "string" or typeof(amount) ~= "number" or amount < 1 then
error(`{part:GetFullName()} needs an ItemId (string) and an Amount (number, 1 or more) attribute`)
end
local prompt = Instance.new("ProximityPrompt")
prompt.ActionText = "Pick up"
prompt.ObjectText = part.Name
prompt.Parent = part
local visibleTransparency = part.Transparency
prompt.Triggered:Connect(function(player: Player)
if not prompt.Enabled then
return -- хтось інший підібрав його щойно
end
-- Перевіряємо відстань на сервері, а не віримо запиту
local character = player.Character
if not character then
return
end
local distance = (character:GetPivot().Position - part.Position).Magnitude
if distance > prompt.MaxActivationDistance + 5 then
return
end
if InventoryService.spaceFor(player, itemId) < amount then
return -- бракує місця: залишаємо предмет на місці
end
InventoryService.add(player, itemId, amount)
prompt.Enabled = false
part.Transparency = 1
task.wait(RESPAWN_SECONDS)
part.Transparency = visibleTransparency
prompt.Enabled = true
end)
Копіюйте парт, щоб розставити більше предметів. Змінюйте атрибути, щоб видавати дерево, ще один меч або стак яблук.
Roblox перевіряє відстань для Triggered, але його гайд з безпеки все одно велить перевіряти підказки на сервері: чітер може викликати події підказки, навіть коли Enabled дорівнює false, і може притягнути незаанкерений парт до свого персонажа. Тому скрипт сам перевіряє Enabled і відстань, і тому парт заанкерений.
Будь-який інший серверний скрипт видає предмети так само. Після покупки, квесту чи вбивства підключіть InventoryService через require, як скрипти вище, і викличте InventoryService.add(player, "wood", 5). Спершу перевіряйте spaceFor, коли предмет не можна втратити. Ще одним джерелом може бути NPC: у гайді з діалогів з NPC відповідь запускає дію на сервері, і ця дія може так само викликати InventoryService.add.
Крок 6: екіпірування Tool і використання предметів
Два RemoteEvent несуть єдині запити, які може зробити клієнт. EquipItem кладе копію Tool предмета із ServerStorage у Backpack гравця (хотбар унизу екрана) і йому в руку, а повторний запит прибирає її. UseItem прибирає одну штуку предмета, придатного до використання, і застосовує його ефект, тут це лікування.
Вставте Script у ServerScriptService і назвіть його InventoryActions:
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ServerScriptService = game:GetService("ServerScriptService")
local ServerStorage = game:GetService("ServerStorage")
type Item = { id: string, toolName: string?, heal: number? }
type Catalog = { get: (id: string) -> Item? }
type InventoryApi = {
count: (player: Player, itemId: string) -> number,
remove: (player: Player, itemId: string, amount: number) -> boolean,
getEquipped: (player: Player) -> string?,
setEquipped: (player: Player, itemId: string?) -> (),
}
local ItemCatalog = require(ReplicatedStorage:WaitForChild("ItemCatalog")) :: Catalog
local InventoryService = require(ServerScriptService:WaitForChild("InventoryService")) :: InventoryApi
local remotes = ReplicatedStorage:WaitForChild("InventoryRemotes")
local equipItem = remotes:WaitForChild("EquipItem") :: RemoteEvent
local useItem = remotes:WaitForChild("UseItem") :: RemoteEvent
local itemTools = ServerStorage:WaitForChild("ItemTools")
local COOLDOWN_SECONDS = 0.25
local lastRequest: { [Player]: number } = {}
-- Кожен запит починається тут. Клієнт може надіслати що завгодно коли завгодно, тому
-- перевіряємо тип, що предмет існує, що гравець його має, і частоту.
local function ownedItem(player: Player, itemId: unknown): Item?
if typeof(itemId) ~= "string" then
return nil
end
local now = os.clock()
if now - (lastRequest[player] or 0) < COOLDOWN_SECONDS then
return nil
end
lastRequest[player] = now
local item = ItemCatalog.get(itemId)
if not item or InventoryService.count(player, itemId) < 1 then
return nil
end
return item
end
-- Знищує Tool цього предмета, де б не була копія: хотбар, рука чи StarterGear
local function destroyTools(container: Instance?, itemId: string)
if not container then
return
end
for _, child in container:GetChildren() do
if child:IsA("Tool") and child:GetAttribute("InventoryItem") == itemId then
child:Destroy()
end
end
end
local function unequip(player: Player)
local equippedId = InventoryService.getEquipped(player)
if equippedId then
destroyTools(player:FindFirstChildOfClass("Backpack"), equippedId)
destroyTools(player.Character, equippedId)
destroyTools(player:FindFirstChildOfClass("StarterGear"), equippedId)
InventoryService.setEquipped(player, nil)
end
end
local function equip(player: Player, item: Item, toolName: string)
local template = itemTools:FindFirstChild(toolName)
local backpack = player:FindFirstChildOfClass("Backpack")
if not template or not template:IsA("Tool") or not backpack then
warn(`Cannot equip {item.id}: no Tool named {toolName} in ServerStorage.ItemTools`)
return
end
unequip(player) -- один екіпірований інструмент за раз
local tool = template:Clone()
tool.CanBeDropped = false -- викинуту копію міг би підібрати хтось інший
tool:SetAttribute("InventoryItem", item.id)
tool.Parent = backpack
-- Друга копія в StarterGear копіюється назад у Backpack після респавну
local starterGear = player:FindFirstChildOfClass("StarterGear")
if starterGear then
local gearCopy = tool:Clone()
gearCopy.Parent = starterGear
end
local character = player.Character
local humanoid = character and character:FindFirstChildOfClass("Humanoid")
if humanoid and humanoid.Health > 0 then
humanoid:EquipTool(tool) -- одразу в руку
end
InventoryService.setEquipped(player, item.id)
end
equipItem.OnServerEvent:Connect(function(player: Player, itemId: unknown)
local item = ownedItem(player, itemId)
if not item or not item.toolName then
return
end
if InventoryService.getEquipped(player) == item.id then
unequip(player) -- повторний клік по екіпірованому предмету прибирає його
else
equip(player, item, item.toolName)
end
end)
useItem.OnServerEvent:Connect(function(player: Player, itemId: unknown)
local item = ownedItem(player, itemId)
if not item or not item.heal then
return
end
local heal = item.heal
local character = player.Character
local humanoid = character and character:FindFirstChildOfClass("Humanoid")
if not humanoid or humanoid.Health <= 0 or humanoid.Health >= humanoid.MaxHealth then
return -- мертвий або вже з повним здоров'ям: не витрачаємо предмет
end
-- Спершу забираємо предмет і лікуємо, лише якщо це вдалося
if InventoryService.remove(player, item.id, 1) then
humanoid.Health = math.min(humanoid.MaxHealth, humanoid.Health + heal)
end
end)
Players.PlayerRemoving:Connect(function(player: Player)
lastRequest[player] = nil
end)
| Запит | Клієнт надсилає | Сервер перевіряє перед дією |
|---|---|---|
EquipItem | Id предмета | Це рядок, предмет існує, гравець його має, запити приходять не частіше чотирьох на секунду, у предмета є toolName, і Tool з таким ім'ям лежить у ServerStorage.ItemTools |
UseItem | Id предмета | Ті самі перевірки типу, володіння і частоти, у предмета є значення heal, персонаж живий і поранений, і один предмет прибрано до того, як додано здоров'я |
Три деталі не дають Tool роздвоїтися чи загубитися. У копії CanBeDropped дорівнює false, бо викинутий Tool падає у Workspace, де його може забрати інший гравець, а оригінал при цьому залишається в інвентарі. Кожна копія несе атрибут InventoryItem, тому під час зняття можна знайти і знищити кожну копію, де б вона не була. А якщо в гравця є контейнер StarterGear, у нього кладеться друга копія. Roblox копіює StarterGear у Backpack за кожної появи персонажа, тому екіпірований меч повертається після респавну.
Екіпірований лише один Tool за раз, і екіпірування не зберігається, тому гравець після перезаходу починає з порожнім хотбаром. Якщо пізніше додасте продаж чи викидання, знімайте предмет, перш ніж його остання копія покине інвентар.
Меч-заглушку можна перетворити на меч, який справді б'ється: зберіть Tool за гайдом із меча, залиште йому ім'я Sword і покладіть у ItemTools замість заглушки. Серверний скрипт із того гайду перевірятиме кожен удар, хоч як гравець отримав меч.
Крок 7: намалюйте сітку інвентарю
LocalScript збирає все вікно в коді, тому нічого не треба розставляти вручну. ScrollingFrame тримає слоти, UIGridLayout усередині нього розкладає їх рядами, а AutomaticCanvasSize збільшує прокручувану область у міру додавання рядів.
В Explorer відкрийте StarterPlayer, вставте LocalScript у StarterPlayerScripts і назвіть його InventoryClient:
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local UserInputService = game:GetService("UserInputService")
type Item = { name: string, description: string, icon: string?, toolName: string?, heal: number? }
type Catalog = { get: (id: string) -> Item? }
type Slot = { id: string, count: number }
type Snapshot = { capacity: number, slots: { Slot }, equipped: string? }
local ItemCatalog = require(ReplicatedStorage:WaitForChild("ItemCatalog")) :: Catalog
local remotes = ReplicatedStorage:WaitForChild("InventoryRemotes")
local inventoryUpdated = remotes:WaitForChild("InventoryUpdated") :: RemoteEvent
local equipItem = remotes:WaitForChild("EquipItem") :: RemoteEvent
local useItem = remotes:WaitForChild("UseItem") :: RemoteEvent
local player = Players.LocalPlayer
local TOGGLE_KEY = Enum.KeyCode.B
local COLOURS = {
panel = Color3.fromRGB(24, 20, 36),
slot = Color3.fromRGB(44, 38, 64),
empty = Color3.fromRGB(34, 30, 48),
equipped = Color3.fromRGB(124, 77, 255),
text = Color3.fromRGB(240, 238, 245),
muted = Color3.fromRGB(170, 165, 185),
}
local function addCorner(parent: GuiObject, radius: number)
local corner = Instance.new("UICorner")
corner.CornerRadius = UDim.new(0, radius)
corner.Parent = parent
end
local function makeLabel(parent: GuiObject, text: string, textSize: number): TextLabel
local label = Instance.new("TextLabel")
label.BackgroundTransparency = 1
label.Font = Enum.Font.BuilderSansBold
label.TextColor3 = COLOURS.text
label.TextSize = textSize
label.Text = text
label.Parent = parent
return label
end
-- 1. Збираємо вікно один раз. ResetOnSpawn = false зберігає його після респавнів.
local gui = Instance.new("ScreenGui")
gui.Name = "InventoryGui"
gui.ResetOnSpawn = false
gui.Parent = player:WaitForChild("PlayerGui")
local openButton = Instance.new("TextButton")
openButton.AnchorPoint = Vector2.new(0, 0.5)
openButton.Position = UDim2.new(0, 16, 0.5, 0)
openButton.Size = UDim2.fromOffset(140, 40)
openButton.BackgroundColor3 = COLOURS.panel
openButton.Font = Enum.Font.BuilderSansBold
openButton.TextColor3 = COLOURS.text
openButton.TextSize = 18
openButton.Text = "Inventory (B)"
addCorner(openButton, 8)
openButton.Parent = gui
local panel = Instance.new("Frame")
panel.AnchorPoint = Vector2.new(0.5, 0.5)
panel.Position = UDim2.fromScale(0.5, 0.5)
panel.Size = UDim2.fromScale(0.9, 0.8)
panel.BackgroundColor3 = COLOURS.panel
panel.Visible = false
addCorner(panel, 12)
panel.Parent = gui
local sizeLimit = Instance.new("UISizeConstraint")
sizeLimit.MaxSize = Vector2.new(440, 400)
sizeLimit.Parent = panel
local title = makeLabel(panel, "Inventory", 22)
title.Position = UDim2.fromOffset(16, 8)
title.Size = UDim2.new(1, -32, 0, 32)
title.TextXAlignment = Enum.TextXAlignment.Left
local slotCount = makeLabel(panel, "", 16)
slotCount.Position = UDim2.fromOffset(16, 8)
slotCount.Size = UDim2.new(1, -32, 0, 32)
slotCount.TextColor3 = COLOURS.muted
slotCount.TextXAlignment = Enum.TextXAlignment.Right
local grid = Instance.new("ScrollingFrame")
grid.Position = UDim2.fromOffset(12, 48)
grid.Size = UDim2.new(1, -24, 1, -100)
grid.BackgroundTransparency = 1
grid.BorderSizePixel = 0
grid.CanvasSize = UDim2.new() -- AutomaticCanvasSize збільшує його під комірки
grid.AutomaticCanvasSize = Enum.AutomaticSize.Y
grid.ScrollingDirection = Enum.ScrollingDirection.Y
grid.ScrollBarThickness = 6
grid.Parent = panel
local layout = Instance.new("UIGridLayout")
layout.CellSize = UDim2.fromOffset(72, 72)
layout.CellPadding = UDim2.fromOffset(8, 8)
layout.SortOrder = Enum.SortOrder.LayoutOrder
layout.Parent = grid
local info = makeLabel(panel, "Click an item to equip or use it.", 16)
info.AnchorPoint = Vector2.new(0, 1)
info.Position = UDim2.new(0, 16, 1, -8)
info.Size = UDim2.new(1, -32, 0, 40)
info.Font = Enum.Font.BuilderSans
info.TextColor3 = COLOURS.muted
info.TextWrapped = true
info.TextXAlignment = Enum.TextXAlignment.Left
-- 2. Одна комірка на слот. Це лише малює те, що надіслав сервер; сам
-- інвентар звідси ніколи не змінюється.
local function makeCell(index: number, slot: Slot?, equippedId: string?)
local cell = Instance.new("TextButton")
cell.LayoutOrder = index
cell.Text = ""
cell.AutoButtonColor = slot ~= nil
cell.BackgroundColor3 = if slot then COLOURS.slot else COLOURS.empty
addCorner(cell, 8)
cell.Parent = grid
if not slot then
return -- порожній слот
end
local itemId = slot.id
local item = ItemCatalog.get(itemId)
local name = if item then item.name else itemId
if item and item.icon then
local image = Instance.new("ImageLabel")
image.BackgroundTransparency = 1
image.Size = UDim2.fromScale(1, 1)
image.Image = item.icon
image.Parent = cell
else
local nameLabel = makeLabel(cell, name, 14)
nameLabel.Size = UDim2.fromScale(1, 1)
nameLabel.TextWrapped = true
end
if slot.count > 1 then
local countLabel = makeLabel(cell, `x{slot.count}`, 14)
countLabel.AnchorPoint = Vector2.new(1, 1)
countLabel.Position = UDim2.new(1, -6, 1, -4)
countLabel.Size = UDim2.fromOffset(40, 16)
countLabel.TextXAlignment = Enum.TextXAlignment.Right
end
if itemId == equippedId then
local outline = Instance.new("UIStroke")
outline.ApplyStrokeMode = Enum.ApplyStrokeMode.Border
outline.Color = COLOURS.equipped
outline.Thickness = 3
outline.Parent = cell
end
cell.MouseEnter:Connect(function()
info.Text = if item then `{item.name}: {item.description}` else name
end)
cell.Activated:Connect(function()
-- Просимо, а не наказуємо: сервер перевіряє запит і надсилає результат
if item and item.toolName then
equipItem:FireServer(itemId)
elseif item and item.heal then
useItem:FireServer(itemId)
end
end)
end
local function render(snapshot: Snapshot)
for _, child in grid:GetChildren() do
if child:IsA("GuiButton") then
child:Destroy()
end
end
for index = 1, snapshot.capacity do
makeCell(index, snapshot.slots[index], snapshot.equipped)
end
slotCount.Text = `{#snapshot.slots} / {snapshot.capacity} slots`
end
-- Сервер надсилає це після завантаження і після кожної зміни
inventoryUpdated.OnClientEvent:Connect(render)
-- 3. Відкриваємо і закриваємо кнопкою або клавішею B
local function toggle()
panel.Visible = not panel.Visible
end
openButton.Activated:Connect(toggle)
UserInputService.InputBegan:Connect(function(input: InputObject, gameProcessedEvent: boolean)
if not gameProcessedEvent and input.KeyCode == TOGGLE_KEY then
toggle()
end
end)
LocalScript у StarterPlayerScripts запускається один раз за сесію, а ResetOnSpawn = false зберігає ScreenGui під час респавну персонажа, тому сітка й далі показує останню копію, яку надіслав сервер.
Клієнт малює по комірці на кожен слот, включно з порожніми, тому інвентар на 20 слотів завжди виглядає як 20 слотів. Кожне оновлення знищує старі комірки й будує нові, це просто і підходить для кількох десятків слотів. Якщо сервер надішле InventoryUpdated раніше, ніж цей скрипт до нього підключився, Roblox поставить повідомлення в чергу і доставить його, щойно обробник підключиться, тому перший інвентар не загубиться.
Хочете намалювати вікно в Studio? Зберіть ScreenGui з одним слотом-шаблоном і робіть йому Clone у makeCell. Для іконок задайте предмету в каталозі icon із завантаженим вами зображенням, і його комірка покаже картинку замість назви.
Перевірте інвентар
- Натисніть Play. Відкрийте інвентар кнопкою ліворуч або клавішею B: новий гравець має Sword і 3 Apple, а лічильник показує 2 / 20 slots. Поки Studio не може звертатися до дата сторів, предмети з'являються через кілька секунд, після попереджень про завантаження в Output, і не зберігаються.
- Клікніть по Sword. Меч з'явиться у вас у руці і в хотбарі, а його слот отримає фіолетову рамку. Клікніть ще раз, щоб прибрати його.
- Підійдіть до парта Apple і скористайтеся його підказкою. Стак яблук зросте до 4, а парт зникне на 15 секунд.
- Щоб перевірити лікування, спершу зменште здоров'я. Перемкніть Client/Server на Server, виділіть
Humanoidсвого персонажа в Explorer, задайте Health рівним 50, перемкніться назад на Client і клікніть по Apple. - З увімкненим доступом Studio до API services зупиніть гру і запустіть знову. Підібране яблуко на місці. Якщо завантаження чи збереження не вдалися, Output про це скаже.
Щоб перевірити з кількома гравцями, виберіть у налаштуваннях тесту Server & Clients з 2 клієнтами. Кожен гравець бачить лише свій інвентар, а меч у руці іншого бачать обидва.
Поширені помилки та рішення
Більшість проблем видно у вікні Output як попередження або червоний рядок помилки. Читайте перший: наступні помилки часто випливають із нього.
Infinite yield possible на виклику WaitForChild
Скрипт чекає об'єкт, якого немає під точно таким ім'ям. Порівняйте свій Explorer із деревом із кроку 1: InventoryRemotes з трьома RemoteEvent у ReplicatedStorage, ItemTools у ServerStorage і два модулі. Імена чутливі до регістру. Гайд із помилок скриптів розбирає це попередження докладніше.
Сітка відкривається, але залишається порожньою
Клієнт малює лише те, що надсилає сервер. Пошукайте в Output попередження Inventory load failed і перевірте, що InventoryData це Script, а не LocalScript, у ServerScriptService, і поруч лежить ModuleScript InventoryService. Якщо Output показує помилку Remote event invocation, на клієнті ніхто не слухає InventoryUpdated: шукайте ранішу помилку від InventoryClient.
Предмети скидаються щоразу, коли я граю в Studio
Якщо Output пише Inventory not loaded: playing with starter items that will not be saved, плейс не опубліковано або доступ Studio до API services вимкнено. Увімкніть його, як описано в кроці 4, у тестовій копії своєї гри.
Клік по мечу нічого не робить
Пошукайте в Output Cannot equip sword: Tool у ServerStorage.ItemTools має називатися точно як toolName у каталозі. Ще Tool потрібен парт з ім'ям Handle, щоб його можна було тримати, якщо тільки ви не задали його RequiresHandle рівним false.
Підказка підбирання з'являється, але нічого не додається
Атрибут ItemId має точно збігатися з id із каталогу, включно з регістром: apple, а не Apple. Нічого не додається, поки інвентар гравця ще завантажується або коли немає місця на всю кількість.
Збереження ламається після того, як я змінив, що зберігається
Дата стори приймають прості дані: рядки, числа, булеві значення і таблиці з них. Збереження Tool, Part чи будь-якого іншого Instance падає, або значення зберігається як nil. Зберігайте id предмета і кількість, а все інше відновлюйте з каталогу, як робить serialize.
Зробити з RoCode
Якщо вам простіше описати систему, ніж збирати її вручну, RoCode може зібрати її у відкритому у вас плейсі. Це ШІ-агент для Roblox Studio: ви описуєте фічу у вебчаті, а його плагін для Studio створює скрипти й об'єкти у вашому Explorer, а не видає код для вставлення.
Додай інвентар на 20 слотів зі стаками предметів, сітку UI, яка відкривається на B, меч із ServerStorage, який гравці можуть екіпірувати, яблука, які лікують, і збереження через DataStoreService.
- Може переглянути ваш плейс, коли кроку це потрібно, через Search Game і Search Scripts, щоб спертися на вже наявні предмети, ремоути чи код збереження, а не додавати другу систему
- Створює папки й RemoteEvent через Create Instance, а ModuleScript, Script і LocalScript через Create Script
- Може зібрати заготовку вікна через Build UI, де є розкладка інвентарю зі слотами-заглушками; код, який заповнює слоти із сервера, пишеться окремими скриптами
- Перевіряє компіляцію кожного скрипта в Studio через Check Script, який ловить помилки компіляції і кілька ризикованих патернів, але не перевіряє типи, не лінтить і не запускає ваш код
Кожна пачка змін це точка скасування в Studio. RoCode не може ввімкнути доступ Studio до API services, це ви робите самі. З плагіном 3.9 або новішим він може запустити короткий плейтест і прочитати помилки, а з плагіном 3.9.15 або новішим його тестовий персонаж може натискати клавіші й екіпірувати предмети, але він перевіряє лише те, що сам вирішив протестувати, тому збереження перевірте плейтестом самі. Інвентар стоїть поверх інших систем, як-от збереження та інструменти, і ШІ-конструктор ігор, який будує у вашому власному плейсі в Studio, додає їх по одному промпту за раз. Як RoCode підключається до Studio.
Поширені запитання
Використовувати Backpack у Roblox замість свого інвентарю?
Backpack це вбудований інвентар Roblox: кожен Tool у ньому показується кнопкою в хотбарі. Якщо всі предмети у вашій грі це Tool і вам не потрібні стаки, кількості та ліміт слотів, його може вистачити, хоча зберігати, які Tool є в кожного гравця, усе одно доведеться. Свій інвентар потрібен для предметів, які не є Tool, наприклад матеріалів і витратних предметів. У цьому гайді використовується і те, і те: інвентар зберігає все, а Backpack тримає екіпірований Tool.
Як приховати стандартний хотбар у Roblox?
З LocalScript викличте StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.Backpack, false). Коли хотбар приховано, гравцям потрібен інший спосіб узяти і прибрати екіпірований Tool, наприклад кнопка, яка просить сервер викликати Humanoid:EquipTool або Humanoid:UnequipTools.
Як зробити, щоб слоти тримали позицію для drag and drop?
Зберігайте список фіксованої довжини з одним записом на слот і позначайте порожні слоти значенням на кшталт порожнього id, а не nil, бо Roblox не радить надсилати таблиці з nil через RemoteEvent. Потім додайте RemoteEvent MoveItem, який надсилає два номери слотів, і нехай сервер перевіряє, що обидва це цілі числа від 1 до місткості, перш ніж міняти їх місцями.
Якого розміру може бути збережений інвентар?
Одне значення в дата сторі може займати до 4 194 304 символів після серіалізації (за документацією на 30 вересня 2026). Список id і кількостей займає крихітну частину цього. Розмір збереження збільшує текст на кожен предмет, наприклад власні назви чи довгі описи, збережені для кожного предмета.
Як купувати і продавати предмети за монети?
Робіть усе на сервері. Щоб продати, викличте InventoryService.remove і платіть, лише якщо він повернув true. Щоб купити, перевірте ціну і spaceFor, заберіть монети, потім викличте add. Гайд із магазину збирає бік покупки.
Джерела та що почитати
- Roblox Creator Docs: Remote events and callbacks (англійською). FireClient, OnServerEvent, обмеження на аргументи і як повідомлення без отримувача стають у чергу
- Roblox Creator Docs: Securing the client-server boundary (англійською). перевірка вхідних даних ремоутів, перевірки ProximityPrompt і підміна даних у дата сторі
- Roblox Creator Docs: Data stores (англійською). GetAsync, SetAsync і ввімкнення доступу зі Studio
- Roblox Creator Docs: Best practices for data stores (англійською). один ключ на гравця, шаблони ключів і періодичні збереження
- Roblox Creator Docs: Data store error codes and limits (англійською). ліміти запитів на сервер і ліміт розміру одного значення
- Roblox Creator Docs: In-game tools (англійською). Handle, анкер, Backpack і StarterGear
- Roblox Creator Docs: Grid and table layouts (англійською). розмір комірок UIGridLayout, відступи і порядок сортування
Як перевірявся код: кожен скрипт на цій сторінці проходить сувору перевірку типів Luau з визначеннями Roblox API (luau-lsp, 20 листопада 2026 р.). Перевірка типів ловить помилки в назвах API та неправильні типи, але не помилки ігрової логіки, тому протестуйте все в Studio перед публікацією.