Inventory

An Inventory in Core is a lightweight system used for tracking many items. Players can view and organize a list of items or resources they have collected. With these lists, players can discover whether they possess particular items (such as a key that opens a door), pay for trading, fulfill crafting requirements, maintain collections, and control other systems that require tracking what a player has acquired during the game.

Inventory Object

The Inventory Object is a core object that represents the container for item objects. Items can be added directly to an inventory, picked up from an Item Object in the world, or transferred between inventories. Core objects and players can have any number of inventories.

Creators can create an Inventory from dragging the Inventory object from Gameplay Objects in Project Content into the Hierarchy, or right-clicking in the hierarchy and selecting Inventory from the Gameplay Object menu.

Inventory Properties

An inventory object in the hierarchy has an Inventory category in the Properties window.

Assign Inventory

An inventory in the hierarchy that is not assigned to a player, is a public inventory. For example, a chest would contain a list of loot items that players can take and place into their inventory.

To give an inventory to a Core Object (such as a treasure chest), it is recommended that creators add an Inventory Object as a descendant of the core object.

If players need an inventory, spawning an Inventory object when the player joins the game would be a good method of making sure all players have an inventory. Players get assigned an inventory using the Assign function.

-- Inventory template.
local BACKPACK = script:GetCustomProperty("Backpack")

local function OnPlayerJoined(player)

    -- Spawn an instance of the inventory object into the world.
    local inventory = World.SpawnAsset(BACKPACK)

    -- Assign this player to that inventory spawned in.
    inventory:Assign(player)
end

Game.playerJoinedEvent:Connect(OnPlayerJoined)

Item Assets

Item Assets are project-level definitions of items. With an item asset, creators can create and manage them in the world or between inventories.

Creators can create an item asset from Project Content by right-clicking and selecting Create Item Asset from the menu, or selecting Create Item Asset from the Script dropdown.

To view created item assets, select My Items in Project Content.

Item Asset Properties

Item Assets have properties that describe the item.

Custom Item Properties

Like script assets, Item Assets can have custom properties. These properties will exist on all item objects or inventory items in the scene. Just like normal custom properties, custom item properties can be static (unchangeable) or dynamic (changeable) during the game.

Custom Item Properties are automatically applied to item objects in the hierarchy or inventory items in an inventory. This data, including changed property values, persist when an item asset is spawned in the world, picked up and added to an inventory, traded between inventories, and dropped again.

Item Object

Item Objects are core objects that manifest items into the 3D world. When an item object is spawned (including when the item is initialized on game start), the item object will automatically spawn an instance of the Item Asset's item template.

Creators can create Item Objects by dragging the Item Object from Project Content which is found under Gameplay Objects into the Hierarchy.

Dropping an inventory item into the world using the DropItem or DropSlot functions will create an item object.

Item Object Properties

A selected Item Object will have the following properties in the Properties window.

Inventory Item

Inventory items are the data blobs stored by inventory objects and only exist during runtime. They inherit any custom properties of the item asset that defines them.

Creators working with inventory items will likely perform one or more of the following operations. Most functions can be performed by a slot (drop item in slot 2) or by an item asset reference (drop 6 apples).

1. Creators can get all inventory items from an inventory or the item in a specified slot.
2. Creators can drop inventory items from an inventory, this spawns them into the world as an Item Object.
3. Creators can transfer inventory items between inventories with the Give functions.
4. Creators can manually sort inventory items from one slot to another with the move function.
5. Creators can delete inventory items with the remove functions.

Networking

In general, networking for these new types attempts to conform to all the existing Core patterns. This means that the context in which the objects reside will largely determine their networking behavior.

In general, because these are dynamic objects, they can only exist in contexts that would normally be modifiable. This means that Inventories and Items may be used inside Networked, Server, Client, and Local contexts, but they may not be used inside Default or Static contexts.

Simple Inventory Example

Below is a simple example of how to implement an inventory system for players that can pick up in-world items. Pressing Q will drop 1 item from the highest item in the inventory.

-- Networked inventory template
local BACKPACK = script:GetCustomProperty("Backpack")
local players = {}

-- Drop an item when the "Drop Item" action is performed.
-- This can be added to your binding set.
local function DropItem(player, action)

    -- Check the player is in the player's table and the input action is Drop Item.
    if players[player.id] ~= nil and action == "Drop Item" then

        -- Loop based on the total slots the inventory has.
        for i = 1, players[player.id].slotCount do

            -- Get the item based on the slot index.
            local item = players[player.id]:GetItem(i)

            -- Check the item is valid and has a count > 0.
            if item and item.count > 0 then
                local templateId = item.itemTemplateId
                local forward = player:GetViewWorldRotation() * Vector3.FORWARD
                local ray_start = player:GetViewWorldPosition() + forward
                local ray_end = ray_start + forward * 2000
                local hit = World.Raycast(ray_start, ray_end)

                if hit ~= nil then

                    -- Remove 1 from slot based on the index.
                    if players[player.id]:RemoveFromSlot(i, { count = 1 }) then
                        item = World.SpawnAsset(templateId, { networkContext = NetworkContextType.NETWORKED, position = hit:GetImpactPosition() })
                    end
                end

                break
            end
        end
    end
end

-- When a player joins the server spawn an inventory object and assign it to the player.
local function OnPlayerJoined(player)
    local backpack = World.SpawnAsset(BACKPACK, { networkContext = NetworkContextType.NETWORKED })

    backpack:Assign(player)
    backpack.name = player.name
    players[player.id] = backpack
end

local function OnPlayerLeft(player)
    players[player.id]:Destroy()
end

Game.playerJoinedEvent:Connect(OnPlayerJoined)
Game.playerLeftEvent:Connect(OnPlayerLeft)

Input.actionPressedEvent:Connect(DropItem)

local SLOTS = script:GetCustomProperty("Slots"):WaitForObject()

local localPlayer = Game.GetLocalPlayer()
local inv = nil

-- When the inventory has changed for the player, update the slots to show
-- the item count.
local function InventoryChanged(inv, slot)
    local item = inv:GetItem(slot)
    local childIcon = SLOTS:GetChildren()[slot]:FindChildByName("Icon")
    local childCount = SLOTS:GetChildren()[slot]:FindChildByName("Count")

    if item ~= nil then
        local icon = item:GetCustomProperty("icon")

        childIcon:SetImage(icon)
        childIcon.visibility = Visibility.FORCE_ON
        childCount.text = tostring(item.count)
    else
        childIcon.visibility = Visibility.FORCE_OFF
        childCount.text = ""
    end
end

-- Make sure the inventory is initialized.
while inv == nil do
    inv = localPlayer:GetInventories()[1]
    Task.Wait()
end

for i, item in pairs(inv:GetItems()) do
    InventoryChanged(inv, item)
end

inv.changedEvent:Connect(InventoryChanged)

Learn More

Inventory API | InventoryItem API | ItemObject API | Networking