Merge branch 'next-minor' into next-major

src/event/block/BlockDeathEvent.php

@@ -0,0 +1,32 @@
+<?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\block;
+
+/**
+ * Called when a block dies.
+ * This could be things like corals dying due to no water being nearby.
+ */
+class BlockDeathEvent extends BaseBlockChangeEvent{
+
+}

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;
 
@@ -42,7 +43,7 @@ class PlayerChatEvent extends PlayerEvent implements Cancellable{
 		Player $player,
 		protected string $message,
 		protected array $recipients,
-		protected string $format = "chat.type.text"
+		protected string $format = KnownTranslationKeys::CHAT_TYPE_TEXT
 	){
 		$this->player = $player;
 	}

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.
+	 *
 	 * @phpstan-return class-string<Player>
 	 */
 	public function getBaseClass() : string{
@@ -61,6 +76,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.
+	 *
 	 * @phpstan-param class-string<Player> $class
 	 */
 	public function setBaseClass(string $class) : void{
@@ -72,6 +91,8 @@ class PlayerCreationEvent extends Event{
 	}
 
 	/**
+	 * Returns the class that will be instantiated to create the player after the event.
+	 *
 	 * @phpstan-return class-string<Player>
 	 */
 	public function getPlayerClass() : string{
@@ -79,6 +100,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.
+	 *
 	 * @phpstan-param class-string<Player> $class
 	 */
 	public function setPlayerClass(string $class) : void{