Item Shape Inventory Grid
The Version 1 spatial inventory component is Item Shape Grid. Its controller and data belong beside the Inventory; the panel displays that state. Use the Item Shape Grid guide for footprint authoring, UI creation and the full Inspector/module setup.

This reference explains collection scope, placement, stacking and persistence when configuring an Inventory-backed spatial Bag.
Bind one layout to its owning Inventory
Create through UI Designer > Item Shape Grid. Assign Inventory, choose a real Bag collection, set Grid Size and pixel Item Shape Size, then create the connected controller/data/view. The first data entry uses ID 0; additional entries need unique IDs.

| Contract | Required configuration |
|---|---|
| Inventory owner | Panel binding points to the Inventory containing controller/data. |
| Data identity | View Item Shape Grid Data ID equals data ID. |
| Dimensions | View/data Grid Size agree; resize connected slots/layout through UI Designer. |
| Collections | Explicit Bag names for a spatial Bag; an empty Item Collections array deliberately includes all collections. |
| Attribute | Definition Shape is ItemShape and matches controller/View Shape Attribute Name. |

Choose collection scope and capacity
The controller selects the first data entry matching receiving collection and Item Info Filter, then checks space there. Order overlapping entries deliberately and enable Warn If Multiple Match while testing. A later matching grid is not an overflow destination for a full first match.
No Grid Add Item, off by default, chooses whether an item with no matching data can be added. It does not bypass the capacity check of a matching grid. Keep it off when every normal Bag item must obtain a footprint, and use Inventory/controller APIs for additions.
Only Try Add To First Collection starts off. The data considers connected collections in order and chooses the first nonzero permitted result, including a partial result; it does not distribute the remaining request across later collections. When enabled, only the first collection is attempted. Define full-amount checks or custom remainder handling where the operation needs all-or-nothing placement.
Hide/Loadout-purpose items do not receive normal footprints, but keep their additions compatible with controller capacity checks. Use a separate Inventory or custom restriction policy when those collections must operate independently of spatial capacity.
Understand footprints and stacking

The authored shape contains rows/columns, enabled cells and an enabled anchor. Placement aligns that anchor with a candidate destination. The complete rectangular bounds, including disabled cells, must stay inside the grid; only enabled cells require free space. Author alternate orientations with custom selection/placement when rotation is required.
New placement scans top-left, row by row. A same-frame collection transfer can reuse the item’s recently cleared position. One ItemStack occupies one footprint regardless of amount. A non-unique, stack-compatible item can reuse an existing footprint when the receiving collection accepts its complete amount into that stack; otherwise another footprint is needed.
The controller follows Inventory add/remove events to place and clear stacks. Keep placement consistent by using the controller/grid/data operations rather than writing individual cells or bypassing Inventory restrictions.
Match movement to the spatial view

The background supplies one interactive slot per cell; the foreground supplies one coherent View per stack. Keep both layers aligned with matching cell sizes/origins, and let the foreground Canvas Group pass input to background cells. Shape sizing, selection, drop-preview and child-label placement modules must use the same Shape data.
Same-grid movement preserves the grabbed-cell offset. With Smart Two Way Move off, occupied positions do not exchange; enable it only when both complete footprints can fit at their new anchors. Between containers, configure both Item View Shape Drop condition and action alongside the shared cursor/drop components. Validate full-amount data transfers as well as geometry, including occupied, full and partially accepting destinations.
Use a potion and tall sword to test stack growth, edge rejection, non-anchor dragging and both exchange directions. Move the sword between Bag and Equipment and verify old cells clear. Preview and final placement must cover the same cells.
Restore layout deliberately
Save Inventory items and every required Item Shape Grid Data separately. Item Shape Grid Data Saver records cell ItemStack identities and anchor markers; referenced stacks must exist before restoring. Saved cell count must equal the current grid’s cell count. Back up and migrate spatial saves before resizing rather than assuming an old map will load into new dimensions.
Test saving, moving items and loading: amounts, identities and positions should all return. Keep each local player’s Inventory/controller/data/view ownership explicit. In multiplayer, authorize the transaction and synchronize both Inventory state and authoritative grid data before local drawing.
Developer reference
ItemShapeGridController.GetGridDataWithID resolves the view’s data. ItemShapeGridData exposes TryFindAvailablePosition, IsPositionAvailable, AddItemToPosition, CanMoveIndex, TryMoveIndex, TryGetAnchorOffset, GetAnchorIndex, GetElementAt and GetItemPos.
Use Inventory add/remove events and the normal container selection/click/drop events for custom behavior. The controller has no separate public placement-changed event; ItemShapeItemView.OnGridInfoSet exposes resolved View state to compatible modules. See Move Items, Inventory and Save System for the surrounding transaction and persistence APIs.