Chest Menu

Export

The Chest Menu lets a player take Items and optional Currency from an interactable chest. One menu can serve many chests because the chest that opens it supplies the active chest Inventory, while the interacting character supplies the destination Inventory.

This page explains the released runtime components. Use UI Designer: Chest to generate and edit the menu hierarchy. Chest Menu is retrieval-only; use Storage Menu when the player must also deposit Items.

Before you begin

Prepare:

  • a player Inventory with Bag as the intended destination and Equipment as a separate collection;
  • an Inventory Interactor that can supply that player Inventory;
  • a chest Inventory whose main Item Collection contains three Health Potions and one Iron Sword;
  • a working Interactable, trigger Collider, and input route; and
  • a Canvas, EventSystem, and Display Panel Manager.

The Demo folder’s Chest prefab is a useful working reference because it already demonstrates the Chest, Chest Interactable, Inventory, Animator, and interaction relationship. When building one manually, make every reference below explicit.

Create the Chest Menu

  1. Open Tools > Opsive > Ultimate Inventory System > UI Designer.
  2. Select the Chest tab and open Create.
  3. Assign Parent Transform below the intended Display Panel Manager.
  4. Select Create. The released creator has no Panel Option; it creates a standalone menu panel that disables itself when closed.
  5. In Edit, select the generated Chest Menu. Use Find Available Targets in Scene if necessary.
  6. Under Inventory Grid, create Chest Inventory Grid if the schema did not supply it.
  7. Select Edit Chest Inventory Grid to configure its Item Views, filter, layout, and navigation.
  8. Under Quantity Picker Panel, create the quantity control.

UI Designer creates the menu, not the world chest. The active Chest and player Inventory are supplied at runtime before the Display Panel opens.

Connect the Chest Menu fields

The generated schema normally assigns the UI references. The released Version 1 script defaults are:

Chest Menu field Default Purpose
Bind To Panel Owner Inventory On Initial inherited player binding when no Inventory is assigned; a normal Chest interaction later replaces it with the interacting Inventory
Bind To Inventory By Identifier 0 Optional player Inventory Identifier when panel-owner binding is off; 0 means unused
Inventory None Direct player destination; a normal Chest.Open binds its client Inventory explicitly
Inventory Grid None Required grid that displays the active chest Inventory
Multi Currency View None Optional display of Currency held by the chest
Take Currency Button None Moves all chest Currency to the player
Take All Items Button None Moves all Items, then closes the menu
Take All Button None Takes Currency, then Items, then closes the menu
Cancel Button None Closes without another transfer
Quantity Picker Panel None Required amount selector for an Item click
Do Not Close Chest If Empty Off When enabled, closing the panel skips Chest.Close if the chest main collection is empty
Add To Item Collection Name Empty Named player destination, with fallback to the player’s main Item Collection

Set Add To Item Collection Name to Bag. This keeps a retrieved Iron Sword in Bag instead of equipping it. When Bag is misspelled or absent, the menu silently falls back to the player’s main Item Collection.

The menu’s player-binding fields are useful for manual opening, but the normal chest flow is more specific: Chest.Open(clientInventory) calls BindInventory, assigns itself through SetChest, and only then smart-opens the panel.

Configure the chest grid and quantity picker

Configure Chest Inventory Grid to show only the active chest Inventory’s main Item Collection. Individual Take and Take All both remove from that main collection, even if a customized grid displays another collection.

In the grid’s filters:

  1. Add the chest’s main collection to Show Item Collections.
  2. Exclude any secondary collections that should not be retrievable.
  3. Confirm that Item Info Category Filters reference the active Inventory System Database.
  4. Map Consumable and Weapon to valid Item Views so Health Potion and Iron Sword draw correctly.
  5. Add navigation when the chest can contain more stacks than visible slots.

Clicking an Item opens Quantity Picker Panel with a minimum of 0, a maximum equal to the clicked stack, and the full stack selected initially. Confirmation text is Take. Selecting a value below 1, cancelling, or closing the panel moves nothing.

The menu handles the grid’s click event directly. It does not open Item Actions or support depositing by drag and drop. Use a custom grid workflow when Take must be an Item Action, Items can be dragged between floating panels, or the destination varies by category.

