Merge branch 'stable' into next-minor

build/php

@@ -1 +1 @@
-Subproject commit 14ed8eaadd921407c87be4964a8726b22427e80e
+Subproject commit 9353116fa8c78ed4f588b983088cabd96885286e

composer.json

@@ -54,7 +54,7 @@
       "webmozart/path-util": "^2.3"
    },
    "require-dev": {
-      "phpstan/phpstan": "1.9.1",
+      "phpstan/phpstan": "1.9.2",
       "phpstan/phpstan-phpunit": "^1.1.0",
       "phpstan/phpstan-strict-rules": "^1.2.0",
       "phpunit/phpunit": "^9.2"

src/crash/CrashDump.php

@@ -43,6 +43,7 @@ use function get_loaded_extensions;
 use function json_encode;
 use function ksort;
 use function max;
+use function mb_scrub;
 use function mb_strtoupper;
 use function microtime;
 use function ob_end_clean;
@@ -196,12 +197,14 @@ class CrashDump{
 				$error["message"] = substr($error["message"], 0, $pos);
 			}
 		}
+		$error["message"] = mb_scrub($error["message"], 'UTF-8');
 
 		if(isset($lastError)){
 			if(isset($lastError["trace"])){
 				$lastError["trace"] = Utils::printableTrace($lastError["trace"]);
 			}
 			$this->data->lastError = $lastError;
+			$this->data->lastError["message"] = mb_scrub($this->data->lastError["message"], 'UTF-8');
 		}
 
 		$this->data->error = $error;

src/event/block/BlockGrowEvent.php

@@ -23,11 +23,9 @@ declare(strict_types=1);
 
 namespace pocketmine\event\block;
 
-use pocketmine\event\Cancellable;
-
 /**
  * Called when plants or crops grow.
  */
