# Inventory Inventories store items on characters. Each inventory is a configurable set of slots that can hold item stacks, with support for filtering, locking, stacking, drag-and-drop, temporary inventories, and persistence. ## Creating an Inventory Entry Open the Spark Editor, go to **Items > Inventory** and click **Create New**. Each inventory entry defines: | Field | Description | | ------------------ | ------------------------------------------------------------------- | | Slot Count | Number of slots in the inventory (default: 20). | | Allow Stacking | Whether items can stack in a single slot. | | Auto Stack Similar | Automatically merge matching items into existing stacks when added. | | Inventory Type | Optional type reference for custom inventory behavior. | ## Slot Filters Individual slots can have filters that restrict what items they accept: | Field | Description | | ------------------ | -------------------------------------------------------------------------------- | | Slot Index | Which slot this filter applies to. | | Allowed Item Types | Whitelist of item types this slot accepts (empty = accept all). | | Blocked Item Types | Blacklist of item types this slot rejects. | | Max Stack Override | Override the item's default max stack size for this slot (0 = use item default). | This lets you create specialized inventory layouts. For example, the first row of slots could only accept potions, or a specific slot could be locked to quest items only. ## Setting Up an Inventory Entity To give a character (or any GameObject) an inventory at runtime, add an **InventoryEntity** component in the Inspector. | Field | Description | | -------------------- | ------------------------------------------------------------------------------------------ | | Inventory Entry | The inventory entry to use as a template. | | Custom Inventory Id | Optional custom ID. Leave empty for auto-generated. | | Auto Create On Start | Automatically create the inventory when the component starts (default: true). | | Destroy On Disable | Destroy the inventory when the component is disabled (default: false). | | Is Persistent | Save and load inventory contents across sessions (default: false). | | Auto Save On Change | Automatically save whenever the inventory changes (default: true). Requires Is Persistent. | | Load On Create | Load saved data when creating the inventory (default: true). Requires Is Persistent. | | Spark Entity | Reference to the SparkEntity on this character. Required for persistence. | ## Inventory Slots Each slot in an inventory is an independent container that holds one item stack. **Slot features:** | Feature | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Locking | Locked slots cannot have items added or removed by the player. Useful for quest items that should not be moved, or reserved slots unlocked later. | | Highlighting | Visual highlight state for UI feedback — for example, highlighting valid slots when the player is dragging an item. | | Quick Use | Marks a slot for quick-use functionality such as hotbar binding. | ## Inventory Operations The inventory supports these operations: | Operation | Description | | --------- | ---------------------------------------------------------------------------------------------------------- | | Add | Add an item to the inventory. If stacking is enabled and a matching stack exists, the item merges into it. | | Remove | Remove an item or quantity from the inventory. | | Move | Move an item between slots within the same inventory. | | Transfer | Move an item from one inventory to another. | | Split | Split a stack into two separate slots. | | Merge | Combine two matching stacks into one slot. | | Sort | Sort all items in the inventory. | | Clear | Remove all items. Optionally skip locked slots. | | Equip | Move an item to an equipment slot. | | Unequip | Return an item from an equipment slot to the inventory. | | Use | Consume or use an item. | ## Temporary Inventories Inventories can be created as temporary with an optional expiration duration. Temporary inventories are useful for timed loot windows, vendor inventories, or any container that should not persist. When a temporary inventory expires, it is automatically cleaned up. ## Drag-and-Drop The inventory system includes built-in drag-and-drop for UI interaction. | Source | Target | Result | | -------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------- | | Inventory Slot | Inventory Slot | Move item between slots. If the target has a compatible item, stacks merge. If both slots have different items, they swap. | | Inventory Slot | Equipment Slot | Equip the item (if compatible). | | Equipment Slot | Inventory Slot | Unequip the item back to the inventory. | | Inventory Slot | Outside Inventory | Triggers an item drop or deletion confirmation. | The drag-and-drop system validates all operations before executing — it checks slot locks, item type filters, stack limits, and slot acceptance rules. Invalid drops are rejected and the item returns to its source slot. ## Persistence When **Is Persistent** is enabled on the InventoryEntity, the inventory contents are saved and loaded through Spark's save system. **What is saved per slot:** | Data | Description | | ---------- | ------------------------------------- | | Slot Index | Which slot the item is in. | | Item Entry | Reference to the item database entry. | | Quantity | Stack count. | | Is Locked | Lock state of the slot. | If **Auto Save On Change** is enabled, the inventory saves automatically whenever any change occurs. If **Load On Create** is enabled, saved data is loaded when the inventory is first created. --- # Agent Instructions: 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: ``` GET https://docs.sparkframework.dev/documentation/user-guide/plugins/items/inventory.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.