How to move and swap items

Grid resize — grow adds empty cells

When you resize a grid container to larger dimensions, the grid expands and fills the new space with empty cells. For example, if you have a container “stash” configured as a 4×4 grid and set its dimensions to 6×6, the grid grows to 6×6, preserving existing contents while making the additional cells available for use.

Grid resize — shrink displaces items in removed cells

When you shrink a grid-based container, any items occupying cells that no longer exist are displaced rather than silently destroyed. For example, if your “stash” is a 6×6 grid and you’ve placed an iron ingot at position (5, 5), resizing the grid down to 4×4 will remove that item from the container and report it as displaced. The result includes the full details of each displaced item — in this case, one iron ingot with a quantity of 1 — so you can decide what to do with them, whether that’s returning them to the player, dropping them in the world, or moving them to another container.

Move by index in a non-grid container

When you move an item to a different index within a non-grid container, the other items shift to fill the gap. For example, if your “backpack” has an “iron_ingot” at index 0 and a “health_potion” at index 1, moving the item at index 0 to index 1 causes the “health_potion” to become the first item in the container.

Move item to occupied cell fails

When you try to move an item to a cell that’s already occupied by another item, the operation fails. For example, if you place an “iron_ingot” at position (0, 0) and a “health_potion” at (2, 2) in a 5×5 grid container, attempting to move the iron ingot to (2, 2) will return a position occupied error. To relocate an item, the target cell must be free — or you can use a swap operation instead.

Move item within a grid container

You can move an item from one position to another within the same grid container. For example, if you place an “iron_ingot” at position (0, 0) in a 5×5 grid container called “grid_chest”, you can then move it to position (3, 3). The operation succeeds and the container still contains exactly one item — the item is relocated, not duplicated.

Swap by index in a non-grid container

You can swap two items in a container by their index positions. If you add an “iron_ingot” and then a “health_potion” to a “backpack” with unlimited capacity, swapping the items at index 0 and index 1 will reverse their order, placing the “health_potion” first. This works in any non-grid container.

Swap two items in a grid

When two items occupy different positions in a grid container, you can swap them directly. If you place an iron ingot at position (0, 0) and a health potion at (2, 2) in a 5×5 grid, swapping those two positions moves the health potion to (0, 0) and the iron ingot to (2, 2). Both items exchange places in a single operation.

Generated from core/tests/features/move_swap.feature