Items and inventories
Look up what an item is, count what a character carries, give or take items, and put a stack in hand.
There are two things here. game.Items knows what each kind of item is. An inventory knows what is in
it: a character's backpack, its hotbar, and so on.
local window = ui.Window({ title = "Wood", width = 280, height = 150 })
local have = window:Field("Wood carried", 0)
window:Button("Count", function()
if not game.Me.Exists then return end
have:Set(game.Me:Count("Wood"))
end)Naming an item
An item is named by its row in the game's table D_ItemsStatic, such as "Wood" or "Stone_Pickaxe".
Letter case, spaces, underscores and hyphens do not matter, so "stone pickaxe" is the same item. A name the
game does not have raises an error that suggests the nearest ones.
What an item is
local facts = game.Items:Get("Stone_Pickaxe")
print(facts.DisplayName, facts.Weight, facts.MaxStack, facts.MaxDurability)| Field | What it is |
|---|---|
Name | The item's name, spelled as the game spells it. |
DisplayName | The name the game shows players. |
Description | The game's description, or nil. |
Weight | What one weighs, in kilograms. |
MaxStack | How many fit in one stack. |
MaxDurability | Its durability when new. nil for an item with none. |
Icon | The path of its picture in the game's files. |
| Function | What it gives |
|---|---|
game.Items:Get(name) | The facts of one item. |
game.Items:Has(name) | true when the game has an item of this name. |
game.Items:GetNames() | The name of every item. |
game.Items:Find(text) | The names that contain the text. |
game.Items:Load() | Reads the name the game shows for every item, so that Find matches those too. |
The first Get of an item reads a few rows of the game's tables. After that it costs nothing.
Search by the name players see
Find goes by item names until Load has run. After it, "iron" also finds Metal_Ore, which the game
shows as Iron Ore. Load only works inside a task. It reads a little each frame and took
about half a second when it was measured.
local window = ui.Window({ title = "Find an item", width = 320, height = 300 })
local results = window:Console({ height = 170 })
task.spawn(function()
game.Items:Load()
end)
window:Input("Search", { hint = "iron" }, function(text)
local lines = {}
for _, name in ipairs(game.Items:Find(text)) do
lines[#lines + 1] = { game.Items:Get(name).DisplayName .. " (" .. name .. ")" }
end
results:SetLines(lines)
end)Find goes through every item. Call it when the player types something, not every frame.
What a character carries
A player's character has six inventories:
| Field | What it is |
|---|---|
character.Backpack | The backpack. |
character.Hotbar | The hotbar. |
character.Equipment | What the character wears. |
character.Suit, character.Upgrades, character.Vision | The envirosuit, its upgrades and the vision slot. |
One is nil when the character has no such inventory. The character in the station has no backpack.
These work on a player's character, and on game.Me, over all six:
| Function | What it gives |
|---|---|
character:Count(item) | How many of an item it carries. |
character:Has(item, count) | true when it carries at least that many. One when count is left out. |
character:List() | Every stack it carries. Each says in Inventory which one it is in. |
character.HeldItem is the stack in the hotbar slot that is in hand, and character.HotbarSlot is that
slot's number.
local held = game.Me.HeldItem
if held then
print(held.Item, held.Count, held.Durability)
endOne inventory
Each inventory has the same three functions for itself, and a few more:
local backpack = game.Me.Backpack
if backpack then
print(backpack.Used, "of", backpack.Size, "slots,", backpack.Weight, "kg")
for _, stack in ipairs(backpack:List()) do
print(stack.Slot, stack.Item, stack.Count)
end
end| Name | What it gives |
|---|---|
inventory.Size, inventory.Used | How many slots it has, and how many hold something. |
inventory.Weight | What everything in it weighs, in kilograms. |
inventory.Kind | What kind the game says it is, such as "Backpack" or "Quickbar". |
inventory:List() | Every stack, in the order of its slots. |
inventory:Slot(number) | What one slot holds, or nil. Slots are counted from 1. |
inventory:Count(item), inventory:Has(item, count) | As for a character, for this inventory alone. |
inventory:Where(item) | The stacks of one item. |
inventory:Refresh() | Reads every slot again now. |
A stack is a table of plain fields: Item, Count, Slot, Durability, and Properties with every number
the game keeps for it. Changing those fields changes nothing in the game.
Other things that hold items have inventories of the game's class Inventory too, and the same functions
work on them. Reading them was tried on a drop ship and a gravestone. Giving, taking and the signals were not
tried there.
How fresh the answer is
Wax keeps a copy of an inventory you ask about, so asking often costs little.
- For the inventories of your own character on the host, the game tells Wax of every slot it changes, and the copy follows at once.
- Anywhere else Wax looks at most four times a second. A new stack shows about a quarter of a second later, and a change that leaves the weight as it was, such as durability, within two seconds.
inventory:Refresh()reads it all now. A whole backpack took about a millisecond, so use it when something has to be exact at once, not every frame.
Count looks at the inventory's own slots. It does not look inside a bag that lies in a slot.
Hotbar slots, the dropship and the hand
character.Inventory is the backpack. It is the same value as character.Backpack, on a player's character
and on game.Me. The character in the station has no backpack, so Inventory is nil there too. On a
creature, Inventory stays the inventory the game keeps on it.
Slots by number
inventory[n] is inventory:Slot(n), and #inventory is how many slots it has. This works on the hotbar,
the backpack, the dropship and any other inventory.
local hotbar = game.Me.Hotbar
if hotbar then
for slot = 1, #hotbar do
local stack = hotbar[slot]
if stack and stack.Item == "Stone_Pickaxe" then
print("A pickaxe is in slot", slot)
end
end
endAn empty slot is nil. ipairs stops at the first empty slot, so count from 1 to #hotbar when you want
every slot.
The dropship
character.ShipInventory is the cargo of the dropship assigned to that character. The game calls that hold
DropShip_Equipment. A new ship has 15 slots there.
local ship = game.Me.ShipInventory
if ship then
print(ship:Count("Wood"), "wood in the dropship")
endIt is nil on the station, and nil while this character has no dropship. Another player's ship stays theirs.
The small hold the game calls Dropship_RemoveOnly is a different inventory.
Count, Has and List on the character count the six inventories it carries. Ask the ship with its own
Count, Has and List.
Wax looks up the ship at most once a second, and again after a map change. Giving, taking and the item signals on that hold have not been tried. Reading it has.
The hand
local stack = game.Me.Hotbar and game.Me.Hotbar[1]
if stack then
stack:Equip()
end
game.Me.Equipped:Connect(function(held, previous)
print("In hand:", held and held.Item or "empty", "was", previous)
end)
game.Me.Activated:Connect(function(held, use)
print(held.Item, use)
end)stack:Equip() tells the game to focus that slot. The game's own location for the slot is Slot - 1.
Pressing a hotbar key changes the slot in hand the same way, and game.Me.Equipped follows either one on
its next look.
game.Me.Equipped fires when the hotbar slot in hand, or the item in it, is not what it was. Wax looks four
times a second, and only while a handler is connected. Your function gets the stack in hand now, or nil when
that slot is empty, and the name of the item that was in hand. What was already in hand when you connect is
where the signal starts. A change of durability alone does not fire it. Bare hands are the item
Player_Fist.
stack:Activate() puts the stack in the hand and fires game.Me.Activated in that call, with the stack
and nil.
stack:Activate("Consume") also runs that use. A use is a row of D_Uses, such as "Consume" or
"Place". A name the game does not have raises an error that says so.
A tool's swing is the game's fire button. Activate() puts the tool in the hand and fires Activated.
The swing stays with that button.
Call them with a colon: stack:Equip() and stack:Activate(). The stack has to be one that Slot,
List, Where or HeldItem gave.
Give and take
local window = ui.Window({ title = "Supplies", width = 280, height = 160 })
window:Button("Give me 20 wood", function()
local given, why = game.Me:Give("Wood", 20)
if why then
ui.Notify(why, { title = given .. " wood given", kind = "warn" })
end
end)
window:Button("Take 5 wood", function()
game.Me:Take("Wood", 5)
end)| Function | What it does |
|---|---|
character:Give(item, count) | Puts items into the backpack. Gives back how many went in, and why not all of them when fewer did. |
character:Take(item, count) | Takes items out of the backpack first, then the hotbar. Gives back how many were taken. |
inventory:Give(item, count) | The same for one inventory. |
inventory:Take(item, count) | The same for one inventory. The last stack of the item goes first. |
- Items go onto the stacks of that item first, then into empty slots.
- What does not fit is not given. Nothing is dropped on the ground and nothing goes to the hotbar.
- A tool comes new, with its full durability.
- What is taken is gone, not dropped. What a character wears is left alone.
Count,HasandListfollow in the same frame. The weight follows a moment later.- Both were tried on a player's backpack. One call took 0.6 to 2.3 ms.
- What a mod gave stays when the mod unloads.
More or fewer slots
inventory:Resize(slots) gives an inventory that many slots.
local pack = game.Me and game.Me.Backpack
if pack then
local size, why = pack:Resize(40)
print("The backpack has", size, "slots", why or "")
end- Slots are added and taken at the end of the inventory.
- A slot that holds something is never taken, nor any slot before it. The inventory then keeps as many slots
as it needs, and the second value says so:
"slot 31 holds something, so 31 slots stay". Size,Listand the others follow in the same frame.- It lasts as long as the inventory does. One the game makes anew, as after a map change, has the number of
its row in
D_InventoryInfoagain. ChangeStartingSlotsthere withgame.Datato cover those. - The new size stays when your mod unloads. Put it back in
mod.OnUnload. - It was tried on the station's loadout, from 15 slots to 50 and back.
Moving stacks between inventories
inventory:Push(item, target) sends every stack of an item from one inventory into another with the game's own
"transfer all of a type", the call behind its Transfer Like button, so it goes through the server and works in
someone else's session as well. inventory:Pull(item, source) is the same the other way, and
inventory:Move(slot, target, amount) moves part of one stack with the game's "shift": onto a stack of the same
item there, else into an empty slot.
task.spawn(function()
local pack = game.Me.Backpack
local crate = game.Containers:Nearby(30, { kind = "storage" })[1]
if crate then
local moved, why = pack:Push("Wood", crate.Inventories[1])
print("moved", moved, why or "")
end
end)- Inside a task the call waits for the game, up to 2.5 seconds, and answers how many went: on a server the
items arrive after a round trip. Outside a task it answers
nil, "asked"at once. - The stacks in the target are topped up first, then its free slots. What does not fit stays.
- Equipped items, the hotbar and tools are whatever the inventory holds: push from
Backpackto leave them alone. - Seen in a client's game on a dedicated server: 19 rope out of a bench and back in a quarter of a second.
Sharing over several stations
game.Items:Share(total, item, stations) deals an amount out over stations of one kind as evenly as their room
allows, so three furnaces smelt at once instead of one. It is pure sums: it answers how many each station gets,
by its index, and what no station had room for. A station that already holds more than its share gets nothing
until the others catch up; the remainder goes to the first station, the nearest when the list is nearest first.
local furnaces = {}
for _, found in ipairs(game.Containers:Nearby(30, { kind = "station" })) do
if found.Row == "Kit_Stone_Furnace" then
furnaces[#furnaces + 1] = { stacks = found.Inputs:List(), size = found.Inputs.Size, used = found.Inputs.Used }
end
end
local given, left = game.Items:Share(90, "Metal_Ore", furnaces) -- { 30, 30, 30 }, 0The structures around you
game.Containers is the list of chests, cupboards, pouches, benches and furnaces that hold items, kept by a list
that follows the world: nothing is looked for until the first call, and after it a structure joins the moment it
appears and leaves when it goes. Nearby(range) gives those within reach, nearest first, each with its name, its
distance, its inventories and whether it takes an item.
for _, found in ipairs(game.Containers:Nearby(30)) do
print(found.Name, found.Kind, math.floor(found.Distance), #found.Inventories, found:Accepts("Wood"))
end
for _, kind in ipairs(game.Containers:Kinds(30)) do
print(kind.Name, kind.Count)
endKindis"station"for a structure with a processor and its input inventory,"cargo"for a tamed animal with saddle bags, else"storage".OwnedBy(state)is true for a cargo animal that belongs to the player whosePlayerStateis given, and true for every structure. A mod that moves items should only use animals the local player owns:record:OwnedBy(game.LocalPlayer.Raw.PlayerState).Accepts(item)is true for storage with an inventory that takes items, and for a station when one of the recipes of its recipe set takes the item: a stone furnace takes iron ore and not aluminium ore.game.Containers:Accepted(row)is the whole list for a station's item row; its first read of the recipes pauses the task it is in.- Fuel slots, water tanks, graves, mission devices and the drop ship are left out of
Inventories; a fuel slot is underFuel. Changedfires when a structure appears or goes. The settings window of a mod can listKindsonce a second while it shows and leave the rest alone.- The structure's own actor is
Actor, for anything else about it.
From a place, and what is held
Around(place, range) is the same list measured from a place in the game's own units instead of from the player:
a station, a build site, a spot on a dedicated server that has no player of its own to measure from. Totals(inventory)
is what an inventory holds by item row in lower case, from one pass over its stacks that is kept until the inventory's
slots used or items held change, so asking every frame costs two cheap reads at most. Held(item, range) adds the
totals of every structure within range, storage, inputs and fuel together, each inventory once.
local furnace = game.Containers:Nearby(30, { kind = "station" })[1]
local around = game.Containers:Around(furnace.Actor.Position, 30) -- what stands within 30 m of the furnace
local ore = game.Containers:Held("Metal_Ore", 30, { around = furnace.Actor.Position })
print(#around, "structures near the furnace hold", ore, "iron ore")
print(game.Containers:Totals(furnace.Inputs).metal_ore or 0, "of it in the furnace itself")A hook that the game calls hundreds of times a frame (a crafting check for every recipe tile) can ask Totals on
every call: after the first, each call is the stamp's two reads and a table lookup.
Signals for items that come and go are on Events of the game.
Every field and function is listed in the Items and inventories reference.