Inventory

Holds items within a grid layout.

Inventories are an object that contains Items in a grid layout. Every Character will have exactly one inventory attached to it, which is the only inventory that is allowed to hold bags - any item that has its own inventory (i.e a suitcase). Inventories can be owned by a character, or it can be individually interacted with as a standalone object. For example, the container plugin attaches inventories to props, allowing for items to be stored outside of any character inventories and remain "in the world".

You may be looking for the following common functions:

Add Which adds an item to the inventory.

GetItems Which gets all of the items inside the inventory.

GetItemByID Which gets an item in the inventory by it's item ID.

GetItemAt Which gets an item in the inventory by it's x and y

GetID Which gets the inventory's ID.

HasItem Which checks if the inventory has an item.

Functions

Inventory:Add(uniqueID, quantity, data, x, y, noReplication)

View source »

Add an item to the inventory.

Parameters

  • uniqueID

    The item unique ID (e.g "handheld_radio") or instance ID (e.g 1024) to add to the inventory

  • quantity number default: 1

    The quantity of the item to add

  • data table

    Item data to add to the item

  • x number default: nil

    The X position for the item

  • y number default: nil

    The Y position for the item

  • noReplication boolean default: false

    Whether or not the item's addition should not be replicated

Returns

  • bool

    Whether the add was successful or not

  • string

    The error, if applicable

  • OR
  • number

    The X position that the item was added to

  • number

    The Y position that the item was added to

  • number

    The inventory ID that the item was added to

Inventory:AddReceiver(client)

View source »

Adds a player as a receiver on this Inventory Receivers are players who will be networked the items inside the inventory.

Calling this will not automatically sync it's current contents to the client. All future contents will be synced, but not anything that was not synced before this is called.

This function does not check the validity of client, therefore if client doesn't exist, it will error.

Parameters

  • client Player

    The player to add as a receiver.

Inventory:CanItemFit(x, y, w, h, item2)

Internal

This is an internal function! You are able to use it, but you risk unintended side effects if used incorrectly.

View source »

Checks whether or not an Item can fit into the Inventory starting from x and y. Internally used by FindEmptySlot, in most cases you are better off using that. This function will search if all of the slots within x + width and y + width are empty, ignoring any space the Item itself already occupies.

Parameters

  • x number

    The beginning x coordinate to search for.

  • y number

    The beginning y coordiate to search for.

  • w number

    The Item's width.

  • h number

    The Item's height.

  • item2 Item default: nil

    An Item, if any, to ignore when searching.

Inventory:FindEmptySlot(w, h, onlyMain)

View source »

Finds an empty slot of a specified width and height. In most cases, to check if an Item can actually fit in the Inventory, as if it can't, it will just return nil.

FindEmptySlot will loop through all the slots for you, as opposed to CanItemFit which you specify an x and y for. this will call CanItemFit anyway. If you need to check if an item will fit exactly at a position, you want CanItemFit instead.

Parameters

  • w number

    The width of the Item you are trying to fit.

  • h number

    The height of the Item you are trying to fit.

  • onlyMain boolean

    Whether or not to search any bags connected to this Inventory

Returns

  • number

    x The x coordinate that the Item can fit into.

  • number

    y The y coordinate that the Item can fit into.

  • OR
  • number

    x The x coordinate that the Item can fit into.

  • number

    y The y coordinate that the Item can fit into.

  • Inventory

    bagInv If the item was in a bag, it will return the inventory it was in.

See Also

Inventory:FindError()

View source »

Searches the inventory to find any stacked items. A common problem with developing, is that items will sometimes error out, or get corrupt. Sometimes, the server knows things you don't while developing live This function can be helpful for getting rid of those pesky errors.

Inventory:GetFilledSlotCount()

View source »

Returns the amount of slots currently filled in the Inventory.

Returns

  • number

    The amount of slots currently filled.

Inventory:GetID()

View source »

Returns this inventory's database ID. This is guaranteed to be unique.

Returns

  • number

    Unique ID of inventory

Inventory:GetItemAt(x, y)

View source »

Returns the item that currently exists within x and y in the Inventory. Items that have a width or height greater than 0 occupy more than 1 x and y.

Parameters

  • x number

    The x coordindate to search in.

  • y number

    The y coordinate to search in.

