Tutorial · Sistemas de jogo

Como fazer um sistema de inventário no Roblox Studio

Um inventário parece trabalho de UI, mas o que decide se o seu pode ser explorado por trapaceiros, ou se perde itens, é onde os itens ficam. Este guia guarda os itens de cada jogador em uma tabela no servidor, manda para cada jogador uma cópia para desenhar como grade, deixa ele equipar Tools e usar consumíveis por pedidos que o servidor confere, e salva tudo com um data store.

Atualizado em 14 de novembro de 202617 min de leituraEscrito por

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
  1. Como se encaixa
  2. Por que o servidor manda
  3. 1. Monte o Explorer
  4. 2. Catálogo de itens
  5. 3. Inventário no servidor
  6. 4. Carregar e salvar
  7. 5. Itens coletáveis
  8. 6. Equipar e usar
  9. 7. Grade de UI
  10. Teste
  11. Erros comuns
  12. Com o RoCode
  13. Perguntas frequentes
  14. Fontes e leitura extra

Como as peças do inventário se encaixam

IlustraçãoAperte B, passe o mouse em um item para ler o que ele faz e clique na Sword para segurar.

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.

As peças e onde elas rodam
PeçaTipo e lugarFunção
ItemCatalogModuleScript no ReplicatedStorageO que cada item é: nome, descrição, pilha máxima e se dá para equipar ou usar. O servidor e todos os clientes leem.
InventoryServiceModuleScript no ServerScriptServiceGuarda os slots de todos os jogadores. O único código que adiciona, remove e empilha itens.
InventoryDataScript no ServerScriptServiceCarrega os itens de um jogador quando ele entra e salva.
InventoryActionsScript no ServerScriptServiceConfere e executa os pedidos de equipar e usar.
ItemPickupScript dentro de uma PartDá um item para quem coletar.
InventoryClientLocalScript no StarterPlayerScriptsDesenha 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.

  1. No ReplicatedStorage, insira uma Folder chamada InventoryRemotes. Dentro dela, insira três RemoteEvents chamados InventoryUpdated, EquipItem e UseItem.
  2. No ServerStorage, insira uma Folder chamada ItemTools. Dentro dela, insira uma Tool chamada Sword, e dentro da Tool uma Part chamada Handle (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.
  3. Adicione os scripts conforme chegar em cada passo. A árvore mostra onde cada um vai.
O Explorer depois deste guia
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:

ModuleScript em ReplicatedStorage chamado ItemCatalog
-- 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:

ModuleScript em ServerScriptService chamado 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, add adiciona o que cabe e devolve esse número. Chame spaceFor antes 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 devolve false, 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.
O que outros scripts de servidor podem chamar
FunçãoDevolveUse para
add(player, itemId, amount)Quantos foram adicionadosItens coletados, recompensas, compras
remove(player, itemId, amount)true se todos foram removidosUsar, vender, craftar
count(player, itemId)O total somando todas as pilhasConferir o que um jogador tem
spaceFor(player, itemId)Quantos mais caberiamConferir antes de um add tudo ou nada
getEquipped, setEquippedO id do item equipado, ou nilEquipar, no Passo 6
load, serialize, unloadUma 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:

Script em ServerScriptService chamado 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 GetAsync devolve 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 canSave sã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 BindToClose salva 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 o SetAsync liga 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.

  1. Adicione uma Part ao Workspace, chame de Apple e pinte de vermelho. Ligue Anchored e desligue CanCollide, para ninguém esbarrar nela enquanto estiver invisível. O prompt mostra o nome da part.
  2. Com a part selecionada, desça até a seção Attributes da janela Properties e clique em +. Adicione ItemId com o tipo string e clique em Save, depois defina o valor como apple. Adicione Amount do mesmo jeito, como number com valor 1.
  3. Insira um Script na part, chame de ItemPickup e cole este código:
Script em a Part Apple no Workspace chamado ItemPickup
-- 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:

Script em ServerScriptService chamado 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)
O que cada pedido pode fazer
PedidoO cliente mandaO servidor confere antes de agir
EquipItemUm 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
UseItemUm id de itemAs 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:

LocalScript em StarterPlayerScripts chamado 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

  1. 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.
  2. 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.
  3. 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.
  4. Para testar a cura, baixe sua vida primeiro. Mude o botão Client/Server para Server, selecione o Humanoid do seu personagem no Explorer, defina Health como 50, volte para Client e clique em uma Apple.
  5. 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.

Você digita

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.

O RoCode faz
  • 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

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.

Teste o RoCode no seu próprio jogo.

Créditos grátis todo dia, sem cartão. Instale o plugin, descreva o recurso e confira o que aparece no Studio.