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.