Returns

  • number

    x The x coordinate that the Item is located at.

  • number

    y The y coordinate that the Item is located at.

Inventory:GetItemByID(id, onlyMain)

View source »

Get an item by it's specific Database ID.

Parameters

  • id number

    The ID to search for.

  • onlyMain boolean

    Whether or not to exclude bags that are present from the search.

Returns

  • item

    The item if it exists.

Inventory:GetItemCount(uniqueID, onlyMain)

View source »

Returns a count of a specific Items in the Inventory

Parameters

  • uniqueID string

    The Unique ID of the item.

  • onlyMain boolean

    Whether or not to exclude bags that are present from the search.

Returns

  • number

    The amount of Items this inventory has.

Example Usage

local curHighest, winner = 0, false
for client, character in ix.util.GetCharacters() do
 local itemCount = character:GetInventory():GetItemCount('water', false)
 if itemCount > curHighest then
  curHighest = itemCount
  winner = character
 end
end
-- Finds the thirstiest character on the server and returns their Character ID or false if no character has water.

Inventory:GetItems(onlyMain)

View source »

Returns a table of all the items that an Inventory has.

Parameters

  • onlyMain boolean

    Whether or not to exclude bags from this search.

Returns

Inventory:GetItemsByBase(baseID, bOnlyMain)

View source »

Returns a table of Items by their base.

Parameters

  • baseID string

    The base to search for.

  • bOnlyMain boolean

    Whether or not to exclude bags that are present from the search.

Inventory:GetItemsByID(id, onlyMain)

View source »

Get a table of Items by their specific Database ID. It's important to note that while in 99% of cases, items will have a unique Database ID, developers or random GMod weirdness could cause a second item with the same ID to appear, even though, ix.item.instances will only store one of those. The inventory only stores a reference to the ix.item.instance ID, not the memory reference itself.

Parameters

  • id number

    The ID to search for.

  • onlyMain boolean

    Whether or not to exclude bags that are present from the search.

Returns

  • item

    The item if it exists.

Inventory:GetItemsByUniqueID(uniqueID, onlyMain)

View source »

Returns a table of all Items in the Inventory by their Unique ID. Not to be confused with GetItemsByID or GetItemByID which take in an Item Instance's ID instead.

Parameters

  • uniqueID string

    The Unique ID of the item.

  • onlyMain boolean

    Whether or not to exclude bags that are present from the search.

Returns

  • number

    The table of specified Items this inventory has.

Inventory:GetOwner()

View source »

Returns the player that owns this inventory.

Returns

  • Player

    Owning player

  • OR
  • nil

    If no connected player owns this inventory

Inventory:GetReceivers()

View source »

Get all of the receivers this Inventory has. Receivers are players who will be networked the items inside the inventory.

This function will automatically sort out invalid players for you.

Returns

  • table

    result The players who are on the server and allowed to see this table.

Inventory:GetShouldSave()

View source »

Gets whether or not an Inventory should save. Inventories that are marked to not save will not update in the Database, if they inventory is already saved, it will not be deleted when unloaded.

Returns

  • bool

    Returns the field noSave.

  • OR
  • bool

    Returns true if the field noSave is not registered to this inventory.

Inventory:GetSize()

View source »

Returns the grid size of this inventory.

Returns

  • number

    Width of inventory

  • number

    Height of inventory

Inventory:HasItem(targetID, data)

View source »

Returns the item with the given unique ID (e.g "handheld_radio") if it exists in this inventory. This method checks both this inventory, and any bags that this inventory has inside of it.

Parameters

  • targetID string

    Unique ID of the item to look for

  • data table optional

    Item data to check for

Returns

  • Item

    Item that belongs to this inventory with the given criteria

  • OR
  • bool

    false if the item does not exist

Example Usage

local item = inventory:HasItem("handheld_radio")

if (item) then
	-- do something with the item table
end

See Also

Inventory:HasItemOfBase(baseID, data)

View source »

Whether or not an Inventory has an item of a base, optionally with specified data. This function has an optional data argument, which will take a table. it will match if the data of the item is correct or not.

Items which are a base will automatically have base_ prefixed to their Unique ID, if you are having trouble finding your base, that is probably why.

Parameters

  • baseID string

    The Item Base's Unique ID.

  • data table optional

    The Item's data to compare against.

