@quenty/experiencecalculator 2.0.2-canary.256.edbbcfc.0 → 2.2.0

package/CHANGELOG.md

@@ -3,7 +3,15 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [2.0.2-canary.256.edbbcfc.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/experiencecalculator@2.0.1...@quenty/experiencecalculator@2.0.2-canary.256.edbbcfc.0) (2022-03-27)
+# [2.2.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/experiencecalculator@2.1.0...@quenty/experiencecalculator@2.2.0) (2022-06-21)
+
+**Note:** Version bump only for package @quenty/experiencecalculator
+
+
+
+
+
+# [2.1.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/experiencecalculator@2.0.1...@quenty/experiencecalculator@2.1.0) (2022-03-27)
 
 **Note:** Version bump only for package @quenty/experiencecalculator
 

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2014-2021 Quenty
+Copyright (c) 2014-2022 Quenty
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/experiencecalculator",
-  "version": "2.0.2-canary.256.edbbcfc.0",
+  "version": "2.2.0",
   "description": "Calculate experience on an exponential curve and perform relevant calculations Uses formulas from stackoverflow.com/questions/6954874/php-game-formula-to-calculate-a-level-based-on-exp",
   "keywords": [
     "Roblox",
@@ -28,5 +28,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "edbbcfc38516772a791d50dc43cd6b304ffc4aff"
+  "gitHead": "c8732cc5dea767b3ff362db43137e2a16da7bc0d"
 }

package/src/Shared/ExperienceUtils.lua

