1 files changed, 39 insertions, 21 deletions

diff --git a/src/Items/ItemHandler.h b/src/Items/ItemHandler.h
index ea0684dd1..74de4eaa5 100644
--- a/src/Items/ItemHandler.h
+++ b/src/Items/ItemHandler.h
@@ -38,28 +38,39 @@ public:
 
 
 	/** Called when the player tries to place the item (right mouse button, IsPlaceable() == true).
-	The block coords are for the block that has been clicked.
+	a_ClickedBlockPos is the (neighbor) block that has been clicked to place this item.
+	a_ClickedBlockFace is the face of the neighbor that has been clicked to place this item.
+	a_CursorPos is the position of the player's cursor within a_ClickedBlockFace.
 	The default handler uses GetBlocksToPlace() and places the returned blocks.
 	Override if the item needs advanced processing, such as spawning a mob based on the blocks being placed.
 	If the block placement is refused inside this call, it will automatically revert the client-side changes.
 	Returns true if the placement succeeded, false if the placement was aborted for any reason. */
 	virtual bool OnPlayerPlace(
-		cWorld & a_World, cPlayer & a_Player, const cItem & a_EquippedItem,
-		int a_BlockX, int a_BlockY, int a_BlockZ, eBlockFace a_BlockFace,
-		int a_CursorX, int a_CursorY, int a_CursorZ
+		cWorld & a_World,
+		cPlayer & a_Player,
+		const cItem & a_EquippedItem,
+		const Vector3i a_ClickedBlockPos,
+		eBlockFace a_ClickedBlockFace,
+		const Vector3i a_CursorPos
 	);
 
 
 	/** Called from OnPlayerPlace() to determine the blocks that the current placement operation should set.
-	The block coords are where the new (main) block should be placed.
+	a_PlacedBlockPos points to the location where the new block should be set.
+	a_ClickedBlockFace is the block face of the neighbor that was clicked to place this block.
+	a_CursorPos is the position of the mouse cursor within the clicked (neighbor's) block face.
+	The blocks in a_BlocksToPlace will be sent through cPlayer::PlaceBlocks() after returning from this function.
 	The default handler uses GetPlacementBlockTypeMeta() and provides that as the single block at the specified coords.
 	Returns true if the placement succeeded, false if the placement was aborted for any reason.
 	If aborted, the server then sends all original blocks in the coords provided in a_BlocksToSet to the client. */
 	virtual bool GetBlocksToPlace(
-		cWorld & a_World, cPlayer & a_Player, const cItem & a_EquippedItem,
-		int a_BlockX, int a_BlockY, int a_BlockZ, eBlockFace a_BlockFace,
-		int a_CursorX, int a_CursorY, int a_CursorZ,
-		sSetBlockVector & a_BlocksToSet
+		cWorld & a_World,
+		cPlayer & a_Player,
+		const cItem & a_EquippedItem,
+		const Vector3i a_PlacedBlockPos,
+		eBlockFace a_ClickedBlockFace,
+		const Vector3i a_CursorPos,
+		sSetBlockVector & a_BlocksToPlace
 	);
 
 
@@ -68,26 +79,29 @@ public:
 	Returns true to allow placement, false to refuse. */
 	virtual bool GetPlacementBlockTypeMeta(
 		cWorld * a_World, cPlayer * a_Player,
-		int a_BlockX, int a_BlockY, int a_BlockZ, eBlockFace a_BlockFace,
-		int a_CursorX, int a_CursorY, int a_CursorZ,
+		const Vector3i a_PlacedBlockPos,
+		eBlockFace a_ClickedBlockFace,
+		const Vector3i a_CursorPos,
 		BLOCKTYPE & a_BlockType, NIBBLETYPE & a_BlockMeta
 	);
 
 
 	/** Called when the player tries to use the item (right mouse button).
-	Return false to abort the usage. DEFAULT: False */
+	Descendants can return false to abort the usage (default behavior). */
 	virtual bool OnItemUse(
-		cWorld * a_World, cPlayer * a_Player, cBlockPluginInterface & a_PluginInterface, const cItem & a_Item,
-		int a_BlockX, int a_BlockY, int a_BlockZ, eBlockFace a_BlockFace
+		cWorld * a_World,
+		cPlayer * a_Player,
+		cBlockPluginInterface & a_PluginInterface,
+		const cItem & a_HeldItem,
+		const Vector3i a_ClickedBlockPos,
+		eBlockFace a_ClickedBlockFace
 	);
 
 
-	/** Called when the client sends the SHOOT status in the lclk packet */
-	virtual void OnItemShoot(cPlayer *, int a_BlockX, int a_BlockY, int a_BlockZ, eBlockFace a_BlockFace)
+	/** Called when the client sends the SHOOT status in the lclk packet (releasing the bow). */
+	virtual void OnItemShoot(cPlayer *, const Vector3i a_BlockPos, eBlockFace a_BlockFace)
 	{
-		UNUSED(a_BlockX);
-		UNUSED(a_BlockY);
-		UNUSED(a_BlockZ);
+		UNUSED(a_BlockPos);
 		UNUSED(a_BlockFace);
 	}
 
@@ -100,9 +114,13 @@ public:
 	}
 
 	/** Called while the player digs a block using this item */
-	virtual bool OnDiggingBlock(cWorld * a_World, cPlayer * a_Player, const cItem & a_HeldItem, int a_BlockX, int a_BlockY, int a_BlockZ, eBlockFace a_BlockFace);
+	virtual bool OnDiggingBlock(
+		cWorld * a_World, cPlayer * a_Player, const cItem & a_HeldItem,
+		const Vector3i a_ClickedBlockPos,
+		eBlockFace a_ClickedBlockFace
+	);
 
-	/** Called when a player attacks a other entity. */
+	/** Called when a player attacks an entity with this item in hand. */
 	virtual void OnEntityAttack(cPlayer * a_Attacker, cEntity * a_AttackedEntity);
 
 	/** Called after the player has eaten this item. */