Merge branch 'stable' into next-minor

changelogs/4.3.md

@@ -43,3 +43,35 @@ Released 16th May 2022.
 - Fixed server crash when chunks are unloaded during chunk generation callbacks
 - Fixed dead coral fan items placing coral fans in the wrong orientation.
 - Fixed max stack size of boat items.
+
+# 4.3.4
+Released 22nd May 2022.
+
+## Fixes
+- Fixed `difficulty` in `server.properties` having no effect - it's now applied to newly generated worlds.
+  - Note: this setting still doesn't behave the same way as vanilla due to potential disruption to existing servers.
+- Fixed paintings not working in newly generated worlds and some other cases.
+- Fixed inventory window switching breaking the inventory UI in some cases (e.g. pressing E while clicking a chest).
+- Fixed minecart items incorrectly stacking.
+- Fixed incorrect light levels in translucent blocks at the top of the world.
+- Fixed teleporting sleeping players causing broken behaviour on the sleeping player's client.
+- Fixed `EntityExplodeEvent->setYield()` accepting values outside the range 0-100.
+- Fixed `ExplosionPrimeEvent->setForce()` accepting negative values (later resulting in crashes).
+
+## Documentation
+- Updated documentation for the following events:
+  - `CommandEvent`
+  - `EntityDespawnEvent`
+  - `EntityExplodeEvent`
+  - `EntitySpawnEvent`
+  - `ExplosionPrimeEvent`
+  - `InventoryTransactionEvent`
+  - `ItemDespawnEvent`
+  - `ItemSpawnEvent`
+  - `PlayerCommandPreprocessEvent`
+  - `PlayerDropItemEvent`
+  - `PlayerItemHeldEvent`
+  - `PlayerKickEvent`
+  - `PlayerQuitEvent`
+  - `PlayerTransferEvent`
+  - `UpdateNotifyEvent`

src/Server.php

