{{indexmenu_n>30}}
====== Player Inventory ======

The QEng engine supports a virtual inventory system for teams or single players. This allows authors to design quests that involve finding and using virtual items (keys, tools, currency).

===== What is Inventory? =====
In the player interface, the inventory is displayed as a list of items with images, short descriptions, and action buttons.

{{ :authors_main:inventory.png?800 |Example of inventory display on a level}}

Each item has a unique string identifier (key) that can be added, removed, or activated (used).

===== How to Display the Inventory on a Level =====

  - In the task text (in **"Source"** mode), insert an HTML container where the inventory list should be rendered:
<code HTML>
<div id="inventory_container">Loading inventory...</div>
</code>
  - In the task script field (at the bottom of the level settings), add the JS call:
<code JavaScript>
showInventoryItems('inventory_container');
</code>

===== Managing Items =====

==== Adding an Item to the Inventory ====
Adding items is linked to solving level bonuses (or spanning bonuses).
  - Create a bonus on the level (e.g., "Find a hammer").
  - In the **"Text after solution"** field of that bonus, in **"Source"** mode, write:
<code HTML>
<script>
addInventoryItem('hammer123');
</script>
</code>
Once the team solves this bonus, the item with key ''hammer123'' will appear in their inventory.

==== Item Images ====
For the item ''hammer123'' to render correctly, upload two image files to the CDN with strict filenames:
  * **''item_hammer123.jpg''** — the item thumbnail displayed in the inventory list.
  * **''item_hammer123_big.jpg''** — the detailed full-size image displayed when clicking the eye icon (detailed view).

==== Removing an Item from the Inventory (Usage or Loss) ====
To remove an item from a team (e.g. when giving it to a character or using it to unlock a door):
  - Create a bonus that is solved during the game.
  - In its **"Text after solution"** field, in **"Source"** mode, write:
<code HTML>
<script>
removeInventoryItem('hammer123');
</script>
</code>

<note important>
**Important:** If an item was added via a **spanning** (global) bonus, it cannot be removed by a regular level bonus. It must be removed via a spanning bonus with a higher sequence number.
</note>

==== The "Use" Button ====
When a player clicks the **"Use"** button next to an item in their inventory, the engine automatically attempts to submit a code matching the item's key.
* For example, using the item ''hammer123'' will automatically submit the code ''hammer123'' to the engine's answer field.

===== Demonstration =====
A live example of a level with inventory configuration can be viewed in the [[https://qeng.org/game.php?gid=3493&tid=68367|Demo game for authors]].