Merge pull request #1065 from SoyChai/experience

Expand tests for and document the Experience API

runelite-api/src/main/java/net/runelite/api/Experience.java

@@ -30,10 +30,13 @@ import static java.lang.Math.max;
 public class Experience
 {
 	/**
-	 * Maximum level under 200m xp
+	 * Maximum virtual skill level at 200m xp
 	 */
 	public static final int MAX_VIRT_LEVEL = 126;
 
+	/**
+	 * Total xp requirements of each skill level
+	 */
 	private static final int[] XP_FOR_LEVEL = new int[MAX_VIRT_LEVEL];
 
 	static
@@ -49,6 +52,12 @@ public class Experience
 		}
 	}
 
+	/**
+	 * Gets the total quantity of xp required to hit a skill level.
+	 *
+	 * @param level Level between 1 and 126 (inclusive).
+	 * @return Positive quantity of xp.
+	 */
 	public static int getXpForLevel(int level)
 	{
 		if (level < 1 || level > MAX_VIRT_LEVEL)
@@ -60,11 +69,17 @@ public class Experience
 		return XP_FOR_LEVEL[level - 1];
 	}
 
+	/**
+	 * Gets the skill level reached with a total quantity of xp.
+	 *
+	 * @param xp Positive quantity of xp.
+	 * @return Level between 1 and 126 (inclusive).
+	 */
 	public static int getLevelForXp(int xp)
 	{
 		if (xp < 0)
 		{
-			throw new IllegalArgumentException("XP must not be negative");
+			throw new IllegalArgumentException("XP (" + xp + ") must not be negative");
 		}
 
 		int low = 0;
@@ -92,6 +107,11 @@ public class Experience
 		return high + 1;
 	}
 
+	/**
+	 * Calculates a high-precision combat level without integer rounding.
+	 *
+	 * @return Combat level between 1.15 and ~126.1 (assuming non-virtual levels).
+	 */
 	public static double getCombatLevelPrecise(int attackLevel, int strengthLevel,
 		int defenceLevel, int hitpointsLevel, int magicLevel,
 		int rangeLevel, int prayerLevel)
@@ -105,6 +125,11 @@ public class Experience
 		return base + max(melee, max(range, magic));
 	}
 
+	/**
+	 * Calculates a regular combat level.
+	 *
+	 * @return Combat level between 1 and 126 (assuming non-virtual levels).
+	 */
 	public static int getCombatLevel(int attackLevel, int strengthLevel,
 		int defenceLevel, int hitpointsLevel, int magicLevel,
 		int rangeLevel, int prayerLevel)

runelite-api/src/test/java/net/runelite/api/ExperienceTest.java

@@ -30,6 +30,7 @@ import org.junit.Test;
 public class ExperienceTest
 {
 	private static final int XP_FOR_99 = 13_034_431;
+	private static final int XP_FOR_126 = 188_884_740;
 
 	@Test
 	public void testGetXpForLevel()
@@ -37,6 +38,9 @@ public class ExperienceTest
 		int xp = Experience.getXpForLevel(99);
 		Assert.assertEquals(XP_FOR_99, xp);
 
+		xp = Experience.getXpForLevel(126);
+		Assert.assertEquals(XP_FOR_126, xp);
+
 		xp = Experience.getXpForLevel(1);
 		Assert.assertEquals(0, xp);
 	}
@@ -56,22 +60,29 @@ public class ExperienceTest
 	@Test
 	public void testGetLevelForXp()
 	{
-		int level;
+		int level = Experience.getLevelForXp(XP_FOR_99);
-
-		level = Experience.getLevelForXp(XP_FOR_99);
-		Assert.assertEquals(99, level);
-
-		level = Experience.getLevelForXp(XP_FOR_99 + 1);
 		Assert.assertEquals(99, level);
 
 		level = Experience.getLevelForXp(XP_FOR_99 - 1);
 		Assert.assertEquals(98, level);
 
+		level = Experience.getLevelForXp(XP_FOR_126);
+		Assert.assertEquals(126, level);
+
+		level = Experience.getLevelForXp(XP_FOR_126 - 1);
+		Assert.assertEquals(125, level);
+
+		level = Experience.getLevelForXp(Integer.MAX_VALUE);
+		Assert.assertEquals(126, level);
+
 		level = Experience.getLevelForXp(0);
 		Assert.assertEquals(1, level);
+	}
 
-		level = Experience.getLevelForXp(200_000_000);
+	@Test(expected = IllegalArgumentException.class)
-		Assert.assertEquals(126, level);
+	public void testGetLevelForNegativeXP()
+	{
+		Experience.getLevelForXp(-1);
 	}
 
 	@Test