Typehinted up Entity API and some cleanup

src/pocketmine/event/entity/EntityArmorChangeEvent.php

@@ -23,39 +23,7 @@ declare(strict_types=1);
 
 namespace pocketmine\event\entity;
 
-use pocketmine\entity\Entity;
-use pocketmine\event\Cancellable;
-use pocketmine\item\Item;
-
-class EntityArmorChangeEvent extends EntityEvent implements Cancellable{
+class EntityArmorChangeEvent extends EntityInventoryChangeEvent{
 	public static $handlerList = null;
 
-	private $oldItem;
-	private $newItem;
-	private $slot;
-
-	public function __construct(Entity $entity, Item $oldItem, Item $newItem, $slot){
-		$this->entity = $entity;
-		$this->oldItem = $oldItem;
-		$this->newItem = $newItem;
-		$this->slot = (int) $slot;
-	}
-
-	public function getSlot(){
-		return $this->slot;
-	}
-
-	public function getNewItem(){
-		return $this->newItem;
-	}
-
-	public function setNewItem(Item $item){
-		$this->newItem = $item;
-	}
-
-	public function getOldItem(){
-		return $this->oldItem;
-	}
-
-
 }

src/pocketmine/event/entity/EntityBlockChangeEvent.php

@@ -33,7 +33,9 @@ use pocketmine\event\Cancellable;
 class EntityBlockChangeEvent extends EntityEvent implements Cancellable{
 	public static $handlerList = null;
 
+	/** @var Block */
 	private $from;
+	/** @var Block */
 	private $to;
 
 	public function __construct(Entity $entity, Block $from, Block $to){
@@ -45,14 +47,14 @@ class EntityBlockChangeEvent extends EntityEvent implements Cancellable{
 	/**
 	 * @return Block
 	 */
-	public function getBlock(){
+	public function getBlock() : Block{
 		return $this->from;
 	}
 
 	/**
 	 * @return Block
 	 */
-	public function getTo(){
+	public function getTo() : Block{
 		return $this->to;
 	}
 

src/pocketmine/event/entity/EntityCombustByBlockEvent.php

@@ -28,6 +28,7 @@ use pocketmine\entity\Entity;
 
 class EntityCombustByBlockEvent extends EntityCombustEvent{
 
+	/** @var Block */
 	protected $combuster;
 
 	/**
@@ -35,7 +36,7 @@ class EntityCombustByBlockEvent extends EntityCombustEvent{
 	 * @param Entity $combustee
 	 * @param int    $duration
 	 */
-	public function __construct(Block $combuster, Entity $combustee, $duration){
+	public function __construct(Block $combuster, Entity $combustee, int $duration){
 		parent::__construct($combustee, $duration);
 		$this->combuster = $combuster;
 	}
@@ -43,7 +44,7 @@ class EntityCombustByBlockEvent extends EntityCombustEvent{
 	/**
 	 * @return Block
 	 */
-	public function getCombuster(){
+	public function getCombuster() : Block{
 		return $this->combuster;
 	}
 

src/pocketmine/event/entity/EntityCombustByEntityEvent.php

@@ -27,6 +27,7 @@ use pocketmine\entity\Entity;
 
 class EntityCombustByEntityEvent extends EntityCombustEvent{
 
+	/** @var Entity */
 	protected $combuster;
 
 	/**
@@ -34,7 +35,7 @@ class EntityCombustByEntityEvent extends EntityCombustEvent{
 	 * @param Entity $combustee
 	 * @param int    $duration
 	 */
-	public function __construct(Entity $combuster, Entity $combustee, $duration){
+	public function __construct(Entity $combuster, Entity $combustee, int $duration){
 		parent::__construct($combustee, $duration);
 		$this->combuster = $combuster;
 	}
@@ -42,7 +43,7 @@ class EntityCombustByEntityEvent extends EntityCombustEvent{
 	/**
 	 * @return Entity
 	 */
-	public function getCombuster(){
+	public function getCombuster() : Entity{
 		return $this->combuster;
 	}
 

src/pocketmine/event/entity/EntityCombustEvent.php

@@ -35,17 +35,21 @@ class EntityCombustEvent extends EntityEvent implements Cancellable{
 	 * @param Entity $combustee
 	 * @param int    $duration
 	 */
-	public function __construct(Entity $combustee, $duration){
+	public function __construct(Entity $combustee, int $duration){
 		$this->entity = $combustee;
 		$this->duration = $duration;
 	}
 
-	public function getDuration(){
+	/**
+	 * Returns the duration in seconds the entity will burn for.
+	 * @return int
+	 */
+	public function getDuration() : int{
 		return $this->duration;
 	}
 
-	public function setDuration($duration){
-		$this->duration = (int) $duration;
+	public function setDuration(int $duration){
+		$this->duration = $duration;
 	}
 
 }

src/pocketmine/event/entity/EntityDamageByBlockEvent.php

@@ -49,7 +49,7 @@ class EntityDamageByBlockEvent extends EntityDamageEvent{
 	/**
 	 * @return Block
 	 */
-	public function getDamager(){
+	public function getDamager() : Block{
 		return $this->damager;
 	}
 

src/pocketmine/event/entity/EntityDeathEvent.php

@@ -52,7 +52,7 @@ class EntityDeathEvent extends EntityEvent{
 	/**
 	 * @return Item[]
 	 */
-	public function getDrops(){
+	public function getDrops() : array{
 		return $this->drops;
 	}
 

src/pocketmine/event/entity/EntityDespawnEvent.php

@@ -50,42 +50,42 @@ class EntityDespawnEvent extends EntityEvent{
 	/**
 	 * @return int
 	 */
-	public function getType(){
+	public function getType() : int{
 		return $this->entityType;
 	}
 
 	/**
 	 * @return bool
 	 */
-	public function isCreature(){
+	public function isCreature() : bool{
 		return $this->entity instanceof Creature;
 	}
 
 	/**
 	 * @return bool
 	 */
-	public function isHuman(){
+	public function isHuman() : bool{
 		return $this->entity instanceof Human;
 	}
 
 	/**
 	 * @return bool
 	 */
-	public function isProjectile(){
+	public function isProjectile() : bool{
 		return $this->entity instanceof Projectile;
 	}
 
 	/**
 	 * @return bool
 	 */
-	public function isVehicle(){
+	public function isVehicle() : bool{
 		return $this->entity instanceof Vehicle;
 	}
 
 	/**
 	 * @return bool
 	 */
-	public function isItem(){
+	public function isItem() : bool{
 		return $this->entity instanceof Item;
 	}
 

src/pocketmine/event/entity/EntityEatBlockEvent.php

@@ -42,6 +42,9 @@ class EntityEatBlockEvent extends EntityEatEvent{
 		return parent::getResidue();
 	}
 
+	/**
+	 * @param Block $residue
+	 */
 	public function setResidue($residue){
 		if(!($residue instanceof Block)){
 			throw new \InvalidArgumentException("Eating a Block can only result in a Block residue");

src/pocketmine/event/entity/EntityEatEvent.php

@@ -37,6 +37,7 @@ class EntityEatEvent extends EntityEvent implements Cancellable{
 	private $foodRestore;
 	/** @var float */
 	private $saturationRestore;
+	/** @var mixed */
 	private $residue;
 	/** @var Effect[] */
 	private $additionalEffects;
@@ -50,7 +51,7 @@ class EntityEatEvent extends EntityEvent implements Cancellable{
 		$this->additionalEffects = $foodSource->getAdditionalEffects();
 	}
 
-	public function getFoodSource(){
+	public function getFoodSource() : FoodSource{
 		return $this->foodSource;
 	}
 
@@ -70,10 +71,17 @@ class EntityEatEvent extends EntityEvent implements Cancellable{
 		$this->saturationRestore = $saturationRestore;
 	}
 
+	/**
+	 * Returns the result of eating the food source.
+	 * @return mixed
+	 */
 	public function getResidue(){
 		return $this->residue;
 	}
 
+	/**
+	 * @param mixed $residue
+	 */
 	public function setResidue($residue){
 		$this->residue = $residue;
 	}
@@ -81,7 +89,7 @@ class EntityEatEvent extends EntityEvent implements Cancellable{
 	/**
 	 * @return Effect[]
 	 */
-	public function getAdditionalEffects(){
+	public function getAdditionalEffects() : array{
 		return $this->additionalEffects;
 	}
 

src/pocketmine/event/entity/EntityEatItemEvent.php

@@ -39,6 +39,9 @@ class EntityEatItemEvent extends EntityEatEvent{
 		return parent::getResidue();
 	}
 
+	/**
+	 * @param Item $residue
+	 */
 	public function setResidue($residue){
 		if(!($residue instanceof Item)){
 			throw new \InvalidArgumentException("Eating an Item can only result in an Item residue");

src/pocketmine/event/entity/EntityEffectAddEvent.php

@@ -26,28 +26,43 @@ namespace pocketmine\event\entity;
 use pocketmine\entity\Effect;
 use pocketmine\entity\Entity;
 
+/**
+ * Called when an effect is added to an Entity.
+ */
 class EntityEffectAddEvent extends EntityEffectEvent{
 	public static $handlerList = null;
 
 	/** @var bool */
 	private $modify;
-	/** @var Effect */
+	/** @var Effect|null */
 	private $oldEffect;
 
-	public function __construct(Entity $entity, Effect $effect, $modify, $oldEffect){
+	/**
+	 * @param Entity      $entity
+	 * @param Effect      $effect
+	 * @param bool        $modify
+	 * @param Effect|null $oldEffect
+	 */
+	public function __construct(Entity $entity, Effect $effect, bool $modify, Effect $oldEffect = null){
 		parent::__construct($entity, $effect);
 		$this->modify = $modify;
 		$this->oldEffect = $oldEffect;
 	}
 
+	/**
+	 * Returns whether the effect addition will replace an existing effect already applied to the entity.
+	 *
+	 * TODO: isn't this pointless? An effect will only modify an existing effect if oldEffect is non-null anyway...
+	 *
+	 * @return bool
+	 */
 	public function willModify() : bool{
 		return $this->modify;
 	}
 
-	public function setWillModify(bool $modify){
-		$this->modify = $modify;
-	}
-
+	/**
+	 * @return bool
+	 */
 	public function hasOldEffect() : bool{
 		return $this->oldEffect instanceof Effect;
 	}

src/pocketmine/event/entity/EntityEffectRemoveEvent.php

@@ -23,6 +23,9 @@ declare(strict_types=1);
 
 namespace pocketmine\event\entity;
 
+/**
+ * Called when an effect is removed from an entity.
+ */
 class EntityEffectRemoveEvent extends EntityEffectEvent{
 	public static $handlerList = null;
 

src/pocketmine/event/entity/EntityEvent.php

@@ -33,6 +33,9 @@ abstract class EntityEvent extends Event{
 	/** @var Entity */
 	protected $entity;
 
+	/**
+	 * @return Entity
+	 */
 	public function getEntity(){
 		return $this->entity;
 	}

src/pocketmine/event/entity/EntityExplodeEvent.php

@@ -51,7 +51,7 @@ class EntityExplodeEvent extends EntityEvent implements Cancellable{
 	 * @param Block[]  $blocks
 	 * @param float    $yield
 	 */
-	public function __construct(Entity $entity, Position $position, array $blocks, $yield){
+	public function __construct(Entity $entity, Position $position, array $blocks, float $yield){
 		$this->entity = $entity;
 		$this->position = $position;
 		$this->blocks = $blocks;
@@ -61,14 +61,14 @@ class EntityExplodeEvent extends EntityEvent implements Cancellable{
 	/**
 	 * @return Position
 	 */
-	public function getPosition(){
+	public function getPosition() : Position{
 		return $this->position;
 	}
 
 	/**
 	 * @return Block[]
 	 */
-	public function getBlockList(){
+	public function getBlockList() : array{
 		return $this->blocks;
 	}
 
@@ -82,14 +82,14 @@ class EntityExplodeEvent extends EntityEvent implements Cancellable{
 	/**
 	 * @return float
 	 */
-	public function getYield(){
+	public function getYield() : float{
 		return $this->yield;
 	}
 
 	/**
 	 * @param float $yield
 	 */
-	public function setYield($yield){
+	public function setYield(float $yield){
 		$this->yield = $yield;
 	}
 

src/pocketmine/event/entity/EntityInventoryChangeEvent.php

@@ -27,33 +27,54 @@ use pocketmine\entity\Entity;
 use pocketmine\event\Cancellable;
 use pocketmine\item\Item;
 
+/**
+ * Called before a slot in an entity's inventory changes.
+ */
 class EntityInventoryChangeEvent extends EntityEvent implements Cancellable{
 	public static $handlerList = null;
 
+	/** @var Item */
 	private $oldItem;
+	/** @var Item */
 	private $newItem;
+	/** @var int */
 	private $slot;
 
-	public function __construct(Entity $entity, Item $oldItem, Item $newItem, $slot){
+	public function __construct(Entity $entity, Item $oldItem, Item $newItem, int $slot){
 		$this->entity = $entity;
 		$this->oldItem = $oldItem;
 		$this->newItem = $newItem;
-		$this->slot = (int) $slot;
+		$this->slot = $slot;
 	}
 
-	public function getSlot(){
+	/**
+	 * Returns the inventory slot number affected by the event.
+	 * @return int
+	 */
+	public function getSlot() : int{
 		return $this->slot;
 	}
 
-	public function getNewItem(){
+	/**
+	 * Returns the item which will be in the slot after the event.
+	 * @return Item
+	 */
+	public function getNewItem() : Item{
 		return $this->newItem;
 	}
 
+	/**
+	 * @param Item $item
+	 */
 	public function setNewItem(Item $item){
 		$this->newItem = $item;
 	}
 
-	public function getOldItem(){
+	/**
+	 * Returns the item currently in the slot.
+	 * @return Item
+	 */
+	public function getOldItem() : Item{
 		return $this->oldItem;
 	}
 

src/pocketmine/event/entity/EntityLevelChangeEvent.php

@@ -30,7 +30,9 @@ use pocketmine\level\Level;
 class EntityLevelChangeEvent extends EntityEvent implements Cancellable{
 	public static $handlerList = null;
 
+	/** @var Level */
 	private $originLevel;
+	/** @var Level */
 	private $targetLevel;
 
 	public function __construct(Entity $entity, Level $originLevel, Level $targetLevel){
@@ -39,11 +41,11 @@ class EntityLevelChangeEvent extends EntityEvent implements Cancellable{
 		$this->targetLevel = $targetLevel;
 	}
 
-	public function getOrigin(){
+	public function getOrigin() : Level{
 		return $this->originLevel;
 	}
 
-	public function getTarget(){
+	public function getTarget() : Level{
 		return $this->targetLevel;
 	}
 }

src/pocketmine/event/entity/EntityMotionEvent.php

@@ -30,6 +30,7 @@ use pocketmine\math\Vector3;
 class EntityMotionEvent extends EntityEvent implements Cancellable{
 	public static $handlerList = null;
 
+	/** @var Vector3 */
 	private $mot;
 
 	public function __construct(Entity $entity, Vector3 $mot){
@@ -40,7 +41,7 @@ class EntityMotionEvent extends EntityEvent implements Cancellable{
 	/**
 	 * @return Vector3
 	 */
-	public function getVector(){
+	public function getVector() : Vector3{
 		return $this->mot;
 	}
 

src/pocketmine/event/entity/EntityRegainHealthEvent.php

@@ -35,7 +35,9 @@ class EntityRegainHealthEvent extends EntityEvent implements Cancellable{
 	const CAUSE_CUSTOM = 3;
 	const CAUSE_SATURATION = 4;
 
+	/** @var float */
 	private $amount;
+	/** @var int */
 	private $reason;
 
 
@@ -44,27 +46,31 @@ class EntityRegainHealthEvent extends EntityEvent implements Cancellable{
 	 * @param float  $amount
 	 * @param int    $regainReason
 	 */
-	public function __construct(Entity $entity, $amount, $regainReason){
+	public function __construct(Entity $entity, float $amount, int $regainReason){
 		$this->entity = $entity;
 		$this->amount = $amount;
-		$this->reason = (int) $regainReason;
+		$this->reason = $regainReason;
 	}
 
 	/**
 	 * @return float
 	 */
-	public function getAmount(){
+	public function getAmount() : float{
 		return $this->amount;
 	}
 
 	/**
 	 * @param float $amount
 	 */
-	public function setAmount($amount){
+	public function setAmount(float $amount){
 		$this->amount = $amount;
 	}
 
-	public function getRegainReason(){
+	/**
+	 * Returns one of the CAUSE_* constants to indicate why this regeneration occurred.
+	 * @return int
+	 */
+	public function getRegainReason() : int{
 		return $this->reason;
 	}
 

src/pocketmine/event/entity/EntityShootBowEvent.php

@@ -45,7 +45,7 @@ class EntityShootBowEvent extends EntityEvent implements Cancellable{
 	 * @param Projectile $projectile
 	 * @param float      $force
 	 */
-	public function __construct(Living $shooter, Item $bow, Projectile $projectile, $force){
+	public function __construct(Living $shooter, Item $bow, Projectile $projectile, float $force){
 		$this->entity = $shooter;
 		$this->bow = $bow;
 		$this->projectile = $projectile;
@@ -62,14 +62,18 @@ class EntityShootBowEvent extends EntityEvent implements Cancellable{
 	/**
 	 * @return Item
 	 */
-	public function getBow(){
+	public function getBow() : Item{
 		return $this->bow;
 	}
 
 	/**
+	 * Returns the entity considered as the projectile in this event.
+	 *
+	 * NOTE: This might not return a Projectile if a plugin modified the target entity.
+	 *
 	 * @return Entity
 	 */
-	public function getProjectile(){
+	public function getProjectile() : Entity{
 		return $this->projectile;
 	}
 
@@ -89,14 +93,14 @@ class EntityShootBowEvent extends EntityEvent implements Cancellable{
 	/**
 	 * @return float
 	 */
-	public function getForce(){
+	public function getForce() : float{
 		return $this->force;
 	}
 
 	/**
 	 * @param float $force
 	 */
-	public function setForce($force){
+	public function setForce(float $force){
 		$this->force = $force;
 	}
 

src/pocketmine/event/entity/EntitySpawnEvent.php

@@ -51,49 +51,49 @@ class EntitySpawnEvent extends EntityEvent{
 	/**
 	 * @return Position
 	 */
-	public function getPosition(){
+	public function getPosition() : Position{
 		return $this->entity->getPosition();
 	}
 
 	/**
 	 * @return int
 	 */
-	public function getType(){
+	public function getType() : int{
 		return $this->entityType;
 	}
 
 	/**
 	 * @return bool
 	 */
-	public function isCreature(){
+	public function isCreature() : bool{
 		return $this->entity instanceof Creature;
 	}
 
 	/**
 	 * @return bool
 	 */
-	public function isHuman(){
+	public function isHuman() : bool{
 		return $this->entity instanceof Human;
 	}
 
 	/**
 	 * @return bool
 	 */
-	public function isProjectile(){
+	public function isProjectile() : bool{
 		return $this->entity instanceof Projectile;
 	}
 
 	/**
 	 * @return bool
 	 */
-	public function isVehicle(){
+	public function isVehicle() : bool{
 		return $this->entity instanceof Vehicle;
 	}
 
 	/**
 	 * @return bool
 	 */
-	public function isItem(){
+	public function isItem() : bool{
 		return $this->entity instanceof Item;
 	}
 

src/pocketmine/event/entity/EntityTeleportEvent.php

@@ -44,11 +44,12 @@ class EntityTeleportEvent extends EntityEvent implements Cancellable{
 	/**
 	 * @return Position
 	 */
-	public function getFrom(){
+	public function getFrom() : Position{
 		return $this->from;
 	}
 
 	/**
+	 * @deprecated This method has no effect or use.
 	 * @param Position $from
 	 */
 	public function setFrom(Position $from){
@@ -58,7 +59,7 @@ class EntityTeleportEvent extends EntityEvent implements Cancellable{
 	/**
 	 * @return Position
 	 */
-	public function getTo(){
+	public function getTo() : Position{
 		return $this->to;
 	}
 

src/pocketmine/event/entity/ExplosionPrimeEvent.php

@@ -32,14 +32,16 @@ use pocketmine\event\Cancellable;
 class ExplosionPrimeEvent extends EntityEvent implements Cancellable{
 	public static $handlerList = null;
 
+	/** @var float */
 	protected $force;
+	/** @var bool */
 	private $blockBreaking;
 
 	/**
 	 * @param Entity $entity
 	 * @param float  $force
 	 */
-	public function __construct(Entity $entity, $force){
+	public function __construct(Entity $entity, float $force){
 		$this->entity = $entity;
 		$this->force = $force;
 		$this->blockBreaking = true;
@@ -48,26 +50,26 @@ class ExplosionPrimeEvent extends EntityEvent implements Cancellable{
 	/**
 	 * @return float
 	 */
-	public function getForce(){
+	public function getForce() : float{
 		return $this->force;
 	}
 
-	public function setForce($force){
-		$this->force = (float) $force;
+	public function setForce(float $force){
+		$this->force = $force;
 	}
 
 	/**
 	 * @return bool
 	 */
-	public function isBlockBreaking(){
+	public function isBlockBreaking() : bool{
 		return $this->blockBreaking;
 	}
 
 	/**
 	 * @param bool $affectsBlocks
 	 */
-	public function setBlockBreaking($affectsBlocks){
-		$this->blockBreaking = (bool) $affectsBlocks;
+	public function setBlockBreaking(bool $affectsBlocks){
+		$this->blockBreaking = $affectsBlocks;
 	}
 
 }