Implement dropped item merging (#4419)

- The following classes have been added:
  - `ItemMergeEvent`
  - `ItemEntityStackSizeChangeAnimation`
- The following API methods have been added:
  - `ItemEntity->isMergeable()`
  - `ItemEntity->tryMergeInto()`
  - `ItemEntity->setStackSize()`

src/entity/animation/ItemEntityStackSizeChangeAnimation.php

@@ -0,0 +1,40 @@
+<?php
+
+/*
+ *
+ *  ____            _        _   __  __ _                  __  __ ____
+ * |  _ \ ___   ___| | _____| |_|  \/  (_)_ __   ___      |  \/  |  _ \
+ * | |_) / _ \ / __| |/ / _ \ __| |\/| | | '_ \ / _ \_____| |\/| | |_) |
+ * |  __/ (_) | (__|   <  __/ |_| |  | | | | | |  __/_____| |  | |  __/
+ * |_|   \___/ \___|_|\_\___|\__|_|  |_|_|_| |_|\___|     |_|  |_|_|
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * @author PocketMine Team
+ * @link http://www.pocketmine.net/
+ *
+ *
+*/
+
+declare(strict_types=1);
+
+namespace pocketmine\entity\animation;
+
+use pocketmine\entity\object\ItemEntity;
+use pocketmine\network\mcpe\protocol\ActorEventPacket;
+use pocketmine\network\mcpe\protocol\types\ActorEvent;
+
+final class ItemEntityStackSizeChangeAnimation implements Animation{
+
+	public function __construct(
+		private ItemEntity $itemEntity,
+		private int $newStackSize
+	){}
+
+	public function encode() : array{
+		return [ActorEventPacket::create($this->itemEntity->getId(), ActorEvent::ITEM_ENTITY_MERGE, $this->newStackSize)];
+	}
+}

src/entity/object/ItemEntity.php

@@ -23,11 +23,13 @@ declare(strict_types=1);
 
 namespace pocketmine\entity\object;
 
+use pocketmine\entity\animation\ItemEntityStackSizeChangeAnimation;
 use pocketmine\entity\Entity;
 use pocketmine\entity\EntitySizeInfo;
 use pocketmine\entity\Location;
 use pocketmine\event\entity\EntityItemPickupEvent;
 use pocketmine\event\entity\ItemDespawnEvent;
+use pocketmine\event\entity\ItemMergeEvent;
 use pocketmine\event\entity\ItemSpawnEvent;
 use pocketmine\item\Item;
 use pocketmine\math\Vector3;
@@ -43,6 +45,7 @@ class ItemEntity extends Entity{
 
 	public static function getNetworkTypeId() : string{ return EntityIds::ITEM; }
 
+	public const MERGE_CHECK_PERIOD = 2; //0.1 seconds
 	public const DEFAULT_DESPAWN_DELAY = 6000; //5 minutes
 	public const NEVER_DESPAWN = -1;
 	public const MAX_DESPAWN_DELAY = 32767 + self::DEFAULT_DESPAWN_DELAY; //max value storable by mojang NBT :(
@@ -105,6 +108,27 @@ class ItemEntity extends Entity{
 			if($this->pickupDelay < 0){
 				$this->pickupDelay = 0;
 			}
+			if($this->hasMovementUpdate() and $this->despawnDelay % self::MERGE_CHECK_PERIOD === 0){
+				$mergeable = [$this]; //in case the merge target ends up not being this
+				$mergeTarget = $this;
+				foreach($this->getWorld()->getNearbyEntities($this->boundingBox->expandedCopy(0.5, 0.5, 0.5), $this) as $entity){
+					if(!$entity instanceof ItemEntity or $entity->isFlaggedForDespawn()){
+						continue;
+					}
+
+					if($entity->isMergeable($this)){
+						$mergeable[] = $entity;
+						if($entity->item->getCount() > $mergeTarget->item->getCount()){
+							$mergeTarget = $entity;
+						}
+					}
+				}
+				foreach($mergeable as $itemEntity){
+					if($itemEntity !== $mergeTarget){
+						$itemEntity->tryMergeInto($mergeTarget);
+					}
+				}
+			}
 
 			$this->despawnDelay -= $tickDiff;
 			if($this->despawnDelay <= 0){
@@ -122,6 +146,37 @@ class ItemEntity extends Entity{
 		return $hasUpdate;
 	}
 
+	/**
+	 * Returns whether this item entity can merge with the given one.
+	 */
+	public function isMergeable(ItemEntity $entity) : bool{
+		$item = $entity->item;
+		return $entity !== $this && $entity->pickupDelay !== self::NEVER_DESPAWN and $item->canStackWith($this->item) and $item->getCount() + $this->item->getCount() <= $item->getMaxStackSize();
+	}
+
+	/**
+	 * Attempts to merge this item entity into the given item entity. Returns true if it was successful.
+	 */
+	public function tryMergeInto(ItemEntity $consumer) : bool{
+		if(!$this->isMergeable($consumer)){
+			return false;
+		}
+
+		$ev = new ItemMergeEvent($this, $consumer);
+		$ev->call();
+
+		if($ev->isCancelled()){
+			return false;
+		}
+
+		$consumer->setStackSize($consumer->item->getCount() + $this->item->getCount());
+		$this->flagForDespawn();
+		$consumer->pickupDelay = max($consumer->pickupDelay, $this->pickupDelay);
+		$consumer->despawnDelay = max($consumer->despawnDelay, $this->despawnDelay);
+
+		return true;
+	}
+
 	protected function tryChangeMovement() : void{
 		$this->checkObstruction($this->location->x, $this->location->y, $this->location->z);
 		parent::tryChangeMovement();
@@ -217,6 +272,14 @@ class ItemEntity extends Entity{
 		));
 	}
 
+	public function setStackSize(int $newCount) : void{
+		if($newCount <= 0){
+			throw new \InvalidArgumentException("Stack size must be at least 1");
+		}
+		$this->item->setCount($newCount);
+		$this->broadcastAnimation(new ItemEntityStackSizeChangeAnimation($this, $newCount));
+	}
+
 	public function getOffsetPosition(Vector3 $vector3) : Vector3{
 		return $vector3->add(0, 0.125, 0);
 	}

src/event/entity/ItemMergeEvent.php

@@ -0,0 +1,52 @@
+<?php
+
+/*
+ *
+ *  ____            _        _   __  __ _                  __  __ ____
+ * |  _ \ ___   ___| | _____| |_|  \/  (_)_ __   ___      |  \/  |  _ \
+ * | |_) / _ \ / __| |/ / _ \ __| |\/| | | '_ \ / _ \_____| |\/| | |_) |
+ * |  __/ (_) | (__|   <  __/ |_| |  | | | | | |  __/_____| |  | |  __/
+ * |_|   \___/ \___|_|\_\___|\__|_|  |_|_|_| |_|\___|     |_|  |_|_|
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * @author PocketMine Team
+ * @link http://www.pocketmine.net/
+ *
+ *
+*/
+
+declare(strict_types=1);
+
+namespace pocketmine\event\entity;
+
+use pocketmine\entity\object\ItemEntity;
+use pocketmine\event\Cancellable;
+use pocketmine\event\CancellableTrait;
+
+/**
+ * Called when an item entity tries to merge into another item entity.
+ *
+ * @phpstan-extends EntityEvent<ItemEntity>
+ */
+class ItemMergeEvent extends EntityEvent implements Cancellable{
+	use CancellableTrait;
+
+	public function __construct(
+		ItemEntity $entity,
+		protected ItemEntity $target
+	){
+		$this->entity = $entity;
+	}
+
+	/**
+	 * Returns the merge destination.
+	 */
+	public function getTarget() : ItemEntity{
+		return $this->target;
+	}
+
+}