Inventories are a fixed size grid of slots capable of holding an amount of items e.g. Item("bucket_noted", 15). The player backpack (aka the inventory), worn equipment, and beast of burden are examples of inventories used by players. Shops are an example of inventories used by npcs. Inventory definitions are found in inventories.yml.

Items come in two categories: stackable and non-stackable. Stackable items can have up to 2,147 million items within one slot. Non-stackable items can only have 1 item per slot.

This means having two non-stackable items like a bronze_dagger will take up two slots, where two stackable bronze_dagger_noted will take up only one slot.

Each inventory has a stack mode which can change the stacking behaviour, banks for example will always stack items even if they are non-stackable.

bank:
  id: 95
  stack: Always

An item can be checked if stackable against a certain inventory using the stackable() function:

val stackable = player.bank.stackable("bronze_dagger") // true

Player's have a map of inventories connected to them, you can access one by calling:

val equipment = player.inventories.inventory("worn_equipment")

val Player.equipment: Inventory
    get() = inventories.inventory("worn_equipment")

You can check if an inventory has an item or a number of items using contains

if (!inventory.contains("tinderbox")) {
    message("You don't have the required items to light this.")
    return
}

And count exactly how many of an item is in an inventory, regardless of stack behaviour.

val goldBars = player.inventory.count("gold_bar")

There are a number of functions to help manage the free slots in an inventory.

Adding a single item or a stack of items is simple with the add helper function

player.inventory.add("coins", 100)

If an inventory is full the item won't be added and add will return false allowing you to run different code depending on the outcome.

if (player.inventory.add("silverlight")) {
    npc<Furious>("Yes, I know, someone returned it to me. Take better care of it this time.")
} else {
    npc<Furious>("Yes, I know, someone returned it to me. I'll keep it until you have free inventory space.")
}

Removing items is much the same as adding, the remove item will return true when the required number of items was removed, and false when the inventory doesn't have the required amount.

player.inventory.remove("coins", 123)

Clearing will remove an item from a given slot, regardless of amount

player.inventory.clear(4)

Clear without a slot will remove all items from an inventory

player.loan.clear()

Replace is commonly used to switch one non-stackable item for another of a different type

inventoryItem("Empty", "pot_of_flour", "inventory") {
    player.inventory.replace("pot_of_flour", "empty_pot")
}

Move will take all of the items on one slot add it to another slot in the same or a different inventory only if the target slot is empty.

inventoryOption("Remove", "worn_equipment") {
    val success = player.equipment.move(slot, player.inventory) // true
}

There are plenty of other helper functions to explore that should cover the majority of use-cases, for a full list see InventoryOperations.kt.