From cdc452916e3ec7e61f4a1ad822666192593b4b08 Mon Sep 17 00:00:00 2001
From: Alexander Harkness <me@bearbin.net>
Date: Thu, 2 Apr 2020 12:42:15 +0000
Subject: Replace buckets to the selected hotbar slot, rather than the first
 available. (#4580)

* Replace buckets to the selected hotbar slot, rather than the first available.

Replicates vanilla behaviour, as well as being more logical.

* Refactor cInventory::AddItem. Behaviour is now documented

* Add new cInventory::ReplaceOneEquippedItem and ::SetEquippedItem methods

* Return empty potion to the same slot after drinking

* Replace buckets correctly in other situations, not simply water and lava

Uses the new ReplaceOneEquippedItem method

* Correct collecting water from source block with bottle

* Add cPlayer::ReplaceOneEquippedItemTossRest method

* Handle stacked filled buckets (in theory)

Use new cPlayer::ReplaceOneEquippedItemTossRest method
---
 Server/Plugins/APIDump/APIDesc.lua | 66 +++++++++++++++++++++++++++++++-------
 1 file changed, 55 insertions(+), 11 deletions(-)

(limited to 'Server')

diff --git a/Server/Plugins/APIDump/APIDesc.lua b/Server/Plugins/APIDump/APIDesc.lua
index 8adda34a7..69e7cd75b 100644
--- a/Server/Plugins/APIDump/APIDesc.lua
+++ b/Server/Plugins/APIDump/APIDesc.lua
@@ -6223,7 +6223,7 @@ These ItemGrids are available in the API and can be manipulated by the plugins,
 							Type = "number",
 						},
 					},
-					Notes = "Adds an item to the storage; if AllowNewStacks is true (default), will also create new stacks in empty slots. Returns the number of items added",
+					Notes = "Adds an item to the storage; if AllowNewStacks is true (default), will also create new stacks in empty slots. Fills existing stacks first and fills the hotbar before the main inventory. Returns the number of items added",
 				},
 				AddItems =
 				{
@@ -6617,6 +6617,28 @@ These ItemGrids are available in the API and can be manipulated by the plugins,
 					},
 					Notes = "Removes one item from the hotbar's currently selected slot. Returns true on success.",
 				},
+				ReplaceOneEquippedItem =
+				{
+					Params =
+					{
+						{
+							Name = "Item",
+							Type = "cItem",
+						},
+						{
+							Name = "TryOtherSlots",
+							Type = "boolean",
+							IsOptional = true,
+						},
+					},
+					Returns =
+					{
+						{
+							Type = "number",
+						},
+					},
+					Notes = "Removes one item from the the current equipped item stack, and attempts to add the specified item stack back to the same slot. If it is not possible to place the item in the same slot, optionally (default true) tries to place the specified item elsewhere in the inventory. Returns the number of items successfully added. If the currently equipped slot is empty, its contents are simply set to the given Item.",
+				},
 				SendEquippedSlot =
 				{
 					Notes = "Sends the equipped item slot to the client",
@@ -6662,31 +6684,31 @@ These ItemGrids are available in the API and can be manipulated by the plugins,
 					},
 					Notes = "Sets the specified hotbar slot contents",
 				},
-				SetShieldSlot =
+				SetInventorySlot =
 				{
 					Params =
 					{
 						{
-							Name = "Item",
+							Name = "InventorySlotNum",
+							Type = "number",
+						},
+						{
+							Name = "cItem",
 							Type = "cItem",
 						},
 					},
-					Notes = "Sets the shield slot content",
+					Notes = "Sets the specified main inventory slot contents",
 				},
-				SetInventorySlot =
+				SetShieldSlot =
 				{
 					Params =
 					{
 						{
-							Name = "InventorySlotNum",
-							Type = "number",
-						},
-						{
-							Name = "cItem",
+							Name = "Item",
 							Type = "cItem",
 						},
 					},
-					Notes = "Sets the specified main inventory slot contents",
+					Notes = "Sets the shield slot content",
 				},
 				SetSlot =
 				{
@@ -6703,6 +6725,17 @@ These ItemGrids are available in the API and can be manipulated by the plugins,
 					},
 					Notes = "Sets the specified slot contents",
 				},
+				SetEquippedItem = 
+				{
+					Params =
+					{
+						{
+							Name = "Item",
+							Type = "cItem",
+						},
+					},
+					Notes = "Sets current item in the equipped hotbar slot",
+				},
 			},
 			Constants =
 			{
@@ -10712,6 +10745,17 @@ a_Player:OpenWindow(Window);
 					},
 					Notes = "Places a block while impersonating the player. The {{OnPlayerPlacingBlock|HOOK_PLAYER_PLACING_BLOCK}} hook is called before the placement, and if it succeeds, the block is placed and the {{OnPlayerPlacedBlock|HOOK_PLAYER_PLACED_BLOCK}} hook is called. Returns true iff the block is successfully placed. Assumes that the block is in a currently loaded chunk.",
 				},
+				ReplaceOneEquippedItemTossRest =
+				{
+					Params =
+					{
+						{
+							Name = "Item",
+							Type = "cItem",
+						},
+					},
+					Notes = "Removes one item from the the current equipped item stack, and attempts to add the specified item stack back to the same slot. If it is not possible to place the item in the same slot, tries to place the specified item elsewhere in the inventory. If this is not possible, then any remaining items are tossed. If the currently equipped slot is empty, its contents are simply set to the given Item.",
+				},
 				Respawn =
 				{
 					Notes = "Restores the health, extinguishes fire, makes visible and sends the Respawn packet.",
-- 
cgit v1.2.3