Storage Chest

A storage chest is a second place for items, next to the bag. It can be locked, closed or open, and items cross between bag and chest only while it is open. Each move takes from one side and gives to the other, so nothing is copied or lost, and the chest keeps its contents when the player walks away.

Also called: Stash, Item box, Treasure chest, Bank.

A small bat courier in a red jacket tips a handful of gems from its satchel into a big open wooden chest that is almost full, in a lantern-lit cellar made of layered paper. — Moth & Mortar, an invented cellar-keeping adventure. 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 "Storage Chest" to my game.

What it should do: A chest gives the player a safe place for things they cannot carry, so the bag can stay small and still feel fair, and so a trip back to the same spot has a reason.

Build it exactly as this state machine. First check that it fits my game, then build it like this:

```mermaid
stateDiagram-v2
  [*] --> locked
  locked: Locked
  closed: Closed
  open: Open
  full: Open and full
  locked --> closed: unlock with key
  closed --> locked: lock with key
  closed --> open: open it
  closed --> full: open a full chest
  open --> closed: close it
  open --> full: last space filled
  full --> open: something taken out
  full --> closed: close it
```

Use these starting values:
- chestLimit: 30 items
- bagLimit: 20 items

Watch out for these common mistakes:
- An item is in both places or in neither: Tell your AI: make every move one single step that changes both sides together, so no half-done move can ever be seen or saved.
- The chest empties when the player leaves: Tell your AI: keep what is inside the chest as part of the game itself, not part of the screen, and save it with everything else.
- Taking everything fails because one item does not fit: Tell your AI: move what fits, report how many were left behind, and refuse only when not even one fits.
- A closed chest still takes and gives: Tell your AI: check that the chest is open at the start of every move, not only when the screen was drawn.
- An empty entry is left behind: Tell your AI: when the last one leaves, remove the entry completely.
- The chest has no limit: Tell your AI: give the chest a limit as well, and tell the player when it is full.

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 chest gives the player a safe place for things they cannot carry, so the bag can stay small and still feel fair, and so a trip back to the same spot has a reason.

How it runs, as a diagram

Everything it can be in, and what moves it on. Your AI builds from exactly this.

How it runs, as a diagram

Locked → Closed: unlock with key
Closed → Locked: lock with key
Closed → Open: open it
Closed → Open and full: open a full chest
Open → Closed: close it
Open → Open and full: last space filled
Open and full → Open: something taken out
Open and full → Closed: close it

Good starting values

Value	Start with	What it changes
chestLimit	30 items	How many items the chest holds in all. It starts larger than the bag, so the chest feels like extra room and the player has a reason to come back.
bagLimit	20 items	How many items the bag holds in all. A small bag is what gives the chest its point.

What usually goes wrong

An item is in both places or in neither

The game adds the item to the chest first and removes it from the bag second. If something goes wrong in between, such as closing the screen, the item is now in both places. Do it the other way round and the item is in neither.

Fix: Tell your AI: make every move one single step that changes both sides together, so no half-done move can ever be seen or saved.

The chest empties when the player leaves

The chest's contents live in the screen that shows it. When the player walks away or the screen closes, the contents are thrown away with it.

Fix: Tell your AI: keep what is inside the chest as part of the game itself, not part of the screen, and save it with everything else.

Taking everything fails because one item does not fit

The player wants to move a big stack and only part of it fits. The game refuses the whole move and says nothing, so the player thinks the chest is broken.

Fix: Tell your AI: move what fits, report how many were left behind, and refuse only when not even one fits.

A closed chest still takes and gives

A quick double click or a button that was still on screen moves an item into a chest that has just closed. Or into a locked chest the player never opened.

Fix: Tell your AI: check that the chest is open at the start of every move, not only when the screen was drawn.

An empty entry is left behind

Moving out the last of an item leaves an entry of zero. The list shows a ghost item and the next check for "does the chest hold this?" gives the wrong answer.

Fix: Tell your AI: when the last one leaves, remove the entry completely.

The chest has no limit

An endless chest makes the bag limit pointless, because the player walks to the chest and back with no cost. The game also has to show an endless list.

Fix: Tell your AI: give the chest a limit as well, and tell the player when it is full.

How to check it works

A locked chest. you try to unlock it without the key, then with it: the first try is refused and the chest stays locked, and the second leaves it closed but not open.
A locked chest and a bag with 6 gems. you try to open it and put 2 gems in: nothing happens, the chest is empty and you still have 6 gems.
An open chest and a bag with 6 gems and 4 ropes. you put 2 gems in: the bag holds 4 gems and 4 ropes, the chest holds 2 gems, and the game reports 2 moved and none left behind.
An open chest with 5 gems and a bag with 1 rope. you take 3 gems out: the bag holds 1 rope and 3 gems, and the chest holds 2 gems.
A closed chest with 2 ropes in it, and 4 gems in your bag. you try to put a gem in or take a rope out: both are refused and nothing changes.
An open chest and a bag with 4 gems. you put 3 gems in, close it, lock it, unlock it and open it again: the 3 gems are still in the chest and 1 gem is in the bag.
A chest that holds 5 items, with 2 ropes already in it, and 8 gems in your bag. you try to put all 8 gems in: 3 gems go in, 5 stay in the bag, the game reports 5 left behind, the chest counts as full, and putting in one more is refused.
A bag that holds 4 items, with 3 ropes in it, and a chest with 6 gems. you try to take all 6 gems: 1 gem moves, 5 stay in the chest, and the game reports 5 left behind.
An open chest with 1 rope and a bag with 2 gems. you try to put 3 gems in or take 2 ropes out: both are refused and nothing changes.
An open chest with 1 rope and a bag with 2 gems. you try to move 0, minus 2, half an item or a number that is not a number: nothing happens.
An open chest and a bag holding two items called constructor. you put one in, and you try to put in an item called toString that you do not hold: the first goes in like any other, and the second is refused as not held.

Works well with

Needs: Inventory System.

Shop (Buy and Sell): A sale and a move to the chest are separate steps and must not overlap. Let the player move goods to the chest before selling, so the bag never has to be the only place to hold stock.
Key Items: A key locked inside its own chest can never be taken out again. Check the key through the key pocket, then unlock. Do not let a chest hold the key that opens it.
Loot Table: Rolling again on every opening lets the player reload for better loot. Roll the contents when the chest is first opened and save them, so opening it again shows the same things.

Common questions

what do i tell my ai to add a storage chest

Paste this: Add a chest with its own list of items and its own item limit. It can be locked, closed or open. Items move between the bag and the chest only while it is open, and each move changes both sides in one step. Keep the chest contents in the game data so they survive leaving the area.

how do item duplication bugs happen with chests

Usually the item is added to one side before it is removed from the other, and something happens in between, such as closing the screen or a second click. Make the move one step that changes both sides together.

should a chest have a size limit

Yes, in most games. A chest bigger than the bag is a good start. With no limit at all, the bag limit stops mattering and the player never has to choose.

what happens when the player tries to move more than fits

Move what fits, tell the player how many stayed behind, and refuse only when nothing fits at all. Refusing the whole move for a single missing space feels like a bug.

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.
The state diagram was checked against the code, at the default values and at every listed low and high value.

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