Player Inventory [wiki.qeng.org]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
{{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_en.png?800 |The inventory on a level: items arrive for solved bonuses}}

Clicking an item selects it and reveals two buttons: the eye shows the picture full size, the tick uses the item.

{{ :authors_main:inventory_item_en.png?800 |A selected item: the eye shows the picture full size, the tick uses the item}}

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).

==== Item Images After Copying a Game ====
By default item images are taken from the CDN folder of the **current** game. Copying a game does not copy its CDN files, so item images disappear in the copy.

To avoid that, bind the inventory to the game the images were uploaded to. One call per game is enough — put it into the **"Common HTML header"** field in the game settings (in **"Source"** mode):
<code HTML>
<script>
setInventoryGameId(1234);
</script>
</code>
where ''1234'' is the id of the game holding the images (the CDN folder number).

The common HTML header is copied together with the game, so the copy keeps taking images from the original game. If the images are uploaded to the new game, change the id in this call.

The same id can be set for a single level only, as the second parameter:
<code JavaScript>
showInventoryItems('inventory_container', 1234);
</code>

==== 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>

> **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.

==== 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.

The whole chain: the bonus is solved, the item arrives in the inventory, and "use" types its code for the player.

{{ :authors_main:inventory_use_en.gif |An item arrives for a bonus, and "use" types its code for the player}}

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