In breve
Conserva gli oggetti di ogni giocatore in una tabella sul server, dentro un ModuleScript in ServerScriptService, e fai in modo che solo quel codice possa aggiungerli, toglierli e impilarli. Descrivi gli oggetti una sola volta in un ModuleScript in ReplicatedStorage (id, nome, stack massimo). Dopo ogni modifica il server invia a quel giocatore un RemoteEvent con una copia del suo inventario, e un LocalScript la disegna come griglia con ScrollingFrame e UIGridLayout.
- Il client non aggiunge mai oggetti. Può solo chiedere, per esempio "equipaggia la mia spada", e il server controlla che il giocatore la possieda prima di fare qualcosa.
- Gli oggetti compaiono solo tramite codice server che controlli tu: raccolte, acquisti nel negozio verificati sul server, ricompense.
- Salva gli id degli oggetti e le loro quantità, non i Tool, con DataStoreService quando il giocatore esce, quando il server si spegne e ogni pochi minuti. Non salvare mai un giocatore i cui dati non si sono caricati.
In questa pagina
Come è fatto un inventario
Il sistema è fatto di sei piccole parti, ognuna con un solo compito. Tutte le regole sugli oggetti vivono in un unico modulo server, quindi quando qualcosa si rompe c'è esattamente un posto dove cercare.
| Parte | Tipo e posizione | Compito |
|---|---|---|
ItemCatalog | ModuleScript in ReplicatedStorage | Cos'è ogni oggetto: nome, descrizione, stack massimo e se si può equipaggiare o usare. Lo leggono il server e tutti i client. |
InventoryService | ModuleScript in ServerScriptService | Conserva gli slot di tutti i giocatori. L'unico codice che aggiunge, toglie e impila gli oggetti. |
InventoryData | Script in ServerScriptService | Carica gli oggetti del giocatore quando entra e li salva. |
InventoryActions | Script in ServerScriptService | Controlla ed esegue le richieste di equipaggiamento e di uso. |
ItemPickup | Script dentro una Part | Dà l'oggetto a chi lo raccoglie. |
InventoryClient | LocalScript in StarterPlayerScripts | Disegna la griglia e invia le richieste. Non cambia niente da solo. |
I dati vanno in una sola direzione. Il server cambia l'inventario, poi invia a quel giocatore InventoryUpdated con l'intero inventario, e il client lo ridisegna. Quando il giocatore clicca su uno slot, il client invia EquipItem o UseItem con l'id dell'oggetto; il server controlla la richiesta, fa la modifica, e la nuova copia arriva per la stessa strada. Inviare tutto l'inventario è più semplice che inviare le modifiche, e con qualche decina di slot il messaggio resta piccolo.
Perché il client non aggiunge mai oggetti
Viene voglia di aggiungere l'oggetto direttamente nel LocalScript che lo mostra: il giocatore clicca e lo slot si riempie. Questo si rompe in due modi.
- Nessun altro lo vede. Una modifica in un LocalScript esiste solo sul dispositivo di quel giocatore. Il server non lo sa, quindi non viene salvata, e nessuno script server può usarla.
- Chiunque può falsificarla. Se la risolvi con un remote come
AddItem(itemId, amount), un cheater può chiamare quell'evento da solo, con qualsiasi argomento e tutte le volte che vuole. La guida di Roblox sulla sicurezza dice che il server deve controllare tutto quello che invia il client prima di usarlo.
Per questo in questa guida il client può solo chiedere di fare qualcosa con oggetti che il giocatore ha già: "equipaggia questo" e "usa questo". Ogni richiesta contiene un solo id di oggetto e nessuna quantità, e sul server passa un unico controllo: è una stringa, l'oggetto esiste, il giocatore ne ha almeno uno e il giocatore non invia più di quattro richieste al secondo. Poi il server trova da solo il Tool nel catalogo. Non accetta mai dal client un Tool, un percorso o un'istanza, come avverte la stessa guida.
Gli oggetti entrano nell'inventario solo tramite codice server: una raccolta controllata dal server, un acquisto per cui il server ha scalato i soldi (lo costruisce la guida al negozio), una ricompensa di una missione o un drop. Sui remote in generale, con il controllo di altri tipi di argomenti, leggi la guida ai RemoteEvent.
Passo 1: prepara l'Explorer
Crea questi oggetti a mano. Gli script dei passi successivi li cercano per nome, quindi scrivi ogni nome esattamente come qui.
- In ReplicatedStorage inserisci una Folder chiamata
InventoryRemotes. Dentro inserisci tre RemoteEvent chiamatiInventoryUpdated,EquipItemeUseItem. - In ServerStorage inserisci una Folder chiamata
ItemTools. Dentro inserisci un Tool chiamatoSword, e nel Tool una Part chiamataHandle(1 per 4 per 1 stud va benissimo). Controlla che la casella Anchored della Handle sia deselezionata: Roblox avverte che il personaggio resta bloccato sul posto se tiene uno strumento con parti ancorate. Va bene anche un Tool che hai già, se il suo nome corrisponde al catalogo del passo 2. - Aggiungi gli script man mano che segui i passi. L'albero mostra dove va ciascuno.
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: descrivi gli oggetti in un catalogo
Il catalogo descrive una sola volta ogni oggetto che può esistere. Gli inventari poi conservano solo l'id dell'oggetto e la quantità. Così i salvataggi restano piccoli, e in seguito puoi rinominare un oggetto o riscriverne la descrizione senza toccare i dati salvati di nessuno.
Inserisci un ModuleScript in ReplicatedStorage, chiamalo ItemCatalog e sostituisci il suo contenuto con questo:
-- Tutti gli oggetti che possono esistere nel gioco. Questa lista la leggono il server e tutti
-- i client; solo il server decide chi possiede cosa.
export type Item = {
id: string, -- deve corrispondere alla chiave qui sotto
name: string,
description: string,
maxStack: number, -- quanti di questo oggetto stanno in un solo slot
icon: string?, -- immagine facoltativa: "rbxassetid://" più l'ID della tua immagine
toolName: string?, -- un Tool in ServerStorage.ItemTools: l'oggetto si può equipaggiare
heal: number?, -- quanta salute restituisce: l'oggetto è consumabile
}
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 = {}
-- Restituisce l'oggetto con questo id, o nil se l'oggetto non esiste
function ItemCatalog.get(id: string): Item?
return items[id]
end
return ItemCatalog
I campi facoltativi decidono cosa fa un oggetto. toolName lo rende equipaggiabile, heal lo rende usabile, e un oggetto senza nessuno dei due, come il legno, resta nell'inventario finché non lo toglie altro codice server (crafting, vendita).
Per aggiungere un oggetto, aggiungi una voce in cui la chiave e l'id coincidono. Gli id distinguono maiuscole e minuscole e sono proprio loro a venire salvati, quindi non cambiare mai un id quando l'oggetto ce l'hanno già dei giocatori: cambia il suo name.
Passo 3: conserva gli inventari sul server
Questo ModuleScript possiede l'inventario di ogni giocatore. Ogni inventario è una lista di slot, ogni slot ha un id di oggetto e una quantità, più una capienza di 20 slot. Gli altri script server chiamano le sue funzioni, e nessun altro modifica la tabella.
Inserisci un ModuleScript in ServerScriptService e chiamalo InventoryService:
-- L'unico codice che cambia gli inventari. Sta in ServerScriptService,
-- dove i client non possono né vederlo né eseguirlo.
local ReplicatedStorage = game:GetService("ReplicatedStorage")
-- La modalità strict non vede cosa restituisce un require tramite WaitForChild, quindi
-- descriviamo la parte del modulo che usa questo 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 -- slot per giocatore
local STARTER_ITEMS: { Slot } = { -- con cosa parte un giocatore del tutto nuovo
{ id = "sword", count = 1 },
{ id = "apple", count = 3 },
}
local inventories: { [Player]: Inventory } = {}
local InventoryService = {}
-- Invia al proprietario una copia del suo inventario. Si chiama dopo ogni modifica.
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
-- Regole degli stack: prima riempiamo gli stack non pieni, poi iniziamo nuovi stack
-- negli slot vuoti. Restituisce quanti ne ha aggiunti, possono essere meno di quelli chiesti.
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
-- Quanti altri di questo oggetto ci stanno: spazio nei suoi stack più gli slot vuoti
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
-- Aggiunge fino ad amount pezzi di un oggetto. Restituisce quanti ne ha aggiunti (0 se
-- l'oggetto non esiste, l'inventario è pieno o non si è ancora caricato).
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
-- Toglie esattamente amount pezzi di un oggetto, partendo dagli ultimi stack.
-- Se il giocatore ne ha meno, non toglie niente e restituisce 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
-- Andiamo dalla fine, così table.remove non salta 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
-- Si chiama quando i dati salvati del giocatore si sono caricati. saved è quello che
-- ha restituito il data store: nil per un giocatore nuovo. Ogni voce ripassa dalle
-- regole degli stack, quindi oggetti rimossi e vecchie dimensioni degli stack non rompono niente.
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 semplice da salvare, o nil se i dati del giocatore non si sono mai caricati
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
Le righe type e il cast :: dopo require servono solo al controllo dei tipi di Luau, che non vede cosa restituisce un modulo trovato tramite WaitForChild. Durante il gioco non cambiano niente. Gli altri script di questa guida fanno lo stesso.
Come funzionano le regole degli stack con il catalogo qui sopra, dove le mele si impilano fino a 10:
- Se aggiungi 15 mele a un giocatore con uno stack da 7, quello stack si riempie fino a 10, e poi inizia un nuovo stack da 5.
- Quando gli slot finiscono,
addaggiunge quello che ci sta e restituisce quel numero. Chiama primaspaceForquando ti serve tutto o niente, come fa la raccolta nel passo 5. removefunziona secondo il principio tutto o niente. Chiedere 3 mele a un giocatore che ne ha 2 non toglie niente e restituiscefalse, quindi controlla il risultato prima di dare qualcosa in cambio.- Negli slot non ci sono buchi: quando uno slot si svuota, gli altri scorrono in su. Così la lista è più semplice da inviare e salvare. Degli slot che mantengono la loro posizione si parla nelle domande alla fine.
| Funzione | Restituisce | A cosa serve |
|---|---|---|
add(player, itemId, amount) | Quanti ne ha aggiunti | Raccolte, ricompense, acquisti |
remove(player, itemId, amount) | true se ha tolto tutto | Uso, vendita, crafting |
count(player, itemId) | Il totale su tutti gli stack | Controllare cosa ha il giocatore |
spaceFor(player, itemId) | Quanti altri ci stanno | Controllo prima di aggiungere con il principio tutto o niente |
getEquipped, setEquipped | L'id dell'oggetto equipaggiato o nil | Equipaggiamento, nel passo 6 |
load, serialize, unload | Una copia pronta da salvare (serialize) | Caricamento e salvataggio, nel passo 4 |
Passo 4: carica e salva ogni inventario
Gli inventari vivono nella memoria del server, quindi spariscono quando il giocatore esce. Questo script carica gli slot del giocatore da un data store quando entra e li riscrive quando esce, quando il server si spegne e ogni tre minuti nel caso il server vada in crash. Salva solo gli id degli oggetti e le quantità: i data store non possono conservare Instance, come i Tool.
Inserisci uno Script in ServerScriptService e chiamalo 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
-- Si salvano solo i giocatori i cui dati si sono caricati. Dopo un caricamento fallito
-- non si deve salvare, altrimenti un inventario vuoto sostituisce quello vero.
local canSave: { [Player]: boolean } = {}
local activeSaves = 0
local function keyFor(player: Player): string
return "User_" .. player.UserId
end
-- Una sola richiesta fallita non deve costare oggetti a nessuno, quindi riproviamo più volte.
-- Anche GetDataStore sta dentro pcall, così una sessione di Studio senza accesso ai data
-- store riceve un avviso invece di fermare questo 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 -- il giocatore è uscito mentre caricavamo
end
if ok then
InventoryService.load(player, saved) -- saved è nil per un giocatore nuovo
canSave[player] = true
elseif RunService:IsStudio() then
-- Di solito significa che l'accesso di Studio alle API services è disattivato. Giochiamo con
-- gli oggetti iniziali, così si può provare, ma non li salviamo mai.
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 -- i dati non si sono mai caricati, non c'è niente da scrivere in sicurezza
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 il server si spegne, salviamo tutti quelli ancora qui e aspettiamo ogni
-- salvataggio in corso, compresi quelli avviati da PlayerRemoving
game:BindToClose(function()
for _, player in Players:GetPlayers() do
task.spawn(save, player)
end
while activeSaves > 0 do
task.wait()
end
end)
-- Salviamo tutti ogni pochi minuti, così un crash del server costa minuti e non l'intera sessione
while true do
task.wait(AUTOSAVE_SECONDS)
for _, player in Players:GetPlayers() do
task.spawn(save, player)
end
end
Cosa fa lo script e perché:
- Caricamento con valori predefiniti. Un giocatore nuovo non ha un valore salvato, quindi
GetAsyncrestituisce nil e lui riceve gli oggetti iniziali. Gli slot salvati ripassano dalle regole degli stack, quindi un oggetto rimosso dal catalogo o uno stack massimo ridotto non rompono il caricamento. Tutto quello che non ci sta più o il cui id non è più nel catalogo viene scartato, e il salvataggio successivo lo rende definitivo, quindi tieni nel catalogo ogni id che i giocatori possono avere. - Mai salvare dopo un caricamento fallito. Vengono scritti solo i giocatori in
canSave. Su un server live, al giocatore i cui dati non si sono caricati nemmeno dopo tre tentativi viene chiesto di rientrare. In Studio invece riceve oggetti iniziali che non vengono salvati, qualche secondo dopo a causa dei tentativi. Succederà così finché il place non è pubblicato con l'accesso alle API attivo. - Salvataggio all'uscita e allo spegnimento.
BindToClosesalva tutti quelli ancora sul server e aspetta i salvataggi già in corso. Roblox dà alle funzioni collegate fino a 30 secondi. - Restare entro i limiti. Una scrittura per giocatore ogni tre minuti più una all'uscita è molto meno del budget standard del server di 60 scritture al minuto più 40 per ogni giocatore (secondo la documentazione al 30 settembre 2026). Lo schema di chiave
User_viene dalle raccomandazioni di Roblox, e passare lo user ID aSetAsynccollega i dati a quel giocatore, cosa che Roblox raccomanda vivamente per gestire le richieste di cancellazione dei dati.
Per un gioco piccolo è una base affidabile. Il blocco di sessione, che impedisce a un giocatore che cambia server in fretta di caricare i dati prima che il vecchio server li abbia salvati, e quando usare UpdateAsync invece di SetAsync, sono spiegati nel tutorial sui DataStore.
Passo 5: dai oggetti dal mondo
La raccolta è il modo più semplice in cui gli oggetti entrano nell'inventario: una parte con un ProximityPrompt che aggiunge un oggetto quando il giocatore lo usa. Lo script ascolta il suo evento Triggered sul server, quindi l'oggetto viene aggiunto dove il client non può intervenire.
- Aggiungi una Part in Workspace, chiamala
Applee colorala di rosso. Attiva Anchored e disattiva CanCollide, così nessuno ci sbatte contro mentre è invisibile. Il prompt mostra il nome della parte. - Con la parte selezionata, scorri la finestra Properties fino alla sezione Attributes e clicca su +. Aggiungi
ItemIddi tipo string e clicca su Save, poi imposta il valoreapple. Allo stesso modo aggiungiAmountdi tipo number con valore1. - Inserisci uno Script nella parte, chiamalo
ItemPickupe incolla questo codice:
-- Metti questo Script dentro una Part e dai alla Part due attributi:
-- ItemId (stringa, per esempio apple) e Amount (numero, per esempio 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 -- qualcun altro l'ha appena raccolto
end
-- Controlliamo la distanza sul server invece di fidarci della richiesta
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 -- non c'è abbastanza spazio: lasciamo l'oggetto dov'è
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 per sistemare altri oggetti. Cambia gli attributi per dare legno, un'altra spada o uno stack di mele.
Roblox controlla la distanza per Triggered, ma la sua guida sulla sicurezza dice comunque di verificare i prompt sul server: un cheater può attivare gli eventi del prompt anche quando Enabled è false, e può tirare una parte non ancorata verso il suo personaggio. Per questo lo script controlla da solo Enabled e la distanza, e per questo la parte è ancorata.
Qualsiasi altro script server dà oggetti allo stesso modo. Dopo un acquisto, una missione o un'uccisione, carica InventoryService con require come negli script qui sopra e chiama InventoryService.add(player, "wood", 5). Controlla prima spaceFor quando l'oggetto non si può perdere. Un'altra fonte può essere un NPC: nella guida ai dialoghi con gli NPC una risposta avvia un'azione sul server, e quell'azione può chiamare allo stesso modo InventoryService.add.
Passo 6: equipaggiare un Tool e usare gli oggetti
Due RemoteEvent trasportano le uniche richieste che il client può fare. EquipItem mette una copia del Tool dell'oggetto da ServerStorage nel Backpack del giocatore (la hotbar in basso sullo schermo) e nella sua mano, e una seconda richiesta la toglie. UseItem toglie un pezzo di un oggetto usabile e ne applica l'effetto, qui una cura.
Inserisci uno Script in ServerScriptService e chiamalo 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 } = {}
-- Ogni richiesta parte da qui. Il client può inviare qualsiasi cosa in qualsiasi momento, quindi
-- controlliamo il tipo, che l'oggetto esista, che il giocatore lo abbia e la frequenza.
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
-- Distrugge il Tool di questo oggetto ovunque sia 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) -- un solo strumento equipaggiato alla volta
local tool = template:Clone()
tool.CanBeDropped = false -- una copia lasciata cadere potrebbe raccoglierla qualcun altro
tool:SetAttribute("InventoryItem", item.id)
tool.Parent = backpack
-- Una seconda copia in StarterGear viene ricopiata nel Backpack dopo il 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) -- subito in 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) -- un secondo clic sull'oggetto equipaggiato lo toglie
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 o già in piena salute: non sprechiamo l'oggetto
end
-- Prima togliamo l'oggetto e curiamo solo se ha funzionato
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)
| Richiesta | Il client invia | Il server controlla prima di agire |
|---|---|---|
EquipItem | Un id di oggetto | È una stringa, l'oggetto esiste, il giocatore lo possiede, le richieste arrivano non più di quattro al secondo, l'oggetto ha un toolName, e un Tool con quel nome si trova in ServerStorage.ItemTools |
UseItem | Un id di oggetto | Gli stessi controlli su tipo, possesso e frequenza, l'oggetto ha un valore heal, il personaggio è vivo e ferito, e un oggetto viene tolto prima che si aggiunga la salute |
Tre dettagli impediscono al Tool di duplicarsi o perdersi. La copia ha CanBeDropped a false, perché un Tool lasciato cadere finisce in Workspace, dove un altro giocatore può prenderlo, mentre l'originale resta nell'inventario. Ogni copia porta l'attributo InventoryItem, quindi quando si toglie l'oggetto si può trovare e distruggere ogni copia, ovunque sia. E se il giocatore ha un contenitore StarterGear, ci va dentro una seconda copia. Roblox copia StarterGear nel Backpack ogni volta che compare il personaggio, quindi la spada equipaggiata torna dopo il respawn.
Si equipaggia un solo Tool alla volta, e l'equipaggiamento non viene salvato, quindi dopo essere rientrato il giocatore parte con la hotbar vuota. Se più avanti aggiungi la vendita o la possibilità di gettare oggetti, togli l'oggetto equipaggiato prima che la sua ultima copia lasci l'inventario.
La spada segnaposto si può trasformare in una spada che combatte davvero: costruisci il Tool con la guida alla spada, lascia il nome Sword e mettilo in ItemTools al posto del segnaposto. Lo script server di quella guida controllerà ogni colpo, in qualunque modo il giocatore abbia ottenuto la spada.
Passo 7: disegna la griglia dell'inventario
Il LocalScript costruisce l'intera finestra nel codice, quindi non c'è niente da sistemare a mano. Un ScrollingFrame contiene gli slot, un UIGridLayout al suo interno li dispone in righe, e AutomaticCanvasSize allarga l'area scorrevole man mano che si aggiungono righe.
Nell'Explorer apri StarterPlayer, inserisci un LocalScript in StarterPlayerScripts e chiamalo 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. Costruiamo la finestra una sola volta. ResetOnSpawn = false la mantiene dopo i respawn.
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 allarga in base alle celle
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 cella per slot. Disegna solo quello che ha inviato il server; l'inventario
-- vero e proprio non cambia mai da qui.
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 -- slot vuoto
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()
-- Chiediamo, non ordiniamo: il server controlla la richiesta e invia il risultato
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
-- Il server lo invia dopo il caricamento e dopo ogni modifica
inventoryUpdated.OnClientEvent:Connect(render)
-- 3. Apriamo e chiudiamo con il pulsante o con il tasto 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 in StarterPlayerScripts parte una sola volta per sessione, e ResetOnSpawn = false mantiene la ScreenGui quando il personaggio fa respawn, quindi la griglia continua a mostrare l'ultima copia inviata dal server.
Il client disegna una cella per ogni slot, compresi quelli vuoti, quindi un inventario da 20 slot sembra sempre da 20 slot. Ogni aggiornamento distrugge le vecchie celle e ne costruisce di nuove, che è semplice e va bene per qualche decina di slot. Se il server invia InventoryUpdated prima che questo script si sia collegato, Roblox mette il messaggio in coda e lo consegna appena il gestore si collega, quindi il primo inventario non va perso.
Vuoi disegnare la finestra in Studio? Costruisci una ScreenGui con un solo slot modello e usa Clone su di esso in makeCell. Per le icone, dai all'oggetto nel catalogo un icon con un'immagine che hai caricato, e la sua cella mostrerà l'immagine al posto del nome.
Prova l'inventario
- Premi Play. Apri l'inventario con il pulsante a sinistra o con il tasto B: un giocatore nuovo ha Sword e 3 Apple, e il contatore mostra 2 / 20 slots. Finché Studio non può accedere ai data store, gli oggetti compaiono dopo qualche secondo, dopo gli avvisi di caricamento nell'Output, e non vengono salvati.
- Clicca su Sword. La spada compare nella tua mano e nella hotbar, e il suo slot riceve un contorno viola. Clicca di nuovo per toglierla.
- Avvicinati alla parte Apple e usa il suo prompt. Lo stack di mele sale a 4, e la parte sparisce per 15 secondi.
- Per provare la cura, prima abbassa la salute. Passa Client/Server su Server, seleziona lo
Humanoiddel tuo personaggio nell'Explorer, imposta Health a 50, torna su Client e clicca su Apple. - Con l'accesso di Studio alle API services attivo, ferma il gioco e avvialo di nuovo. La mela raccolta è ancora lì. Se il caricamento o il salvataggio non riescono, l'Output te lo dice.
Per provare con più giocatori, scegli nelle impostazioni di test Server & Clients con 2 client. Ogni giocatore vede solo il proprio inventario, e la spada in mano all'altro la vedono entrambi.
Errori comuni e soluzioni
La maggior parte dei problemi si vede nella finestra Output come avviso o come riga di errore rossa. Leggi la prima: gli errori successivi spesso derivano da quella.
Infinite yield possible su una chiamata WaitForChild
Lo script aspetta un oggetto che non esiste con esattamente quel nome. Confronta il tuo Explorer con l'albero del passo 1: InventoryRemotes con tre RemoteEvent in ReplicatedStorage, ItemTools in ServerStorage e i due moduli. I nomi distinguono maiuscole e minuscole. La guida agli errori degli script spiega questo avviso più nel dettaglio.
La griglia si apre ma resta vuota
Il client disegna solo quello che invia il server. Cerca nell'Output gli avvisi Inventory load failed e controlla che InventoryData sia uno Script, non un LocalScript, in ServerScriptService, con accanto il ModuleScript InventoryService. Se l'Output mostra un errore Remote event invocation, sul client nessuno ascolta InventoryUpdated: cerca un errore precedente di InventoryClient.
Gli oggetti si azzerano ogni volta che gioco in Studio
Se l'Output scrive Inventory not loaded: playing with starter items that will not be saved, il place non è pubblicato o l'accesso di Studio alle API services è disattivato. Attivalo come descritto nel passo 4, in una copia di prova del tuo gioco.
Cliccare sulla spada non fa niente
Cerca nell'Output Cannot equip sword: il Tool in ServerStorage.ItemTools deve chiamarsi esattamente come il toolName nel catalogo. Inoltre il Tool ha bisogno di una parte chiamata Handle per poter essere tenuto in mano, a meno che tu non abbia impostato il suo RequiresHandle a false.
Il prompt di raccolta compare ma non viene aggiunto niente
L'attributo ItemId deve corrispondere esattamente all'id del catalogo, maiuscole comprese: apple, non Apple. Non viene aggiunto niente mentre l'inventario del giocatore si sta ancora caricando o quando non c'è spazio per tutta la quantità.
Il salvataggio si rompe dopo che ho cambiato cosa viene salvato
I data store accettano dati semplici: stringhe, numeri, booleani e tabelle fatte di questi. Salvare un Tool, una Part o qualsiasi altra Instance fallisce, oppure il valore viene salvato come nil. Salva l'id dell'oggetto e la quantità, e ricostruisci tutto il resto dal catalogo, come fa serialize.
Farlo con RoCode
Se per te è più facile descrivere il sistema che costruirlo a mano, RoCode può costruirlo nel place che hai aperto. È un agente IA per Roblox Studio: descrivi la funzione nella chat web, e il suo plugin per Studio crea script e oggetti nel tuo Explorer, invece di darti codice da incollare.
Aggiungi un inventario da 20 slot con stack di oggetti, una griglia UI che si apre con B, una spada da ServerStorage che i giocatori possono equipaggiare, mele che curano e il salvataggio con DataStoreService.
- Può esaminare il tuo place quando un passo lo richiede, con Search Game e Search Scripts, per basarsi su oggetti, remote o codice di salvataggio che hai già invece di aggiungere un secondo sistema
- Crea le cartelle e i RemoteEvent con Create Instance, e i ModuleScript, gli Script e i LocalScript con Create Script
- Può costruire una bozza della finestra con Build UI, che include un layout di inventario con slot segnaposto; il codice che riempie gli slot dal server viene scritto in script separati
- Controlla che ogni script compili in Studio con Check Script, che individua errori di compilazione e alcuni schemi rischiosi, ma non verifica i tipi, non fa linting e non esegue il tuo codice
Ogni blocco di modifiche è un punto di annullamento in Studio. RoCode non può attivare l'accesso di Studio alle API services, quello lo fai tu. Con il plugin 3.9 o successivo può avviare un breve playtest e leggere gli errori, e con il plugin 3.9.15 o successivo il suo personaggio di prova può premere tasti ed equipaggiare oggetti, ma verifica solo quello che ha deciso di provare, quindi il salvataggio controllalo tu con un playtest. Un inventario si appoggia ad altri sistemi, come il salvataggio e gli strumenti, e un creatore di giochi con IA che costruisce nel tuo place in Studio li aggiunge un prompt alla volta. Come RoCode si collega a Studio.
Domande frequenti
Conviene usare il Backpack di Roblox invece di un inventario proprio?
Il Backpack è l'inventario integrato di Roblox: ogni Tool al suo interno compare come pulsante nella hotbar. Se tutti gli oggetti del tuo gioco sono Tool e non ti servono stack, quantità e un limite di slot, può bastare, anche se dovrai comunque salvare quali Tool ha ogni giocatore. Un inventario proprio serve per gli oggetti che non sono Tool, come materiali e consumabili. Questa guida usa entrambi: l'inventario conserva tutto, e il Backpack tiene il Tool equipaggiato.
Come si nasconde la hotbar predefinita di Roblox?
Da un LocalScript chiama StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.Backpack, false). Quando la hotbar è nascosta, i giocatori hanno bisogno di un altro modo per prendere e togliere il Tool equipaggiato, per esempio un pulsante che chiede al server di chiamare Humanoid:EquipTool o Humanoid:UnequipTools.
Come faccio a far mantenere la posizione agli slot per il drag and drop?
Conserva una lista di lunghezza fissa con una voce per slot e segna gli slot vuoti con un valore come un id vuoto, non con nil, perché Roblox sconsiglia di inviare tabelle con nil tramite RemoteEvent. Poi aggiungi un RemoteEvent MoveItem che invia due numeri di slot, e fai controllare al server che entrambi siano interi tra 1 e la capienza prima di scambiarli.
Quanto può essere grande un inventario salvato?
Un singolo valore in un data store può occupare fino a 4 194 304 caratteri dopo la serializzazione (secondo la documentazione al 30 settembre 2026). Una lista di id e quantità ne occupa una minima parte. Le dimensioni del salvataggio crescono con il testo per ogni oggetto, come nomi personalizzati o lunghe descrizioni salvate per ogni oggetto.
Come si comprano e vendono oggetti con le monete?
Fai tutto sul server. Per vendere, chiama InventoryService.remove e paga solo se ha restituito true. Per comprare, controlla il prezzo e spaceFor, prendi le monete, poi chiama add. La guida al negozio costruisce la parte dell'acquisto.
Fonti e letture
- Roblox Creator Docs: Remote events and callbacks (in inglese). FireClient, OnServerEvent, limiti sugli argomenti e come i messaggi senza destinatario vengono messi in coda
- Roblox Creator Docs: Securing the client-server boundary (in inglese). controllo degli input dei remote, verifiche dei ProximityPrompt e manomissione dei dati nel data store
- Roblox Creator Docs: Data stores (in inglese). GetAsync, SetAsync e attivazione dell'accesso da Studio
- Roblox Creator Docs: Best practices for data stores (in inglese). una chiave per giocatore, schemi di chiave e salvataggi periodici
- Roblox Creator Docs: Data store error codes and limits (in inglese). limiti di richieste per server e limite di dimensione di un singolo valore
- Roblox Creator Docs: In-game tools (in inglese). Handle, ancoraggio, Backpack e StarterGear
- Roblox Creator Docs: Grid and table layouts (in inglese). dimensione delle celle di UIGridLayout, spaziatura e ordine
Come è stato controllato il codice: ogni script di questa pagina supera il controllo dei tipi rigoroso di Luau con le definizioni dell'API di Roblox (luau-lsp, 20 novembre 2026). Il controllo dei tipi trova API scritte male e tipi sbagliati, non la logica del gioco, quindi provalo in Studio prima di pubblicare.