Item Shape Grid

Use an Item Shape Grid when placement is part of the inventory experience and Items can occupy several cells in a finite Bag. A Health Potion can use one cell while an Iron Sword spans a taller footprint. Use a regular Inventory Grid when every Item should occupy one equal slot.

The runtime grid is more than a visual layout. An ItemShape value defines each footprint, Item Shape Grid Data records occupied cells beside the Inventory, and the Item Shape Grid renders and moves those Items through a shape-aware two-layer view.

Before you begin

Prepare:

• an Inventory System Database with Health Potion and Iron Sword Item Definitions;
• a Shape Item Definition Attribute of type ItemShape on the category used by those Items;
• a player Inventory with a Bag Item Collection;
• UI Designer Canvas Managers and a duplicated schema; and
• enough panel space for the intended number and pixel size of cells.

The UI Designer Item Shape Grid workflow is the safest way to generate the connected UI, controller, data, and Inventory binding. This page explains how those generated runtime parts work and what to check when customizing them.

Define each Item shape

1. In the Item Category editor, add Shape as an ItemShape in the Item Definition attribute collection.
2. Open Health Potion and leave its footprint at one cell.
3. Open Iron Sword and use Columns and Rows to create its footprint.
4. Enable Use a custom shape? only when an Item should not occupy every cell in its rectangle.
5. For a custom footprint, enable each occupied cell. Right-click an enabled cell and choose Set Anchor to choose the cell that follows the selected destination.

The anchor must remain on an enabled cell. The editor keeps the anchor cell enabled, and the runtime aligns that anchor to the destination cell. An Item without the configured Shape value, or with a one-cell shape, is treated as one cell.

Released Version 1 stores one fixed footprint and anchor. It has no built-in rotation field or rotate command. If Iron Sword needs horizontal and vertical orientations, provide separate authored data and custom logic for choosing and placing the orientation.

Create the spatial Bag

1. Open Tools > Opsive > Ultimate Inventory System > UI Designer.
2. Select Item Shape Grid, then open Create.
3. Assign the intended Parent Transform and Inventory.
4. Keep the default Panel Option of Simple, or choose the panel type needed by the surrounding UI.
5. Give Panel Name and Grid Name stable names such as Spatial Bag.
6. Set Grid Size. The creator starts at 8 by 8 cells.
7. Set Item Shape Size, the pixel size of one cell. The creator starts at 100 by 100 pixels.
8. Under Item Collection, select Bag.
9. Create the grid.

UI Designer creates the panel and Item Shape Grid, adds an Item Shape Grid Controller and Item Shape Grid Data beside the assigned Inventory when needed, assigns the next available data ID, and adds an Item View Slots Container Panel Binding for that Inventory.

The Version 1 creator also displays an ALL (NONE) collection choice. The creator writes that text into the data’s Item Collections array, but runtime all-collection behavior requires the array to be empty. Select a real collection such as Bag for the normal workflow. To intentionally use every Inventory collection, clear Item Collections on the generated Item Shape Grid Data and confirm that the Console does not report an ALL (NONE) collection warning.

Understand the runtime parts

Part	Runtime responsibility
ItemShape attribute	Stores the footprint size, enabled cells, and anchor for an Item Definition.
Item Shape Grid Controller	Acts as an Inventory restriction, chooses the first matching data entry, and checks that an added Item can be placed.
Item Shape Grid Data	Owns the cell map for one spatial grid and its collection or filter rules. It belongs with the Inventory.
Item Shape Grid	Resolves data by ID from the bound Inventory and presents the background cells and foreground Item views.
Shape-aware Item View modules	Size the Icon, highlight the occupied cells, preview drops, and position labels within irregular footprints.
Shape drop condition and action	Validate and perform shape-aware movement between Item View Slots Containers.
Item Shape Grid Data Saver	Persists the cell map and anchor markers for one data entry.

The Inventory owns the Items and placement data. The panel displays that data; moving or copying the UI does not create another independent grid.

Match the data and view settings

The Item Shape Grid uses Item Shape Grid Data ID to find one data entry on the bound Inventory. The first generated entry uses ID 0. Every additional spatial grid on the same Inventory needs a unique ID and a clear collection or filter scope.

Item Shape Grid Controller

Setting	Default	Effect
No Grid Add Item	Off	Allows an add when no grid matches the Item and receiving collection. It does not bypass space checks on a matching grid; a full matching grid rejects the add with either setting.
Shape Attribute Name	Shape	Must exactly match the Item Definition Attribute and the shape-aware Item View.
Warn If Multiple Match	Off	Reports when more than one data entry accepts an Item. The controller still uses the first match.

Hide and Loadout collections skip footprint placement and the no-grid warning, but still undergo the Inventory restriction’s space check. A full first matching grid can reject an add to those collections even though it would create no footprint. Use a corrected restriction path or a separate Inventory when those additions must be independent of grid capacity. When several normal collections or filters overlap, order the controller’s data entries deliberately and enable the warning while testing.

