Read the Inventory documentation first. Jigsaw Inventory builds on the core container system, item structs, and inventory component behavior. This page covers only the Jigsaw-specific logic.

For shared setup guidance, see the Migration Guide and Integration Guide. Use the System Atlas to look up functions, variables, events, components, and ownership references. Use this page for Jigsaw-specific container behavior and setup.

Related setup: Set Up Inventory for the Player, Change Inventory Type on Interact Locations.

Related Videos

Version note: Some videos may have been recorded before V4. Concepts still apply, but asset names, component names, and folder locations may differ. Treat this written documentation as the source of truth.

• Play

Overview

The Jigsaw Inventory is a specialized inventory type where items can occupy multiple grid slots. Instead of every item using one slot, each item has a rectangular footprint such as 1×1, 2×2, 1×3, or 3×2.

The system is implemented through BP_Container_Jigsaw, which extends BP_Inventory_Container with multi-slot placement, rotation, linked slot data, custom move validation, and unique-item retrieval.

Use this style when inventory management should become a spatial puzzle, similar to Resident Evil, Escape from Tarkov, or Diablo-style layouts.

Performance note: Larger grids increase validation and slot-management cost. Keep grids to reasonable sizes, such as 8×10 or smaller, especially for multiplayer projects.

Item Footprints

Jigsaw item size is configured in DT_Items.

• Width: Horizontal slot count.
• Height: Vertical slot count.
• Jigsaw Icon: Inventory image used specifically for Jigsaw display.

The Jigsaw Icon lets the same item use a normal square icon in vendors, tooltips, or list inventories while using a correctly shaped icon in the Jigsaw grid. This prevents stretched icons for non-square items.

Items can rotate 90 degrees while being dragged. A 1×3 rifle can become 3×1, allowing it to fit into different open spaces.

Primary Slot and Linked Slots

Each multi-slot item uses the top-left occupied slot as its primary reference point. This gives the system a consistent origin for dragging, dropping, rotation, UI rendering, and item-data access.

The top-left slot contains the complete item data, rotation state, gameplay values such as durability and amount, and the list of every slot occupied by the item.

In this implementation, every occupied slot also stores the complete item data and the same linked-slot index array. For example, a 2×2 item occupying slots 5, 6, 13, and 14 stores the complete item data and [5, 6, 13, 14] in each of those slots.

This design makes each occupied slot self-contained, simplifies edge-case handling, and makes debugging easier. It also means functions that gather items must avoid returning the same multi-slot item multiple times.

Adding and Moving Multi-Slot Items

When a multi-slot item is added, the container calculates its occupied slots from the item size, rotation, and target position. It then writes the complete item data and linked-slot list into every occupied slot.

The Jigsaw container overrides the normal move behavior because moving one item may affect many slots.

Before moving an item, the system checks that all destination slots are inside the inventory bounds, empty or occupied by the same item being moved, and valid for the current rotation. During execution it stores the item data, clears all source slots, writes all destination slots, updates linked indices, and triggers inventory update events.

Get All Items Override

BP_Container_Jigsaw overrides GetAllItems so multi-slot items are returned once, not once per occupied slot.

The override iterates through slots, tracks which linked-slot groups have already been processed, and skips duplicate slots that belong to the same item. This keeps weight calculations, item counts, saving/loading, searches, and UI lists accurate.

Drag-and-Drop UI

The Jigsaw UI validates placement while the item is being dragged and gives immediate visual feedback.

• Green highlight: The current footprint is valid and the item can be dropped.
• Red highlight: The current footprint is invalid because slots are occupied, out of bounds, or otherwise unavailable.

During drag, the UI calculates the slot under the cursor, derives all slots the item would occupy, validates those slots, and updates the highlight color. If the player rotates the item during drag, the width and height swap, occupied slots are recalculated, and the highlight updates immediately.

Set Up Jigsaw Items

1. Open DT_Items.
2. Select the item you want to support in Jigsaw inventory.
3. Set Jigsaw Width and Jigsaw Height.
4. Assign a Jigsaw Icon with an aspect ratio that matches the footprint.
5. Keep the standard icon for vendors, tooltips, and non-Jigsaw UI.
6. Add the item to a Jigsaw inventory.
7. Verify that the item occupies the correct number of slots, displays without stretching, rotates correctly, blocks overlap, and preserves its item data.

Create Custom Item Sizes

1. Define the item dimensions in DT_Items. Width multiplied by height determines total occupied slots.
2. Create a Jigsaw icon with a matching visual orientation: portrait for 1×2, landscape for 2×1, square for 2×2, and wide for 3×1.
3. If using Gameplay Tags, assign appropriate tags such as Items.Equipment.Weapon.Rifle, Items.Consumable.Food, or Items.Resource.Metal. See https://docs.unrealengine.com/5.3/en-US/gameplay-tags-in-unreal-engine/ for Unreal’s Gameplay Tags documentation.
4. Test that all occupied slots contain complete item data and correct linked indices.
5. Test movement, rotation, save/load, and multiplayer behavior where applicable.
6. Check performance with several large items in the same grid.

Technical limits: The current system supports rectangular footprints. Non-rectangular L-shapes, T-shapes, or other custom silhouettes require extending BP_Container_Jigsaw, implementing custom occupied-slot calculations, updating UI rendering, and adding more complex placement validation. Rectangular shapes are recommended for most projects.