@@ -0,0 +1,185 @@
+--[=[
+	Calculate experience on an exponential curve and perform relevant calculations.
+
+	Uses formulas from https://stackoverflow.com/questions/6954874/php-game-formula-to-calculate-a-level-based-on-exp
+
+	```lua
+	local config = ExperienceUtils.createExperienceConfig({
+		factor = 200;
+	})
+
+	local totalExperience = 2000
+	local level = ExperienceUtils.getLevel(config, totalExperience)
+	local percentDone = ExperienceUtils.percentLevelComplete(config, totalExperience)
+	```
+	@class ExperienceUtils
+]=]
+
+local ExperienceUtils = {}
+
+--[=[
+	Creates a new experience configuration to be used
+
+	@param options ExperienceConfig
+	@return ExperienceConfig
+]=]
+function ExperienceUtils.createExperienceConfig(options)
+	assert(type(options) == "table", "Bad options")
+
+	return {
+		factor = options.factor or 200;
+		maxLevel = options.maxLevel or math.huge;
+	}
+end
+
+--[=[
+	Returns whether a value is an experience config
+
+	@param value any
+	@return boolean
+]=]
+function ExperienceUtils.isExperienceConfig(value)
+	return type(value) == "table"
+		and type(value.factor) == "number"
+end
+
+--[=[
+	Gets the current level from experience.
+
+	@param config ExperienceConfig
+	@param totalExperience number
+	@return number -- Level
+]=]
+function ExperienceUtils.getLevel(config, totalExperience)
+	assert(ExperienceUtils.isExperienceConfig(config), "Bad experience config")
+	assert(type(totalExperience) == "number", "Bad totalExperience")
+
+	local factor = config.factor
+	local level = math.floor(
+		(factor
+			+ math.sqrt(factor*factor - 4*factor*(-totalExperience)))
+		/(2*factor))
+	if level >= config.maxLevel then
+		return config.maxLevel
+	else
+		return level
+	end
+end
+
+--[=[
+	Gets experience required for a current level. Once the experience is
+	equal to this threshold, or greater, then the level is considered
+	earned.
+
+	@param config ExperienceConfig
+	@param level number
+	@return number -- Total experience required for a level
+]=]
+function ExperienceUtils.experienceFromLevel(config, level)
+	assert(ExperienceUtils.isExperienceConfig(config), "Bad experience config")
+	assert(type(level) == "number", "Bad level")
+
+	return config.factor*level*(level - 1)
+end
+
+--[=[
+	For this level only, how much experience is earned.
+
+	@param config ExperienceConfig
+	@param totalExperience number
+	@return number
+]=]
+function ExperienceUtils.levelExperienceEarned(config, totalExperience)
+	assert(ExperienceUtils.isExperienceConfig(config), "Bad experience config")
+	assert(type(totalExperience) == "number", "Bad totalExperience")
+
+	if totalExperience ~= totalExperience then -- math.huge
+		return 0
+	end
+
+	local currentLevel = ExperienceUtils.getLevel(config, totalExperience)
+	if currentLevel >= config.maxLevel then
+		return 0
+	end
+
+	local levelExperience = ExperienceUtils.experienceFromLevel(config, currentLevel)
+
+	return totalExperience - levelExperience
+end
+
+--[=[
+	For this level only, how much experience is left to earn.
+
+	@param config ExperienceConfig
+	@param totalExperience number
+	@return number
+]=]
+function ExperienceUtils.levelExperienceLeft(config, totalExperience)
+	assert(ExperienceUtils.isExperienceConfig(config), "Bad experience config")
+	assert(type(totalExperience) == "number", "Bad totalExperience")
+
+	if totalExperience ~= totalExperience then -- math.huge
+		return 0
+	end
+
+	local currentLevel = ExperienceUtils.getLevel(config, totalExperience)
+	if currentLevel >= config.maxLevel then
+		return 0
+	end
+
+	local experienceRequired = ExperienceUtils.experienceFromLevel(config, currentLevel + 1)
+
+	return experienceRequired - totalExperience
+end
+
+--[=[
+	For this level only, how much experience is required
+
+	@param config ExperienceConfig
+	@param totalExperience number -- Current experience of player
+	@return number -- Total required for next level
+]=]
+function ExperienceUtils.levelExperienceRequired(config, totalExperience)
+	assert(ExperienceUtils.isExperienceConfig(config), "Bad experience config")
+	assert(type(totalExperience) == "number", "Bad totalExperience")
+
+	if totalExperience ~= totalExperience then -- math.huge
+		return 0
+	end
+
+	local currentLevel = ExperienceUtils.getLevel(config, totalExperience)
+	if currentLevel >= config.maxLevel then
+		return 0
+	end
+
+	local thisLevelExperience = ExperienceUtils.experienceFromLevel(config, currentLevel)
+	local nextLevelExperience = ExperienceUtils.experienceFromLevel(config, currentLevel + 1)
+	return nextLevelExperience - thisLevelExperience
+end
+
+--[=[
+	Returns the percent of the level complete
+
+	@param config ExperienceConfig
+	@param totalExperience number
+	@return number
+]=]
+function ExperienceUtils.percentLevelComplete(config, totalExperience)
+	assert(ExperienceUtils.isExperienceConfig(config), "Bad experience config")
+	assert(type(totalExperience) == "number", "Bad totalExperience")
+
+	if totalExperience ~= totalExperience then -- math.huge
+		return 0
+	end
+
+	local earned = ExperienceUtils.levelExperienceEarned(config, totalExperience)
+	local required = ExperienceUtils.levelExperienceRequired(config, totalExperience)
+
+	if required == 0 then
+		return 0
+	end
+
+	return earned/required
+end
+
+return ExperienceUtils

package/src/Shared/ExperienceUtils.spec.lua

@@ -0,0 +1,37 @@
+--[[
+	@class ExperienceUtils.spec.lua
+]]
+
+local ExperienceUtils = require(script.Parent.ExperienceUtils)
+
+return function()
+	local config = ExperienceUtils.createExperienceConfig({
+		factor = 200;
+	})
+
+	describe("ExperienceUtils.getLevel", function()
+		it("should return a level", function()
+			local level = ExperienceUtils.getLevel(config, 0)
+			expect(level).to.equal(1)
+
+			level = ExperienceUtils.getLevel(config, 399)
+			expect(level).to.equal(1)
+
+			level = ExperienceUtils.getLevel(config, 400)
+			expect(level).to.equal(2)
+		end)
+	end)
+
+	describe("ExperienceUtils.experienceFromLevel", function()
+		it("should return experience", function()
+			local experience = ExperienceUtils.experienceFromLevel(config, 1)
+			expect(experience).to.equal(0)
+
+			experience = ExperienceUtils.experienceFromLevel(config, 2)
+			expect(experience).to.equal(400)
+
+			experience = ExperienceUtils.experienceFromLevel(config, 3)
+			expect(experience).to.equal(1200)
+		end)
+	end)
+end