Connect the world chest

  1. Add an Inventory to the chest GameObject and configure its main Item Collection.
  2. Add Chest and assign Panel Manager, Chest Menu, Inventory, and Animator.
  3. Give the Animator controller Open and Close triggers.
  4. Add Interactable and a trigger Collider. Ensure Interactor Layer Mask includes the player.
  5. Add Chest Interactable beside Interactable and assign its Chest, or assign Chest Game Object when using another IChest implementation.
  6. On the player, assign its Inventory to Inventory Interactor and configure interaction input or deliberate auto-interaction.

When Chest Menu initializes, it finds concrete Chest components in the scene and assigns itself only to those whose Chest Menu is currently None. Explicit assignments are safer when a scene contains more than one menu.

Chest Interactable accepts an interactor that implements IInteractorWithInventory. It passes that Inventory into the Chest, disables further interaction while the chest is open, and re-enables interaction when the Chest publishes its close event.

Choose the available retrieval controls

Control Released behavior
Click an Item Opens the quantity picker with the whole stack selected; confirmation moves that amount to Bag or the fallback main collection
Take Currency Moves all Currency from the chest Currency Owner to the player’s Currency Owner and redraws the optional Currency view
Take All Items Attempts to move every Item from the chest main collection, then closes the Display Panel
Take All Takes Currency first, then attempts all Items, then closes the Display Panel
Cancel Closes without taking another Item

There is no Store control. To verify a true store-and-retrieve round trip, use Storage Menu to place Health Potion and Iron Sword into the same chest Inventory, then use Chest Menu to take them back. Pre-populating the chest in the editor tests retrieval only.

Leave Do Not Close Chest If Empty off for the normal lifecycle. With it on, closing an empty chest’s menu does not call Chest.Close; the close animation and IChest.OnClose event do not run, so Chest Interactable can remain disabled. Enable it only as part of a custom open-chest lifecycle that handles those consequences.

Understand destination rejection

Individual Take and Take All remove from the chest first and call the destination collection’s add operation. In released Version 1, Chest Menu passes no rejected-Item callback. If Bag accepts only part of an amount because of capacity, category, or stack restrictions, the rejected remainder is not automatically returned to the chest.

Before shipping the supplied menu:

  • ensure Bag can accept every Item and quantity exposed by the chest; or
  • customize Chest Menu to preflight CanAddItem and return rejected amounts to the source.

This differs from the supplied Storage Menu, which installs a callback that attempts to return rejected amounts. Neither menu is a network transaction or durable rollback system.

How opening and retrieval runs

  1. Chest Interactable passes the interacting player’s Inventory to Chest.Open.
  2. Chest triggers its Open animation, binds the player Inventory, calls SetChest(this), opens the Display Panel, and invokes IChest.OnOpen.
  3. Chest Menu closes any old quantity panel, binds Chest Inventory Grid to the active Chest Inventory, draws it, and selects the first button.
  4. The optional Multi Currency View draws the chest Currency balance.
  5. An Item click waits asynchronously for a quantity decision, then gives that amount from the chest main collection to Bag or the fallback player main collection.
  6. Closing the menu closes the quantity panel and normally calls Chest.Close, which triggers the close animation and IChest.OnClose.

Do not open the Display Panel directly before calling SetChest; OnOpen immediately reads the active IChest and its Inventory.

Editor checkpoint

Before entering Play Mode, confirm that:

  • Chest Menu is registered below the intended Display Panel Manager;
  • Inventory Grid and Quantity Picker Panel are assigned;
  • Add To Item Collection Name is exactly Bag, and the player owns that collection;
  • the chest grid shows only the chest main collection and resolves Consumable and Weapon Item Views;
  • every filter uses categories from the active database;
  • Chest references the intended Panel Manager, Chest Menu, chest Inventory, and Animator;
  • Chest Interactable resolves the same Chest and sits beside an enabled Interactable;
  • the trigger Collider and Interactor Layer Mask admit the player;
  • Inventory Interactor supplies the intended player Inventory;
  • both Inventories have Currency Owners when Take Currency is present; and
  • Do Not Close Chest If Empty is off unless a custom lifecycle replaces the close event.

