Wax

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.

init.lua
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)
FieldWhat it is
NameThe item's name, spelled as the game spells it.
DisplayNameThe name the game shows players.
DescriptionThe game's description, or nil.
WeightWhat one weighs, in kilograms.
MaxStackHow many fit in one stack.
MaxDurabilityIts durability when new. nil for an item with none.
IconThe path of its picture in the game's files.
FunctionWhat 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.

init.lua
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:

FieldWhat it is
character.BackpackThe backpack.
character.HotbarThe hotbar.
character.EquipmentWhat the character wears.
character.Suit, character.Upgrades, character.VisionThe 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:

FunctionWhat 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)
end

One 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
NameWhat it gives
inventory.Size, inventory.UsedHow many slots it has, and how many hold something.
inventory.WeightWhat everything in it weighs, in kilograms.
inventory.KindWhat 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.

init.lua
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
end

An 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.

init.lua
local ship = game.Me.ShipInventory
if ship then
    print(ship:Count("Wood"), "wood in the dropship")
end

It 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

init.lua
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

init.lua
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)
FunctionWhat 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, Has and List follow 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.

init.lua
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, List and 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_InventoryInfo again. Change StartingSlots there with game.Data to 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.

init.lua
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 Backpack to 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.

init.lua
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 }, 0

The 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.

init.lua
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)
end
  • Kind is "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 whose PlayerState is 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 under Fuel.
  • Changed fires when a structure appears or goes. The settings window of a mod can list Kinds once 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.

init.lua
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.

On this page