Inventory System

An inventory system is a row of slots, and each slot is empty or holds a stack of one item. Moving, splitting and merging only shift items between slots, so nothing may appear or vanish. Watch the case where a slot acts on itself, the usual cause of duplicated items, and say what does not fit.

Also called: Slot inventory, Item stacks, Backpack, Item container.

A traveller kneels at night beside an open pack and a lantern, placing a wrapped bundle into a glowing grid of slots that holds a jar, rope, a trowel, a leaf and a long staff across two squares. — Lanternpack Trail, an invented forest survival 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 "Inventory System" to my game.

What it should do: A place for what the player carries, with limits that force choices and rules that never lose or copy an item.

Use these starting values:
- slots: 12
- maxStack: 20 items

Watch out for these common mistakes:
- A stack dropped onto itself: Tell your AI: if both slots are the same one, do nothing at all, before anything else happens.
- Splitting off the whole stack: Tell your AI: only allow a split smaller than the stack, or clear the slot.
- Items vanish when the inventory is full: Tell your AI: hand back what did not fit, so the game can leave it on the ground or refuse the pickup.
- Two requests at once: Tell your AI: handle actions one at a time in one central place. This page does not cover online play.

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

A place for what the player carries, with limits that force choices and rules that never lose or copy an item.

Good starting values

Value	Start with	What it changes
slots	12	How many slots the inventory has. Fewer slots make the player choose harder.
maxStack	20 items	How many of one item fit in one slot. Smaller stacks fill the inventory sooner.

What usually goes wrong

A stack dropped onto itself

The player drags a stack onto its own slot and the game forgets what it just did. Merging a stack with itself then creates items from nothing. This is a common way for duplicated items to appear.

Fix: Tell your AI: if both slots are the same one, do nothing at all, before anything else happens.

Splitting off the whole stack

Splitting off the full amount leaves a stack of zero, which looks like an item but holds nothing.

Fix: Tell your AI: only allow a split smaller than the stack, or clear the slot.

Items vanish when the inventory is full

Items beyond the last free slot disappear without a word.

Fix: Tell your AI: hand back what did not fit, so the game can leave it on the ground or refuse the pickup.

Two requests at once

In an online game, two requests can move the same stack, and one of them works from an old view of the slots.

Fix: Tell your AI: handle actions one at a time in one central place. This page does not cover online play.

How to check it works

You have a stack and an empty slot. you move the stack there: the stack has moved and its old slot is empty.
You have two stacks of different items. you move one onto the other: they swap places.
You have a stack. you move, merge or split it onto its own slot: nothing changes.
You have a stack. you ask your AI to move it to a slot number that does not exist: nothing changes.
You have a stack of 5. you split off 2: the slots hold 3 and 2, and trying to split off 5 or 0 does nothing.
You have a stack and a slot with something in it. you try to split onto that slot: nothing changes.
You have stacks of 15 and 10 of one item, and a stack limit of 20. you merge the first onto the second: they hold 5 and 20.
You have stacks of 4 and 10 of one item. you merge the first onto the second: the first slot is empty and the second holds 14.
You have stacks of two different items. you merge one onto the other: nothing changes.
You have two slots with a stack limit of 10, and one holds 8. you pick up 20: both hold 10, and the game reports 8 that did not fit.
You have two stacks of 3. you ask to take out 7, then 4: the first try takes nothing and reports 7, the second takes 4.

Works well with

Crafting System: Half-done steps are where items get lost. Check the whole recipe first, then take and give in one go.
Loot Table: A full inventory must never make a drop vanish without a word. Roll first, then add the drop to the inventory. If it does not fit, the game must say so.

Common questions

what do i tell my ai to add an inventory

Paste this: Add an inventory with a list of slots, where each slot is empty or holds an item and a count. Make every change one single action on that list, and do nothing unless the two slots of an action are different and exist.

how do item duplication bugs happen

Often a slot gets paired with itself: the game reads both slots, writes both, and the second write wipes out the first. Any action on two slots should do nothing when they are the same.

should an inventory use slots or weight

Slots are simple to show and force a choice per item. Weight suits games about carrying things. Slots with a stack limit are the usual place to start.

what happens when the inventory is full

Nothing may vanish. The game should say what did not fit, then leave it on the ground or refuse the pickup.

Where it comes from

