Human: Refactored XP API methods

src/pocketmine/entity/Human.php

@@ -24,6 +24,7 @@ declare(strict_types=1);
 namespace pocketmine\entity;
 
 use pocketmine\entity\projectile\ProjectileSource;
+use pocketmine\entity\utils\ExperienceUtils;
 use pocketmine\event\entity\EntityDamageEvent;
 use pocketmine\event\entity\EntityRegainHealthEvent;
 use pocketmine\event\player\PlayerExhaustEvent;
@@ -286,42 +287,127 @@ class Human extends Creature implements ProjectileSource, InventoryHolder{
 		return parent::consumeObject($consumable);
 	}
 
+	/**
+	 * Returns the player's experience level.
+	 * @return int
+	 */
 	public function getXpLevel() : int{
 		return (int) $this->attributeMap->getAttribute(Attribute::EXPERIENCE_LEVEL)->getValue();
 	}
 
+	/**
+	 * Sets the player's experience level. This does not affect their total XP or their XP progress.
+	 * @param int $level
+	 */
 	public function setXpLevel(int $level){
 		$this->attributeMap->getAttribute(Attribute::EXPERIENCE_LEVEL)->setValue($level);
 	}
 
+	/**
+	 * Adds a number of XP levels to the player.
+	 * @param int $amount
+	 */
+	public function addXpLevels(int $amount) : void{
+		$this->setXpLevel($this->getXpLevel() + $amount);
+	}
+
+	/**
+	 * Subtracts a number of XP levels from the player.
+	 * @param int $amount
+	 */
+	public function subtractXpLevels(int $amount) : void{
+		$this->setXpLevel($this->getXpLevel() - $amount);
+	}
+
+	/**
+	 * Returns a value between 0.0 and 1.0 to indicate how far through the current level the player is.
+	 * @return float
+	 */
 	public function getXpProgress() : float{
 		return $this->attributeMap->getAttribute(Attribute::EXPERIENCE)->getValue();
 	}
 
+	/**
+	 * Sets the player's progress through the current level to a value between 0.0 and 1.0.
+	 * @param float $progress
+	 */
 	public function setXpProgress(float $progress){
 		$this->attributeMap->getAttribute(Attribute::EXPERIENCE)->setValue($progress);
 	}
 
-	public function getTotalXp() : int{
+	/**
+	 * Returns the number of XP points the player has progressed into their current level.
+	 * @return int
+	 */
+	public function getRemainderXp() : int{
+		return (int) (ExperienceUtils::getXpToCompleteLevel($this->getXpLevel()) * $this->getXpProgress());
+	}
+
+	/**
+	 * Returns the amount of XP points the player currently has, calculated from their current level and progress
+	 * through their current level. This will be reduced by enchanting deducting levels and is used to calculate the
+	 * amount of XP the player drops on death.
+	 *
+	 * @return int
+	 */
+	public function getCurrentTotalXp() : int{
+		return ExperienceUtils::getXpToReachLevel($this->getXpLevel()) + $this->getRemainderXp();
+	}
+
+	/**
+	 * Sets the current total of XP the player has, recalculating their XP level and progress.
+	 * Note that this DOES NOT update the player's lifetime total XP.
+	 *
+	 * @param int $amount
+	 */
+	public function setCurrentTotalXp(int $amount) : void{
+		$newLevel = ExperienceUtils::getLevelFromXp($amount);
+
+		$this->setXpLevel((int) $newLevel);
+		$this->setXpProgress($newLevel - ((int) $newLevel));
+	}
+
+	/**
+	 * Adds an amount of XP to the player, recalculating their XP level and progress. XP amount will be added to the
+	 * player's lifetime XP.
+	 *
+	 * @param int $amount
+	 */
+	public function addXp(int $amount) : void{
+		$this->totalXp += $amount;
+		$this->setCurrentTotalXp($this->getCurrentTotalXp() + $amount);
+	}
+
+	/**
+	 * Takes an amount of XP from the player, recalculating their XP level and progress.
+	 * @param int $amount
+	 */
+	public function subtractXp(int $amount) : void{
+		$this->addXp(-$amount);
+	}
+
+	/**
+	 * Returns the total XP the player has collected in their lifetime. Resets when the player dies.
+	 * XP levels being removed in enchanting do not reduce this number.
+	 *
+	 * @return int
+	 */
+	public function getLifetimeTotalXp() : int{
 		return $this->totalXp;
 	}
 
-	public function getRemainderXp() : int{
-		return $this->getTotalXp() - self::getTotalXpForLevel($this->getXpLevel());
-	}
-
-	public function recalculateXpProgress() : float{
-		$this->setXpProgress($progress = $this->getRemainderXp() / self::getTotalXpForLevel($this->getXpLevel()));
-		return $progress;
-	}
-
-	public static function getTotalXpForLevel(int $level) : int{
-		if($level <= 16){
-			return $level ** 2 + $level * 6;
-		}elseif($level < 32){
-			return $level ** 2 * 2.5 - 40.5 * $level + 360;
+	/**
+	 * Sets the lifetime total XP of the player. This does not recalculate their level or progress. Used for player
+	 * score when they die. (TODO: add this when MCPE supports it)
+	 *
+	 * @param int $amount
+	 */
+	public function setLifetimeTotalXp(int $amount) : void{
+		if($amount < 0){
+			throw new \InvalidArgumentException("XP must be greater than 0");
 		}
-		return $level ** 2 * 4.5 - 162.5 * $level + 2220;
+
+		$this->totalXp = $amount;
 	}
 
 	public function getInventory(){

src/pocketmine/entity/utils/ExperienceUtils.php

@@ -0,0 +1,90 @@
+<?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\entity\utils;
+
+use pocketmine\math\Math;
+
+abstract class ExperienceUtils{
+
+	/**
+	 * Calculates and returns the amount of XP needed to get from level 0 to level $level
+	 *
+	 * @param int $level
+	 * @return int
+	 */
+	public static function getXpToReachLevel(int $level) : int{
+		if($level <= 16){
+			return $level ** 2 + $level * 6;
+		}elseif($level <= 31){
+			return (int) ($level ** 2 * 2.5 - 40.5 * $level + 360);
+		}
+
+		return (int) ($level ** 2 * 4.5 - 162.5 * $level + 2220);
+	}
+
+	/**
+	 * Returns the amount of XP needed to reach $level + 1.
+	 *
+	 * @param int $level
+	 *
+	 * @return int
+	 */
+	public static function getXpToCompleteLevel(int $level) : int{
+		if($level <= 15){
+			return 2 * $level + 7;
+		}elseif($level <= 30){
+			return 5 * $level - 38;
+		}else{
+			return 9 * $level - 158;
+		}
+	}
+
+	/**
+	 * Calculates and returns the number of XP levels the specified amount of XP points are worth.
+	 * This returns a floating-point number, the decimal part being the progress through the resulting level.
+	 *
+	 * @param int $xp
+	 *
+	 * @return float
+	 */
+	public static function getLevelFromXp(int $xp) : float{
+		if($xp <= self::getXpToReachLevel(16)){
+			$a = 1;
+			$b = 6;
+			$c = 0;
+		}elseif($xp <= self::getXpToReachLevel(31)){
+			$a = 2.5;
+			$b = -40.5;
+			$c = 360;
+		}else{
+			$a = 4.5;
+			$b = -162.5;
+			$c = 2220;
+		}
+
+		$x = Math::solveQuadratic($a, $b, $c - $xp);
+
+		return (float) max($x); //we're only interested in the positive solution
+	}
+}