InventorySystem

Getting it

local InventorySystem = Engine:GetSystem("InventorySystem")

Overview

InventorySystem is a complete inventory built around Roblox Tools, on top of DataService:

• Items you define once, with stack sizes, weight, categories, tags, stats and your own data. Every stack keeps its own Id and can carry its own Data, such as durability or a custom name.
• Containers with slots, weight limits and filters. Every player gets the containers you define, by default one 30-slot Backpack, saved in their profile and mirrored to their client.
• Tools: an item with a Tool is a Tool in the player's Backpack, given back after every respawn.
• Equipment slots that put an item's Accessory on the character and add up its stats.
• Using items, with cooldowns and consumables.
• Crafting with ingredients, tools that are kept, currency costs, unlocks and crafting stations.
• World containers for chests and stashes, and pickups that lie in the world with a ProximityPrompt.
• Selling items and item shops through EconomySystem.
• Offline and cross-server gives and takes that are applied exactly once.

Inventories live in player profiles. By default the system creates and runs its own profile store (Engine.Inventory) and starts a session for every player. If your game already has a player profile store, see Profiles.

Get the system in a server script that runs at start-up, and define your items, player containers and equipment slots there, before the first player joins.

local ServerStorage = game:GetService("ServerStorage")
local InventorySystem = Engine:GetSystem("InventorySystem")

InventorySystem:DefineItem("Sword", {
	Name = "Iron Sword",
	Tool = ServerStorage.Tools.Sword, -- the player holds it like any Tool
	Droppable = true,
})

InventorySystem:DefineItem("Apple", {
	MaxStack = 20,
	Consume = true,
	Use = function(player)
		local humanoid = player.Character and player.Character:FindFirstChildOfClass("Humanoid")
		if not humanoid then
			return false -- refused: the apple is given back
		end
		humanoid.Health += 20
	end,
})

InventorySystem:DefineItem("Wood", { MaxStack = 50 })
InventorySystem:DefineItem("Plank", { MaxStack = 50 })
InventorySystem:DefineRecipe("Planks", { Inputs = { Wood = 1 }, Outputs = { Plank = 4 } })

-- Somewhere in your game
local result = InventorySystem:Give(player, "Wood", 10)
if not result.Ok then
	warn("Could not give wood:", result.Reason) -- for example "no space"
end

local InventorySystem = Engine:GetSystem("InventorySystem")

local function show(slot, stack)
	slotLabels[slot].Text = if stack then string.format("%s x%d", stack.Item, stack.Amount) else ""
end

InventorySystem:WaitForContainerAsync("Backpack"):andThen(function(backpack)
	for slot = 1, backpack.Size do
		show(slot, backpack:GetSlot(slot))
	end
	backpack.Changed:Connect(show)
end)

craftButton.Activated:Connect(function()
	InventorySystem:CraftAsync("Planks"):catch(showError) -- for example "missing ingredients"
end)

Items

DefineItem

InventorySystem:DefineItem(id: string, options: ItemOptions?): Item

An Item has the same fields, read-only, plus Id and Usable. :GetItem(id), :FindItem(id) and :GetItems() look items up.

Stacks

A stack is { Id, Item, Amount, Data?, Slot }. Its Id stays the same when the whole stack moves to another slot or container, and through saves. Data is the stack's own data, such as durability or a custom name: two stacks only merge when their Data is equal. A stack of an item that is no longer defined is kept in the player's profile, never deleted.

Containers

Containers hold stacks in numbered slots. Players get their containers automatically (Player containers), and world containers are for chests and stashes. Both have the same API.

Every change returns a Result: { Ok, Amount, Reason? }. Add and Remove are all-or-nothing: when not everything fits or is there, nothing changes. Pass Partial = true to take what fits instead. Move and Transfer move as much as fits, and Amount tells you how much that was. Reasons: "no space", "too heavy", "not accepted", "not enough items", "empty slot", "slot occupied", "invalid amount", "unknown item", "same container" and "container destroyed".

Filters and weight

Accepts limits what a container holds: a list of item ids, categories, Slot names or tags (an item fits when any of them matches), or a function (item, amount, data) -> boolean. MaxWeight caps the total Weight of the contents.

Player containers

Every player gets the containers in PlayerContainers, by default one 30-slot Backpack that gives Tools. They are saved in the player's profile, loaded when the session starts and mirrored to the player's client.

