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)

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)

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.

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)

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

CanItemFit

Inventory:FindError()

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()

Returns the amount of slots currently filled in the Inventory.

Returns

number
The amount of slots currently filled.

Inventory:GetID()

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

Returns

number
Unique ID of inventory

Inventory:GetItemAt(x, y)

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)

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)

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)

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

Parameters

onlyMain boolean
Whether or not to exclude bags from this search.

Returns

table
The items this Inventory has.

Inventory:GetItemsByBase(baseID, bOnlyMain)

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)

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)

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()

Returns the player that owns this inventory.

Returns

Player
Owning player

OR

nil
If no connected player owns this inventory

Inventory:GetReceivers()

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()

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()

Returns the grid size of this inventory.

Returns

number
Width of inventory
number
Height of inventory

Inventory:HasItem(targetID, data)

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)

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)

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.

Initializes the inventory with the provided arguments.

Parameters

id number
The Inventory's database ID.

width number
The inventory's width.

height number
The inventory's height.

Inventory:Iter()

Returns an iterator that returns all contained items, a better way to iterate items than pairs(inventory:GetItems())

Returns

function
iterator

Inventory:OnCheckAccess(client)

Internal

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

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()

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)

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)

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.

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)

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)

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.

Sets the grid size of this inventory.

Parameters

width number
New width of inventory

height number
New height of inventory

Inventory:Sync(receiver)

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()

Returns a string representation of this inventory

Returns

string
String representation

Example Usage

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