Накратко
Пази предметите на всеки играч в таблица на сървъра, в 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 съществува само на устройството на този играч. Сървърът не научава за нея, затова тя не се запазва и нито един сървърен скрипт не може да я използва.
- Всеки може да я подправи. Ако го поправиш с RemoteEvent като
AddItem(itemId, amount), измамникът ще може сам да извиква това събитие, с какви ли не аргументи и колкото пъти иска. В ръководството на Roblox за сигурност пише, че сървърът трябва да проверява всичко, което клиентът изпраща, преди да го използва.
Затова в това ръководство клиентът може само да моли да се направи нещо с предмети, които играчът вече има: "екипирай това" и "използвай това". Всяка заявка носи едно id на предмет и никакви количества, а на сървъра минава една проверка: това е низ, такъв предмет съществува, играчът има поне един и не праща повече от четири заявки в секунда. След това сървърът сам намира Tool по каталога. Той никога не приема от клиента Tool, път или инстанция, за което предупреждава същото ръководство.
Предметите влизат в инвентара само чрез сървърен код: вдигане, проверено от сървъра, покупка, за която сървърът е взел парите (тя е описана в ръководството за магазин), награда за мисия или дроп. За RemoteEvent като цяло, с проверка на други видове аргументи, прочети ръководството за 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 или кода за запазване, които вече имаш, вместо да добавя втора система
- Създава папки и RemoteEvent чрез Create Instance, а ModuleScript, Script и LocalScript чрез Create Script
- Може да сглоби заготовка на прозореца чрез Build UI, където има оформление на инвентар със слотове заместители; кодът, който попълва слотовете от сървъра, се пише в отделни скриптове
- Проверява компилирането на всеки скрипт в Studio чрез Check Script, който хваща грешки при компилиране и няколко рискови модела, но не проверява типовете, не прави lint и не пуска кода ти
Всеки пакет промени е точка за отмяна в 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 (на английски). проверка на входните данни на RemoteEvent, проверки на 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, преди да публикуваш.