Skip to content

inventory_api.md

Latest commit

 

History

History
317 lines (224 loc) · 6.17 KB

inventory_api.md

File metadata and controls

317 lines (224 loc) · 6.17 KB
Raw

Inventory API Documentation

The Inventory API provides Lua scripts with the ability to create and manage inventories, including custom GUI inventories, item manipulation, and inventory operations.

Global Access

The API is accessed via the global InventoryApi table in Lua scripts.

Methods

createInventory

Creates a new inventory.

Syntax:

local inventory = InventoryApi:createInventory(size, title)
-- or
local inventory = InventoryApi:createInventory(holder, size, title)

Parameters:

  • size (number): Inventory size (must be a multiple of 9 between 9 and 54)
  • title (userdata): A Component object for the inventory title (from AdventureApi)
  • holder (userdata, optional): An InventoryHolder (e.g., a Player) to own the inventory

Returns:

  • inventory (userdata): The Inventory object, or nil on failure

Example:

local title = AdventureApi:parseMiniMessage("<gold>My Inventory</gold>")
local inv = InventoryApi:createInventory(27, title)

createItem

Creates an ItemStack.

Syntax:

local itemStack = InventoryApi:createItem(material, [amount], [displayName])

Parameters:

  • material (string): The material name (e.g., "DIAMOND", "STONE")
  • amount (number, optional): The stack size (defaults to 1, clamped to material's max stack size)
  • displayName (userdata, optional): A Component object for the item's display name

Returns:

  • itemStack (userdata): The ItemStack object, or nil on failure

Example:

local item = InventoryApi:createItem("DIAMOND", 64)
local namedItem = InventoryApi:createItem("DIAMOND_SWORD", 1, AdventureApi:parseMiniMessage("<red>Excalibur</red>"))

fillBackground

Fills empty slots in an inventory with a filler material.

Syntax:

InventoryApi:fillBackground(inventory, fillerMaterial)

Parameters:

  • inventory (userdata): The Inventory to fill
  • fillerMaterial (string): The material name for the filler (e.g., "GRAY_STAINED_GLASS_PANE")

Returns:

  • inventory (userdata): The modified Inventory object

Example:

InventoryApi:fillBackground(inv, "GRAY_STAINED_GLASS_PANE")

setItem

Sets an item in a specific slot.

Syntax:

InventoryApi:setItem(inventory, slot, itemStack)

Parameters:

  • inventory (userdata): The Inventory to modify
  • slot (number): The slot index (0-based)
  • itemStack (userdata): The ItemStack to set

Returns:

  • inventory (userdata): The modified Inventory object

Example:

local item = InventoryApi:createItem("DIAMOND", 1)
InventoryApi:setItem(inv, 0, item)

getItem

Gets the item in a specific slot.

Syntax:

local itemStack = InventoryApi:getItem(inventory, slot)

Parameters:

  • inventory (userdata): The Inventory to query
  • slot (number): The slot index (0-based)

Returns:

  • itemStack (userdata): The ItemStack in the slot, or nil if empty

Example:

local item = InventoryApi:getItem(inv, 0)

addItem

Adds an item to the inventory.

Syntax:

local fullyAdded = InventoryApi:addItem(inventory, itemStack)

Parameters:

  • inventory (userdata): The Inventory to add to
  • itemStack (userdata): The ItemStack to add

Returns:

  • fullyAdded (boolean): true if the entire stack was added, false if the inventory is full

Example:

local item = InventoryApi:createItem("DIAMOND", 64)
local success = InventoryApi:addItem(inv, item)

clearSlot

Clears a specific slot.

Syntax:

InventoryApi:clearSlot(inventory, slot)

Parameters:

  • inventory (userdata): The Inventory to modify
  • slot (number): The slot index (0-based)

Example:

InventoryApi:clearSlot(inv, 0)

clear

Clears all items from the inventory.

Syntax:

InventoryApi:clear(inventory)

Parameters:

  • inventory (userdata): The Inventory to clear

Example:

InventoryApi:clear(inv)

getSize

Gets the size of the inventory.

Syntax:

local size = InventoryApi:getSize(inventory)

Parameters:

  • inventory (userdata): The Inventory to query

Returns:

  • size (number): The number of slots in the inventory

Example:

local size = InventoryApi:getSize(inv)
print("Inventory size: " .. size)

firstEmpty

Gets the first empty slot in the inventory.

Syntax:

local slot = InventoryApi:firstEmpty(inventory)

Parameters:

  • inventory (userdata): The Inventory to query

Returns:

  • slot (number): The first empty slot index, or -1 if the inventory is full

Example:

local slot = InventoryApi:firstEmpty(inv)
if slot >= 0 then
    InventoryApi:setItem(inv, slot, item)
end

contains

Checks if the inventory contains a specific material.

Syntax:

local contains = InventoryApi:contains(inventory, material)

Parameters:

  • inventory (userdata): The Inventory to query
  • material (string): The material name to check for

Returns:

  • contains (boolean): true if the inventory contains the material

Example:

if InventoryApi:contains(inv, "DIAMOND") then
    print("Inventory contains diamonds")
end

open

Opens an inventory for a player.

Syntax:

InventoryApi:open(player, inventory)

Parameters:

  • player (userdata): The Player to open the inventory for
  • inventory (userdata): The Inventory to open

Example:

InventoryApi:open(player, inv)

close

Closes a player's currently open inventory.

Syntax:

InventoryApi:close(player)

Parameters:

  • player (userdata): The Player whose inventory should be closed

Example:

InventoryApi:close(player)

Notes

  • Inventory sizes must be multiples of 9 between 9 and 54 (standard chest sizes)
  • Slot indices are 0-based (0 to size-1)
  • Material names must be valid Bukkit material names
  • Amount values are automatically clamped to the material's maximum stack size
  • Display names use Adventure API Components for formatting
  • The fillBackground method only fills empty slots, preserving existing items
  • The addItem method returns false if the inventory is full and some items couldn't be added