Item Shape Grid Data

Setting	Default	Effect
ID	0 on the first generated entry	Connects this data to the UI’s Item Shape Grid Data ID.
Only Try Add To First Collection	Off	Selects the first connected collection with a nonzero permitted amount, even if it accepts only part of the request. The remainder is not tried in later collections. When on, only the first is attempted.
Item Collections	Generated from the UI Designer choice	Empty means all Inventory collections. Named entries such as Bag limit the data to those collections.
Item Info Filter	None	Optionally limits which Items can enter this spatial grid.
Grid Size	Copied from UI Designer	Must match the UI grid. A manually added data component has no useful nonzero size until configured.
Smart Two Way Move	Off	Allows a same-grid exchange only when both complete footprints fit at their new anchors.

Item Shape Grid view

Setting	Default	Effect
Item Shape Grid Data ID	0	Selects the Inventory-side data entry.
Grid Size	8 by 8	Creates one background Item View Slot for every cell and must match the data.
Item Shape Size	100 by 100	Sets the pixel size of one cell.
Item View Slot Prefab	Supplied by the generated schema	Creates the interactive background cells.
Item View Drawer	The component on the same GameObject when unassigned	Supplies and reuses Item views.
Item Shape View Content	Generated foreground content	Receives one coherent foreground view for each placed ItemStack.
Grid Layout Group	The drawer content’s layout when unassigned	Arranges the background cells.
Navigation Type	Per Item	Chooses whether selection moves per Item, per cell, or uses custom Unity navigation.

Use UI Designer when changing Grid Size or Item Shape Size so it can update the connected slots, layout, and data together. At runtime, a size mismatch between the view and Item Shape Grid Data produces an error and prevents reliable cell mapping.

Keep the two view layers aligned

The generated grid uses two matching layers:

1. The background layer contains one interactive Item View Slot per cell. Selection and drop feedback color every enabled cell in the Item’s footprint.
2. The foreground layer draws one coherent Item Icon across the complete footprint. Its Canvas Group does not block pointer input intended for the background slots.

Keep Item Shape View Content assigned to the foreground transform and the Item View Drawer’s Content assigned to the background transform. Both layers need the same cell size and origin.

The shape-aware Item View normally includes:

• Item Shape Item View, which reads Shape Attribute Name (Shape by default), sizes the view from a 100 by 100 Default Slot Size, and reads Shape Icon Attribute Name (Icon by default). Use Backup Icon is on by default.
• Item Shape Drop Preview Item View, which colors all prospective cells according to whether the drop conditions pass.
• Item Shape Selected Item View, which highlights the selected Item’s complete footprint.
• Item Shape Rect Placer Item View, which places a Rect Transform such as an amount label on the anchor or another occupied cell.
• Canvas Group, which allows the foreground layer to remain visible without intercepting input.

Do not replace this prefab with a normal one-cell Item View unless the replacement retains the required Item Shape modules and exact attribute names.

How placement and stacking work

Before the Inventory accepts an Item, the controller checks matching Item Shape Grid Data entries in order. It chooses the first matching data entry by Item Collections and Item Info Filter, then checks its footprint space. A full match rejects the Item; No Grid Add Item only permits the separate case where no data entry matches.

New placements scan from the top-left, row by row, and align the Item’s anchor to the candidate cell. The full Rows-by-Columns bounding rectangle, including disabled cells, must fit inside the grid. Only enabled cells require free space. When an Item transfers between collections in the same frame, the data can reuse its recently cleared position.

One ItemStack uses one footprint regardless of its amount. Another non-unique, stack-compatible Item can reuse that footprint only when the receiving collection accepts the complete amount into the existing stack. Otherwise it needs another open footprint.

Configure movement, input, and navigation

Use the shared drag-and-drop workflow for the cursor manager, drop handler, pointer drag handler, and keyboard or controller move cursor. A shape grid adds these rules:

• same-grid movement uses Item Shape Grid Data and preserves the offset between the grabbed cell and the Item’s anchor;
• Smart Two Way Move controls whether two Items can exchange positions inside the same grid;
• movement between containers needs the shape-aware Item View Shape Drop condition and action so the complete destination footprint and any reverse exchange are checked; and
• placement always uses the authored orientation because Version 1 has no runtime rotation command.

Choose Navigation Type according to the intended input:

• Per Item moves between Item anchors and empty cells, skips redundant occupied cells within the same Item footprint, and is the default;
• Per Slot navigates through individual cells; or
• Custom leaves the configured Unity Navigation links unchanged.

Test pointer, keyboard, and controller paths separately. The same valid or invalid cells should appear in the preview and final placement.

Save and synchronize the layout