@@ -1118,6 +1118,7 @@ class Server{
 				$creationOptions->setGeneratorClass($generatorClass);
 				$creationOptions->setGeneratorOptions($generatorOptions);
 
+				$creationOptions->setDifficulty($this->getDifficulty());
 				if(isset($options["difficulty"]) && is_string($options["difficulty"])){
 					$creationOptions->setDifficulty(World::getDifficultyFromString($options["difficulty"]));
 				}
@@ -1161,6 +1162,7 @@ class Server{
 				if($convertedSeed !== null){
 					$creationOptions->setSeed($convertedSeed);
 				}
+				$creationOptions->setDifficulty($this->getDifficulty());
 				$this->worldManager->generateWorld($default, $creationOptions);
 			}
 

src/block/inventory/ShulkerBoxInventory.php

@@ -23,9 +23,9 @@ declare(strict_types=1);
 
 namespace pocketmine\block\inventory;
 
-use pocketmine\block\BlockLegacyIds;
 use pocketmine\inventory\SimpleInventory;
 use pocketmine\item\Item;
+use pocketmine\item\ItemIds;
 use pocketmine\network\mcpe\protocol\BlockEventPacket;
 use pocketmine\network\mcpe\protocol\types\BlockPosition;
 use pocketmine\world\Position;
@@ -50,7 +50,7 @@ class ShulkerBoxInventory extends SimpleInventory implements BlockInventory{
 	}
 
 	public function canAddItem(Item $item) : bool{
-		if($item->getId() === BlockLegacyIds::UNDYED_SHULKER_BOX || $item->getId() === BlockLegacyIds::SHULKER_BOX){
+		if($item->getId() === ItemIds::UNDYED_SHULKER_BOX || $item->getId() === ItemIds::SHULKER_BOX){
 			return false;
 		}
 		return parent::canAddItem($item);

src/event/entity/EntityDespawnEvent.php

@@ -26,7 +26,9 @@ namespace pocketmine\event\entity;
 use pocketmine\entity\Entity;
 
 /**
- * Called when a entity is despawned
+ * Called when an entity is removed from the world. This could be for a variety of reasons, including chunks being
+ * unloaded, entity death, etc.
+ *
  * @phpstan-extends EntityEvent<Entity>
  */
 class EntityDespawnEvent extends EntityEvent{

src/event/entity/EntityExplodeEvent.php

@@ -31,7 +31,11 @@ use pocketmine\utils\Utils;
 use pocketmine\world\Position;
 
 /**
- * Called when a entity explodes
+ * Called when an entity explodes, after the explosion's impact has been calculated.
+ * No changes have been made to the world at this stage.
+ *
+ * @see ExplosionPrimeEvent
+ *
  * @phpstan-extends EntityEvent<Entity>
  */
 class EntityExplodeEvent extends EntityEvent implements Cancellable{
@@ -47,12 +51,16 @@ class EntityExplodeEvent extends EntityEvent implements Cancellable{
 	protected $yield;
 
 	/**
-	 * @param Block[]  $blocks
+	 * @param Block[] $blocks
+	 * @param float   $yield 0-100
 	 */
 	public function __construct(Entity $entity, Position $position, array $blocks, float $yield){
 		$this->entity = $entity;
 		$this->position = $position;
 		$this->blocks = $blocks;
+		if($yield < 0.0 || $yield > 100.0){
+			throw new \InvalidArgumentException("Yield must be in range 0.0 - 100.0");
+		}
 		$this->yield = $yield;
 	}
 
@@ -61,6 +69,8 @@ class EntityExplodeEvent extends EntityEvent implements Cancellable{
 	}
 
 	/**
+	 * Returns a list of blocks destroyed by the explosion.
+	 *
 	 * @return Block[]
 	 */
 	public function getBlockList() : array{
@@ -68,6 +78,8 @@ class EntityExplodeEvent extends EntityEvent implements Cancellable{
 	}
 
 	/**
+	 * Sets the blocks destroyed by the explosion.
+	 *
 	 * @param Block[] $blocks
 	 */
 	public function setBlockList(array $blocks) : void{
@@ -75,11 +87,22 @@ class EntityExplodeEvent extends EntityEvent implements Cancellable{
 		$this->blocks = $blocks;
 	}
 
+	/**
+	 * Returns the percentage chance of drops from each block destroyed by the explosion.
+	 * @return float 0-100
+	 */
 	public function getYield() : float{
 		return $this->yield;
 	}
 
+	/**
+	 * Sets the percentage chance of drops from each block destroyed by the explosion.
+	 * @param float $yield 0-100
+	 */
 	public function setYield(float $yield) : void{
+		if($yield < 0.0 || $yield > 100.0){
+			throw new \InvalidArgumentException("Yield must be in range 0.0 - 100.0");
+		}
 		$this->yield = $yield;
 	}
 }

src/event/entity/EntitySpawnEvent.php

@@ -26,7 +26,8 @@ namespace pocketmine\event\entity;
 use pocketmine\entity\Entity;
 
 /**
- * Called when a entity is spawned
+ * Called when an entity is added to the world. This might be a new entity or an entity loaded from storage.
+ *
  * @phpstan-extends EntityEvent<Entity>
  */
 class EntitySpawnEvent extends EntityEvent{

src/event/entity/ExplosionPrimeEvent.php

@@ -28,7 +28,11 @@ use pocketmine\event\Cancellable;
 use pocketmine\event\CancellableTrait;
 
 /**
- * Called when a entity decides to explode
+ * Called when an entity decides to explode, before the explosion's impact is calculated.
+ * This allows changing the force of the explosion and whether it will destroy blocks.
+ *
+ * @see EntityExplodeEvent
+ *
  * @phpstan-extends EntityEvent<Entity>
  */
 class ExplosionPrimeEvent extends EntityEvent implements Cancellable{
@@ -39,6 +43,9 @@ class ExplosionPrimeEvent extends EntityEvent implements Cancellable{
 	private bool $blockBreaking = true;
 
 	public function __construct(Entity $entity, float $force){
+		if($force <= 0){
+			throw new \InvalidArgumentException("Explosion radius must be positive");
+		}
 		$this->entity = $entity;
 		$this->force = $force;
 	}
@@ -48,6 +55,9 @@ class ExplosionPrimeEvent extends EntityEvent implements Cancellable{
 	}
 
 	public function setForce(float $force) : void{
+		if($force <= 0){
+			throw new \InvalidArgumentException("Explosion radius must be positive");
+		}
 		$this->force = $force;
 	}
 

src/event/entity/ItemDespawnEvent.php

@@ -28,6 +28,9 @@ use pocketmine\event\Cancellable;
 use pocketmine\event\CancellableTrait;
 
 /**
+ * Called when a dropped item tries to despawn due to its despawn delay running out.
+ * Cancelling the event will reset the despawn delay to default (5 minutes).
+ *
  * @phpstan-extends EntityEvent<ItemEntity>
  */
 class ItemDespawnEvent extends EntityEvent implements Cancellable{

src/event/entity/ItemSpawnEvent.php

@@ -26,6 +26,15 @@ namespace pocketmine\event\entity;
 use pocketmine\entity\object\ItemEntity;
 
 /**
+ * Called when an item is spawned or loaded.
+ *
+ * Some possible reasons include:
+ * - item is loaded from disk
+ * - player dropping an item
+ * - block drops
+ * - loot of a player or entity
+ *
+ * @see PlayerDropItemEvent
  * @phpstan-extends EntityEvent<ItemEntity>
  */
 class ItemSpawnEvent extends EntityEvent{

src/event/inventory/InventoryTransactionEvent.php

@@ -29,8 +29,17 @@ use pocketmine\event\Event;
 use pocketmine\inventory\transaction\InventoryTransaction;
 
 /**
- * Called when there is a transaction between two Inventory objects.
- * The source of this can be a Player, entities, mobs, or even hoppers in the future!
+ * Called when a player performs actions involving items in inventories.
+ *
+ * This may involve multiple inventories, and may include actions such as:
+ * - moving items from one slot to another
+ * - splitting itemstacks
+ * - dragging itemstacks across inventory slots (slot painting)
+ * - dropping an item on the ground
+ * - taking an item from the creative inventory menu
+ * - destroying (trashing) an item
+ *
+ * @see https://doc.pmmp.io/en/rtfd/developer-reference/inventory-transactions.html for more information on inventory transactions
  */
 class InventoryTransactionEvent extends Event implements Cancellable{
 	use CancellableTrait;

src/event/player/PlayerDropItemEvent.php

@@ -29,7 +29,7 @@ use pocketmine\item\Item;
 use pocketmine\player\Player;
 
 /**
- * Called when a player tries to drop an item from its hotbar
+ * Called when a player tries to drop an item
  */
 class PlayerDropItemEvent extends PlayerEvent implements Cancellable{
 	use CancellableTrait;

src/event/player/PlayerItemHeldEvent.php

@@ -28,6 +28,11 @@ use pocketmine\event\CancellableTrait;
 use pocketmine\item\Item;
 use pocketmine\player\Player;
 
+/**
+ * Called when a player's held item changes.
+ * This could be because they selected a different hotbar slot, or because the item in the selected hotbar slot was
+ * changed.
+ */
 class PlayerItemHeldEvent extends PlayerEvent implements Cancellable{
 	use CancellableTrait;
 

src/event/player/PlayerKickEvent.php

@@ -29,7 +29,7 @@ use pocketmine\lang\Translatable;
 use pocketmine\player\Player;
 
 /**
- * Called when a player leaves the server
+ * Called when a player is kicked (forcibly disconnected) from the server, e.g. if an operator used /kick.
  */
 class PlayerKickEvent extends PlayerEvent implements Cancellable{
 	use CancellableTrait;
@@ -46,18 +46,33 @@ class PlayerKickEvent extends PlayerEvent implements Cancellable{
 		$this->reason = $reason;
 	}
 
+	/**
+	 * Sets the message shown on the kicked player's disconnection screen.
+	 * This message is also displayed in the console and server log.
+	 */
 	public function setReason(string $reason) : void{
 		$this->reason = $reason;
 	}
 
+	/**
+	 * Returns the message shown on the kicked player's disconnection screen.
+	 * This message is also displayed in the console and server log.
+	 * When kicked by the /kick command, the default is something like "Kicked by admin.".
+	 */
 	public function getReason() : string{
 		return $this->reason;
 	}
 
+	/**
+	 * Sets the quit message broadcasted to other players.
+	 */
 	public function setQuitMessage(Translatable|string $quitMessage) : void{
 		$this->quitMessage = $quitMessage;
 	}
 
+	/**
+	 * Returns the quit message broadcasted to other players, e.g. "Steve left the game".
+	 */
 	public function getQuitMessage() : Translatable|string{
 		return $this->quitMessage;
 	}

src/event/player/PlayerQuitEvent.php

@@ -27,7 +27,14 @@ use pocketmine\lang\Translatable;
 use pocketmine\player\Player;
 
 /**
- * Called when a player leaves the server
+ * Called when a player disconnects from the server for any reason.
+ *
+ * Some possible reasons include:
+ * - being kicked by an operator
+ * - disconnecting from the game
+ * - timeout due to network connectivity issues
+ *
+ * @see PlayerKickEvent
  */
 class PlayerQuitEvent extends PlayerEvent{
 
@@ -42,14 +49,23 @@ class PlayerQuitEvent extends PlayerEvent{
 		$this->quitReason = $quitReason;
 	}
 
+	/**
+	 * Sets the quit message broadcasted to other players.
+	 */
 	public function setQuitMessage(Translatable|string $quitMessage) : void{
 		$this->quitMessage = $quitMessage;
 	}
 
+	/**
+	 * Returns the quit message broadcasted to other players, e.g. "Steve left the game".
+	 */
 	public function getQuitMessage() : Translatable|string{
 		return $this->quitMessage;
 	}
 
+	/**
+	 * Returns the disconnect reason shown in the server log and on the console.
+	 */
 	public function getQuitReason() : string{
 		return $this->quitReason;
 	}

src/event/player/PlayerTransferEvent.php

@@ -27,6 +27,9 @@ use pocketmine\event\Cancellable;
 use pocketmine\event\CancellableTrait;
 use pocketmine\player\Player;
 
+/**
+ * Called when a player attempts to be transferred to another server, e.g. by using /transferserver.
+ */
 class PlayerTransferEvent extends PlayerEvent implements Cancellable{
 	use CancellableTrait;
 
@@ -44,26 +47,44 @@ class PlayerTransferEvent extends PlayerEvent implements Cancellable{
 		$this->message = $message;
 	}
 
+	/**
+	 * Returns the destination server address. This could be an IP or a domain name.
+	 */
 	public function getAddress() : string{
 		return $this->address;
 	}
 
+	/**
+	 * Sets the destination server address.
+	 */
 	public function setAddress(string $address) : void{
 		$this->address = $address;
 	}
 
+	/**
+	 * Returns the destination server port.
+	 */
 	public function getPort() : int{
 		return $this->port;
 	}
 
+	/**
+	 * Sets the destination server port.
+	 */
 	public function setPort(int $port) : void{
 		$this->port = $port;
 	}
 
+	/**
+	 * Returns the disconnect reason shown in the server log and on the console.
+	 */
 	public function getMessage() : string{
 		return $this->message;
 	}
 
+	/**
+	 * Sets the disconnect reason shown in the server log and on the console.
+	 */
 	public function setMessage(string $message) : void{
 		$this->message = $message;
 	}

src/event/server/CommandEvent.php

@@ -28,12 +28,18 @@ use pocketmine\event\Cancellable;
 use pocketmine\event\CancellableTrait;
 
 /**
- * Called when any CommandSender runs a command, early in the process
+ * Called when any CommandSender runs a command, before it is parsed.
  *
- * You don't want to use this except for a few cases like logging commands,
- * blocking commands on certain places, or applying modifiers.
+ * This can be used for logging commands, or preprocessing the command string to add custom features (e.g. selectors).
  *
- * The message DOES NOT contain a slash at the start
+ * WARNING: DO NOT use this to block commands. Many commands have aliases.
+ * For example, /version can also be invoked using /ver or /about.
+ * To prevent command senders from using certain commands, deny them permission to use the commands you don't want them
+ * to have access to.
+ *
+ * @see Permissible::addAttachment()
+ *
+ * The message DOES NOT begin with a slash.
  */
 class CommandEvent extends ServerEvent implements Cancellable{
 	use CancellableTrait;

src/event/server/UpdateNotifyEvent.php

@@ -26,7 +26,7 @@ namespace pocketmine\event\server;
 use pocketmine\updater\UpdateChecker;
 
 /**
- * Called when the AutoUpdater receives notification of an available PocketMine-MP update.
+ * Called when the update checker receives notification of an available PocketMine-MP update.
  * Plugins may use this event to perform actions when an update notification is received.
  */
 class UpdateNotifyEvent extends ServerEvent{

src/event/world/ChunkLoadEvent.php

@@ -27,7 +27,7 @@ use pocketmine\world\format\Chunk;
 use pocketmine\world\World;
 
 /**
- * Called when a Chunk is loaded
+ * Called when a Chunk is loaded or newly created by the world generator.
  */
 class ChunkLoadEvent extends ChunkEvent{
 	public function __construct(
@@ -40,6 +40,10 @@ class ChunkLoadEvent extends ChunkEvent{
 		parent::__construct($world, $chunkX, $chunkZ, $chunk);
 	}
 
+	/**
+	 * Returns whether the chunk is newly generated.
+	 * If false, the chunk was loaded from storage.
+	 */
 	public function isNewChunk() : bool{
 		return $this->newChunk;
 	}

src/event/world/ChunkPopulateEvent.php

@@ -24,7 +24,8 @@ declare(strict_types=1);
 namespace pocketmine\event\world;
 
 /**
- * Called when a Chunk is populated (after receiving it on the main thread)
+ * Called when a Chunk is fully populated by the world generator.
+ * This means that the terrain has been generated, and all artifacts (e.g. trees, grass, ponds, etc.) have been placed.
  */
 class ChunkPopulateEvent extends ChunkEvent{
 

src/event/world/ChunkUnloadEvent.php

@@ -27,7 +27,7 @@ use pocketmine\event\Cancellable;
 use pocketmine\event\CancellableTrait;
 
 /**
- * Called when a Chunk is unloaded
+ * Called when a Chunk is unloaded from memory.
  */
 class ChunkUnloadEvent extends ChunkEvent implements Cancellable{
 	use CancellableTrait;

src/event/world/WorldInitEvent.php

@@ -24,7 +24,7 @@ declare(strict_types=1);
 namespace pocketmine\event\world;
 
 /**
- * Called when a World is initializing
+ * Called when a new world is created/generated.
  */
 class WorldInitEvent extends WorldEvent{
 

src/event/world/WorldLoadEvent.php

@@ -24,7 +24,7 @@ declare(strict_types=1);
 namespace pocketmine\event\world;
 
 /**
- * Called when a World is loaded
+ * Called when a world is loaded or newly created/generated.
  */
 class WorldLoadEvent extends WorldEvent{
 

src/event/world/WorldSaveEvent.php

@@ -24,7 +24,7 @@ declare(strict_types=1);
 namespace pocketmine\event\world;
 
 /**
- * Called when a World is saved
+ * Called when a world is saved. Saving may be triggered manually (e.g. via commands) or automatically (autosave).
  */
 class WorldSaveEvent extends WorldEvent{
 

src/event/world/WorldUnloadEvent.php

@@ -27,7 +27,7 @@ use pocketmine\event\Cancellable;
 use pocketmine\event\CancellableTrait;
 
 /**
- * Called when a World is unloaded
+ * Called when a world is unloaded from memory.
  */
 class WorldUnloadEvent extends WorldEvent implements Cancellable{
 	use CancellableTrait;

src/inventory/transaction/InventoryTransaction.php

@@ -148,7 +148,7 @@ class InventoryTransaction{
 			try{
 				$action->validate($this->source);
 			}catch(TransactionValidationException $e){
-				throw new TransactionValidationException(get_class($action) . ": " . $e->getMessage(), 0, $e);
+				throw new TransactionValidationException(get_class($action) . "#" . spl_object_id($action) . ": " . $e->getMessage(), 0, $e);
 			}
 
 			if(!$action->getSourceItem()->isNull()){

src/network/mcpe/NetworkSession.php

@@ -713,6 +713,7 @@ class NetworkSession{
 	}
 
 	public function onServerRespawn() : void{
+		$this->syncAttributes($this->player, $this->player->getAttributeMap()->getAll());
 		$this->player->sendData(null);
 
 		$this->syncAdventureSettings($this->player);

src/player/Player.php

@@ -2379,6 +2379,7 @@ class Player extends Human implements CommandSender, ChunkListener, IPlayer{
 		if(parent::teleport($pos, $yaw, $pitch)){
 
 			$this->removeCurrentWindow();
+			$this->stopSleep();
 
 			$this->sendPosition($this->location, $this->location->yaw, $this->location->pitch, MovePlayerPacket::MODE_TELEPORT);
 			$this->broadcastMovement(true);
@@ -2390,7 +2391,6 @@ class Player extends Human implements CommandSender, ChunkListener, IPlayer{
 			if($this->spawnChunkLoadCount !== -1){
 				$this->spawnChunkLoadCount = 0;
 			}
-			$this->stopSleep();
 			$this->blockBreakHandler = null;
 
 			//TODO: workaround for player last pos not getting updated

src/world/Explosion.php

@@ -42,6 +42,7 @@ use pocketmine\world\utils\SubChunkExplorer;
 use pocketmine\world\utils\SubChunkExplorerStatus;
 use function ceil;
 use function floor;
+use function min;
 use function mt_rand;
 use function sqrt;
 
@@ -90,9 +91,6 @@ class Explosion{
 
 		$blockFactory = BlockFactory::getInstance();
 
-		$currentChunk = null;
-		$currentSubChunk = null;
-
 		$mRays = $this->rays - 1;
 		for($i = 0; $i < $this->rays; ++$i){
 			for($j = 0; $j < $this->rays; ++$j){
@@ -151,10 +149,8 @@ class Explosion{
 	 * and creating sounds and particles.
 	 */
 	public function explodeB() : bool{
-		$updateBlocks = [];
-
 		$source = (new Vector3($this->source->x, $this->source->y, $this->source->z))->floor();
-		$yield = (1 / $this->size) * 100;
+		$yield = min(100, (1 / $this->size) * 100);
 
 		if($this->what instanceof Entity){
 			$ev = new EntityExplodeEvent($this->what, $this->source, $this->affectedBlocks, $yield);

src/world/light/LightUpdate.php

@@ -114,6 +114,9 @@ abstract class LightUpdate{
 						$context->removalQueue->enqueue([$x, $y, $z, $oldLevel]);
 					}
 				}
+			}elseif($this->getEffectiveLight($x, $y, $z) > 0){ //outside the chunk (e.g. virtual sky light from y=256)
+				$context->spreadVisited[$blockHash] = true;
+				$context->spreadQueue->enqueue([$x, $y, $z]);
 			}
 		}
 		return $context;

tests/phpstan/configs/actual-problems.neon

@@ -635,6 +635,11 @@ parameters:
 			count: 1
 			path: ../../../src/network/mcpe/NetworkSession.php
 
+		-
+			message: "#^Cannot call method getAttributeMap\\(\\) on pocketmine\\\\player\\\\Player\\|null\\.$#"
+			count: 1
+			path: ../../../src/network/mcpe/NetworkSession.php
+
 		-
 			message: "#^Cannot call method getLanguage\\(\\) on pocketmine\\\\player\\\\Player\\|null\\.$#"
 			count: 1
@@ -690,6 +695,11 @@ parameters:
 			count: 1
 			path: ../../../src/network/mcpe/NetworkSession.php
 
+		-
+			message: "#^Parameter \\#1 \\$entity of method pocketmine\\\\network\\\\mcpe\\\\NetworkSession\\:\\:syncAttributes\\(\\) expects pocketmine\\\\entity\\\\Living, pocketmine\\\\player\\\\Player\\|null given\\.$#"
+			count: 1
+			path: ../../../src/network/mcpe/NetworkSession.php
+
 		-
 			message: "#^Parameter \\#1 \\$for of method pocketmine\\\\network\\\\mcpe\\\\NetworkSession\\:\\:syncAdventureSettings\\(\\) expects pocketmine\\\\player\\\\Player, pocketmine\\\\player\\\\Player\\|null given\\.$#"
 			count: 2
@@ -970,11 +980,6 @@ parameters:
 			count: 1
 			path: ../../../src/utils/Utils.php
 
-		-
-			message: "#^Parameter \\#2 \\$array of function array_map expects array, mixed given\\.$#"
-			count: 1
-			path: ../../../src/utils/Utils.php
-
 		-
 			message: "#^Cannot call method getFullBlock\\(\\) on pocketmine\\\\world\\\\format\\\\SubChunk\\|null\\.$#"
 			count: 1