Verify in Play Mode

  1. Start with three Health Potions and one Iron Sword in the chest main collection. Record Bag and Equipment.
  2. Interact with the chest. Confirm that the Open animation runs, the menu shows the current chest contents, and the chest becomes temporarily non-interactable.
  3. Click Health Potion. Confirm that the picker initially selects all three, change the amount to 1, and Take. Verify that the chest has two and Bag gains one.
  4. Take Iron Sword and confirm that it enters Bag while Equipment remains unchanged.
  5. Open the picker for Health Potion and cancel. Repeat and close the menu. Confirm that neither action moves an Item.
  6. Close normally and confirm that the Close animation runs and the chest becomes interactable again.
  7. Open a second Chest that shares the same menu and confirm that its Inventory replaces the first chest’s contents.
  8. If Currency is configured, give the chest 25 Gold, select Take Currency, and verify that all 25 moves to the player’s Currency Owner while the chest view redraws at zero.
  9. Use Take All Items with a destination known to accept every remaining Item. Confirm that the Items enter Bag and the panel closes.
  10. For a bidirectional round trip, use Storage Menu to store Health Potion and Iron Sword in this Inventory, then reopen Chest Menu and retrieve them. Confirm that Chest Menu itself never exposes a deposit action.

Test rejection only in a disposable save or duplicated scene: released Chest Menu does not return a rejected remainder.

Troubleshooting

Symptom Check Fix
Interaction does nothing Trigger, layer mask, Inventory Interactor, Chest Interactable, and IInteractorWithInventory Restore the interaction chain and ensure the interactor supplies an Inventory
Chest Menu is null is logged Chest Menu on Chest Assign the intended menu explicitly; automatic discovery only fills a currently unassigned concrete Chest
The open animation runs but no menu appears Chest triggers Animator before checking its menu reference Assign Chest Menu and Panel Manager, then retry
The panel opens with a null-reference error Active IChest, its Inventory, Inventory Grid, or Quantity Picker Panel is missing Open through Chest.Open or call SetChest and bind the player before opening
The wrong chest contents appear Active Chest assignment and its Inventory Assign each world Chest explicitly when multiple menus exist and verify its main collection
The grid is empty Main-collection filter and Category Item View Set Show the chest main collection and map Consumable and Weapon from the active database
Clicking an Item does nothing Inventory Grid, Quantity Picker Panel, and clicked Item amount Restore the generated references; the supplied menu uses direct clicks rather than Item Actions
Iron Sword enters Equipment Add To Item Collection Name or player main collection Set the name to Bag and ensure Bag exists
Only part of a stack reaches Bag and the remainder disappears Destination capacity or restrictions Do not use the supplied transfer with rejecting destinations; add a preflight and rejection callback
Take Currency does nothing Currency Owners and button reference Add Currency Owners to both Inventories and assign Take Currency Button
An empty chest stays open and cannot be interacted with Do Not Close Chest If Empty skipped Chest.Close and its close event Disable the option or implement a custom lifecycle that closes and re-enables interaction
Take All closes after an incomplete result Destination rejected an Item, but Take All closes unconditionally Preflight the complete transfer or replace Take All with a transactional custom operation

Developer, save, and network boundaries

Any IChest can be assigned before opening:

chestMenu.BindInventory(playerInventory);
chestMenu.SetChest(myChest);
chestMenu.DisplayPanel.SmartOpen();

IChest exposes its Inventory and open state, plus Open(Inventory), Close(), OnOpen, and OnClose. The concrete Chest implementation uses Open and Close Animator triggers. Chest Menu itself publishes no completed-transfer event; observe Inventory and Currency changes or add a project-specific event around the operation.

To persist retrieval, add Inventory Saver components for both the player and chest Inventories and keep the Inventory System Manager Item Saver available. Add Currency Owner Saver to both owners when chest Currency should persist. Chest Menu does not save its selected Item, pending quantity, panel state, Animator state, or active Chest assignment.

The supplied operations are local, remove-before-add, and not atomic. They do not provide chest locks, access permissions, rollback, network authority, or simultaneous-client conflict handling. In multiplayer, let the server or host reserve the chest, validate capacity, perform the transfer, and replicate the accepted result.