Release 4.10.2

tput requires a value for TERM, so it will generate errors if the var is
not set, as it appears not to be in PhpStorm on macOS.

changelogs/4.10.md

@@ -36,3 +36,18 @@ Released 7th November 2022.
 - Added validation for the array given to `BaseInventory->setContents()` to ensure that it contains only `Item` instances.
 - Silenced `PlayerAuthInputPacket` spam when the session is in the "spawn response" state.
 - Updated to PHPStan 1.9.
+
+# 4.10.2
+Released 25th November 2022.
+
+## Fixes
+- Fixed crashes on macOS and Linux when using console colours without the `TERM` environment variable set.
+- Fixed crashdumps not being generated when error messages contained invalid UTF-8 characters.
+
+## Documentation
+- Clarified documentation of caching behaviour for `Internet::getIP()`.
+- Added and improved documentation for many `Inventory` methods.
+- Rewritten documentation for `PlayerCreationEvent` with warnings and more detail.
+
+## Internals
+- Non-arrow projectile damage is now unscaled. Scaling according to velocity is only applied to arrows. This currently doesn't cause any observable change in behaviour, but is required for future additions.

composer.json

@@ -53,7 +53,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"

composer.lock

@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "e2b0a5b76ace05c6d6bd760d1f96ebe5",
+    "content-hash": "9d5a8688ca7ac8143921659525641a00",
     "packages": [
         {
             "name": "adhocore/json-comment",
@@ -536,16 +536,16 @@
         },
         {
             "name": "pocketmine/locale-data",
-            "version": "2.9.2",
+            "version": "2.9.3",
             "source": {
                 "type": "git",
                 "url": "https://github.com/pmmp/Language.git",
-                "reference": "8813ffd2a4501521ca9433c534f3009f941de136"
+                "reference": "73db4397b4150b29819bf39cc371924cc2e3f502"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/pmmp/Language/zipball/8813ffd2a4501521ca9433c534f3009f941de136",
-                "reference": "8813ffd2a4501521ca9433c534f3009f941de136",
+                "url": "https://api.github.com/repos/pmmp/Language/zipball/73db4397b4150b29819bf39cc371924cc2e3f502",
+                "reference": "73db4397b4150b29819bf39cc371924cc2e3f502",
                 "shasum": ""
             },
             "type": "library",
@@ -553,9 +553,9 @@
             "description": "Language resources used by PocketMine-MP",
             "support": {
                 "issues": "https://github.com/pmmp/Language/issues",
-                "source": "https://github.com/pmmp/Language/tree/2.9.2"
+                "source": "https://github.com/pmmp/Language/tree/2.9.3"
             },
-            "time": "2022-10-21T20:30:38+00:00"
+            "time": "2022-11-12T13:59:25+00:00"
         },
         {
             "name": "pocketmine/log",
@@ -1022,16 +1022,16 @@
         },
         {
             "name": "symfony/polyfill-php81",
-            "version": "v1.26.0",
+            "version": "v1.27.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/symfony/polyfill-php81.git",
-                "reference": "13f6d1271c663dc5ae9fb843a8f16521db7687a1"
+                "reference": "707403074c8ea6e2edaf8794b0157a0bfa52157a"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/symfony/polyfill-php81/zipball/13f6d1271c663dc5ae9fb843a8f16521db7687a1",
-                "reference": "13f6d1271c663dc5ae9fb843a8f16521db7687a1",
+                "url": "https://api.github.com/repos/symfony/polyfill-php81/zipball/707403074c8ea6e2edaf8794b0157a0bfa52157a",
+                "reference": "707403074c8ea6e2edaf8794b0157a0bfa52157a",
                 "shasum": ""
             },
             "require": {
@@ -1040,7 +1040,7 @@
             "type": "library",
             "extra": {
                 "branch-alias": {
-                    "dev-main": "1.26-dev"
+                    "dev-main": "1.27-dev"
                 },
                 "thanks": {
                     "name": "symfony/polyfill",
@@ -1081,7 +1081,7 @@
                 "shim"
             ],
             "support": {
-                "source": "https://github.com/symfony/polyfill-php81/tree/v1.26.0"
+                "source": "https://github.com/symfony/polyfill-php81/tree/v1.27.0"
             },
             "funding": [
                 {
@@ -1097,7 +1097,7 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2022-05-24T11:49:31+00:00"
+            "time": "2022-11-03T14:55:06+00:00"
         },
         {
             "name": "webmozart/assert",
@@ -1341,16 +1341,16 @@
         },
         {
             "name": "nikic/php-parser",
-            "version": "v4.15.1",
+            "version": "v4.15.2",
             "source": {
                 "type": "git",
                 "url": "https://github.com/nikic/PHP-Parser.git",
-                "reference": "0ef6c55a3f47f89d7a374e6f835197a0b5fcf900"
+                "reference": "f59bbe44bf7d96f24f3e2b4ddc21cd52c1d2adbc"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/0ef6c55a3f47f89d7a374e6f835197a0b5fcf900",
-                "reference": "0ef6c55a3f47f89d7a374e6f835197a0b5fcf900",
+                "url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/f59bbe44bf7d96f24f3e2b4ddc21cd52c1d2adbc",
+                "reference": "f59bbe44bf7d96f24f3e2b4ddc21cd52c1d2adbc",
                 "shasum": ""
             },
             "require": {
@@ -1391,9 +1391,9 @@
             ],
             "support": {
                 "issues": "https://github.com/nikic/PHP-Parser/issues",
-                "source": "https://github.com/nikic/PHP-Parser/tree/v4.15.1"
+                "source": "https://github.com/nikic/PHP-Parser/tree/v4.15.2"
             },
-            "time": "2022-09-04T07:30:47+00:00"
+            "time": "2022-11-12T15:38:23+00:00"
         },
         {
             "name": "phar-io/manifest",
@@ -1508,16 +1508,16 @@
         },
         {
             "name": "phpstan/phpstan",
-            "version": "1.9.1",
+            "version": "1.9.2",
             "source": {
                 "type": "git",
                 "url": "https://github.com/phpstan/phpstan.git",
-                "reference": "a59c8b5bfd4a236f27efc8b5ce72c313c2b54b5f"
+                "reference": "d6fdf01c53978b6429f1393ba4afeca39cc68afa"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/phpstan/phpstan/zipball/a59c8b5bfd4a236f27efc8b5ce72c313c2b54b5f",
-                "reference": "a59c8b5bfd4a236f27efc8b5ce72c313c2b54b5f",
+                "url": "https://api.github.com/repos/phpstan/phpstan/zipball/d6fdf01c53978b6429f1393ba4afeca39cc68afa",
+                "reference": "d6fdf01c53978b6429f1393ba4afeca39cc68afa",
                 "shasum": ""
             },
             "require": {
@@ -1547,7 +1547,7 @@
             ],
             "support": {
                 "issues": "https://github.com/phpstan/phpstan/issues",
-                "source": "https://github.com/phpstan/phpstan/tree/1.9.1"
+                "source": "https://github.com/phpstan/phpstan/tree/1.9.2"
             },
             "funding": [
                 {
@@ -1563,7 +1563,7 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2022-11-04T13:35:59+00:00"
+            "time": "2022-11-10T09:56:11+00:00"
         },
         {
             "name": "phpstan/phpstan-phpunit",
@@ -1667,16 +1667,16 @@
         },
         {
             "name": "phpunit/php-code-coverage",
-            "version": "9.2.18",
+            "version": "9.2.19",
             "source": {
                 "type": "git",
                 "url": "https://github.com/sebastianbergmann/php-code-coverage.git",
-                "reference": "12fddc491826940cf9b7e88ad9664cf51f0f6d0a"
+                "reference": "c77b56b63e3d2031bd8997fcec43c1925ae46559"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/sebastianbergmann/php-code-coverage/zipball/12fddc491826940cf9b7e88ad9664cf51f0f6d0a",
-                "reference": "12fddc491826940cf9b7e88ad9664cf51f0f6d0a",
+                "url": "https://api.github.com/repos/sebastianbergmann/php-code-coverage/zipball/c77b56b63e3d2031bd8997fcec43c1925ae46559",
+                "reference": "c77b56b63e3d2031bd8997fcec43c1925ae46559",
                 "shasum": ""
             },
             "require": {
@@ -1732,7 +1732,7 @@
             ],
             "support": {
                 "issues": "https://github.com/sebastianbergmann/php-code-coverage/issues",
-                "source": "https://github.com/sebastianbergmann/php-code-coverage/tree/9.2.18"
+                "source": "https://github.com/sebastianbergmann/php-code-coverage/tree/9.2.19"
             },
             "funding": [
                 {
@@ -1740,7 +1740,7 @@
                     "type": "github"
                 }
             ],
-            "time": "2022-10-27T13:35:33+00:00"
+            "time": "2022-11-18T07:47:47+00:00"
         },
         {
             "name": "phpunit/php-file-iterator",

src/VersionInfo.php

@@ -32,7 +32,7 @@ use function str_repeat;
 final class VersionInfo{
 	public const NAME = "PocketMine-MP";
 	public const BASE_VERSION = "4.10.2";
-	public const IS_DEVELOPMENT_BUILD = true;
+	public const IS_DEVELOPMENT_BUILD = false;
 	public const BUILD_CHANNEL = "stable";
 
 	private function __construct(){

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: