[fix] Updated offline documentation and added new item macro

docs/inventory.js

@@ -236,13 +236,17 @@
  * @func steam_inventory_exchange_items
  * @desc This function grants one item in exchange for a set of other items.
  * 
+ * The API currently takes an array of items to generate but at this time the size of that array must be 1 and the quantity of the new item must be 1.
+ * 
+ * [[NOTE: Any items that can be granted MUST have an exchange attribute in their itemdef.]]
+ * 
  * [[WARNING: You must call ${function.steam_inventory_result_destroy} on the returned async result ID when you are done with it.]]
  * 
  * > [!TIP]
  * >
  * > A wrapper around [ExchangeItems](https://partner.steamgames.com/doc/api/ISteamInventory#ExchangeItems).
  * 
- * @param {array[struct.InventoryItemCreationData]} create_arr An array of [structs](https://manual.yoyogames.com/GameMaker_Language/GML_Overview/Structs.htm) representing items to be created
+ * @param {array[struct.InventoryItemCreationData]} create_arr An array of [structs](https://manual.yoyogames.com/GameMaker_Language/GML_Overview/Structs.htm) representing items to be created (must be of size 1 and the item quantity must also be 1)
  * @param {array[struct.InventoryItemConsumptionData]} destroy_arr An array of [structs](https://manual.yoyogames.com/GameMaker_Language/GML_Overview/Structs.htm) representing items to be consumed
  * 
  * @returns {real}
@@ -263,7 +267,6 @@
  * 
  * var _arrayCreate = [
  *     { item_def: global.holy_sword, quantity: 1 },
- *     { item_def: global.orange, quantity: 2 }
  * ];
  * 
  * steam_inventory_exchange_items(_arrayCreate, _arrayDestroy);
@@ -475,7 +478,9 @@
 
 /**
  * @func steam_inventory_transfer_item_quantity
- * @desc This function transfers items between stacks within a user's inventory.
+ * @desc Transfer items between stacks within a user's inventory.
+ *
+ * This can be used to stack, split, and moving items. The source and destination items must have the same itemdef id. To move items onto a destination stack specify the source, the quantity to move, and the destination item id. To split an existing stack, pass `steam_item_instance_id_invalid` into `dest_item_id`. A new item stack will be generated with the requested quantity.
  * 
  * [[WARNING: You must call ${function.steam_inventory_result_destroy} on the returned async result ID when you are done with it.]]
  * 
@@ -485,7 +490,7 @@
  * 
  * @param {int64} source_item_id The source [steam_inventory_item_id](https://partner.steamgames.com/doc/api/ISteamInventory#SteamItemInstanceID_t) to transfer from
  * @param {real} quantity The quantity of the item that will be transferred
- * @param  {int64} dest_item_id The destination [steam_inventory_item_id](https://partner.steamgames.com/doc/api/ISteamInventory#SteamItemInstanceID_t) to transfer to
+ * @param  {int64} dest_item_id The destination [steam_inventory_item_id](https://partner.steamgames.com/doc/api/ISteamInventory#SteamItemInstanceID_t) to transfer to or `steam_item_instance_id_invalid` to create a new stack
  * 
  * @returns {real}
  * 
@@ -498,9 +503,9 @@
  * 
  * @example
  * ```gml
- * handle = steam_inventory_transfer_item_quantity(global.apple, 2, global.oranges);
+ * handle = steam_inventory_transfer_item_quantity(global.apples[0], 2, global.apples[1]);
  * ```
- * The above code will trigger a transfer between two items owned by the user the amount to be transferred in the example, the user will lose 2 apples and receive 2 oranges. For an example on how to use the ${event.steam} to read the callback response, refer to the function ${function.steam_inventory_get_all_items}.
+ * The above code will trigger a transfer between two item stacks owned by the user the amount to be transferred in the example, this will move 2 apples from stack 0 to stack 1. For an example on how to use the ${event.steam} to read the callback response, refer to the function ${function.steam_inventory_get_all_items}.
  * @func_end
  */
 

source/Steamworks_gml/extensions/steamworks/docs/index.html

@@ -194,5 +194,5 @@ <h2 id="project-layout">Project layout</h2>
 
 <!--
 MkDocs version : 1.5.3
-Build Date UTC : 2024-04-15 10:29:01.772093+00:00
+Build Date UTC : 2024-06-10 09:35:33.638277+00:00
 -->

source/Steamworks_gml/extensions/steamworks/docs/inventory.html

@@ -766,6 +766,11 @@ <h1 id="steam_inventory_add_promo_items">steam_inventory_add_promo_items</h1>
 
 <h1 id="steam_inventory_exchange_items">steam_inventory_exchange_items</h1>
 <p>This function grants one item in exchange for a set of other items.</p>
+<p>The API currently takes an array of items to generate but at this time the size of that array must be 1 and the quantity of the new item must be 1.</p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>Any items that can be granted MUST have an exchange attribute in their itemdef.</p>
+</div>
 <div class="admonition warning">
 <p class="admonition-title">Warning</p>
 <p>You must call <a href="inventory.html#steam_inventory_result_destroy">steam_inventory_result_destroy</a> on the returned async result ID when you are done with it.</p>
@@ -792,7 +797,7 @@ <h1 id="steam_inventory_exchange_items">steam_inventory_exchange_items</h1>
 <tr>
 <td>create_arr</td>
 <td><a href="https://manual.gamemaker.io/monthly/en/GameMaker_Language/GML_Overview/Arrays.htm">Array</a> of <a href="inventory.html#inventoryitemcreationdata">InventoryItemCreationData</a></td>
-<td>An array of <a href="https://manual.yoyogames.com/GameMaker_Language/GML_Overview/Structs.htm">structs</a> representing items to be created</td>
+<td>An array of <a href="https://manual.yoyogames.com/GameMaker_Language/GML_Overview/Structs.htm">structs</a> representing items to be created (must be of size 1 and the item quantity must also be 1)</td>
 </tr>
 <tr>
 <td>destroy_arr</td>
@@ -851,7 +856,6 @@ <h1 id="steam_inventory_exchange_items">steam_inventory_exchange_items</h1>
 
 var _arrayCreate = [
     { item_def: global.holy_sword, quantity: 1 },
-    { item_def: global.orange, quantity: 2 }
 ];
 
 steam_inventory_exchange_items(_arrayCreate, _arrayDestroy);</code></pre>
@@ -1278,7 +1282,8 @@ <h1 id="steam_inventory_submit_update_properties">steam_inventory_submit_update_
 <p align="right"><a href="#top">Back To Top</a></p>
 
 <h1 id="steam_inventory_transfer_item_quantity">steam_inventory_transfer_item_quantity</h1>
-<p>This function transfers items between stacks within a user's inventory.</p>
+<p>Transfer items between stacks within a user's inventory.</p>
+<p>This can be used to stack, split, and moving items. The source and destination items must have the same itemdef id. To move items onto a destination stack specify the source, the quantity to move, and the destination item id. To split an existing stack, pass <code>steam_item_instance_id_invalid</code> into <code>dest_item_id</code>. A new item stack will be generated with the requested quantity.</p>
 <div class="admonition warning">
 <p class="admonition-title">Warning</p>
 <p>You must call <a href="inventory.html#steam_inventory_result_destroy">steam_inventory_result_destroy</a> on the returned async result ID when you are done with it.</p>
@@ -1315,7 +1320,7 @@ <h1 id="steam_inventory_transfer_item_quantity">steam_inventory_transfer_item_qu
 <tr>
 <td>dest_item_id</td>
 <td><a href="https://manual.gamemaker.io/monthly/en/GameMaker_Language/GML_Overview/Data_Types.htm">Int64</a></td>
-<td>The destination <a href="https://partner.steamgames.com/doc/api/ISteamInventory#SteamItemInstanceID_t">steam_inventory_item_id</a> to transfer to</td>
+<td>The destination <a href="https://partner.steamgames.com/doc/api/ISteamInventory#SteamItemInstanceID_t">steam_inventory_item_id</a> to transfer to or <code>steam_item_instance_id_invalid</code> to create a new stack</td>
 </tr>
 </tbody>
 </table>
@@ -1362,8 +1367,8 @@ <h1 id="steam_inventory_transfer_item_quantity">steam_inventory_transfer_item_qu
 </table>
 <p><br></p>
 <p><strong>Example:</strong></p>
-<p><pre class="highlight"><code class="language-gml">handle = steam_inventory_transfer_item_quantity(global.apple, 2, global.oranges);</code></pre>
-The above code will trigger a transfer between two items owned by the user the amount to be transferred in the example, the user will lose 2 apples and receive 2 oranges. For an example on how to use the <a href="https://manual.gamemaker.io/monthly/en/The_Asset_Editors/Object_Properties/Async_Events/Steam.htm">Steam Async Event</a> to read the callback response, refer to the function <a href="inventory.html#steam_inventory_get_all_items">steam_inventory_get_all_items</a>.</p>
+<p><pre class="highlight"><code class="language-gml">handle = steam_inventory_transfer_item_quantity(global.apples[0], 2, global.apples[1]);</code></pre>
+The above code will trigger a transfer between two item stacks owned by the user the amount to be transferred in the example, this will move 2 apples from stack 0 to stack 1. For an example on how to use the <a href="https://manual.gamemaker.io/monthly/en/The_Asset_Editors/Object_Properties/Async_Events/Steam.htm">Steam Async Event</a> to read the callback response, refer to the function <a href="inventory.html#steam_inventory_get_all_items">steam_inventory_get_all_items</a>.</p>
 <p><br></p>
 <p><br></p>
 <hr />

source/Steamworks_gml/objects/Obj_Steam/Create_0.gml

@@ -7,3 +7,5 @@ randomize();
 #macro SteamLeaderboard "YYLeaderboard_10/29/21--"
 
 if (steam_initialised()) room_goto(Room_Steam_Main);
+
+handle = -1;

source/Steamworks_gml/objects/Obj_Steam/KeyPress_65.gml

@@ -0,0 +1,4 @@
+/// @description Insert description here
+// You can write your code in this editor
+
+handle = steam_inventory_get_all_items();

source/Steamworks_gml/objects/Obj_Steam/KeyPress_68.gml

@@ -0,0 +1,5 @@
+/// @description Insert description here
+// You can write your code in this editor
+
+
+handle = steam_inventory_trigger_item_drop(10);

source/Steamworks_gml/objects/Obj_Steam/Other_69.gml

@@ -26,4 +26,28 @@ if (async_load[? "event_type"] == "remote_storage_local_file_change")
 
 if (async_load[? "event_type"] == "playback_status_has_changed"){
 	show_debug_message("playback_change_detected");
+}
+
+// Early exit if event type doesn't match
+if (async_load[? "event_type"] == "inventory_result_ready") {
+
+	// Early exit if handle doesn't match
+	if (async_load[? "handle"] == handle) {
+
+		// Early exit if handle doesn't match
+		if (async_load[? "success"])
+		{
+		    var _items = steam_inventory_result_get_items(handle);
+
+		    for (var i = 0; i < array_length(_items); i++)
+		    {
+		        var _item = _items[i];
+		        show_debug_message(_item);
+		    }
+		}
+	}
+
+	// Don't forget to clean the ununsed handle
+	steam_inventory_result_destroy(handle);
+	handle = -1;
 }