Resumo
Guarde os itens de cada jogador em uma tabela no servidor, dentro de um ModuleScript no ServerScriptService que é o único código que pode adicionar, remover ou empilhar itens. Liste seus itens uma vez em um ModuleScript no ReplicatedStorage (id, nome, pilha máxima). Depois de cada mudança, o servidor dispara um RemoteEvent para aquele jogador com uma cópia do inventário dele, e um LocalScript desenha isso como grade com um ScrollingFrame e um UIGridLayout.
- O cliente nunca adiciona itens. Ele só pode pedir, por exemplo "equipar minha espada", e o servidor confere se o jogador tem uma antes de agir.
- Itens só chegam por código de servidor que você controla: itens coletados no mapa, compras na loja que o servidor conferiu, recompensas.
- Salve ids e quantidades dos itens, não Tools, com o DataStoreService quando os jogadores saem, quando o servidor desliga e a cada poucos minutos. Nunca salve um jogador cujos dados falharam ao carregar.
Nesta página
Como as peças do inventário se encaixam
O sistema tem seis peças pequenas, cada uma com uma função. Toda regra sobre itens fica em um módulo no servidor, então quando algo dá errado existe exatamente um lugar para olhar.
| Peça | Tipo e lugar | Função |
|---|---|---|
ItemCatalog | ModuleScript no ReplicatedStorage | O que cada item é: nome, descrição, pilha máxima e se dá para equipar ou usar. O servidor e todos os clientes leem. |
InventoryService | ModuleScript no ServerScriptService | Guarda os slots de todos os jogadores. O único código que adiciona, remove e empilha itens. |
InventoryData | Script no ServerScriptService | Carrega os itens de um jogador quando ele entra e salva. |
InventoryActions | Script no ServerScriptService | Confere e executa os pedidos de equipar e usar. |
ItemPickup | Script dentro de uma Part | Dá um item para quem coletar. |
InventoryClient | LocalScript no StarterPlayerScripts | Desenha a grade e envia pedidos. Ele mesmo não muda nada. |
Os dados andam em um sentido só. O servidor muda um inventário, depois dispara InventoryUpdated para aquele jogador com o inventário inteiro, e o cliente redesenha a partir dele. Quando o jogador clica em um slot, o cliente dispara EquipItem ou UseItem com o id do item; o servidor confere o pedido, faz a mudança, e a cópia nova chega do mesmo jeito. Mandar o inventário inteiro é mais simples do que mandar as mudanças, e com algumas dezenas de slots a mensagem continua pequena.
Por que o cliente nunca adiciona itens
Dá vontade de adicionar um item no LocalScript que o mostra: o jogador clica, o slot enche. Isso quebra de dois jeitos.
- Ninguém mais vê. Uma mudança feita em um LocalScript existe só no dispositivo daquele jogador. O servidor nunca fica sabendo, então ela não é salva e nenhum script de servidor consegue usar.
- Qualquer um pode falsificar. Se você resolve isso com um RemoteEvent como
AddItem(itemId, amount), um exploiter pode disparar esse evento ele mesmo, com quaisquer argumentos, quantas vezes quiser. O guia de segurança da Roblox diz que o servidor precisa validar tudo o que um cliente envia antes de usar.
Por isso, neste guia o cliente só pode fazer pedidos sobre itens que o jogador já tem: "equipar isto" e "usar isto". Cada pedido leva um id de item e nenhuma quantidade, e passa por uma checagem no servidor: é uma string, é um item real, o jogador tem pelo menos um, e o jogador não está mandando mais de quatro pedidos por segundo. Depois o próprio servidor procura a Tool no catálogo. Ele nunca aceita uma Tool, um caminho ou uma instância vinda do cliente, algo contra o que o mesmo guia avisa.
Itens só entram por código de servidor: um item coletado que o servidor conferiu, uma compra que o servidor cobrou (o guia de loja monta uma), uma recompensa de missão ou um drop. Para o padrão de RemoteEvent em geral, com validação de outros tipos de argumento, leia o guia de RemoteEvents.
Passo 1: Monte o Explorer
Crie estes objetos à mão. Os scripts dos próximos passos acham cada um pelo nome, então escreva cada nome exatamente como aparece aqui.
- No ReplicatedStorage, insira uma Folder chamada
InventoryRemotes. Dentro dela, insira três RemoteEvents chamadosInventoryUpdated,EquipItemeUseItem. - No ServerStorage, insira uma Folder chamada
ItemTools. Dentro dela, insira uma Tool chamadaSword, e dentro da Tool uma Part chamadaHandle(1 por 4 por 1 studs serve). Deixe a caixa Anchored do Handle desmarcada: a Roblox avisa que o personagem fica preso no lugar quando segura uma tool com parts ancoradas. Uma Tool que você já tem também serve, desde que o nome dela bata com o catálogo do Passo 2. - Adicione os scripts conforme chegar em cada passo. A árvore mostra onde cada um vai.
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
Passo 2: Liste seus itens em um catálogo
O catálogo descreve uma vez cada item que pode existir. Os inventários guardam só o id e a quantidade de um item. Isso deixa os saves pequenos e permite renomear um item ou reescrever a descrição dele depois sem mexer nos dados salvos de ninguém.
Insira um ModuleScript no ReplicatedStorage, chame de ItemCatalog e troque o conteúdo por isto:
-- Todo item que pode existir no jogo. O servidor e todos os clientes leem esta
-- lista; só o servidor decide quem tem o quê.
export type Item = {
id: string, -- precisa ser igual à chave abaixo
name: string,
description: string,
maxStack: number, -- o máximo deste item que cabe em um slot
icon: string?, -- imagem opcional, escrita como "rbxassetid://" mais o ID da sua imagem
toolName: string?, -- uma Tool em ServerStorage.ItemTools: o item pode ser equipado
heal: number?, -- vida recuperada ao usar: o item é um consumível
}
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 = {}
-- Devolve o item com este id, ou nil se esse item não existe
function ItemCatalog.get(id: string): Item?
return items[id]
end
return ItemCatalog
Os campos opcionais decidem o que um item faz. toolName deixa ele equipável, heal deixa ele usável, e um item sem nenhum dos dois, como a madeira, fica no inventário até outro código de servidor (crafting, venda) remover.
Para adicionar um item, crie uma entrada em que a chave e o id sejam iguais. Ids diferenciam maiúsculas de minúsculas e são o que fica salvo, então nunca mude o id depois que jogadores tiverem o item: mude o name no lugar.
Passo 3: Guarde os inventários no servidor
Este ModuleScript é dono do inventário de todos os jogadores. Cada inventário é uma lista de slots, cada slot um id de item e uma quantidade, mais uma capacidade de 20 slots. Outros scripts de servidor chamam as funções dele, e nada mais edita a tabela.
Insira um ModuleScript no ServerScriptService e chame de InventoryService:
-- O único código que muda inventários. Ele fica no ServerScriptService,
-- onde os clientes não conseguem nem ver nem rodar.
local ReplicatedStorage = game:GetService("ReplicatedStorage")
-- O modo strict não consegue seguir um require através do WaitForChild, então
-- declaramos a parte do módulo que este script usa
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 -- slots por jogador
local STARTER_ITEMS: { Slot } = { -- com o que um jogador novo começa
{ id = "sword", count = 1 },
{ id = "apple", count = 3 },
}
local inventories: { [Player]: Inventory } = {}
local InventoryService = {}
-- Manda para o dono uma cópia do inventário dele. Roda depois de cada mudança.
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
-- Regras de pilha: completa as pilhas que não estão cheias, depois começa pilhas
-- novas em slots vazios. Devolve quantos foram adicionados, que pode ser menos que o pedido.
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
-- Quantos mais de um item cabem: espaço livre nas pilhas dele mais slots vazios
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
-- Adiciona até amount de um item. Devolve quantos foram adicionados (0 se o
-- item não existe, o inventário está cheio ou ainda não carregou).
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
-- Remove exatamente amount de um item, tirando primeiro das últimas pilhas.
-- Se o jogador tem menos que isso, não remove nada e devolve 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
-- Anda de trás para frente para o table.remove nunca pular um slot
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
-- Chamado uma vez quando os dados salvos de um jogador carregam. saved é o que o data
-- store devolveu: nil para um jogador novo. Toda entrada passa de novo pelas
-- regras de pilha, então itens removidos e tamanhos de pilha antigos não quebram nada.
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
-- Uma cópia simples para salvar, ou nil se os dados deste jogador nunca carregaram
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
As linhas type e o cast :: depois do require só ajudam o verificador de tipos do Luau, que não consegue ver o que um módulo achado com WaitForChild devolve. Elas não mudam nada quando o jogo roda. Os outros scripts deste guia fazem o mesmo.
Como as regras de pilha funcionam com o catálogo acima, em que maçãs empilham até 10:
- Adicionar 15 maçãs a um jogador que tem uma pilha de 7 enche essa pilha até 10 e depois começa uma pilha nova de 5.
- Quando os slots acabam,
addadiciona o que cabe e devolve esse número. ChamespaceForantes quando tiver que ser tudo ou nada, como faz o item coletável do Passo 5. removeé tudo ou nada. Pedir 3 maçãs de um jogador que tem 2 não remove nenhuma e devolvefalse, então confira o resultado antes de dar qualquer coisa em troca.- Os slots não têm buracos: quando um esvazia, os outros sobem. Isso deixa a lista simples de mandar e salvar. As perguntas no fim tratam de slots que mantêm a posição.
| Função | Devolve | Use para |
|---|---|---|
add(player, itemId, amount) | Quantos foram adicionados | Itens coletados, recompensas, compras |
remove(player, itemId, amount) | true se todos foram removidos | Usar, vender, craftar |
count(player, itemId) | O total somando todas as pilhas | Conferir o que um jogador tem |
spaceFor(player, itemId) | Quantos mais caberiam | Conferir antes de um add tudo ou nada |
getEquipped, setEquipped | O id do item equipado, ou nil | Equipar, no Passo 6 |
load, serialize, unload | Uma cópia pronta para salvar (serialize) | Carregar e salvar, no Passo 4 |
Passo 4: Carregue e salve cada inventário
Os inventários ficam na memória do servidor, então somem quando o jogador sai. Este script carrega os slots de um jogador de um data store quando ele entra e grava de volta quando ele sai, quando o servidor desliga e a cada três minutos, para o caso de o servidor cair. Ele salva só ids e quantidades: data stores não guardam Instances como Tools.
Insira um Script no ServerScriptService e chame de 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
-- Só jogadores cujos dados salvos carregaram são salvos. Uma carga que falhou
-- nunca pode ser seguida de um save, senão o inventário vazio substitui o real.
local canSave: { [Player]: boolean } = {}
local activeSaves = 0
local function keyFor(player: Player): string
return "User_" .. player.UserId
end
-- Um pedido que falhou não deve custar os itens de ninguém, então tente de novo algumas vezes.
-- O GetDataStore também fica dentro do pcall, então uma sessão do Studio que não
-- acessa data stores recebe um aviso em vez de parar este script.
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 -- ele saiu enquanto carregávamos
end
if ok then
InventoryService.load(player, saved) -- saved é nil para um jogador novo
canSave[player] = true
elseif RunService:IsStudio() then
-- Normalmente quer dizer que o acesso do Studio às API services está desligado. Jogue com os
-- itens iniciais para poder testar, mas nunca salve esses itens.
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 -- os dados dele nunca carregaram, então não há nada seguro para gravar
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)
-- Quando o servidor desliga, salva todos que ainda estão aqui e espera cada
-- save em andamento, inclusive os que o PlayerRemoving começou
game:BindToClose(function()
for _, player in Players:GetPlayers() do
task.spawn(save, player)
end
while activeSaves > 0 do
task.wait()
end
end)
-- Salva todo mundo a cada poucos minutos, para uma queda do servidor custar minutos, não uma sessão
while true do
task.wait(AUTOSAVE_SECONDS)
for _, player in Players:GetPlayers() do
task.spawn(save, player)
end
end
O que o script faz, e por quê:
- Carrega com padrões. Um jogador novo não tem valor salvo, então
GetAsyncdevolve nil e ele recebe os itens iniciais. Os slots salvos passam de novo pelas regras de pilha, então um item que você tirou do catálogo ou uma pilha máxima menor não quebram uma carga. O que não cabe mais, ou cujo id não está mais no catálogo, é descartado, e o próximo save torna isso permanente, então mantenha no catálogo todo id que jogadores possam ter. - Nunca salva depois de uma carga que falhou. Só jogadores em
canSavesão gravados. Em um servidor publicado, um jogador cujos dados ainda não carregam depois de três tentativas recebe um pedido para entrar de novo. No Studio ele recebe itens iniciais que não são salvos, alguns segundos atrasados por causa das novas tentativas, e é isso que você vê até o place ser publicado com o acesso às API ligado. - Salva ao sair e ao desligar. O
BindToClosesalva todos que ainda estão no servidor e espera os saves que já estão rodando. A Roblox dá até 30 segundos para as funções ligadas a ele. - Fica dentro dos limites. Uma gravação por jogador a cada três minutos, mais uma quando ele sai, fica muito abaixo do orçamento padrão por servidor de 60 gravações por minuto mais 40 por jogador (conforme documentado em 30 de setembro de 2026). O padrão de chave
User_segue as boas práticas da Roblox, e passar o user ID para oSetAsyncliga os dados àquele jogador, o que a Roblox recomenda muito para lidar com pedidos de remoção de dados.
Essa é uma base sólida para um jogo pequeno. Session locking, que impede um jogador que troca de servidor rápido de carregar os dados antes de o servidor antigo salvar, e quando usar UpdateAsync em vez de SetAsync, estão no tutorial de DataStore.
Passo 5: Dê itens a partir do mapa
Um item coletável é o jeito mais simples de itens entrarem em um inventário: uma part com um ProximityPrompt que adiciona um item quando um jogador usa. O script escuta o evento Triggered dele no servidor, então o item é adicionado onde o cliente não consegue interferir.
- Adicione uma Part ao Workspace, chame de
Applee pinte de vermelho. Ligue Anchored e desligue CanCollide, para ninguém esbarrar nela enquanto estiver invisível. O prompt mostra o nome da part. - Com a part selecionada, desça até a seção Attributes da janela Properties e clique em +. Adicione
ItemIdcom o tipo string e clique em Save, depois defina o valor comoapple. AdicioneAmountdo mesmo jeito, como number com valor1. - Insira um Script na part, chame de
ItemPickupe cole este código:
-- Coloque este Script dentro de uma Part e dê à Part dois atributos:
-- ItemId (uma string, como apple) e Amount (um number, como 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 -- outra pessoa coletou agora há pouco
end
-- Confere a distância no servidor em vez de confiar no pedido
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 -- sem espaço suficiente: deixa o item onde está
end
InventoryService.add(player, itemId, amount)
prompt.Enabled = false
part.Transparency = 1
task.wait(RESPAWN_SECONDS)
part.Transparency = visibleTransparency
prompt.Enabled = true
end)
Copie a part para colocar mais itens coletáveis. Mude os atributos para dar madeira, outra espada ou uma pilha de maçãs.
A Roblox confere a distância para o Triggered, mas o guia de segurança dela ainda manda validar os prompts no servidor: um exploiter consegue disparar os eventos de um prompt mesmo com o Enabled em false, e consegue puxar uma part não ancorada para perto do personagem. Por isso o script confere o Enabled e a distância ele mesmo, e por isso a part fica ancorada.
Qualquer outro script de servidor dá itens do mesmo jeito. Depois de uma compra, uma missão ou um abate, faça o require do InventoryService como os scripts acima fazem e chame InventoryService.add(player, "wood", 5). Confira o spaceFor antes sempre que o item não puder ser perdido. Um NPC pode ser outra fonte: no guia de diálogo de NPC, uma resposta roda uma ação no servidor, e essa ação pode chamar InventoryService.add do mesmo jeito.
Passo 6: Equipe Tools e use itens
Dois RemoteEvents levam os únicos pedidos que um cliente pode fazer. EquipItem coloca uma cópia da Tool do item, vinda do ServerStorage, na Backpack do jogador (a hotbar na parte de baixo da tela) e na mão dele, e pedir de novo tira a Tool. UseItem remove um de um item usável e aplica o efeito dele, que aqui é curar.
Insira um Script no ServerScriptService e chame de 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 } = {}
-- Todo pedido começa aqui. Um cliente pode mandar qualquer coisa a qualquer hora, então confira
-- o tipo, se o item existe, se o jogador tem um, e a frequência.
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
-- Destrói a Tool deste item onde houver uma cópia: hotbar, mão ou 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) -- uma tool equipada por vez
local tool = template:Clone()
tool.CanBeDropped = false -- uma cópia largada poderia ser pega por outra pessoa
tool:SetAttribute("InventoryItem", item.id)
tool.Parent = backpack
-- Uma segunda cópia no StarterGear volta para a Backpack depois de um respawn
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) -- coloca direto na mão
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) -- clicar de novo no item equipado tira ele da mão
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 -- morto ou já com vida cheia: não desperdiça o item
end
-- Tira o item primeiro, e só cura se isso funcionou
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)
| Pedido | O cliente manda | O servidor confere antes de agir |
|---|---|---|
EquipItem | Um id de item | É uma string, o item existe, o jogador tem um, os pedidos não chegam mais rápido que quatro por segundo, o item tem um toolName, e há uma Tool com esse nome em ServerStorage.ItemTools |
UseItem | Um id de item | As mesmas checagens de tipo, posse e frequência, o item tem um valor heal, o personagem está vivo e ferido, e um item foi removido antes de qualquer vida ser dada |
Três detalhes impedem que uma Tool seja duplicada ou perdida. A cópia tem CanBeDropped em false, porque uma Tool largada cai no Workspace, onde outro jogador poderia pegar enquanto a original continua no inventário. Cada cópia leva um atributo InventoryItem, então desequipar consegue achar e destruir todas as cópias onde quer que estejam. E quando o jogador tem um container StarterGear, uma segunda cópia vai para ele. A Roblox copia o StarterGear para a Backpack toda vez que o personagem nasce, então uma espada equipada volta depois de um respawn.
Só uma Tool fica equipada por vez, e o que está equipado não é salvo, então um jogador que entra de novo começa com a hotbar vazia. Se depois você adicionar venda ou largar itens, desequipe um item antes que a última cópia dele saia do inventário.
A Sword provisória pode virar uma que luta de verdade: monte a Tool do guia de espada, mantenha o nome Sword e coloque em ItemTools no lugar da provisória. O script de servidor daquele guia então confere cada golpe, não importa como o jogador conseguiu a espada.
Passo 7: Desenhe a grade do inventário
O LocalScript monta a janela inteira em código, então não há UI para montar à mão. Um ScrollingFrame guarda os slots, um UIGridLayout dentro dele organiza os slots em linhas, e o AutomaticCanvasSize aumenta a área de rolagem conforme as linhas são adicionadas.
No Explorer, abra o StarterPlayer, insira um LocalScript no StarterPlayerScripts e chame de 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. Monta a janela uma vez. ResetOnSpawn = false mantém ela depois de respawns.
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() -- o AutomaticCanvasSize aumenta para caber as células
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. Uma célula por slot. Isto só desenha o que o servidor mandou; nunca
-- muda o inventário por conta própria.
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 -- um slot vazio
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()
-- Pede, nunca manda: o servidor confere o pedido e devolve o resultado
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
-- O servidor dispara isto depois de carregar e depois de cada mudança
inventoryUpdated.OnClientEvent:Connect(render)
-- 3. Abre e fecha com o botão ou com a tecla 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)
Um LocalScript no StarterPlayerScripts roda uma vez por sessão, e ResetOnSpawn = false mantém a ScreenGui quando o personagem renasce, então a grade continua mostrando a última cópia que o servidor mandou.
O cliente desenha uma célula para cada slot, inclusive os vazios, então um inventário de 20 slots sempre parece ter 20 slots. Cada atualização destrói as células antigas e monta novas, o que é simples e serve bem para algumas dezenas de slots. Se o servidor disparar InventoryUpdated antes de este script se conectar a ele, a Roblox guarda a mensagem na fila e entrega quando o handler se conecta, então o primeiro inventário não se perde.
Prefere desenhar a janela no Studio? Monte uma ScreenGui com um slot modelo e faça Clone dele no makeCell. Para ícones, defina o icon de um item no catálogo como uma imagem que você enviou, e a célula dele mostra a imagem em vez do nome.
Teste o inventário
- Aperte Play. Abra o inventário com o botão à esquerda ou com B: um jogador novo tem uma Sword e 3 Apples, e o contador mostra 2 / 20 slots. Enquanto o Studio não acessar data stores, os itens demoram alguns segundos para aparecer, depois de avisos de carga no Output, e não são salvos.
- Clique na Sword. Ela aparece na sua mão e na hotbar, e o slot dela ganha um contorno roxo. Clique de novo para guardar.
- Ande até a part Apple e use o prompt dela. A pilha de maçãs sobe para 4, e a part some por 15 segundos.
- Para testar a cura, baixe sua vida primeiro. Mude o botão Client/Server para Server, selecione o
Humanoiddo seu personagem no Explorer, defina Health como 50, volte para Client e clique em uma Apple. - Com o acesso do Studio às API services ligado, pare e jogue de novo. A maçã que você coletou continua lá. Se uma carga ou um save falhou, o Output avisa.
Para ver com mais de um jogador, escolha Server & Clients nas opções de teste com 2 clientes. Cada jogador vê só o próprio inventário, mas os dois conseguem ver uma espada na mão do outro.
Erros comuns e como resolver
A maioria dos problemas aparece na janela Output como um aviso ou uma linha vermelha de erro. Leia o primeiro: os erros seguintes muitas vezes são consequência dele.
Infinite yield possible em uma chamada de WaitForChild
Um script está esperando um objeto que não existe com aquele nome exato. Compare o seu Explorer com a árvore do Passo 1: InventoryRemotes com os três RemoteEvents no ReplicatedStorage, ItemTools no ServerStorage, e os dois módulos. Os nomes diferenciam maiúsculas de minúsculas. O guia de erros de script explica esse aviso com mais detalhes.
A grade abre, mas fica vazia
O cliente só desenha o que o servidor manda. Procure avisos Inventory load failed no Output, e confira se o InventoryData é um Script, não um LocalScript, no ServerScriptService, com o ModuleScript InventoryService ao lado. Se o Output mostra um erro Remote event invocation, nada no cliente está escutando o InventoryUpdated: procure um erro anterior vindo do InventoryClient.
Os itens resetam toda vez que jogo no Studio
Se o Output diz Inventory not loaded: playing with starter items that will not be saved, o place não está publicado ou o acesso do Studio às API services está desligado. Ligue como descrito no Passo 4, em uma cópia de teste do seu jogo.
Clicar na espada não faz nada
Procure Cannot equip sword no Output: a Tool em ServerStorage.ItemTools precisa ter exatamente o mesmo nome que o toolName no catálogo. Uma Tool também precisa de uma part chamada Handle para ser segurada, a não ser que você defina o RequiresHandle dela como false.
O prompt do item aparece, mas nada é adicionado
O atributo ItemId precisa ser igual a um id do catálogo exatamente, inclusive as maiúsculas: apple, não Apple. Nada é adicionado enquanto o inventário do jogador ainda está carregando, ou quando não há espaço para a quantidade inteira.
O save falha depois que mudei o que é salvo
Data stores aceitam dados simples: strings, números, booleanos e tabelas deles. Salvar uma Tool, uma Part ou qualquer outra Instance falha, ou o valor é guardado como nil. Salve o id e a quantidade do item, e reconstrua todo o resto a partir do catálogo, como faz o serialize.
Crie com o RoCode
Se você prefere descrever o sistema em vez de ligar tudo à mão, o RoCode pode construir ele no place que você tem aberto. É um agente de IA para Roblox Studio: você descreve a função em um chat na web, e o plugin dele para o Studio cria os scripts e os objetos no seu Explorer em vez de te entregar código para colar.
Adicione um inventário com 20 slots que empilha itens, uma grade de UI que abre com B, uma espada do ServerStorage que os jogadores podem equipar, maçãs que curam, e salvamento com DataStoreService.
- Pode olhar o seu place quando um passo precisa, com Search Game e Search Scripts, para aproveitar itens, remotes ou código de salvamento que você já tem em vez de adicionar um segundo sistema
- Cria as pastas e os RemoteEvents com Create Instance, e os ModuleScripts, Scripts e o LocalScript com Create Script
- Pode montar a base da janela com Build UI, que tem um layout de inventário com slots provisórios; o código que preenche os slots a partir do servidor é escrito em scripts separados
- Checa a compilação de cada script dentro do Studio com Check Script, que pega erros de compilação e alguns padrões arriscados, mas não verifica tipos, não faz lint e não roda o seu código
Cada lote de mudanças é um ponto de desfazer no Studio. O RoCode não consegue ligar o acesso do Studio às API services, então isso você faz. Com o plugin 3.9 ou mais recente ele pode rodar um teste curto e ler os erros, e com o plugin 3.9.15 ou mais recente o personagem de teste dele consegue apertar teclas e equipar itens, mas ele confere só o que escolheu testar, então teste o salvamento você mesmo. Um inventário fica em cima de outros sistemas, como salvamento e tools, e um criador de jogos com IA que constrói no seu próprio place do Studio adiciona esses sistemas um prompt de cada vez. Como o RoCode se conecta ao Studio.
Perguntas frequentes
Devo usar a Backpack do Roblox em vez de um inventário próprio?
A Backpack é o inventário que já vem no Roblox: toda Tool nela aparece como um botão na hotbar. Se todo item do seu jogo é uma Tool e você não precisa de pilhas, quantidades nem limite de slots, ela pode bastar, mas você ainda tem que salvar quais Tools cada jogador tem. Um inventário próprio serve para itens que não são Tools, como materiais e consumíveis. Este guia usa os dois: o inventário guarda tudo, e a Backpack segura a Tool que estiver equipada.
Dá para esconder a hotbar padrão?
Sim. Em um LocalScript, chame StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.Backpack, false). Com a hotbar escondida, os jogadores precisam de outro jeito de segurar e guardar uma Tool equipada, por exemplo um botão que pede ao servidor para chamar Humanoid:EquipTool ou Humanoid:UnequipTools.
Como fazer os slots manterem a posição para arrastar e soltar?
Guarde uma lista de tamanho fixo com uma entrada por slot, e marque os slots vazios com um valor como um id vazio em vez de nil, porque a Roblox desaconselha valores nil em tabelas enviadas por um RemoteEvent. Depois adicione um RemoteEvent MoveItem que manda dois números de slot, e faça o servidor conferir se os dois são números inteiros entre 1 e a capacidade antes de trocar os slots.
Qual o tamanho máximo de um inventário salvo?
Um valor de data store pode ter até 4.194.304 caracteres depois de serializado (conforme documentado em 30 de setembro de 2026). Uma lista de ids e quantidades usa uma parte minúscula disso. Texto por item, como nomes personalizados ou descrições longas salvas para cada item, é o que faz um save crescer.
Como comprar ou vender itens por moedas?
Faça tudo no servidor. Para vender, chame InventoryService.remove e só pague se ele devolveu true. Para comprar, confira o preço e o spaceFor, tire as moedas e depois chame add. O guia de loja monta a parte da compra.
Fontes e leitura extra
- Roblox Creator Docs: Remote events and callbacks (em inglês). FireClient, OnServerEvent, limites de argumentos e como mensagens não entregues entram na fila
- Roblox Creator Docs: Securing the client-server boundary (em inglês). validar o que chega pelos remotes, checagens de ProximityPrompt e manipulação de data stores
- Roblox Creator Docs: Data stores (em inglês). GetAsync, SetAsync e como ligar o acesso do Studio
- Roblox Creator Docs: Best practices for data stores (em inglês). uma chave por jogador, padrões de chave e saves periódicos
- Roblox Creator Docs: Data store error codes and limits (em inglês). limites de pedidos por servidor e o tamanho máximo de um valor
- Roblox Creator Docs: In-game tools (em inglês). handles, ancoragem, a Backpack e o StarterGear
- Roblox Creator Docs: Grid and table layouts (em inglês). tamanho das células, espaçamento e ordem do UIGridLayout
Como o código foi verificado: todo script desta página passa no verificador de tipos estrito do Luau com as definições da API do Roblox (luau-lsp, 14 de novembro de 2026). A verificação de tipos pega APIs com nome errado e tipos incorretos, não a lógica do jogo, então teste no Studio antes de publicar.