package/test/default.project.json

@@ -0,0 +1,11 @@
+{
+  "name": "ExperienceTest",
+  "tree": {
+    "$className": "DataModel",
+    "ServerScriptService": {
+      "experience": {
+        "$path": ".."
+      }
+    }
+  }
+}

package/src/Shared/ExperienceCalculator.lua

@@ -1,95 +0,0 @@
---[=[
-	Calculate experience on an exponential curve and perform relevant calculations.
-
-	Uses formulas from https://stackoverflow.com/questions/6954874/php-game-formula-to-calculate-a-level-based-on-exp
-
-	@class ExperienceCalculator
-]=]
-
-local ExperienceCalculator = {}
-ExperienceCalculator._experienceFactor = 200
-
---[=[
-	Sets the global experience factor to be used across this library.
-
-	:::tip
-	This API is global, poorly designed and will be refactored at some point.
-	:::
-
-	@param factor number
-]=]
-function ExperienceCalculator.setExperienceFactor(factor)
-	ExperienceCalculator._experienceFactor = factor
-end
-
---[=[
-	Gets the current level from experience.
-	@param experience number -- Current experience
-	@return number -- The level the player should be
-]=]
-function ExperienceCalculator.getLevel(experience)
-	local factor = ExperienceCalculator._experienceFactor
-	return math.floor(
-		(factor
-			+ math.sqrt(factor*factor - 4*factor*(-experience)))
-		/(2*factor))
-end
-
---[=[
-	Given a current level, return the experience required for the next one.
-	@param currentLevel number -- The current level the player is
-	@return number -- Experience required for next level
-]=]
-function ExperienceCalculator.getExperienceRequiredForNextLevel(currentLevel)
-	return ExperienceCalculator._experienceFactor*(currentLevel*(1+currentLevel))
-end
-
---[=[
-	Gets experience required for a current level.
-	@param level number
-	@return number -- Total experience required for a level
-]=]
-function ExperienceCalculator.getExperienceRequiredForLevel(level)
-	return ExperienceCalculator.getExperienceRequiredForNextLevel(level - 1)
-end
-
---[=[
-	Gets experience left to earn required for next level.
-	@param currentExperience number -- Current experience of player
-	@return number -- Experience points left to earn for the player
-]=]
-function ExperienceCalculator.getExperienceForNextLevel(currentExperience)
-	if currentExperience - 1 == currentExperience then -- math.huge
-		return 0
-	end
-
-	local currentLevel = ExperienceCalculator.getLevel(currentExperience)
-	local experienceRequired = ExperienceCalculator.getExperienceRequiredForNextLevel(currentLevel)
-
-	return experienceRequired - currentExperience
-end
-
---[=[
-	Calculates subtotal experience.
-	@param currentExperience number -- Current experience of player
-	@return number -- Achieved of next level
-	@return number -- Total required for next level
-]=]
-function ExperienceCalculator.getSubExperience(currentExperience)
-	if currentExperience - 1 == currentExperience then -- math.huge
-		return 1, 1
-	end
-
-	local currentLevel = ExperienceCalculator.getLevel(currentExperience)
-	local lastLevel = currentLevel-1
-
-	local xpForCurrentLevel = ExperienceCalculator._experienceFactor*(lastLevel*(1+lastLevel))
-	local experienceRequired = ExperienceCalculator._experienceFactor*(currentLevel*(1+currentLevel))
-
-	local achievedOfNext = currentExperience - xpForCurrentLevel
-	local subTotalRequired = experienceRequired - xpForCurrentLevel
-
-	return achievedOfNext, subTotalRequired
-end
-
-return ExperienceCalculator