Earliest example we could find: Dungeons & Dragons, Volume 1: Men & Magic (Gygax and Arneson, Tactical Studies Rules) (1974). Tabletop rules that list the weight of carried items and tie the total load to a character's movement rate. It is a paper bookkeeping system: the player tracks what the character carries, and a heavier load slows the character down. The rulebook was read in an unofficial copy, which is not linked here.

1974 Dungeons & Dragons, Volume 1: Men & Magic (Gygax and Arneson, Tactical Studies Rules): Tabletop rules that list the weight of carried items and tie the total load to a character's movement rate. It is a paper bookkeeping system: the player tracks what the character carries, and a heavier load slows the character down. The rulebook was read in an unofficial copy, which is not linked here. [Dungeons & Dragons (1974), Wikipedia, bibliographic reference]
1977 Adventure (Colossal Cave), Don Woods's expansion of Will Crowther's game: Jerz's study of the code shows that Crowther's version had take and drop style verbs but no command to list possessions. Woods added an INVENTORY verb that prints what the player is carrying. The 1977 date comes from Jerz, and Woods agrees with it after earlier estimating 1976. [Somewhere Nearby is Colossal Cave: Examining Will Crowther's Original 'Adventure' in Code and in Kentucky (Dennis G. Jerz, Digital Humanities Quarterly, 2007)]
1987 Dungeon Master (FTL Games): Each character has a screen showing a figure with body slots, hands, packs and pockets, and the player drags objects onto it with the mouse. Jimmy Maher describes this as the paper-doll layout later common in computer RPGs. Carried weight also feeds into stamina. [Dungeon Master, Part 2: The Playing of (Jimmy Maher, The Digital Antiquarian, 2015)][Dungeon Master, Part 1: The Making of (Jimmy Maher, The Digital Antiquarian, 2015)]
1989 Sweet Home (Capcom, Famicom): Horror RPG in which a limited inventory is part of the survival pressure, and items can be dropped and later retrieved by other party members. Sourced from Wikipedia only, which cites GameSpot, Famitsu and others; those were not opened. [Sweet Home (video game), Wikipedia]
1996 Resident Evil (Capcom) and Diablo (Blizzard North): Two games from the same year that the Journal of Geek Studies names as the probable popularizers of the visual grid inventory, where space itself is the limit. Resident Evil adds safe-room item boxes for spare items and took its limited inventory from Sweet Home. The Diablo pitch of 1994 lists inventory screens among its art needs but does not describe a grid. [The Two-Dimensional Knapsack Problem, or how to optimize your inventory to fight zombies (João Vitor Tomotani, Journal of Geek Studies, 2022)][Resident Evil (1996 video game), Wikipedia][Diablo game concept (Condor, Inc., 1994), hosted by David Brevik]
2005 Resident Evil 4 (Capcom): Weapons, ammunition and healing items share a grid drawn as an attaché case, and the case can be upgraded for more room. Sourced from Wikipedia only; no developer statement was found. [Resident Evil 4, Wikipedia]

Strength of the sources: the 1974 rulebook, Jerz's peer-reviewed code study and Maher's game history are strong. Sweet Home and Resident Evil 4 rest on Wikipedia only, and the 1996 grid claim rests on one Journal of Geek Studies article, a lighter piece with references. The 1974 event is a tabletop load rule, not a computer screen. The earliest computer example documented here is Adventure in 1977; PLATO games and other pre-1977 computer RPGs were not documented, so an earlier computer example may exist. Source claims: Maher calls Dungeon Master 'the debut' of the paper-doll approach to inventory in CRPGs. That is his claim, and no other source was checked against it. The Journal of Geek Studies hedges its point with 'probably' and says popularized, not invented. Could not document where the grid inventory began. Giant Bomb's user-edited concept page lists Captive, X-COM: UFO Defense, System Shock 2, Diablo and many others but gives no dates and no history, and no stronger source was found, so a grid inventory earlier than Diablo stays undocumented here. Could not document: inventory or equipment layouts in Wizardry and Ultima from 1981. The Digital Antiquarian post on Wizardry that was opened does not cover them. The Journal of Geek Studies dates Colossal Cave to Crowther in 1976, while Jerz places Crowther's work in the 1975-76 academic year and Woods's in 1977; Jerz is preferred. The rulebook was read in an unofficial copy with some lines missing; that copy is not linked here. Carrying capacities and grid sizes are left out on purpose.

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