InventorySystem:DefinePlayerContainer("Vault", { Size = 50, Carried = false })

Define player containers before the first inventory loads: in a server script at start-up, or in the PlayerContainers setting. Later calls error.

Give and Take return a Result, all-or-nothing unless you pass Partial = true, with the reason "no inventory" while the player's inventory is not loaded. Methods on this page that take a container for a player accept a Container or the name of one of the player's containers.

Offline and cross-server

Options: { Data?, Container?, Partial?, WaitForApply? }. Both resolve with { Ok, Status, Amount?, Reason? }, where Status is the edit result ("applied", "queued", "rejected" or "missing"). For a player in this server the change happens right away. Use them for gifts, admin tools and rewards from other places.

Tools

An item with a Tool in a container with Tools = true, such as the default Backpack, is a Tool in the player's Backpack: one Tool per stack, given back after every respawn. Each Tool has the attributes EngineItem, EngineStack (the stack's Id) and EngineAmount. The Tool you pass in DefineItem is a template that is cloned for every stack, so keep it out of the world, for example in ServerStorage, and leave its Archivable on.

When a Droppable Tool is dropped with Backspace, it becomes a pickup. Any other Tool that leaves the player is put back in the Backpack.

Holding a Tool is not the same as equipment: equipment slots are for items the player wears.

Equipment

Equipment slots hold what a player wears or carries on them, such as a helmet. Define them in the EquipmentSlots setting, or before the first inventory loads with:

InventorySystem:DefineEquipmentSlot("Head")

InventorySystem:DefineItem("IronHelmet", {
	Slot = "Head",
	Accessory = ServerStorage.Accessories.IronHelmet,
	Stats = { Armor = 5 },
})

-- Later, for a helmet in the player's Backpack
InventorySystem:Equip(player, "Backpack", slot)
print(InventorySystem:GetStats(player).Armor) --> 5

An equipped item's Accessory is put on the character, and again after every respawn (EquipAccessories). Equipment is saved with the inventory.

Using items

InventorySystem:Use(player, container, slot): Result

Calls the item's Use. With Consume, one unit is taken, and given back when Use returns false or errors. After a use, Cooldown blocks the same item for that many seconds, and one item cannot be used twice at the same moment.

A refused use returns the reason Use gave, or "refused". Other reasons: "not usable", "cooldown", "busy", and "use failed" when Use errored. ItemUsed: Signal<(player, itemId, stack)> fires after every use, and :IsOnCooldown(player, itemId) tells whether the cooldown still runs.

Crafting

DefineRecipe

InventorySystem:DefineRecipe(id: string, options: RecipeOptions): Recipe

Recipes name items by id, so define the items first.

A craft is all-or-nothing: when the outputs do not fit, nothing is taken. A currency Cost is paid first and refunded when the craft cannot finish. Reasons: "missing ingredients", "missing tools" (catalysts), "no space", "insufficient" (currency), "recipe locked", "not at station", "requirement not met" or the reason your Requires gave.

Stations

anvilPrompt.Triggered:Connect(function(player)
	InventorySystem:OpenStation(player, "Anvil", { Anchor = workspace.Anvil })
end)

:OpenStation(player, station, { Anchor?, MaxDistance? }) lets the player craft that station's recipes, from the server and from their client. It ends with :CloseStation(player, station?), or once the player is farther than MaxDistance (default MaxOpenDistance) from the Anchor. :IsAtStation(player, station) checks it. In your own server code you can also pass Station to :Craft when you know the player is there.

World containers

local chest = InventorySystem:CreateContainer("Chest_1", { Size = 20 })
chest:Add("Apple", 5)

chestPrompt.Triggered:Connect(function(player)
	chest:Open(player, { Anchor = chestModel })
end)

:CreateContainer(name, { Size, MaxWeight?, Accepts?, Contents? }) makes a container that belongs to no player, for chests, stashes and shared storage. :GetContainer(name), :FindContainer(name) and :GetContainers() look them up, and container:Destroy() removes one.

World containers are not saved for you. :Serialize() returns the contents to save yourself, for example in a Store, and Contents or :Load(stored) puts them back.

A request from a player who is farther than MaxDistance (default MaxOpenDistance) from the Anchor closes the container for them. Player containers can be opened to other players too, for example to let staff look into someone's backpack.

Pickups

