Inventory
The Inventory API provides functionality for managing player items and currency in Highrise Studio.
Use Inventory for:
- Player items (weapons, collectibles, consumables)
- Currency and virtual goods
- Transaction-based inventory operations
IMPORTANT: Inventory API is only available on the SERVER side.
Transaction System:
- All inventory changes are done through transactions for data consistency
- Transactions can be committed (applied) or rolled back (cancelled)
- Use InventoryTransaction with: Give, Take, Move, Reserve, Release operations
For persistent non-item data (scores, progress), use the Storage API instead.
Methods
Commits an inventory transaction, applying all operations.
Use InventoryTransaction to create transactions with:
- Give/GivePlayer (add items to inventory)
- Take/TakePlayer (remove items from inventory)
- Move/MovePlayers (transfer items between holders)
- Reserve/ReservePlayer (lock items for specific purpose)
- Release/ReleasePlayer (unlock reserved items)
Transactions ensure atomic operations - all succeed or all fail. A transaction ID is returned which can be used for rollback if needed.
-- Without callback
local transaction = InventoryTransaction.new()
transaction:GivePlayer(player, "coins", 100)
transaction:TakePlayer(player, "gems", 5)
Inventory.CommitTransaction(transaction)
-- With callback
local transaction = InventoryTransaction.new()
transaction:GivePlayer(player, "sword", 1)
Inventory.CommitTransaction(transaction, function(transactionId, error)
if error == InventoryError.None then
print("Transaction committed: " .. transactionId)
else
print("Transaction failed: " .. tostring(error))
end
end)
Parameters
transaction
Returns
Commits an inventory transaction, applying all operations.
Use InventoryTransaction to create transactions with:
- Give/GivePlayer (add items to inventory)
- Take/TakePlayer (remove items from inventory)
- Move/MovePlayers (transfer items between holders)
- Reserve/ReservePlayer (lock items for specific purpose)
- Release/ReleasePlayer (unlock reserved items)
Transactions ensure atomic operations - all succeed or all fail. A transaction ID is returned which can be used for rollback if needed.
-- Without callback
local transaction = InventoryTransaction.new()
transaction:GivePlayer(player, "coins", 100)
transaction:TakePlayer(player, "gems", 5)
Inventory.CommitTransaction(transaction)
-- With callback
local transaction = InventoryTransaction.new()
transaction:GivePlayer(player, "sword", 1)
Inventory.CommitTransaction(transaction, function(transactionId, error)
if error == InventoryError.None then
print("Transaction committed: " .. transactionId)
else
print("Transaction failed: " .. tostring(error))
end
end)
Parameters
transaction
callback
Returns
Retrieves a single item from an inventory holder's inventory. The callback receives the item and error code. If the item doesn't exist, item is nil and error is InventoryError.None.
Inventory.GetItem(player.user.id, "sword_123", function(item, error)
if error == InventoryError.None then
if item ~= nil then
print("Item amount: " .. item.amount)
else
print("Item not found")
end
else
print("Error: " .. tostring(error))
end
end)
Parameters
holderId
itemId
callback
Returns
Retrieves multiple items from an inventory holder's inventory with pagination.
Pagination: Pass nil for cursor to get first results. Use returned cursor for next page. If returned cursor is nil, no more results exist.
Callback receives: array of InventoryItems, cursor, error
Inventory.GetItems(player.user.id, 10, nil, function(items, cursor, error)
if error == InventoryError.None then
print("Found " .. #items .. " items")
for i, item in ipairs(items) do
print("Item: " .. item.id .. " x" .. item.amount)
end
-- Get next page if available
if cursor ~= nil then
-- Call GetItems again with cursor
end
end
end)
Parameters
holderId
limit
cursor
callback
Returns
Retrieves a single item from a player's inventory. Convenience method equivalent to: GetItem(player.user.id, itemId, callback)
Inventory.GetPlayerItem(player, "coins", function(item, error)
if error == InventoryError.None and item ~= nil then
print(player.name .. " has " .. item.amount .. " coins")
end
end)
Parameters
Returns
Retrieves multiple items from a player's inventory with pagination. Convenience method equivalent to: GetItems(player.user.id, limit, cursor, callback)
Inventory.GetPlayerItems(player, 20, nil, function(items, cursor, error)
if error == InventoryError.None then
print(player.name .. " inventory:")
for i, item in ipairs(items) do
print("- " .. item.id .. ": " .. item.amount)
end
end
end)
Parameters
player
limit
cursor
callback
Returns
Rolls back a previously committed transaction, reversing all operations.
Use this to undo inventory changes if something goes wrong after a transaction. For example, if a player disconnects before receiving their purchased items.
Requires the transactionId returned from CommitTransaction.
-- Without callback
Inventory.RollbackTransaction(transactionId)
-- With callback
Inventory.RollbackTransaction(transactionId, function(error)
if error == InventoryError.None then
print("Transaction rolled back successfully")
else
print("Rollback failed: " .. tostring(error))
end
end)
Parameters
transactionId
Returns
Rolls back a previously committed transaction, reversing all operations.
Use this to undo inventory changes if something goes wrong after a transaction. For example, if a player disconnects before receiving their purchased items.
Requires the transactionId returned from CommitTransaction.
-- Without callback
Inventory.RollbackTransaction(transactionId)
-- With callback
Inventory.RollbackTransaction(transactionId, function(error)
if error == InventoryError.None then
print("Transaction rolled back successfully")
else
print("Rollback failed: " .. tostring(error))
end
end)
Parameters
transactionId
callback
Returns
Updated 19 days ago
