Item Stacking

Item stacking decides how identical items share a slot. Each item has its own limit, so arrows may pile up to forty while a sword always takes a slot alone. A pickup tops up unfinished stacks first, then opens new ones. Whatever does not fit is reported back, never thrown away.

Also called: Stack limit, Stackable items, Item stacks, Merge and split stacks.

A clay otter shopkeeper pours red berries into a row of glass jars, two already full, the third almost full, while three spare berries wait in her paw and one has rolled onto the counter. — Fumblecrock Row, an invented claymation shop game. Invented game, image generated with AI.

Paste this to your AI

Copy it into Claude, Cursor or ChatGPT. It already has good values and the usual mistakes in it.

Add "Item Stacking" to my game.

What it should do: Stack limits turn a bag into a set of choices: small piles for rare things, big piles for common things, and a clear answer every time an item arrives and there is not enough room.

Use these starting values:
- slots: 8
- defaultLimit: 16 items

Watch out for these common mistakes:
- The pickup fits only in part: Tell your AI: take as many as fit, and tell the game exactly how many were left over, so it can keep them on the ground.
- Merging a stack past its limit: Tell your AI: move only as many as the target has room for, and leave the rest in the source slot.
- Items that never stack: Tell your AI: every stack carries its own limit, and a stack at its limit is never topped up.
- A limit that was changed later: Tell your AI: never remove items to enforce a new limit. Leave the old stack as it is and let it take no more.
- Half a stack of one: Tell your AI: a split needs at least two items, a whole number, and an empty target slot. Otherwise do nothing.
- A broken limit from the item data: Tell your AI: if an item's limit is not a whole number of at least one, use the default limit instead.

Do not change anything else in the game. Do not claim anything without proof: model what it takes, and show me what your solution rests on and how I can see that it works. If you cannot show something, say you do not know. When you are done, tell me in plain words how to try it.

Or skip this and connect the MCP: your AI then finds all of this by itself.Connect the MCP

What it does

Stack limits turn a bag into a set of choices: small piles for rare things, big piles for common things, and a clear answer every time an item arrives and there is not enough room.

Good starting values

Value	Start with	What it changes
slots	8	How many slots the bag has. Eight is small enough that a few unfinished stacks already hurt, which is when the player first feels the stack rules.
defaultLimit	16 items	The limit for an item that does not bring its own. Sixteen is easy to read at a glance and big enough that a stack feels like a pile. Set it to 1 and nothing stacks unless the item says so.

What usually goes wrong

The pickup fits only in part

Thirty arrows arrive and only twenty fit. If the game takes all thirty and cuts the stack back to its limit, ten arrows silently vanish. If it refuses all thirty, the player cannot even take what would fit.

Fix: Tell your AI: take as many as fit, and tell the game exactly how many were left over, so it can keep them on the ground.

Merging a stack past its limit

Ten and ten herbs with a limit of sixteen: a merge that adds the two counts makes a stack of twenty, which breaks the limit. A merge that deletes the source loses four herbs.

Fix: Tell your AI: move only as many as the target has room for, and leave the rest in the source slot.

Items that never stack

A sword has a limit of one. If the pickup code tops up any stack of the same name without looking at the limit, two swords end up in one slot.

Fix: Tell your AI: every stack carries its own limit, and a stack at its limit is never topped up.

A limit that was changed later

A patch lowers the limit of herbs from 30 to 16 while a player holds a stack of 30. A check that fixes the stack back down deletes fourteen herbs.

Fix: Tell your AI: never remove items to enforce a new limit. Leave the old stack as it is and let it take no more.

Half a stack of one

Splitting a stack of one in half either makes a stack of zero or a stack of half an item. Both break the count.

Fix: Tell your AI: a split needs at least two items, a whole number, and an empty target slot. Otherwise do nothing.

A broken limit from the item data

An item arrives with a limit of zero, a minus number, or a fraction. A stack of limit zero can never hold anything, and the item is stuck outside.

Fix: Tell your AI: if an item's limit is not a whole number of at least one, use the default limit instead.

How to check it works

A bag with a stack of 38 arrows and a stack of 10 arrows, both with a limit of 40, and an empty slot in between. you pick up 5 arrows: the first stack rises to 40, the second to 13, and the empty slot stays empty.
A bag with two empty slots and an ore limit of 10. you pick up 30 ore: two stacks of 10 are made and 10 ore is reported as not fitting.
An empty bag and swords with a limit of 1. you pick up 3 swords and then try to merge one stack into another: each sword has its own slot and the merge does nothing.
Two stacks of 10 herbs with a limit of 16. you merge the first onto the second: the second holds 16 and the first keeps 4.
A stack of herbs next to a stack of rope. you merge the herbs onto the rope: nothing changes.
A stack of 5 herbs. you split it onto an occupied slot, split all 5 of them, or split a stack of only one: nothing changes each time.
A stack of 7 herbs and an empty slot. you split it in half: the new stack holds 4 and the old one keeps 3.
A messy bag with herbs of 10, 10 and 5 spread over three slots, rope in between, and gaps. you tidy the bag: the herbs become 16 and 9, the rope stays at 3, all stacks sit at the front, and tidying a second time changes nothing.
A bag with 3 herbs. you pick up 2.5 herbs, zero herbs, minus 4 herbs, or split off 1.5: the bag stays exactly as it was.

Works well with

Inventory System: Keep one place that knows the limits, so the bag and the pickup code never disagree. Stacking is the rule inside each slot. The inventory decides which slot gets the item and where the leftover goes.
Weight Limit: A pickup may be cut short by weight, by slots, or by both. Report the smaller amount that fits. Check the weight for the whole pickup first, then stack what is allowed in.
Loot Table: Drops with a leftover must be kept in the world, not deleted. Roll the drop first, then offer it to the bag.

Variations: Grid Backpack.

Common questions

what is a good stack size for items in a game

Match it to how the item is used. Things you burn through, like arrows or herbs, can go to a few dozen. Rare or powerful things should stay low, even at one. Sixteen is a handy first guess.

what do i tell my ai to add item stacks

Paste this: Items stack up to a limit that each item brings along. A pickup fills unfinished stacks first, then opens new slots, and tells me how many did not fit. Merging moves only what the target has room for. Never delete items to enforce a limit.

what happens to items that do not fit in the bag

They stay outside. The pickup takes what fits and reports the rest, so the game can leave it on the ground or in the chest. Deleting the leftover is the usual way players lose items.

why does splitting a stack need an empty slot

The new stack has to go somewhere. Putting it onto another stack is a merge, and putting it on a different item would swap them. Asking for an empty slot keeps the action simple and predictable.

Where it comes from

We could not find a reliable origin for this one yet.

Where this mechanic comes from has not been researched yet.

Games are named only as references. Names and marks belong to their owners, and nothing here is endorsed by them.

What was checked

15 tests pass on the reference code.

This is what separates the blueprint from a catalogue entry: the values on this page come from code that runs.

Your AI gets the code

Tested example code comes through the Spielerando connection, so your AI can use it right away. How to connect it