Understand Inventory
When to use
Inventory is an optional, Stable-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
For a connected starting setup, choose Inventory Canvas in Tools > Lost Lily > Grid Toolkit > Create Grid Board.... It creates a Square item asset, structure library, label visual, Canvas renderer with a font, and Place/Move/Reset sample controls. Follow Interact with a uGUI board to add pointer dragging and consult the working Inventory topology examples.
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
Ownership and operation contracts
The board owner controls its live state and disposes it when rebuilt or destroyed. A view binds to that state without owning it. Keep actions, definitions, snapshots, logical drag sessions, and temporary presentation separate; disposing a presenter never disposes a customer board.
Preview is read-only and publishes no committed events. Failed actions, sorting, transfers, and merges leave every affected live board unchanged. A successful Apply publishes the committed operation result and mutation batch. Read failure codes and diagnostics from the current result; invalid API arguments such as null resolvers throw argument exceptions. Do not mutate live state from planning callbacks.
Quantity is an integer in [1, MaxStack]; non-stackable items have quantity one. Remove the
structure to delete a stack instead of setting quantity to zero. A missing instance quantity
extension reads as one. Sorting compares category, sort key, display name, item ID, and instance
ID using ordinal comparisons, then original index. It tries board anchors deterministically;
rotation-to-fit is opt-in and a failed arrangement commits nothing.
Transfers preserve instance identity and require a resolvable definition and valid free footprint on the destination. A transfer to the same board follows move behavior. Stack merges require matching item IDs and stackable definitions, fill the target to its capacity, retain any remainder, and remove a fully consumed source stack. Cross-board operations commit atomically.
Snapshots require the Inventory definition and instance resolvers. Preserve definition, item, instance, topology, and project extension identities and version project-owned save schemas. Restoration validates before committing, increments the current revision once, and emits a restoration batch. These rules apply to Square, Hex, and Triangle Inventory authoring.
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. |