# Item Bar

The Item Bar plugin provides a hotbar system where players can assign items to numbered slots for quick access. Slots can be cycled with scroll wheel input, and the selected item can auto-equip.

## Creating an Item Bar Entry

Open the Spark Editor, go to **Item Bar** and click **Create New**.

Each item bar entry defines:

| Field              | Description                                                                        |
| ------------------ | ---------------------------------------------------------------------------------- |
| Display Name       | Item bar name (e.g., "Main Hotbar", "Consumables Bar").                            |
| Allowed Item Types | Whitelist of item types that can be placed in this bar (empty = accept all types). |

## Setting Up an Item Bar Entity

To give a character an item bar, add an **ItemBarEntity** component in the Inspector.

### Slot Configuration

| Field           | Description                                       |
| --------------- | ------------------------------------------------- |
| Number Of Slots | Total number of hotbar slots (1–20, default: 10). |

### Input Configuration

| Field                   | Description                                               |
| ----------------------- | --------------------------------------------------------- |
| Scroll Input Action     | Input action reference for scroll wheel slot cycling.     |
| Enable Scroll Cycling   | Allow scrolling to switch between slots (default: false). |
| Invert Scroll Direction | Reverse the scroll direction (default: false).            |

### Equipment Integration

| Field            | Description                                                         |
| ---------------- | ------------------------------------------------------------------- |
| Auto Equip Items | Automatically equip the item in the selected slot (default: false). |
| Equipment Entity | Reference to the EquipmentEntity for auto-equipping.                |

### Persistence

| Field               | Description                                                       |
| ------------------- | ----------------------------------------------------------------- |
| Is Persistent       | Save and load item bar contents across sessions (default: false). |
| Load On Initialize  | Auto-load saved data on startup (default: true).                  |
| Auto Save On Change | Auto-save when items change (default: true).                      |

## Slot Features

Each item bar slot supports:

| Feature         | Description                                                                                |
| --------------- | ------------------------------------------------------------------------------------------ |
| Item Assignment | Place any allowed item into the slot.                                                      |
| Locking         | Lock slots to prevent changes.                                                             |
| Selection       | One slot is always the "selected" slot. Switching selection can trigger equipment changes. |

Slot switching is blocked while a UI is open or during an ability cast (using the Rules system).

## Item Bar Display UI

The **ItemBarDisplayView** component displays the item bar in-game.

| Field              | Description                                                                                                      |
| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
| Item Bar Entry     | Type restrictions for item validation.                                                                           |
| Connection Type    | How to find the ItemBarEntity: **Scene Reference** (direct drag-and-drop) or **Find By Tag** (auto-find by tag). |
| Item Bar Entity    | Direct reference when using Scene Reference.                                                                     |
| Item Bar Tag       | Tag to search for when using Find By Tag (default: "Player").                                                    |
| Search In Children | Search in child GameObjects when finding by tag.                                                                 |
| Slot UIs           | List of pre-existing slot UI components.                                                                         |

## Drag-and-Drop

Item bar slots support drag-and-drop with inventories:

| Source         | Target         | Result                              |
| -------------- | -------------- | ----------------------------------- |
| Item Bar Slot  | Item Bar Slot  | Swap items between slots.           |
| Inventory Slot | Item Bar Slot  | Move item from inventory to hotbar. |
| Item Bar Slot  | Inventory Slot | Move item from hotbar to inventory. |

The drag-and-drop system respects the item bar's allowed item types and slot lock states.


---

# 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/item-bar.md?ask=<question>
```

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.