Understand Inventory
When to use
Inventory is an optional, Preview-tier gameplay module included with Grid Toolkit. Use it when placed structures also need item metadata, quantities, sorting, stack merging, or atomic transfers between boards. Inventory augments an ordinary Grid Toolkit board; there is no separate Inventory board type.
Before you start
Complete Create your first board or have an authored board ready. The Inventory path assumes that Unity creates and owns the board state. Runtime excerpts then work with the item definitions and instance IDs established by that authored setup.
Logical Inventory does not require a renderer, Canvas, or EventSystem. Add those only when the inventory must be visible or interactive.
Procedure
Follow the pages in order for the first implementation. Return directly to a later page when you only need one operation.
- Add Inventory to a board in Unity.
- Add, read, update, and remove items.
- Move, rotate, and sort items.
- Transfer and merge items.
- Save and restore Inventory.
- Display Inventory state and feedback.
Inventory identities
| Term | Meaning |
|---|---|
| Item asset or item type | The Unity asset you edit. It combines a topology-specific structure definition with Inventory metadata. |
| Structure definition | The immutable footprint, layer, orientation rules, and descriptive extensions produced from the item asset. |
| Placed item instance | A structure placed on a board at runtime. It owns mutable instance data such as quantity. |
| Structure ID | Resolves the structure definition from the board's structure library. |
| Item ID | Identifies stack-compatible item types. Matching item IDs are required for a merge. |
| Instance ID | Identifies one placed item on one board. Actions use it to move, update, or remove that instance. |
| Quantity | Mutable instance data. An item without a quantity extension behaves as quantity 1. |
The GridInventoryItemDefinitionExtension stores item-type metadata on the structure definition. The GridInventoryItemInstanceExtension stores quantity on the placed structure instance.
Capabilities
| Goal | Use |
|---|---|
| Author item types and initial contents | Inventory item assets, a structure library, and setup placements |
| Place, remove, or inspect an item | Built-in structure actions and read-only structure views |
| Change quantity, move, rotate, or sort | Inventory actions |
| Transfer or merge across boards | Inventory operations with atomic multi-board commits |
| Save item metadata and quantities | Inventory definition and instance snapshot resolvers |
| Show quantities and action feedback | Inventory visualization helpers and a retained renderer |
| Add pointer interaction | The optional uGUI renderer and project-owned input handling |
Result
Inventory item types are authored structure definitions, placed items are structure instances, and runtime extensions hold per-instance values such as quantity. Every focused Inventory guide builds on ordinary board state and uses the same preview, diagnostics, revision, event, persistence, and visualization rules as the rest of Grid Toolkit.
Troubleshooting
| Symptom | Check |
|---|---|
| An item action cannot resolve its definition. | Confirm the item asset is in the structure library used by the board setup. |
| Two stacks do not merge. | Confirm both item definitions use the same item ID, allow stacking, and leave capacity in the target stack. |
| Quantity is missing. | Quantity 1 is implicit. Add an instance extension only when the value must differ or be persisted explicitly. |