# `inventory`

Your own inventory, addressed by player-screen slot numbers. For the slots of an open
container, use [`container`](screen.md#container).

| Function | Does |
|----------|------|
| `inventory.swap(a, b)` | Swaps two slots |
| `inventory.drop(slot[, all])` | Drops from a slot; `all` defaults to `true`, the whole stack |
| `inventory.merge(from, to)` | Moves a stack onto another |
| `inventory.use(slot[, yaw, pitch])` | Uses the item in a slot, facing a direction first when given |
| `inventory.item(slot)` | Live [item handle](item.md), or `nil` |
| `inventory.find(item_id)` | First slot holding that item, or `nil` |
| `inventory.count(item_id)` | Total count of that item you carry |
| `inventory.cooldown(item_id)` | Cooldown progress, `1` right after use down to `0` when ready |
| `inventory.slot()`, `inventory.set_slot(i)` | Reads and sets the selected hotbar slot, `0–8` |

## `hotbar`

Arbitrated slot holds for keeping a hotbar slot selected **across ticks**. Holds from every
module and script compose by priority, and the service restores the pre-override slot when
the last hold releases — never save and restore `inventory.slot()` yourself around a
multi-tick hold. For an atomic same-tick switch–use–switch-back, plain `set_slot` is fine.

| Function | Does |
|----------|------|
| `hotbar.hold(slot[, priority])` | Holds a hotbar slot `0–8`, `false` when outprioritized |
| `hotbar.release()` | Releases this script's hold |
| `hotbar.owns()` | Whether this script holds the hotbar right now |
| `hotbar.base()` | The slot selected before any hold overrode it |

The hold belongs to the script and is released automatically on script reload; still pair
`hold` with `release` in `disable`.

## Slot numbering

| Range | Holds |
|-------|-------|
| `0` | Crafting result |
| `1–4` | Crafting grid |
| `5–8` | Armor, helmet to boots |
| `9–35` | Main inventory |
| `36–44` | Hotbar |
| `45` | Offhand |

```lua
module:event("tick", function()
    local totem = inventory.find("minecraft:totem_of_undying")
    if totem and inventory.item(45):id() ~= "minecraft:totem_of_undying" then
        inventory.swap(totem, 45)
    end
end)
```