Saving the Inventory and saving its spatial layout are separate operations. Add an Item Shape Grid Data Saver for every data entry whose positions must persist, in addition to the saver for the Inventory Items. The data saver stores each cell’s ItemStack identity and anchor marker. During load, those Items must already exist in the Inventory and the saved cell count must match the current grid size.

UI Designer does not add the data saver automatically. Resizing a saved grid also changes its cell count, so old placement data is not loaded into a differently sized layout.

Released Version 1 has no shape-grid-specific network replication. For multiplayer, keep one Inventory, controller, data set, and bound grid per local owner. A network implementation must synchronize both the authoritative Inventory transaction and Item Shape Grid Data; synchronizing only the UI or Inventory amount is not enough to reproduce positions.

Editor checkpoint

Before entering Play Mode, confirm that:

• Health Potion and Iron Sword resolve Shape through the exact configured attribute name;
• every custom footprint has its anchor on an enabled cell;
• the panel binding references the Inventory that owns the controller and data;
• Item Shape Grid Data ID matches one data ID on that Inventory;
• Item Collections contains Bag, not the literal ALL (NONE) placeholder;
• Grid Size matches between the view and data;
• foreground and background content use the same geometry;
• the Item View retains the shape, selection, drop-preview, label-placement, and Canvas Group modules; and
• the shape-aware condition and action are present when Items move between containers.

Verify in Play Mode

1. Open Bag. Confirm that Health Potion occupies one cell and Iron Sword covers its authored footprint.
2. Select each Item. Confirm that every occupied background cell highlights while the foreground remains one coherent Icon.
3. Add another Health Potion to a compatible stack. Confirm that its amount changes without creating a second footprint.
4. Drag Iron Sword from a non-anchor cell to an open area. Confirm that the preview and final placement cover the same cells without the Icon jumping.
5. Hover Iron Sword over the grid edge and an occupied area. Confirm that the invalid preview prevents the move.
6. Test an occupied destination with Smart Two Way Move off and then on. Confirm that an exchange occurs only when enabled and both complete footprints fit.
7. Move Iron Sword between Bag and Equipment. Confirm that its old Bag cells clear and no ghost footprint remains.
8. Save, move the Items, then load. Confirm that both Item amounts and cell positions return.

Troubleshooting

Symptom	Check	Fix
The grid is empty and the Console names ALL (NONE) as missing	Item Collections on Item Shape Grid Data	Select Bag in UI Designer, or clear the data array when all collections are intentional.
Every Item occupies one cell	The Shape Item Definition Attribute and Shape Attribute Name	Add an ItemShape value to each definition and use the same exact name on the controller and Item View.
The grid cannot find its data	Panel binding Inventory, Item Shape Grid Data ID, and data ID	Bind the owning Inventory and make the two IDs match.
The Console reports different grid sizes	Grid Size on the Item Shape Grid and Item Shape Grid Data	Resize through UI Designer so data, slots, and layout update together.
An Item is offset or clipped	Its anchor, Item Shape Size, foreground content, and drawer content	Put the anchor on the intended enabled cell and realign both view layers.
Selection or preview colors only one cell	Item Shape Selected Item View and Item Shape Drop Preview Item View	Restore the shape-aware modules and confirm they read the same Shape value.
A preview is valid but the final drop fails	The destination data and shape-aware drop action set	Use both the Item View Shape Drop condition and action for movement between containers.
Items never exchange inside the grid	Smart Two Way Move and both footprints	Enable the setting and confirm each full shape fits at the other’s anchor.
An Item exists in the Inventory but has no position	No Grid Add Item, filters, and controller warnings	Keep the setting off for a strict spatial Bag and remove overlapping or nonmatching scopes.
Positions reset after loading	Inventory saver, Item Shape Grid Data Saver, load order, and grid dimensions	Save every data entry, load Items first, and keep the saved and current cell counts equal.
Remote players disagree about positions	Network authority and synchronized shape data	Replicate the Inventory transaction and authoritative Item Shape Grid Data in custom networking code.

Related pages

• Create an Item Shape Grid in UI Designer
• Detailed Item Shape Inventory Grid reference
• Inventory Grid
• Item View Slots Container
• Move Items with drag-and-drop
• ItemInfo filters and sorters
• Common attribute types
• Inventory
• Save system

Developer details

ItemShapeGridController registers for Inventory add and remove events, selects the first matching ItemShapeGridData, and exposes GetGridDataWithID for view lookup. It does not publish a separate public placement-changed event. The normal Item View Slots Container selection, click, and drop events still drive UI interaction, while ItemShapeItemView.OnGridInfoSet is available when a custom module needs the resolved shape-grid view state.

ItemShapeGridData provides TryFindAvailablePosition, IsPositionAvailable, AddItemToPosition, CanMoveIndex, TryMoveIndex, TryGetAnchorOffset, GetAnchorIndex, GetElementAt, and GetItemPos. Use these APIs instead of editing cells independently so Inventory ownership, anchors, and complete footprints remain consistent.