Returns

  • item

    The first Item of baseID that is found and there is no data argument or data was matched.

  • OR
  • false

    If no Items of baseID is found or the data argument, if specified didn't match.

Example Usage

local bHasWeaponEquipped = Entity(1):GetCharacter():GetInventory():HasItemOfBase('base_weapons', {['equip'] = true})
if bHasWeaponEquipped then
 Entity(1):Notify('One gun is fun, two guns is Woo-tastic.')
end
-- Notifies the player that they should get some more guns.

Inventory:HasItems(targetIDs)

View source »

Checks whether or not the Inventory has a table of items. This function takes a table with no keys and runs in order of first item > last item, this is due to the usage of the # operator in the function.

Parameters

  • targetIDs table

    A table of Item Unique ID's.

Returns

  • bool

    true Whether or not the Inventory has all of the items.

  • table

    targetIDs Your provided targetIDs table, but it will be empty.

  • OR
  • bool

    false

  • table

    targetIDs Table consisting of the items the Inventory did not have.

Example Usage

local itemFilter = {'water', 'water_sparkling'}
if not Entity(1):GetCharacter():GetInventory():HasItems(itemFilter) then return end
-- Filters out if this player has both a water, and a sparkling water.

Inventory:Initialize(id, width, height)

Internal

This is an internal function! You are able to use it, but you risk unintended side effects if used incorrectly.

View source »

Initializes the inventory with the provided arguments.

Parameters

  • width number

    The inventory's width.

  • height number

    The inventory's height.

Inventory:OnCheckAccess(client)

Internal

This is an internal function! You are able to use it, but you risk unintended side effects if used incorrectly.

View source »

Checks whether a player has access to an inventory

Parameters

  • client Player

    Player to check access for

Returns

  • bool

    Whether or not the player has access to the inventory

Inventory:PrintAll()

View source »

Prints out the id, width, height, slots and each item in each slot of an Inventory, used for debugging.

Inventory:Remove(id, bNoReplication, bNoDelete, bTransferring)

View source »

Removes an item from the inventory.

Parameters

  • id number

    The item instance ID to remove

  • bNoReplication boolean default: false

    Whether or not the item's removal should not be replicated

  • bNoDelete boolean default: false

    Whether or not the item should not be fully deleted

  • bTransferring boolean default: false

    Whether or not the item is being transferred to another inventory

Returns

  • number

    The X position that the item was removed from

  • number

    The Y position that the item was removed from

Inventory:RemoveReceiver(client)

View source »

The opposite of AddReceiver. This function does not check the validity of client, therefore if client doesn't exist, it will error.

Parameters

  • client Player

    The player to remove from the receiver list.

Inventory:SendSlot(x, y, item)

Internal

This is an internal function! You are able to use it, but you risk unintended side effects if used incorrectly.

View source »

Sends a specific slot to a character. This will not send all of the slots of the Item to the character, items can occupy multiple slots.

This will call OnSendData on the Item using all of the Inventory's receivers.

This function should not be used to sync an entire inventory, if you need to do that, use AddReceiver and Sync.

Parameters

  • x number

    The Inventory x position to send.

  • y number

    The Inventory y position to send.

  • item Item optional

    The item to send, if any.

See Also

Inventory:SetOwner(owner, fullUpdate)

View source »

Sets the player that owns this inventory.

Parameters

  • owner Player

    The player to take control over the inventory.

  • fullUpdate boolean

    Whether or not to update the inventory immediately to the new owner.

Inventory:SetShouldSave(bNoSave)

View source »

Sets whether or not an Inventory should save. This will prevent an Inventory from updating in the Database, if the inventory is already saved, it will not be deleted when unloaded.

Parameters

  • bNoSave boolean

    Whether or not the Inventory should save.

Inventory:SetSize(width, height)

Internal

This is an internal function! You are able to use it, but you risk unintended side effects if used incorrectly.

View source »

Sets the grid size of this inventory.

Parameters

  • width number

    New width of inventory

  • height number

    New height of inventory

Inventory:Sync(receiver)

View source »

Syncs the Inventory to the receiver. This will call Item.OnSendData on every item in the Inventory.

Parameters

  • receiver Player

    The player to

Inventory:__tostring()

View source »

Returns a string representation of this inventory

Returns

  • string

    String representation

Example Usage

print(ix.item.inventories[1])
 > "inventory[1]"