InventorySystem:SpawnPickup(itemId: string, amount: number?, at: Vector3 | CFrame, options: PickupOptions?): Pickup

Puts items in the world with a ProximityPrompt. Picking them up gives them to the player's carried containers; whatever does not fit stays on the ground.

:Drop(player, container, slot, amount?) takes items out of a player's container and drops them in front of the character. A Pickup has Id, Item, Amount, Data, Instance, Owner, :Collect(player), :Destroy(), and the PickedUp and Rejected signals. :FindPickup(id) and :GetPickups() look pickups up. PickedUp: Signal<(player, pickup, amount)> and Dropped: Signal<(player, pickup)> fire on the system.

Selling and shops

EconomySystem:CreateCurrency("Coins", { Leaderstat = true })

InventorySystem:DefineItem("Gem", { MaxStack = 99, SellPrice = 40, SellCurrency = "Coins" })
InventorySystem:DefineItem("Arrow", { MaxStack = 99 })

InventorySystem:CreateShop("Fletcher", {
	Currency = "Coins",
	Items = {
		{ Item = "Arrow", Amount = 20, Price = 30 }, -- 20 arrows for 30 coins
	},
})

:Sell(player, container, slot, amount?) pays the item's SellPrice per unit in its SellCurrency, and returns { Ok, Amount, Total, Reason? }. Sold: Signal<(player, itemId, amount, total)> fires after each sale.

:CreateShop(name, options) makes an EconomySystem shop that sells items. Each entry is { Item, Amount?, Price } plus the other shop item options (Id, Name, Currency, Limit, Requires, ...). The shop checks for space before it charges, then gives the items. Players buy through the shop as usual, with PurchaseAsync.

Profiles

To keep the inventory in your own player profiles, call :BindProfileStore(store) before the first player joins, and start your sessions with Player = player, because the system only loads inventories for sessions that have a player. The inventory is then stored under ProfilePath (default "Inventory") in your profiles.

Under ProfilePath the system keeps Containers (the slots of every player container, and a raised Size or MaxWeight), Equipment and the unlocked Recipes. It adds these tables itself. When your data already holds a value that is not a table at ProfilePath, it errors instead of overwriting that value. Stacks that cannot be read are dropped with a warning when an inventory loads.

Client

The client InventorySystem shows the player's own containers, and every container opened to them, as read-only containers that stay up to date.

A client container has the read methods of a server container (:GetSlot, :GetStacks, :FindStack, :Count, :Has, :CanAdd, :GetSpaceFor, :FirstEmptySlot, :IsEmpty), the properties Name, Owner, Kind, Size, MaxWeight, Weight, UsedSlots, FreeSlots, Access and IsOpen, the Changed, Resized and Closed signals, and these requests:

The server checks every request again: a "Read" container cannot be changed, only the player's own containers and those opened to them can be reached, and an opened container closes when the player walks away from its Anchor. Requests are rate-limited (ClientRequestRatePerSec) and reject with the reason, such as "no space", "read only" or "too far". ClientActions = false turns them all off.

Configuration

Types

export type Item
export type ItemOptions
export type ItemDescription
export type Stack = { Id: string, Item: string, Amount: number, Data: { [string]: any }?, Slot: number }
export type Result = { Ok: boolean, Amount: number, Reason: string? }
export type Container
export type ContainerOptions
export type AddOptions = { Data: { [string]: any }?, Slot: number?, Partial: boolean? }
export type RemoveOptions = { Partial: boolean? }
export type OpenOptions = { Access: "Read" | "ReadWrite" | nil, Anchor: (BasePart | Model)?, MaxDistance: number? }
export type Stored
export type Comparator = (a: Item, b: Item) -> boolean
export type PlayerContainerOptions
export type PlayerContainerDefinition
export type GiveOptions = { Data: { [string]: any }?, Container: string?, Partial: boolean? }
export type TakeOptions = { Container: string?, Partial: boolean? }
export type AsyncOptions
export type RemoteResult
export type Equipment
export type EquippedStack
export type EquipmentSlotOptions
export type EquipmentSlotDefinition
export type Recipe
export type RecipeOptions
export type CraftOptions = { Amount: number?, Station: string? }
export type Pickup
export type PickupOptions
export type SellResult = { Ok: boolean, Amount: number, Total: number, Reason: string? }
export type ShopItemOptions
export type ShopOptions
export type Catalog