In het kort
Bewaar de items van elke speler in een tabel op de server, in een ModuleScript in ServerScriptService, en laat alleen die code ze toevoegen, weghalen en stapelen. Beschrijf de items één keer in een ModuleScript in ReplicatedStorage (id, naam, maximale stack). Na elke wijziging stuurt de server die speler een RemoteEvent met een kopie van zijn inventaris, en een LocalScript tekent die als grid met een ScrollingFrame en UIGridLayout.
- De client voegt nooit items toe. Hij kan alleen iets vragen, bijvoorbeeld "rust mijn zwaard uit", en de server controleert of de speler het heeft voordat er iets gebeurt.
- Items verschijnen alleen via servercode die jij beheert: oppakken, winkelaankopen na controle op de server, beloningen.
- Sla item-id's en aantallen op, geen Tools, met DataStoreService als de speler vertrekt, als de server afsluit en om de paar minuten. Sla nooit een speler op van wie de data niet geladen zijn.
Op deze pagina
Hoe een inventaris in elkaar zit
Het systeem bestaat uit zes kleine onderdelen, elk met één taak. Alle regels over items leven in één servermodule, dus als er iets kapotgaat, hoef je maar op één plek te zoeken.
| Onderdeel | Type en plek | Taak |
|---|---|---|
ItemCatalog | ModuleScript in ReplicatedStorage | Wat elk item is: naam, beschrijving, maximale stack en of je het kunt uitrusten of gebruiken. De server en alle clients lezen het. |
InventoryService | ModuleScript in ServerScriptService | Bewaart de slots van alle spelers. De enige code die items toevoegt, weghaalt en stapelt. |
InventoryData | Script in ServerScriptService | Laadt de items van een speler als hij binnenkomt, en slaat ze op. |
InventoryActions | Script in ServerScriptService | Controleert en voert verzoeken uit om uit te rusten en te gebruiken. |
ItemPickup | Script in een Part | Geeft het item aan wie het oppakt. |
InventoryClient | LocalScript in StarterPlayerScripts | Tekent het grid en stuurt verzoeken. Verandert zelf niets. |
De data gaan één kant op. De server wijzigt de inventaris, stuurt die speler daarna InventoryUpdated met de hele inventaris, en de client tekent hem opnieuw. Als de speler op een slot klikt, stuurt de client EquipItem of UseItem met het item-id; de server controleert het verzoek, voert de wijziging door, en de nieuwe kopie komt via dezelfde weg terug. De hele inventaris sturen is eenvoudiger dan wijzigingen sturen, en voor een paar dozijn slots blijft het bericht klein.
Waarom de client nooit items toevoegt
Het is verleidelijk om een item direct toe te voegen in het LocalScript dat het toont: de speler klikt, het slot vult zich. Dat gaat op twee manieren mis.
- Niemand anders ziet het. Een wijziging in een LocalScript bestaat alleen op het apparaat van die speler. De server weet er niets van, dus wordt het niet opgeslagen en kan geen enkel serverscript het gebruiken.
- Iedereen kan het vervalsen. Als je dit oplost met een remote als
AddItem(itemId, amount), kan een cheater dat event zelf afvuren, met welke argumenten en hoe vaak hij maar wil. De beveiligingshandleiding van Roblox zegt dat de server alles wat een client stuurt moet controleren voordat hij het gebruikt.
Daarom kan de client in deze handleiding alleen vragen om iets te doen met items die de speler al heeft: "rust dit uit" en "gebruik dit". Elk verzoek bevat één item-id en geen aantallen, en op de server doorloopt het één controle: het is een string, het item bestaat, de speler heeft er minstens één, en de speler stuurt niet meer dan vier verzoeken per seconde. Daarna zoekt de server de Tool zelf op in de catalogus. Hij accepteert nooit een Tool, pad of instance van de client, waar dezelfde handleiding voor waarschuwt.
Items komen alleen in de inventaris via servercode: een oppakactie die de server controleerde, een aankoop waarvoor de server het geld afschreef (de handleiding over een winkel bouwt die), een beloning voor een quest of een drop. Over remotes in het algemeen, met controles voor andere soorten argumenten, lees je in de handleiding over RemoteEvents.
Stap 1: bereid de Explorer voor
Maak deze objecten met de hand. De scripts uit de volgende stappen zoeken ze op naam, dus schrijf elke naam precies zoals hier.
- Voeg in ReplicatedStorage een Folder in met de naam
InventoryRemotes. Voeg daarin drie RemoteEvents in met de namenInventoryUpdated,EquipItemenUseItem. - Voeg in ServerStorage een Folder in met de naam
ItemTools. Voeg daarin een Tool in met de naamSword, en in de Tool een Part met de naamHandle(1 bij 4 bij 1 stud is prima). Controleer dat het vinkje Anchored bij Handle uit staat: Roblox waarschuwt dat een personage vast komt te staan als het een tool met verankerde parts vasthoudt. Een Tool die je al hebt werkt ook, als de naam overeenkomt met de catalogus uit stap 2. - Voeg de scripts toe terwijl je de stappen doorloopt. De boom laat zien waar elk script komt.
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
Stap 2: beschrijf de items in een catalogus
De catalogus beschrijft elk item dat kan bestaan, één keer. Inventarissen bewaren daarna alleen het item-id en het aantal. Zo blijven opslagen klein, en kun je later een item hernoemen of de beschrijving herschrijven zonder iemands opgeslagen data aan te raken.
Voeg een ModuleScript in ReplicatedStorage in, noem het ItemCatalog en vervang de inhoud door dit:
-- Alle items die in de game kunnen bestaan. De server en alle clients lezen
-- deze lijst; alleen de server beslist wie wat heeft.
export type Item = {
id: string, -- moet gelijk zijn aan de sleutel hieronder
name: string,
description: string,
maxStack: number, -- hoeveel van dit item in één slot past
icon: string?, -- optionele afbeelding: "rbxassetid://" plus de ID van je afbeelding
toolName: string?, -- Tool in ServerStorage.ItemTools: het item kan uitgerust worden
heal: number?, -- hoeveel gezondheid het herstelt: het item is verbruikbaar
}
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 = {}
-- Geeft het item met dit id terug, of nil als zo'n item niet bestaat
function ItemCatalog.get(id: string): Item?
return items[id]
end
return ItemCatalog
De optionele velden bepalen wat een item doet. toolName maakt het uitrustbaar, heal maakt het bruikbaar, en een item zonder beide velden, zoals hout, ligt in de inventaris tot andere servercode het weghaalt (craften, verkopen).
Om een item toe te voegen, voeg je een regel toe waarvan de sleutel en het id gelijk zijn. Id's zijn hoofdlettergevoelig en zijn precies wat er wordt opgeslagen, dus verander nooit een id als spelers het item al hebben: verander de name.
Stap 3: bewaar de inventarissen op de server
Dit ModuleScript is eigenaar van de inventaris van elke speler. Elke inventaris is een lijst slots, elk slot met een item-id en een aantal, plus een capaciteit van 20 slots. Andere serverscripts roepen zijn functies aan, en niemand anders bewerkt de tabel.
Voeg een ModuleScript in ServerScriptService in en noem het InventoryService:
-- De enige code die inventarissen wijzigt. Hij staat in ServerScriptService,
-- waar clients hem niet kunnen zien of draaien.
local ReplicatedStorage = game:GetService("ReplicatedStorage")
-- De strict-modus ziet niet wat require via WaitForChild teruggeeft, dus
-- beschrijven we het deel van de module dat dit script gebruikt
type Item = { id: string, maxStack: number }
type Catalog = { get: (id: string) -> Item? }
local ItemCatalog = require(ReplicatedStorage:WaitForChild("ItemCatalog")) :: Catalog
local remotes = ReplicatedStorage:WaitForChild("InventoryRemotes")
local inventoryUpdated = remotes:WaitForChild("InventoryUpdated") :: RemoteEvent
export type Slot = { id: string, count: number }
type Inventory = { slots: { Slot }, capacity: number, equipped: string? }
local CAPACITY = 20 -- slots per speler
local STARTER_ITEMS: { Slot } = { -- waarmee een gloednieuwe speler begint
{ id = "sword", count = 1 },
{ id = "apple", count = 3 },
}
local inventories: { [Player]: Inventory } = {}
local InventoryService = {}
-- Stuurt de eigenaar een kopie van zijn inventaris. Wordt na elke wijziging aangeroepen.
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
-- Stackregels: vul eerst onvolledige stacks aan, begin daarna nieuwe stacks
-- in lege slots. Geeft terug hoeveel er is toegevoegd, dat kan minder zijn dan gevraagd.
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
-- Hoeveel van het item er nog bij past: ruimte in zijn stacks plus lege slots
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
-- Voegt tot amount exemplaren van het item toe. Geeft terug hoeveel er is toegevoegd (0 als
-- het item niet bestaat, de inventaris vol is of nog niet geladen is).
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
-- Haalt precies amount exemplaren van het item weg, te beginnen bij de laatste stacks.
-- Als de speler er minder heeft, wordt er niets weggehaald en komt false terug.
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
-- We lopen vanaf het eind, zodat table.remove geen slots overslaat
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
-- Wordt aangeroepen als de opgeslagen data van de speler geladen zijn. saved is wat
-- de data store teruggaf: nil voor een nieuwe speler. Elke regel gaat opnieuw door de
-- stackregels, dus verwijderde items en oude stackgroottes breken niets.
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
-- Een eenvoudige kopie om op te slaan, of nil als de data van de speler nooit geladen zijn
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
De regels met type en de cast :: na require zijn alleen voor de Luau-typecontrole, die niet ziet wat een module teruggeeft die via WaitForChild gevonden is. Tijdens het spelen veranderen ze niets. De andere scripts in deze handleiding doen hetzelfde.
Zo werken de stackregels met de catalogus hierboven, waarin appels tot 10 stapelen:
- Als je 15 appels toevoegt aan een speler met een stack van 7, wordt die stack aangevuld tot 10 en begint daarna een nieuwe stack van 5.
- Als de slots op zijn, voegt
addtoe wat past en geeft dat aantal terug. Roep eerstspaceForaan als het alles of niets moet zijn, zoals het oppakken in stap 5 doet. removewerkt volgens alles of niets. Vraag je 3 appels van een speler die er 2 heeft, dan wordt er niets weggehaald en komtfalseterug, dus controleer het resultaat voordat je er iets voor teruggeeft.- Er zitten geen gaten in de slots: als een slot leeg raakt, schuiven de andere omhoog. Zo is de lijst makkelijker te versturen en op te slaan. Over slots die hun positie houden lees je in de vragen aan het eind.
| Functie | Geeft terug | Waarvoor |
|---|---|---|
add(player, itemId, amount) | Hoeveel er is toegevoegd | Oppakken, beloningen, aankopen |
remove(player, itemId, amount) | true als alles is weggehaald | Gebruiken, verkopen, craften |
count(player, itemId) | Totaal over alle stacks | Controleren wat de speler heeft |
spaceFor(player, itemId) | Hoeveel er nog bij past | Controle vóór toevoegen volgens alles of niets |
getEquipped, setEquipped | Id van het uitgeruste item, of nil | Uitrusten, in stap 6 |
load, serialize, unload | Een kopie klaar om op te slaan (serialize) | Laden en opslaan, in stap 4 |
Stap 4: laad en bewaar elke inventaris
Inventarissen leven in het geheugen van de server, dus ze verdwijnen als de speler vertrekt. Dit script laadt de slots van een speler uit een data store als hij binnenkomt, en schrijft ze terug als hij vertrekt, als de server afsluit en elke drie minuten voor het geval de server crasht. Het slaat alleen item-id's en aantallen op: data stores kunnen geen Instance zoals een Tool bewaren.
Voeg een Script in ServerScriptService in en noem het 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
-- Alleen spelers van wie de data geladen zijn, worden opgeslagen. Na een mislukte lading
-- mag je niet opslaan, anders vervangt een lege inventaris de echte.
local canSave: { [Player]: boolean } = {}
local activeSaves = 0
local function keyFor(player: Player): string
return "User_" .. player.UserId
end
-- Eén mislukt verzoek mag niemand items kosten, dus we proberen het een paar keer.
-- GetDataStore staat ook in de pcall, dus een Studio-sessie zonder toegang tot data
-- stores krijgt een waarschuwing in plaats van dat dit script stopt.
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 -- de speler vertrok terwijl we laadden
end
if ok then
InventoryService.load(player, saved) -- saved is nil voor een nieuwe speler
canSave[player] = true
elseif RunService:IsStudio() then
-- Betekent meestal dat Studio-toegang tot API services uit staat. We spelen met
-- startitems zodat je kunt testen, maar slaan ze nooit op.
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 -- de data zijn nooit geladen, er is niets om veilig te schrijven
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)
-- Als de server afsluit, slaan we iedereen op die er nog is, en wachten we op elke
-- opslag die nog loopt, ook die PlayerRemoving startte
game:BindToClose(function()
for _, player in Players:GetPlayers() do
task.spawn(save, player)
end
while activeSaves > 0 do
task.wait()
end
end)
-- We slaan iedereen om de paar minuten op, zodat een servercrash minuten kost en niet de hele sessie
while true do
task.wait(AUTOSAVE_SECONDS)
for _, player in Players:GetPlayers() do
task.spawn(save, player)
end
end
Wat het script doet en waarom:
- Laden met standaardwaarden. Een nieuwe speler heeft geen opgeslagen waarde, dus
GetAsyncgeeft nil terug en hij krijgt de startitems. Opgeslagen slots gaan opnieuw door de stackregels, dus een item dat uit de catalogus is verwijderd of een verlaagde maximale stack breekt het laden niet. Alles wat niet meer past of waarvan het id niet meer in de catalogus staat, valt weg, en de volgende opslag maakt dat definitief, dus houd elk id dat spelers kunnen hebben in de catalogus. - Nooit opslaan na een mislukte lading. Alleen spelers in
canSaveworden geschreven. Op een live server wordt een speler van wie de data ook na drie pogingen niet geladen zijn, gevraagd opnieuw te joinen. In Studio krijgt hij in plaats daarvan startitems die niet worden opgeslagen, een paar seconden later door de retries. Zo blijft het tot de place gepubliceerd is met API-toegang aan. - Opslaan bij vertrek en bij afsluiten.
BindToCloseslaat iedereen op die nog op de server is, en wacht op opslagen die al lopen. Roblox geeft gekoppelde functies tot 30 seconden. - Binnen de limieten blijven. Eén schrijfactie per speler elke drie minuten plus één bij vertrek is veel minder dan het standaardbudget van een server van 60 schrijfacties per minuut plus 40 per speler (volgens de documentatie per 30 september 2026). Het sleutelpatroon
User_komt uit de aanbevelingen van Roblox, en de user ID doorgeven aanSetAsynckoppelt de data aan die speler, wat Roblox sterk aanraadt voor het afhandelen van verzoeken om data te verwijderen.
Voor een kleine game is dit een betrouwbare basis. Session locking, dat voorkomt dat een speler die snel van server wisselt zijn data laadt voordat de oude server ze heeft opgeslagen, en wanneer je UpdateAsync gebruikt in plaats van SetAsync, komen aan bod in de DataStore-tutorial.
Stap 5: geef items uit de wereld
Oppakken is de eenvoudigste manier waarop items in de inventaris komen: een part met een ProximityPrompt die het item toevoegt als de speler hem gebruikt. Het script luistert naar het Triggered-event op de server, dus het item wordt toegevoegd waar de client er niet aan kan komen.
- Voeg een Part toe aan Workspace, noem het
Appleen kleur het rood. Zet Anchored aan en CanCollide uit, zodat niemand ertegenaan botst terwijl het onzichtbaar is. De prompt toont de naam van het part. - Scroll met het part geselecteerd in het Properties-venster naar het onderdeel Attributes en klik op +. Voeg
ItemIdtoe met het type string en klik op Save, en geef het daarna de waardeapple. Voeg op dezelfde manierAmounttoe van het type number met de waarde1. - Voeg een Script in het part in, noem het
ItemPickupen plak deze code erin:
-- Zet dit Script in een Part en geef het Part twee attributen:
-- ItemId (een string, bijvoorbeeld apple) en Amount (een getal, bijvoorbeeld 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 -- iemand anders heeft het net opgepakt
end
-- We controleren de afstand op de server in plaats van het verzoek te geloven
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 -- niet genoeg ruimte: laat het item liggen
end
InventoryService.add(player, itemId, amount)
prompt.Enabled = false
part.Transparency = 1
task.wait(RESPAWN_SECONDS)
part.Transparency = visibleTransparency
prompt.Enabled = true
end)
Kopieer het part om meer items neer te zetten. Verander de attributen om hout, nog een zwaard of een stack appels te geven.
Roblox controleert de afstand voor Triggered, maar de beveiligingshandleiding zegt toch dat je prompts op de server moet controleren: een cheater kan prompt-events afvuren, ook als Enabled false is, en kan een niet-verankerd part naar zijn personage trekken. Daarom controleert het script zelf Enabled en de afstand, en daarom is het part verankerd.
Elk ander serverscript geeft items op dezelfde manier. Laad na een aankoop, quest of kill InventoryService met require, zoals de scripts hierboven, en roep InventoryService.add(player, "wood", 5) aan. Controleer eerst spaceFor als het item niet verloren mag gaan. Een NPC kan ook een bron zijn: in de handleiding over NPC-dialogen start een antwoord een actie op de server, en die actie kan op dezelfde manier InventoryService.add aanroepen.
Stap 6: Tools uitrusten en items gebruiken
Twee RemoteEvents dragen de enige verzoeken die de client kan doen. EquipItem legt een kopie van de Tool van het item uit ServerStorage in de Backpack van de speler (de hotbar onderaan het scherm) en in zijn hand, en een tweede verzoek haalt hem weg. UseItem haalt één exemplaar van een bruikbaar item weg en past het effect toe, hier is dat genezen.
Voeg een Script in ServerScriptService in en noem het 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 } = {}
-- Elk verzoek begint hier. De client kan alles sturen, op elk moment, dus
-- controleren we het type, of het item bestaat, of de speler het heeft, en de frequentie.
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
-- Vernietigt de Tool van dit item, waar de kopie ook is: hotbar, hand of 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) -- één uitgeruste tool tegelijk
local tool = template:Clone()
tool.CanBeDropped = false -- een weggegooide kopie zou iemand anders kunnen oppakken
tool:SetAttribute("InventoryItem", item.id)
tool.Parent = backpack
-- De tweede kopie in StarterGear wordt na een respawn terug naar de Backpack gekopieerd
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) -- meteen in de hand
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) -- nog een klik op het uitgeruste item legt het weg
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 -- dood of al op volle gezondheid: verspil het item niet
end
-- Haal eerst het item weg en genees alleen als dat lukte
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)
| Verzoek | Client stuurt | Server controleert vóór de actie |
|---|---|---|
EquipItem | Item-id | Het is een string, het item bestaat, de speler heeft het, verzoeken komen niet vaker dan vier per seconde, het item heeft een toolName, en een Tool met die naam ligt in ServerStorage.ItemTools |
UseItem | Item-id | Dezelfde controles op type, bezit en frequentie, het item heeft een heal-waarde, het personage leeft en is gewond, en één item is weggehaald voordat er gezondheid bijkomt |
Drie details voorkomen dat een Tool verdubbelt of verdwijnt. De kopie heeft CanBeDropped op false, omdat een weggegooide Tool in Workspace valt, waar een andere speler hem kan pakken, terwijl het origineel in de inventaris blijft. Elke kopie draagt het attribuut InventoryItem, zodat je bij het wegleggen elke kopie kunt vinden en vernietigen, waar die ook is. En als de speler een StarterGear-container heeft, komt daar een tweede kopie in. Roblox kopieert StarterGear bij elke spawn van het personage naar de Backpack, dus een uitgerust zwaard komt terug na een respawn.
Er is maar één Tool tegelijk uitgerust, en uitrusten wordt niet opgeslagen, dus een speler begint na opnieuw joinen met een lege hotbar. Als je later verkopen of weggooien toevoegt, leg het item dan weg voordat de laatste kopie de inventaris verlaat.
Je kunt het nepzwaard veranderen in een zwaard dat echt vecht: bouw de Tool volgens de handleiding over een zwaard, houd de naam Sword en leg hem in ItemTools in plaats van het nepzwaard. Het serverscript uit die handleiding controleert elke slag, hoe de speler het zwaard ook kreeg.
Stap 7: teken het inventarisgrid
Het LocalScript bouwt het hele venster in code, dus je hoeft niets met de hand te plaatsen. Een ScrollingFrame bevat de slots, een UIGridLayout erin zet ze in rijen, en AutomaticCanvasSize maakt het scrollgebied groter naarmate er rijen bijkomen.
Open in de Explorer StarterPlayer, voeg een LocalScript in StarterPlayerScripts in en noem het 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. Bouw het venster één keer. ResetOnSpawn = false houdt het na respawns.
local gui = Instance.new("ScreenGui")
gui.Name = "InventoryGui"
gui.ResetOnSpawn = false
gui.Parent = player:WaitForChild("PlayerGui")
local openButton = Instance.new("TextButton")
openButton.AnchorPoint = Vector2.new(0, 0.5)
openButton.Position = UDim2.new(0, 16, 0.5, 0)
openButton.Size = UDim2.fromOffset(140, 40)
openButton.BackgroundColor3 = COLOURS.panel
openButton.Font = Enum.Font.BuilderSansBold
openButton.TextColor3 = COLOURS.text
openButton.TextSize = 18
openButton.Text = "Inventory (B)"
addCorner(openButton, 8)
openButton.Parent = gui
local panel = Instance.new("Frame")
panel.AnchorPoint = Vector2.new(0.5, 0.5)
panel.Position = UDim2.fromScale(0.5, 0.5)
panel.Size = UDim2.fromScale(0.9, 0.8)
panel.BackgroundColor3 = COLOURS.panel
panel.Visible = false
addCorner(panel, 12)
panel.Parent = gui
local sizeLimit = Instance.new("UISizeConstraint")
sizeLimit.MaxSize = Vector2.new(440, 400)
sizeLimit.Parent = panel
local title = makeLabel(panel, "Inventory", 22)
title.Position = UDim2.fromOffset(16, 8)
title.Size = UDim2.new(1, -32, 0, 32)
title.TextXAlignment = Enum.TextXAlignment.Left
local slotCount = makeLabel(panel, "", 16)
slotCount.Position = UDim2.fromOffset(16, 8)
slotCount.Size = UDim2.new(1, -32, 0, 32)
slotCount.TextColor3 = COLOURS.muted
slotCount.TextXAlignment = Enum.TextXAlignment.Right
local grid = Instance.new("ScrollingFrame")
grid.Position = UDim2.fromOffset(12, 48)
grid.Size = UDim2.new(1, -24, 1, -100)
grid.BackgroundTransparency = 1
grid.BorderSizePixel = 0
grid.CanvasSize = UDim2.new() -- AutomaticCanvasSize maakt het groot genoeg voor de cellen
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. Eén cel per slot. Dit tekent alleen wat de server stuurde; de
-- inventaris zelf wordt hiervandaan nooit gewijzigd.
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 -- leeg slot
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()
-- Vragen, niet bevelen: de server controleert het verzoek en stuurt het resultaat
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
-- De server stuurt dit na het laden en na elke wijziging
inventoryUpdated.OnClientEvent:Connect(render)
-- 3. Openen en sluiten met de knop of de toets 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)
Een LocalScript in StarterPlayerScripts draait één keer per sessie, en ResetOnSpawn = false houdt de ScreenGui bij een respawn van het personage, dus het grid blijft de laatste kopie tonen die de server stuurde.
De client tekent een cel voor elk slot, ook de lege, dus een inventaris van 20 slots ziet er altijd uit als 20 slots. Elke update vernietigt de oude cellen en bouwt nieuwe, wat eenvoudig is en past bij een paar dozijn slots. Als de server InventoryUpdated stuurt voordat dit script ermee verbonden is, zet Roblox het bericht in een wachtrij en levert het af zodra de handler verbindt, dus de eerste inventaris gaat niet verloren.
Wil je het venster in Studio tekenen? Bouw een ScreenGui met één sjabloonslot en Clone dat in makeCell. Geef een item in de catalogus voor iconen een icon met een afbeelding die je hebt geüpload, en de cel toont dan de afbeelding in plaats van de naam.
Test de inventaris
- Klik op Play. Open de inventaris met de knop links of met de toets B: een nieuwe speler heeft Sword en 3 Apple, en de teller toont 2 / 20 slots. Zolang Studio geen data stores kan gebruiken, verschijnen de items na een paar seconden, na laadwaarschuwingen in Output, en worden ze niet opgeslagen.
- Klik op Sword. Het zwaard verschijnt in je hand en in de hotbar, en zijn slot krijgt een paarse rand. Klik nog een keer om het weg te leggen.
- Loop naar het Apple-part en gebruik de prompt. De stack appels groeit naar 4, en het part verdwijnt 15 seconden.
- Verlaag eerst je gezondheid om het genezen te testen. Zet Client/Server op Server, selecteer de
Humanoidvan je personage in de Explorer, zet Health op 50, schakel terug naar Client en klik op Apple. - Zet Studio-toegang tot API services aan, stop de game en start hem opnieuw. De opgepakte appel is er nog. Als laden of opslaan mislukte, meldt Output dat.
Om met meerdere spelers te testen kies je in de testinstellingen Server & Clients met 2 clients. Elke speler ziet alleen zijn eigen inventaris, en het zwaard in de hand van de ander zien ze allebei.
Veelvoorkomende fouten en oplossingen
De meeste problemen zie je in het Output-venster als een waarschuwing of een rode foutregel. Lees de eerste: de volgende fouten komen er vaak uit voort.
Infinite yield possible bij een WaitForChild-aanroep
Het script wacht op een object dat niet onder precies die naam bestaat. Vergelijk je Explorer met de boom uit stap 1: InventoryRemotes met drie RemoteEvents in ReplicatedStorage, ItemTools in ServerStorage en de twee modules. Namen zijn hoofdlettergevoelig. De handleiding over scriptfouten behandelt deze waarschuwing uitgebreider.
Het grid opent maar blijft leeg
De client tekent alleen wat de server stuurt. Zoek in Output naar waarschuwingen Inventory load failed en controleer dat InventoryData een Script is, geen LocalScript, in ServerScriptService, met het ModuleScript InventoryService ernaast. Toont Output de fout Remote event invocation, dan luistert niemand op de client naar InventoryUpdated: zoek een eerdere fout van InventoryClient.
Items worden gereset elke keer dat ik in Studio speel
Als Output Inventory not loaded: playing with starter items that will not be saved schrijft, is de place niet gepubliceerd of staat Studio-toegang tot API services uit. Zet die aan zoals beschreven in stap 4, in een testkopie van je game.
Klikken op het zwaard doet niets
Zoek in Output naar Cannot equip sword: de Tool in ServerStorage.ItemTools moet precies zo heten als toolName in de catalogus. De Tool heeft ook een part met de naam Handle nodig om vastgehouden te kunnen worden, tenzij je RequiresHandle op false hebt gezet.
De oppakprompt verschijnt, maar er wordt niets toegevoegd
Het attribuut ItemId moet precies overeenkomen met het id uit de catalogus, inclusief hoofdletters: apple, niet Apple. Er wordt niets toegevoegd terwijl de inventaris van de speler nog laadt, of als er geen plek is voor het hele aantal.
Opslaan gaat mis nadat ik veranderde wat er wordt opgeslagen
Data stores accepteren eenvoudige data: strings, getallen, booleans en tabellen daarvan. Een Tool, Part of andere Instance opslaan mislukt, of de waarde wordt als nil opgeslagen. Sla het item-id en het aantal op en bouw de rest weer op uit de catalogus, zoals serialize doet.
Maken met RoCode
Als je een systeem liever beschrijft dan met de hand bouwt, kan RoCode het bouwen in de place die je open hebt. Het is een AI-agent voor Roblox Studio: je beschrijft een functie in een webchat, en de Studio-plugin maakt de scripts en objecten in je Explorer, in plaats van je code te geven om te plakken.
Voeg een inventaris van 20 slots toe met item-stacks, een UI-grid dat opent met B, een zwaard uit ServerStorage dat spelers kunnen uitrusten, appels die genezen, en opslaan met DataStoreService.
- Kan je place bekijken als een stap dat nodig heeft, met Search Game en Search Scripts, zodat hij voortbouwt op items, remotes of opslagcode die je al hebt in plaats van een tweede systeem toe te voegen
- Maakt de mappen en RemoteEvents met Create Instance, en de ModuleScripts, Scripts en LocalScripts met Create Script
- Kan een basisvenster bouwen met Build UI, dat een inventarislayout met lege slots heeft; de code die de slots vanaf de server vult, wordt in aparte scripts geschreven
- Controleert de compilatie van elk script in Studio met Check Script, dat compileerfouten en een paar riskante patronen vangt, maar geen types controleert, niet lint en je code niet draait
Elke batch wijzigingen is een ongedaan-maakpunt in Studio. RoCode kan Studio-toegang tot API services niet aanzetten, dat doe je zelf. Met plugin 3.9 of nieuwer kan hij een korte playtest draaien en de fouten lezen, en met plugin 3.9.15 of nieuwer kan zijn testpersonage toetsen indrukken en items uitrusten, maar hij controleert alleen wat hij zelf besloot te testen, dus test het opslaan zelf met een playtest. Een inventaris staat boven op andere systemen, zoals opslaan en tools, en de AI-gamemaker die in je eigen place in Studio bouwt voegt ze één prompt tegelijk toe. Hoe RoCode met Studio verbindt.
Veelgestelde vragen
Gebruik je de Backpack van Roblox in plaats van een eigen inventaris?
De Backpack is de ingebouwde inventaris van Roblox: elke Tool erin verschijnt als knop in de hotbar. Als alle items in je game Tools zijn en je geen stacks, aantallen en slotlimiet nodig hebt, kan die genoeg zijn, al moet je nog steeds opslaan welke Tools elke speler heeft. Een eigen inventaris heb je nodig voor items die geen Tool zijn, zoals materialen en verbruiksitems. Deze handleiding gebruikt beide: de inventaris bewaart alles, en de Backpack houdt de uitgeruste Tool.
Hoe verberg je de standaard hotbar in Roblox?
Roep vanuit een LocalScript StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.Backpack, false) aan. Als de hotbar verborgen is, hebben spelers een andere manier nodig om de uitgeruste Tool te pakken en weg te leggen, bijvoorbeeld een knop die de server vraagt Humanoid:EquipTool of Humanoid:UnequipTools aan te roepen.
Hoe laat je slots hun positie houden voor drag and drop?
Bewaar een lijst van vaste lengte met één regel per slot en markeer lege slots met een waarde zoals een leeg id, niet met nil, omdat Roblox afraadt tabellen met nil via een RemoteEvent te sturen. Voeg daarna een RemoteEvent MoveItem toe dat twee slotnummers stuurt, en laat de server controleren dat beide gehele getallen zijn van 1 tot de capaciteit voordat hij ze verwisselt.
Hoe groot kan een opgeslagen inventaris zijn?
Eén waarde in een data store mag na serialisatie tot 4.194.304 tekens bevatten (volgens de documentatie per 30 september 2026). Een lijst id's en aantallen neemt daar een piepklein deel van in. Wat de opslag laat groeien, is tekst per item, zoals eigen namen of lange beschrijvingen die bij elk item worden opgeslagen.
Hoe koop en verkoop je items voor munten?
Doe alles op de server. Om te verkopen roep je InventoryService.remove aan en betaal je alleen als die true teruggaf. Om te kopen controleer je de prijs en spaceFor, neem je de munten af en roep je daarna add aan. De handleiding over een winkel bouwt de koopkant.
Bronnen en verder lezen
- Roblox Creator Docs: Remote events and callbacks (in het Engels). FireClient, OnServerEvent, beperkingen op argumenten en hoe berichten zonder ontvanger in een wachtrij komen
- Roblox Creator Docs: Securing the client-server boundary (in het Engels). invoer van remotes controleren, ProximityPrompt-controles en vervalste data in een data store
- Roblox Creator Docs: Data stores (in het Engels). GetAsync, SetAsync en toegang vanuit Studio aanzetten
- Roblox Creator Docs: Best practices for data stores (in het Engels). één sleutel per speler, sleutelpatronen en periodiek opslaan
- Roblox Creator Docs: Data store error codes and limits (in het Engels). verzoeklimieten per server en de groottelimiet van één waarde
- Roblox Creator Docs: In-game tools (in het Engels). Handle, verankeren, Backpack en StarterGear
- Roblox Creator Docs: Grid and table layouts (in het Engels). celgrootte van UIGridLayout, tussenruimte en sorteervolgorde
Hoe de code is gecontroleerd: elk script op deze pagina doorloopt een strikte Luau-typecontrole met de Roblox API-definities (luau-lsp, 20 november 2026). De typecontrole vangt fouten in API-namen en verkeerde types op, maar geen fouten in de gamelogica, dus test alles in Studio voordat je publiceert.