Merge branch 'stable' into next-minor

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{