La respuesta corta
Guarda los objetos de cada jugador en una tabla en el servidor, dentro de un ModuleScript en ServerScriptService que sea el único código con permiso para añadirlos, quitarlos o apilarlos. Lista tus objetos una sola vez en un ModuleScript en ReplicatedStorage (id, nombre, pila máxima). Después de cada cambio, el servidor dispara un RemoteEvent a ese jugador con una copia de su inventario, y un LocalScript lo dibuja como cuadrícula con un ScrollingFrame y un UIGridLayout.
- El cliente nunca añade objetos. Solo puede pedir, por ejemplo "equipa mi espada", y el servidor comprueba que el jugador tiene una antes de actuar.
- Los objetos solo llegan a través de código del servidor que tú controlas: objetos que se recogen, compras de la tienda que el servidor ha comprobado, recompensas.
- Guarda ids de objetos y cantidades, no Tools, con DataStoreService cuando el jugador sale, cuando el servidor se apaga y cada pocos minutos. Nunca guardes a un jugador cuyos datos no se cargaron.
En esta página
Cómo encaja el inventario
El sistema son seis piezas pequeñas, cada una con un trabajo. Todas las reglas sobre objetos viven en un módulo del servidor, así que cuando algo falla hay un solo sitio donde mirar.
| Pieza | Tipo y ubicación | Trabajo |
|---|---|---|
ItemCatalog | ModuleScript en ReplicatedStorage | Qué es cada objeto: nombre, descripción, pila máxima y si se puede equipar o usar. Lo leen el servidor y todos los clientes. |
InventoryService | ModuleScript en ServerScriptService | Guarda los espacios de cada jugador. Es el único código que añade, quita y apila objetos. |
InventoryData | Script en ServerScriptService | Carga los objetos de un jugador cuando entra y los guarda. |
InventoryActions | Script en ServerScriptService | Comprueba y ejecuta las peticiones de equipar y usar. |
ItemPickup | Script dentro de una Part | Da un objeto a quien lo recoja. |
InventoryClient | LocalScript en StarterPlayerScripts | Dibuja la cuadrícula y envía peticiones. No cambia nada por sí mismo. |
Los datos van en una sola dirección. El servidor cambia un inventario, luego dispara InventoryUpdated a ese jugador con el inventario entero, y el cliente vuelve a dibujar a partir de él. Cuando el jugador hace clic en un espacio, el cliente dispara EquipItem o UseItem con el id del objeto; el servidor comprueba la petición, hace el cambio y la copia nueva llega de la misma forma. Enviar el inventario entero es más sencillo que enviar los cambios, y con unas pocas decenas de espacios el mensaje sigue siendo pequeño.
Por qué el cliente nunca añade objetos
Es tentador añadir un objeto en el LocalScript que lo muestra: el jugador hace clic y el espacio se llena. Eso falla de dos maneras.
- Nadie más lo ve. Un cambio hecho en un LocalScript existe solo en el dispositivo de ese jugador. El servidor nunca se entera, así que no se guarda y ningún script del servidor lo puede usar.
- Cualquiera lo puede falsificar. Si lo arreglas con un RemoteEvent como
AddItem(itemId, amount), un exploiter puede disparar ese evento por su cuenta, con los argumentos que quiera y tantas veces como quiera. La guía de seguridad de Roblox dice que el servidor debe validar todo lo que envía un cliente antes de usarlo.
Por eso en esta guía el cliente solo puede hacer peticiones sobre objetos que el jugador ya tiene: "equipa esto" y "usa esto". Cada petición lleva un id de objeto y ninguna cantidad, y pasa una comprobación en el servidor: que sea un string, que sea un objeto real, que el jugador tenga al menos uno y que no envíe más de cuatro peticiones por segundo. Después el servidor busca la Tool por su cuenta en el catálogo. Nunca acepta una Tool, una ruta ni una instancia del cliente, algo que la misma guía desaconseja.
Los objetos entran solo por código del servidor: algo que se recoge y el servidor ha comprobado, una compra que el servidor ha cobrado (la guía de la tienda construye una), una recompensa de misión o un drop. Para el patrón de RemoteEvent en general, con validación para otros tipos de argumentos, lee la guía de RemoteEvents.
Paso 1: Prepara el Explorer
Crea estos objetos a mano. Los scripts de los pasos siguientes los buscan por nombre, así que escribe cada nombre exactamente como aparece.
- En ReplicatedStorage, inserta una Folder llamada
InventoryRemotes. Dentro, inserta tres RemoteEvents llamadosInventoryUpdated,EquipItemyUseItem. - En ServerStorage, inserta una Folder llamada
ItemTools. Dentro, inserta una Tool llamadaSword, y dentro de la Tool una Part llamadaHandle(1 por 4 por 1 studs está bien). Asegúrate de que la casilla Anchored del Handle esté desmarcada: Roblox avisa de que los personajes se quedan atascados cuando sostienen una tool con partes ancladas. También sirve una Tool que ya tengas, siempre que su nombre coincida con el catálogo del Paso 2. - Añade los scripts a medida que llegues a cada paso. El árbol muestra dónde va cada uno.
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
Paso 2: Lista tus objetos en un catálogo
El catálogo describe una sola vez cada objeto que puede existir. Los inventarios guardan solo el id del objeto y una cantidad. Así los guardados son pequeños, y puedes cambiar el nombre de un objeto o reescribir su descripción más adelante sin tocar los datos guardados de nadie.
Inserta un ModuleScript en ReplicatedStorage, llámalo ItemCatalog y reemplaza su contenido por esto:
-- Todos los objetos que pueden existir en el juego. El servidor y todos los clientes leen esta
-- lista; solo el servidor decide quién tiene qué.
export type Item = {
id: string, -- debe coincidir con la clave de abajo
name: string,
description: string,
maxStack: number, -- la cantidad máxima de este objeto que cabe en un espacio
icon: string?, -- imagen opcional, escrita como "rbxassetid://" más el ID de tu imagen
toolName: string?, -- una Tool en ServerStorage.ItemTools: el objeto se puede equipar
heal: number?, -- vida que recupera al usarlo: el objeto es un consumible
}
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 = {}
-- Devuelve el objeto con este id, o nil si no existe ningún objeto así
function ItemCatalog.get(id: string): Item?
return items[id]
end
return ItemCatalog
Los campos opcionales deciden qué hace un objeto. toolName lo hace equipable, heal lo hace usable, y un objeto sin ninguno de los dos, como la madera, se queda en el inventario hasta que otro código del servidor (crafteo, venta) lo quite.
Para añadir un objeto, añade una entrada cuya clave y cuyo id coincidan. Los ids distinguen mayúsculas y minúsculas y son lo que se guarda, así que nunca cambies un id cuando los jugadores ya tienen el objeto: cambia su name.
Paso 3: Guarda los inventarios en el servidor
Este ModuleScript es dueño del inventario de cada jugador. Cada inventario es una lista de espacios, cada espacio un id de objeto y una cantidad, más una capacidad de 20 espacios. Otros scripts del servidor llaman a sus funciones, y nada más edita la tabla.
Inserta un ModuleScript en ServerScriptService y llámalo InventoryService:
-- El único código que cambia inventarios. Está en ServerScriptService,
-- donde los clientes no lo pueden ver ni ejecutar.
local ReplicatedStorage = game:GetService("ReplicatedStorage")
-- El modo estricto no puede seguir un require a través de WaitForChild, así que indicamos
-- la parte del módulo que usa este script
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 -- espacios por jugador
local STARTER_ITEMS: { Slot } = { -- con qué empieza un jugador nuevo
{ id = "sword", count = 1 },
{ id = "apple", count = 3 },
}
local inventories: { [Player]: Inventory } = {}
local InventoryService = {}
-- Envía al dueño una copia de su inventario. Se ejecuta después de cada cambio.
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
-- Reglas de apilado: rellena las pilas que no están llenas y luego empieza pilas nuevas en
-- espacios vacíos. Devuelve cuántos se añadieron, que pueden ser menos de los pedidos.
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
-- Cuántos más caben de un objeto: el hueco que queda en sus pilas más los espacios vacíos
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
-- Añade hasta amount unidades de un objeto. Devuelve cuántas se añadieron (0 si el
-- objeto no existe, el inventario está lleno o todavía no se ha cargado).
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
-- Quita exactamente amount unidades de un objeto, empezando por las últimas pilas.
-- Si el jugador tiene menos, no quita nada y devuelve 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
-- Recorre la lista hacia atrás para que table.remove nunca se salte un espacio
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
-- Se llama una vez cuando se han cargado los datos guardados de un jugador. saved es lo que
-- devolvió el data store: nil para un jugador nuevo. Cada entrada vuelve a pasar por las
-- reglas de apilado, así que objetos eliminados y tamaños de pila antiguos no rompen 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
-- Una copia simple para guardar, o nil si los datos de este jugador nunca se cargaron
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
Las líneas type y el cast :: después de require solo ayudan al comprobador de tipos de Luau, que no puede ver lo que devuelve un módulo encontrado con WaitForChild. No cambian nada cuando el juego se ejecuta. Los demás scripts de esta guía hacen lo mismo.
Así funcionan las reglas de apilado con el catálogo de arriba, donde las manzanas se apilan hasta 10:
- Si añades 15 manzanas a un jugador que tiene una pila de 7, esa pila se llena hasta 10 y luego empieza una pila nueva de 5.
- Cuando se acaban los espacios,
addañade lo que cabe y devuelve ese número. Llama antes aspaceForcuando tenga que ser todo o nada, como hace el objeto para recoger del Paso 5. removees todo o nada. Pedir 3 manzanas a un jugador que tiene 2 no quita ninguna y devuelvefalse, así que comprueba el resultado antes de dar algo a cambio.- Los espacios no tienen huecos: cuando uno se vacía, los demás suben. Así la lista es fácil de enviar y guardar. Las preguntas del final explican cómo hacer espacios que mantienen su posición.
| Función | Devuelve | Úsala para |
|---|---|---|
add(player, itemId, amount) | Cuántos se añadieron | Objetos recogidos, recompensas, compras |
remove(player, itemId, amount) | true si se quitaron todos | Usar, vender, craftear |
count(player, itemId) | El total sumando todas las pilas | Comprobar qué tiene un jugador |
spaceFor(player, itemId) | Cuántos más cabrían | Comprobar antes de añadir todo o nada |
getEquipped, setEquipped | El id del objeto equipado, o nil | Equipar, en el Paso 6 |
load, serialize, unload | Una copia lista para guardar (serialize) | Cargar y guardar, en el Paso 4 |
Paso 4: Carga y guarda cada inventario
Los inventarios viven en la memoria del servidor, así que desaparecen cuando el jugador sale. Este script carga los espacios de un jugador desde un data store cuando entra y los vuelve a escribir cuando sale, cuando el servidor se apaga y cada tres minutos por si el servidor se cae. Solo guarda ids de objetos y cantidades: los data stores no pueden guardar Instances como las Tools.
Inserta un Script en ServerScriptService y llámalo 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
-- Solo se guardan los jugadores cuyos datos guardados se cargaron. Después de una carga fallida
-- nunca debe haber un guardado, o el inventario vacío reemplaza al real.
local canSave: { [Player]: boolean } = {}
local activeSaves = 0
local function keyFor(player: Player): string
return "User_" .. player.UserId
end
-- Una petición fallida no debería costarle a nadie sus objetos, así que reintenta unas veces.
-- GetDataStore también está dentro del pcall, así que una sesión de Studio que no puede
-- usar data stores recibe una advertencia en vez de detener 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 -- salió mientras cargábamos
end
if ok then
InventoryService.load(player, saved) -- saved es nil para un jugador nuevo
canSave[player] = true
elseif RunService:IsStudio() then
-- Suele significar que el acceso de Studio a los servicios de API está desactivado. Juega con
-- los objetos iniciales para poder probar, pero nunca los guardes.
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 -- sus datos nunca se cargaron, así que no hay nada seguro que escribir
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)
-- Cuando el servidor se apaga, guarda a todos los que siguen aquí y luego espera a cada
-- guardado en curso, incluidos los que empezó PlayerRemoving
game:BindToClose(function()
for _, player in Players:GetPlayers() do
task.spawn(save, player)
end
while activeSaves > 0 do
task.wait()
end
end)
-- Guarda a todos cada pocos minutos, así una caída del servidor cuesta minutos, no una sesión
while true do
task.wait(AUTOSAVE_SECONDS)
for _, player in Players:GetPlayers() do
task.spawn(save, player)
end
end
Qué hace el script, y por qué:
- Carga con valores por defecto. Un jugador nuevo no tiene nada guardado, así que
GetAsyncdevuelve nil y recibe los objetos iniciales. Los espacios guardados vuelven a pasar por las reglas de apilado, así que un objeto que quitaste del catálogo o una pila máxima más pequeña no pueden romper una carga. Lo que ya no cabe, o cuyo id ya no está en el catálogo, se descarta, y el siguiente guardado lo hace permanente, así que mantén en el catálogo todos los ids que los jugadores puedan tener. - Nunca guardes después de una carga fallida. Solo se escriben los jugadores que están en
canSave. En un servidor en vivo, a un jugador cuyos datos siguen sin cargar después de tres intentos se le pide que vuelva a entrar. En Studio recibe objetos iniciales sin guardar, unos segundos tarde por los reintentos, y eso es lo que verás hasta que el place esté publicado con el acceso a la API activado. - Guarda al salir y al apagar.
BindToCloseguarda a todos los que siguen en el servidor y espera a los guardados que ya están en marcha. Roblox da a las funciones enlazadas hasta 30 segundos. - Mantente dentro de los límites. Una escritura por jugador cada tres minutos, más una cuando sale, queda muy por debajo del presupuesto por defecto por servidor de 60 escrituras por minuto más 40 por cada jugador (según la documentación del 30 de septiembre de 2026). El patrón de clave
User_sigue las buenas prácticas de Roblox, y pasar el user ID aSetAsyncvincula los datos con ese jugador, algo que Roblox recomienda mucho para atender las solicitudes de borrado de datos.
Es una buena base para un juego pequeño. El bloqueo de sesión, que impide que un jugador que cambia de servidor muy rápido cargue sus datos antes de que el servidor anterior los haya guardado, y cuándo usar UpdateAsync en vez de SetAsync, se explican en el tutorial de DataStore.
Paso 5: Da objetos desde el mundo
Un objeto para recoger es la forma más sencilla de que entren objetos en un inventario: una parte con un ProximityPrompt que añade un objeto cuando un jugador lo usa. El script escucha su evento Triggered en el servidor, así que el objeto se añade donde el cliente no puede interferir.
- Añade una Part a Workspace, llámala
Appley píntala de rojo. Marca Anchored y desmarca CanCollide, para que nadie choque con ella mientras es invisible. El prompt muestra el nombre de la parte. - Con la parte seleccionada, baja hasta la sección Attributes de la ventana Properties y haz clic en +. Añade
ItemIdcon el tipo string y haz clic en Save, luego pon su valor enapple. AñadeAmountde la misma forma como number con el valor1. - Inserta un Script en la parte, llámalo
ItemPickupy pega este código:
-- Pon este Script dentro de una Part y dale a la Part dos atributos:
-- ItemId (un string, como apple) y Amount (un 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 -- otra persona lo recogió hace un momento
end
-- Comprueba la distancia en el servidor en vez de fiarte de la petición
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 -- no hay sitio suficiente: deja el objeto donde está
end
InventoryService.add(player, itemId, amount)
prompt.Enabled = false
part.Transparency = 1
task.wait(RESPAWN_SECONDS)
part.Transparency = visibleTransparency
prompt.Enabled = true
end)
Copia la parte para poner más objetos para recoger. Cambia los atributos para dar madera, otra espada o una pila de manzanas.
Roblox comprueba la distancia para Triggered, pero su guía de seguridad igualmente dice que valides los prompts en el servidor: un exploiter puede disparar los eventos de un prompt incluso con Enabled en false, y puede acercar una parte sin anclar a su personaje. Por eso el script comprueba Enabled y la distancia por su cuenta, y por eso la parte está anclada.
Cualquier otro script del servidor da objetos de la misma forma. Después de una compra, una misión o una eliminación, haz require de InventoryService como los scripts de arriba y llama a InventoryService.add(player, "wood", 5). Comprueba antes spaceFor siempre que el objeto no se pueda perder. Un NPC puede ser otra fuente: en la guía de diálogo de NPC, una respuesta ejecuta una acción en el servidor, y esa acción puede llamar a InventoryService.add de la misma forma.
Paso 6: Equipa Tools y usa objetos
Dos RemoteEvents llevan las únicas peticiones que puede hacer un cliente. EquipItem pone una copia de la Tool del objeto desde ServerStorage en la Backpack del jugador (la hotbar de la parte de abajo de la pantalla) y en su mano, y pedirlo otra vez se la quita. UseItem quita una unidad de un objeto usable y aplica su efecto, que aquí es curar.
Inserta un Script en ServerScriptService y llámalo 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 } = {}
-- Todas las peticiones empiezan aquí. Un cliente puede enviar cualquier cosa en cualquier momento, así que
-- comprueba el tipo, que el objeto existe, que el jugador tiene uno, y el ritmo.
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
-- Destruye la Tool de este objeto esté donde esté la copia: hotbar, mano o 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) -- una sola tool equipada a la vez
local tool = template:Clone()
tool.CanBeDropped = false -- otra persona podría recoger una copia soltada
tool:SetAttribute("InventoryItem", item.id)
tool.Parent = backpack
-- Una segunda copia en StarterGear se vuelve a copiar a la Backpack después de reaparecer
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) -- la pone directamente en su mano
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) -- hacer clic otra vez en el objeto equipado lo guarda
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 -- muerto o con la vida llena: no malgastes el objeto
end
-- Quita primero el objeto, y cura solo si eso funcionó
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)
| Petición | El cliente envía | El servidor comprueba antes de actuar |
|---|---|---|
EquipItem | Un id de objeto | Que es un string, que el objeto existe, que el jugador tiene uno, que las peticiones no llegan más rápido que cuatro por segundo, que el objeto tiene un toolName y que hay una Tool con ese nombre en ServerStorage.ItemTools |
UseItem | Un id de objeto | Las mismas comprobaciones de tipo, propiedad y ritmo, que el objeto tiene un valor heal, que el personaje está vivo y herido, y que se quitó un objeto antes de dar vida |
Tres detalles evitan que una Tool se duplique o se pierda. La copia tiene CanBeDropped en false, porque una Tool soltada cae en Workspace, donde otro jugador podría cogerla mientras el original sigue en el inventario. Cada copia lleva un atributo InventoryItem, así que al desequipar se pueden encontrar y destruir todas las copias estén donde estén. Y cuando el jugador tiene un contenedor StarterGear, va una segunda copia dentro. Roblox copia StarterGear a la Backpack cada vez que aparece el personaje, así que una espada equipada vuelve después de reaparecer.
Solo se equipa una Tool a la vez, y lo que está equipado no se guarda, así que un jugador que vuelve a entrar empieza con la hotbar vacía. Si más adelante añades vender o soltar objetos, desequipa un objeto antes de que su última copia salga del inventario.
La Sword de ejemplo puede convertirse en una que luche de verdad: construye la Tool de la guía de la espada, deja su nombre como Sword y ponla en ItemTools en lugar de la de ejemplo. El script del servidor de esa guía comprueba entonces cada golpe, sin importar cómo consiguió el jugador la espada.
Paso 7: Dibuja la cuadrícula del inventario
El LocalScript construye toda la ventana con código, así que no hay que montar ninguna UI a mano. Un ScrollingFrame contiene los espacios, un UIGridLayout dentro los ordena en filas, y AutomaticCanvasSize hace crecer la zona de desplazamiento a medida que se añaden filas.
En el Explorer, abre StarterPlayer, inserta un LocalScript en StarterPlayerScripts y llámalo 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. Construye la ventana una vez. ResetOnSpawn = false la mantiene al reaparecer.
local gui = Instance.new("ScreenGui")
gui.Name = "InventoryGui"
gui.ResetOnSpawn = false
gui.Parent = player:WaitForChild("PlayerGui")
local openButton = Instance.new("TextButton")
openButton.AnchorPoint = Vector2.new(0, 0.5)
openButton.Position = UDim2.new(0, 16, 0.5, 0)
openButton.Size = UDim2.fromOffset(140, 40)
openButton.BackgroundColor3 = COLOURS.panel
openButton.Font = Enum.Font.BuilderSansBold
openButton.TextColor3 = COLOURS.text
openButton.TextSize = 18
openButton.Text = "Inventory (B)"
addCorner(openButton, 8)
openButton.Parent = gui
local panel = Instance.new("Frame")
panel.AnchorPoint = Vector2.new(0.5, 0.5)
panel.Position = UDim2.fromScale(0.5, 0.5)
panel.Size = UDim2.fromScale(0.9, 0.8)
panel.BackgroundColor3 = COLOURS.panel
panel.Visible = false
addCorner(panel, 12)
panel.Parent = gui
local sizeLimit = Instance.new("UISizeConstraint")
sizeLimit.MaxSize = Vector2.new(440, 400)
sizeLimit.Parent = panel
local title = makeLabel(panel, "Inventory", 22)
title.Position = UDim2.fromOffset(16, 8)
title.Size = UDim2.new(1, -32, 0, 32)
title.TextXAlignment = Enum.TextXAlignment.Left
local slotCount = makeLabel(panel, "", 16)
slotCount.Position = UDim2.fromOffset(16, 8)
slotCount.Size = UDim2.new(1, -32, 0, 32)
slotCount.TextColor3 = COLOURS.muted
slotCount.TextXAlignment = Enum.TextXAlignment.Right
local grid = Instance.new("ScrollingFrame")
grid.Position = UDim2.fromOffset(12, 48)
grid.Size = UDim2.new(1, -24, 1, -100)
grid.BackgroundTransparency = 1
grid.BorderSizePixel = 0
grid.CanvasSize = UDim2.new() -- AutomaticCanvasSize lo hace crecer para que quepan las celdas
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. Una celda por espacio. Esto solo dibuja lo que envió el servidor; nunca
-- cambia el inventario por sí mismo.
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 -- un espacio vacío
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()
-- Pide, nunca ordenes: el servidor comprueba la petición y devuelve el 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
-- El servidor dispara esto después de cargar y después de cada cambio
inventoryUpdated.OnClientEvent:Connect(render)
-- 3. Abre y cierra con el botón o con la 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)
Un LocalScript en StarterPlayerScripts se ejecuta una vez por sesión, y ResetOnSpawn = false mantiene la ScreenGui cuando el personaje reaparece, así que la cuadrícula sigue mostrando la última copia que envió el servidor.
El cliente dibuja una celda por cada espacio, también los vacíos, así que un inventario de 20 espacios siempre se ve como 20 espacios. Cada actualización destruye las celdas viejas y construye otras nuevas, algo simple que funciona bien con unas pocas decenas de espacios. Si el servidor dispara InventoryUpdated antes de que este script se haya conectado, Roblox pone el mensaje en cola y lo entrega cuando se conecta el manejador, así que el primer inventario no se pierde.
¿Prefieres diseñar la ventana en Studio? Construye una ScreenGui con un espacio de plantilla y haz Clone de él en makeCell. Para los iconos, pon en el icon de un objeto del catálogo una imagen que hayas subido, y su celda mostrará la imagen en vez del nombre.
Prueba el inventario
- Pulsa Play. Abre el inventario con el botón de la izquierda o con B: un jugador nuevo tiene una Sword y 3 Apples, y el contador dice 2 / 20 slots. Hasta que Studio pueda usar data stores, los objetos tardan unos segundos en aparecer, después de advertencias de carga en Output, y no se guardan.
- Haz clic en la Sword. Aparece en tu mano y en la hotbar, y su espacio recibe un borde morado. Haz clic otra vez para guardarla.
- Camina hasta la parte Apple y usa su prompt. La pila de manzanas sube a 4 y la parte desaparece durante 15 segundos.
- Para probar la curación, baja primero tu vida. Cambia el interruptor Client/Server a Server, selecciona el
Humanoidde tu personaje en el Explorer, pon Health en 50, vuelve a Client y haz clic en una Apple. - Con el acceso de Studio a los servicios de API activado, detén el juego y vuelve a jugar. La manzana que recogiste sigue ahí. Si una carga o un guardado falló, Output lo indica.
Para verlo con más de un jugador, elige Server & Clients en las opciones de prueba con 2 clientes. Cada jugador ve solo su propio inventario, pero los dos pueden ver una espada en la mano del otro.
Errores comunes y soluciones
La mayoría de los problemas aparecen en la ventana Output como una advertencia o una línea de error roja. Lee la primera: los errores posteriores suelen ser consecuencia de ella.
Infinite yield possible en una llamada a WaitForChild
Un script está esperando un objeto que no existe con ese nombre exacto. Compara tu Explorer con el árbol del Paso 1: InventoryRemotes con sus tres RemoteEvents en ReplicatedStorage, ItemTools en ServerStorage y los dos módulos. Los nombres distinguen mayúsculas y minúsculas. La guía de errores de scripts explica esta advertencia con más detalle.
La cuadrícula se abre pero sigue vacía
El cliente solo dibuja lo que envía el servidor. Busca advertencias Inventory load failed en Output, y comprueba que InventoryData es un Script, no un LocalScript, en ServerScriptService, con el ModuleScript InventoryService al lado. Si Output muestra un error Remote event invocation, nada en el cliente está escuchando InventoryUpdated: busca un error anterior de InventoryClient.
Los objetos se reinician cada vez que juego en Studio
Si Output dice Inventory not loaded: playing with starter items that will not be saved, el place no está publicado o el acceso de Studio a los servicios de API está desactivado. Actívalo como se explica en el Paso 4, en una copia de prueba de tu juego.
Hacer clic en la espada no hace nada
Busca Cannot equip sword en Output: la Tool en ServerStorage.ItemTools debe llamarse exactamente igual que toolName en el catálogo. Una Tool también necesita una parte llamada Handle para poder sostenerla, a menos que pongas su RequiresHandle en false.
El prompt para recoger aparece, pero no se añade nada
El atributo ItemId debe coincidir exactamente con un id del catálogo, mayúsculas incluidas: apple, no Apple. No se añade nada mientras el inventario del jugador todavía se está cargando, ni cuando no hay sitio para toda la cantidad.
El guardado falla después de cambiar lo que se guarda
Los data stores aceptan datos simples: strings, números, booleanos y tablas de ellos. Guardar una Tool, una Part o cualquier otra Instance falla, o el valor se guarda como nil. Guarda el id del objeto y la cantidad, y reconstruye todo lo demás a partir del catálogo, como hace serialize.
Constrúyelo con RoCode
Si prefieres describir el sistema en vez de montarlo a mano, RoCode puede construirlo en el place que tienes abierto. Es un agente de IA para Roblox Studio: describes la función en un chat web y su plugin de Studio crea los scripts y los objetos en tu Explorer, en vez de darte código para pegar.
Añade un inventario de 20 espacios que apile objetos, una UI en cuadrícula que se abra con B, una espada en ServerStorage que los jugadores puedan equipar, manzanas que curen y guardado con DataStoreService.
- Puede revisar tu place cuando un paso lo necesita, con Search Game y Search Scripts, para construir sobre los objetos, remotes o código de guardado que ya tienes en vez de añadir un segundo sistema
- Crea las carpetas y los RemoteEvents con Create Instance, y los ModuleScripts, Scripts y el LocalScript con Create Script
- Puede montar la ventana con Build UI, que tiene un diseño de inventario con espacios de ejemplo; el código que llena los espacios desde el servidor se escribe en scripts aparte
- Comprueba que cada script compila dentro de Studio con Check Script, que detecta errores de compilación y algunos patrones arriesgados, pero no comprueba tipos, no hace lint ni ejecuta tu código
Cada lote de cambios es un punto de deshacer en Studio. RoCode no puede activar el acceso de Studio a los servicios de API, así que eso lo haces tú. Con el plugin 3.9 o posterior puede hacer una prueba corta y leer los errores, y con el plugin 3.9.15 o posterior su personaje de prueba puede pulsar teclas y equipar objetos, pero solo comprueba lo que eligió probar, así que prueba tú mismo el guardado. Un inventario se apoya en otros sistemas, como el guardado y las tools, y un creador de juegos con IA que construye en tu propio place de Studio (en inglés) los añade de prompt en prompt. Cómo se conecta RoCode a Studio.
Preguntas frecuentes
¿Uso la Backpack de Roblox o hago un inventario propio?
La Backpack es el inventario integrado de Roblox: cada Tool que contiene aparece como un botón en la hotbar. Si todos los objetos de tu juego son Tools y no necesitas pilas, cantidades ni límite de espacios, puede bastar, aunque igualmente tienes que guardar qué Tools tiene cada jugador. Un inventario propio es para objetos que no son Tools, como materiales y consumibles. Esta guía usa los dos: el inventario lo guarda todo, y la Backpack contiene la Tool que está equipada.
¿Cómo oculto la hotbar por defecto de Roblox?
Desde un LocalScript, llama a StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.Backpack, false). Con la hotbar oculta, los jugadores necesitan otra forma de sostener y guardar una Tool equipada, por ejemplo un botón que le pida al servidor que llame a Humanoid:EquipTool o Humanoid:UnequipTools.
¿Cómo hago que los espacios mantengan su posición para arrastrar y soltar?
Guarda una lista de longitud fija con una entrada por espacio, y marca los espacios vacíos con un valor como un id vacío en vez de nil, porque Roblox desaconseja los valores nil en tablas que se envían por un RemoteEvent. Luego añade un RemoteEvent MoveItem que envíe dos números de espacio, y haz que el servidor compruebe que los dos son números enteros entre 1 y la capacidad antes de intercambiarlos.
¿Cuánto puede ocupar un inventario guardado?
Un valor de data store puede tener hasta 4,194,304 caracteres una vez serializado (según la documentación del 30 de septiembre de 2026). Una lista de ids y cantidades usa una parte minúscula de eso. Lo que hace crecer un guardado es el texto por objeto, como nombres personalizados o descripciones largas guardadas para cada objeto.
¿Cómo compro o vendo objetos por monedas?
Hazlo todo en el servidor. Para vender, llama a InventoryService.remove y paga solo si devolvió true. Para comprar, comprueba el precio y spaceFor, quita las monedas y luego llama a add. La guía de la tienda construye la parte de la compra.
Fuentes y lecturas
- Roblox Creator Docs: Remote events and callbacks (en inglés). FireClient, OnServerEvent, límites de los argumentos y cómo se ponen en cola los mensajes no entregados
- Roblox Creator Docs: Securing the client-server boundary (en inglés). validar lo que llega por los remotes, comprobaciones de ProximityPrompt y manipulación de data stores
- Roblox Creator Docs: Data stores (en inglés). GetAsync, SetAsync y cómo activar el acceso desde Studio
- Roblox Creator Docs: Best practices for data stores (en inglés). una clave por jugador, patrones de clave y guardados periódicos
- Roblox Creator Docs: Data store error codes and limits (en inglés). límites de peticiones por servidor y el tamaño máximo de un valor
- Roblox Creator Docs: In-game tools (en inglés). el Handle, el anclaje, la Backpack y StarterGear
- Roblox Creator Docs: Grid and table layouts (en inglés). tamaño de celda, separación y orden de UIGridLayout
Cómo se comprobó el código: cada script de esta página pasa el verificador de tipos estricto de Luau con las definiciones de la API de Roblox (luau-lsp, 14 de noviembre de 2026). Una verificación de tipos detecta APIs mal escritas y tipos incorrectos, no la lógica del juego, así que pruébalo en Studio antes de publicar.