-class BlockGrowEvent extends BaseBlockChangeEvent implements Cancellable{
+class BlockGrowEvent extends BaseBlockChangeEvent{
 
 }

src/event/player/PlayerChatEvent.php

@@ -26,6 +26,7 @@ namespace pocketmine\event\player;
 use pocketmine\command\CommandSender;
 use pocketmine\event\Cancellable;
 use pocketmine\event\CancellableTrait;
+use pocketmine\lang\KnownTranslationKeys;
 use pocketmine\player\Player;
 use pocketmine\utils\Utils;
 
@@ -47,7 +48,7 @@ class PlayerChatEvent extends PlayerEvent implements Cancellable{
 	/**
 	 * @param CommandSender[] $recipients
 	 */
-	public function __construct(Player $player, string $message, array $recipients, string $format = "chat.type.text"){
+	public function __construct(Player $player, string $message, array $recipients, string $format = KnownTranslationKeys::CHAT_TYPE_TEXT){
 		$this->player = $player;
 		$this->message = $message;
 

src/event/player/PlayerCreationEvent.php

@@ -30,7 +30,20 @@ use pocketmine\utils\Utils;
 use function is_a;
 
 /**
- * Allows the creation of players overriding the base Player class
+ * Allows the use of custom Player classes. This enables overriding built-in Player methods to change behaviour that is
+ * not possible to alter any other way.
+ *
+ * You probably don't need this event, and found your way here because you looked at some code in an old plugin that
+ * abused it (very common). Instead of using custom player classes, you should consider making session classes instead.
+ *
+ * @see https://github.com/pmmp/SessionsDemo
+ *
+ * This event is a power-user feature, and multiple plugins using it at the same time will conflict and break unless
+ * they've been designed to work together. This means that it's only usually useful in private plugins.
+ *
+ * WARNING: This should NOT be used for adding extra functions or properties. This is intended for **overriding existing
+ * core behaviour**, and should only be used if you know EXACTLY what you're doing.
+ * Custom player classes may break in any update without warning. This event isn't much more than glorified reflection.
  */
 class PlayerCreationEvent extends Event{
 
@@ -54,6 +67,8 @@ class PlayerCreationEvent extends Event{
 	}
 
 	/**
+	 * Returns the base class that the final player class must extend.
+	 *
 	 * @return string
 	 * @phpstan-return class-string<Player>
 	 */
@@ -62,6 +77,10 @@ class PlayerCreationEvent extends Event{
 	}
 
 	/**
+	 * Sets the class that the final player class must extend.
+	 * The new base class must be a subclass of the current base class.
+	 * This can (perhaps) be used to limit the options for custom player classes provided by other plugins.
+	 *
 	 * @param string $class
 	 * @phpstan-param class-string<Player> $class
 	 */
@@ -74,6 +93,8 @@ class PlayerCreationEvent extends Event{
 	}
 
 	/**
+	 * Returns the class that will be instantiated to create the player after the event.
+	 *
 	 * @return string
 	 * @phpstan-return class-string<Player>
 	 */
@@ -82,6 +103,9 @@ class PlayerCreationEvent extends Event{
 	}
 
 	/**
+	 * Sets the class that will be instantiated to create the player after the event. The class must not be abstract,
+	 * and must be an instance of the base class.
+	 *
 	 * @param string $class
 	 * @phpstan-param class-string<Player> $class
 	 */

src/inventory/Inventory.php

@@ -33,12 +33,25 @@ use pocketmine\utils\ObjectSet;
 interface Inventory{
 	public const MAX_STACK = 64;
 
+	/**
+	 * Returns the number of slots in the inventory.
+	 */
 	public function getSize() : int;
 
+	/**
+	 * Returns the maximum stack size for items in this inventory. Individual item types (such as armor or tools) may
+	 * have a smaller maximum stack size.
+	 */
 	public function getMaxStackSize() : int;
 
+	/**
+	 * Sets the maximum stack size for items in this inventory.
+	 */
 	public function setMaxStackSize(int $size) : void;
 
+	/**
+	 * Returns the item in the specified slot.
+	 */
 	public function getItem(int $index) : Item;
 
 	/**
@@ -65,10 +78,11 @@ interface Inventory{
 	public function setContents(array $items) : void;
 
 	/**
-	 * Stores the given Items in the inventory. This will try to fill
-	 * existing stacks and empty slots as well as it can.
+	 * Stores the given Items in the inventory.
+	 * This will add to any non-full existing stacks first, and then put the remaining items in empty slots if there are
+	 * any available.
 	 *
-	 * Returns the Items that did not fit.
+	 * Returns an array of items which could not fit in the inventory.
 	 *
 	 * @return Item[]
 	 */
@@ -85,15 +99,20 @@ interface Inventory{
 	public function getAddableItemQuantity(Item $item) : int;
 
 	/**
-	 * Checks if the inventory contains any Item with the same material data.
-	 * It will check id, amount, and metadata (if not null)
+	 * Returns whether the total amount of matching items is at least the stack size of the given item. Multiple stacks
+	 * of the same item are added together.
+	 *
+	 * If the input item has specific NBT, only items with the same type and NBT will match. Otherwise, only the item
+	 * type is checked.
 	 */
 	public function contains(Item $item) : bool;
 
 	/**
-	 * Will return all the Items that has the same id and metadata (if not null).
-	 * Won't check amount
-	 * The returned array is indexed by slot number.
+	 * Returns all matching items in the inventory, irrespective of stack size. The returned array is indexed by slot
+	 * number.
+	 *
+	 * If the input item has specific NBT, only items with the same type and NBT will match. Otherwise, only the item
+	 * type is checked.
 	 *
 	 * @return Item[]
 	 * @phpstan-return array<int, Item>
@@ -101,10 +120,10 @@ interface Inventory{
 	public function all(Item $item) : array;
 
 	/**
-	 * Returns the first slot number containing an item with the same ID, damage (if not any-damage), NBT (if not empty)
-	 * and count >= to the count of the specified item stack.
+	 * Returns the first slot number containing a matching item with a stack size greater than or equal to the input item.
 	 *
-	 * If $exact is true, only items with equal ID, damage, NBT and count will match.
+	 * If the input item has specific NBT, or if $exact is true, only items with the same type and NBT will match.
+	 * Otherwise, only the item type is checked.
 	 */
 	public function first(Item $item, bool $exact = false) : int;
 
@@ -119,13 +138,19 @@ interface Inventory{
 	public function isSlotEmpty(int $index) : bool;
 
 	/**
-	 * Will remove all the Items that has the same id and metadata (if not null)
+	 * Clears all slots containing items equivalent to the given item.
+	 *
+	 * If the input item has specific NBT, only items with the same type and NBT will match. Otherwise, only the item
+	 * type is checked.
 	 */
 	public function remove(Item $item) : void;
 
 	/**
-	 * Removes the given Item from the inventory.
-	 * It will return the Items that couldn't be removed.
+	 * Removes items from the inventory in the amounts specified by the given itemstacks.
+	 * Returns an array of items that couldn't be removed.
+	 *
+	 * If the input item has specific NBT, only items with the same type and NBT will match. Otherwise, only the item
+	 * type is checked.
 	 *
 	 * @return Item[]
 	 */

src/network/Network.php

@@ -54,7 +54,7 @@ class Network{
 
 	private BidirectionalBandwidthStatsTracker $bandwidthTracker;
 	private string $name;
-	private NetworkSessionManager$sessionManager;
+	private NetworkSessionManager $sessionManager;
 
 	public function __construct(
 		private \Logger $logger

src/utils/Terminal.php

@@ -166,8 +166,10 @@ abstract class Terminal{
 			case Utils::OS_LINUX:
 			case Utils::OS_MACOS:
 			case Utils::OS_BSD:
-				self::getEscapeCodes();
-				return;
+				if(getenv('TERM') !== false){
+					self::getEscapeCodes();
+					return;
+				}
 
 			case Utils::OS_WINDOWS:
 			case Utils::OS_ANDROID: