How to use grid inventories

Containers with Grid constraint use a 2D grid for item placement. Items must have “width” and “height” fields. The core validates placement and prevents overlaps.

Adjacent multi-cell items succeed

When your container uses a grid constraint, items can be placed side by side as long as they don’t overlap. If you have a “backpack” with a 10×6 grid and place a “shield” at position (0, 0), you can place a second “shield” at (2, 0) without conflict. Both items coexist in the grid, and the backpack correctly reports 2 items.

Can place at checks without placing

You can check whether an item would fit at a specific position in a grid container without actually placing it. Given a “backpack” with a 10×6 grid, querying position (0, 0) for a “sword” confirms it can be placed there, while querying position (10, 0) correctly reports that placement is impossible since that coordinate falls outside the grid boundary.

Find free spot for item

When you need to find available space for an item in a grid container, the system can automatically locate a free spot. If you have a 10×6 “backpack” grid with a “sword” already placed at position (0, 0), asking the system to find a free spot for another “sword” will return position (1, 0) — the next available location that avoids overlapping with the existing item.

Get item at position

You can look up which item occupies any cell in the grid. If you place a “sword” at position (3, 2) in a 10×6 “backpack” grid, querying the cell at (3, 3) returns that “sword” — because the item spans multiple cells based on its dimensions, any cell it covers will resolve back to it.

Item missing grid fields

If you try to place an item into a grid container but the item’s type definition lacks the required “width” and “height” fields, the operation will fail with a missing field error. For example, a type “no_size” that only defines a “name” field cannot be placed at any position in a 10×6 grid container — the core requires every item placed in a grid to declare its dimensions.

Multi-cell item checks all cells

When you place a multi-cell item like a “shield” at position (0, 0) in a grid container, it occupies all the cells its width and height cover. If you then try to place a “potion” at position (1, 1) in the same “backpack” (a 10×6 grid), the operation fails with a position occupied error because the shield already occupies that cell. The core checks every cell a new item would cover, not just its origin point, ensuring no overlaps occur.

Multi-cell item partially out of bounds fails

When you have a grid-based container like a “backpack” with a 10×6 grid, the system prevents items from being placed partially outside the grid boundaries. If you try to place a “shield” at position (9, 0) and the item’s width would extend beyond column 10, the operation fails with an out of bounds error. This ensures every cell an item occupies must fall within the grid dimensions.

Multiple item types in same grid

A grid container can hold different item types simultaneously. If you define a “backpack” with a 10×6 grid, you can place a “sword” at position (0, 0), a “shield” at (2, 0), and a “potion” at (5, 0) — as long as each item fits within the grid bounds and doesn’t overlap another, the placement succeeds and the backpack will contain all 3 items.

Out of bounds placement fails

If you attempt to place an item at a position that falls outside the grid boundaries, the operation will fail. For example, given a container “backpack” with a 10×6 grid, trying to place a “sword” at position (10, 0) results in an out-of-bounds error, since valid column indices run from 0 to 9.

Overlapping placement fails

When you place a “sword” at position (0, 0) in a “backpack” container using a grid(10, 6) constraint, attempting to place a “shield” at the same (0, 0) position will fail with a position occupied error. The core prevents items from overlapping on the grid — each cell can only be claimed by one item at a time.

Partial overlap of multi-cell items fails

When two multi-cell items partially overlap on a grid, placement is rejected. If you place a shield at position (0, 0) in a 10×6 backpack grid, then attempt to place another shield at (1, 0), the operation fails with a position occupied error. The grid enforces that every cell an item would occupy must be free — even a single cell of overlap is enough to block placement.

Place item in grid

When you set up a container with a grid constraint, you can place items at specific coordinates within that grid. For example, given a “backpack” container with a 10×6 grid, placing a “sword” at position (0, 0) succeeds, and the backpack then contains one item. This confirms that the grid accepts valid placements within its bounds.

Query grid state after placing items

You can query the grid state of a container to inspect its current layout. After creating a “chest” with a 10×6 grid and placing a “sword” at position (0, 0) and a “potion” at (5, 5), querying the grid state returns the full dimensions (10×6), the number of occupied cells (5), and the number of free cells (55). This gives you a snapshot of how much space remains and how densely packed the container is, which is useful for UI display or placement logic.

Remove item frees grid space

When you remove an item from a grid container, the space it occupied becomes available again. If you place a “sword” at position (0, 0) in a 10×6 “backpack” grid and then remove it, the operation succeeds and you can immediately place a different item, such as a “shield,” at that same (0, 0) position.

Stack potions at same grid position

When items occupy a specific grid cell, you can stack additional items of the same type into that position. If you place 3 “potion” items at position (5, 5) in a 10×6 grid backpack and then add 2 more “potion” to the same cell, the stack grows to a total quantity of 5.

Generated from core/tests/features/grid_capacity.feature