> For the complete documentation index, see [llms.txt](https://wyne.gitbook.io/wyne-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wyne.gitbook.io/wyne-docs/contributing/common/inventories.md).

# Inventories

InventoryUtils: adding, dropping and inspecting ItemStacks against an inventory.

`InventoryUtils` (`common/src/main/java/me/wyne/wutils/common/inventory/InventoryUtils.java`) is the entire `inventory/` package: helpers for adding, dropping, and inspecting `ItemStack`s against inventories, players, and locations.

All of these are item-mutating operations that run on the calling thread — like any other Bukkit inventory API, call them from the main server thread.

## addItem

Four overloads, all funnelling into `Inventory.addItem`:

* `addItem(Inventory, ItemStack...)` (`common/src/main/java/me/wyne/wutils/common/inventory/InventoryUtils.java:26-28`)
* `addItem(Inventory, Collection<ItemStack>)`
* `addItem(Player, ItemStack...)`
* `addItem(Player, Collection<ItemStack>)`

Each returns `true` only if every item fit. Leftovers that didn't fit are **not** returned or tracked — call `Inventory.addItem` directly if you need the excess map back.

## addOrDrop

Four overloads — `addOrDrop(Player, ItemStack...)`, `addOrDrop(Player, Collection<ItemStack>)`, and `boolean setOwner` variants of both (`common/src/main/java/me/wyne/wutils/common/inventory/InventoryUtils.java:46-68`). Adds items to `player`'s inventory, then drops whatever didn't fit at their feet via `drop` (below). When `setOwner` is `true`, dropped items are marked as owned by `player`, subject to Bukkit's normal pickup-delay-vs-owner semantics.

## drop

Four overloads: `drop(Player, ItemStack...)`, `drop(Player, Collection<ItemStack>)`, `drop(Player, boolean setOwner, ItemStack...)`, `drop(Player, boolean setOwner, Collection<ItemStack>)` (`common/src/main/java/me/wyne/wutils/common/inventory/InventoryUtils.java:74-102`), plus a location-based `drop(Location, Collection<ItemStack>)` (`common/src/main/java/me/wyne/wutils/common/inventory/InventoryUtils.java:108-115`).

**Contract worth knowing:** the item collection/varargs argument is itself non-null, but its *elements* may be `null`, and any element that is `null` or `Material.AIR` is silently filtered out before dropping — via [`ItemUtils::isNotNullOrAir`](/wyne-docs/contributing/common/items.md). Callers can pass sparse arrays or collections through unfiltered without pre-cleaning them. Every drop gets `pickupDelay` set to `0`; the player-targeted overloads drop at the player's current location and world.

## getAffectedItems

`getAffectedItems(InventoryClickEvent)` (`common/src/main/java/me/wyne/wutils/common/inventory/InventoryUtils.java:122-131`) collects the item(s) a click event would actually move:

* the clicked slot's current item, always checked;
* additionally the hotbar slot's item, for a `ClickType.NUMBER_KEY` click;
* additionally the off-hand item, for a `ClickType.SWAP_OFFHAND` click.

Null/air items are omitted from the result at each step; the returned `List` is immutable (`List.copyOf`).

## See also

* [Items](/wyne-docs/contributing/common/items.md) for `ItemUtils.isNotNullOrAir`/`isNullOrAir` and the matching null/air tolerance in `ItemUtils.dropActuallyNaturally`.
* [Anvil](/wyne-docs/contributing/common/anvil.md) for another consumer of `InventoryClickEvent` internals.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://wyne.gitbook.io/wyne-docs/contributing/common/inventories.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.