README
A flexible xp-based level system framework that uses mongoDB
This package was designed for Discord but nothing is linking it to discord directly, so if you are searching for a general xp-based level system think of guildId as a group name and userId as the individual users. (Note: guildId has to be unique, and the userId's inside that guild have to be unique as well)
Setup
npm i cronos-xp
const CronosXp = require("cronos-xp")
const Level = new CronosXp("mongoDBUrlGoesHere", {
linear: false, //Default value
xpGap: 300, //Default value
growthMultiplier: 30, //Default value
startWithZero: true, //Default value
returnDetails: false //Default value
})
Constructor Options
linear:
Defines if the leveling is linear (aka. you always need the same amount of xp for each level) or exponential (see below).
Here is an example of how it works
xpGap:
Only needed if linear is true
This value defines the xp gap between the different levels
growthMultiplier:
Only needed if linear is false
The XP needed for a level is calculated with the function ƒ(x) = g * x² where g = growthMultiplier.
(A growthMultiplier of 0 equals x, turning the function into ƒ(x) = x³)
Hint:
High growthMultiplier = rapid increase in the amount of xp needed for the next level.
Low growthMultiplier = slow increase in the amount of xp needed for the next level.
startWithZero:
Since ƒ(0) = g * 0² equals 0 the starting level would be 0.
To have it start with level 1 set this property to false.
(This changes the function to ƒ(x) = g * x² - g or ƒ(x) = x³ - x)
returnDetails:
If this option is on some functions will return more information than they normally do.
This includes:
For more information take a look at the Declaration file index.d.ts
Example
linear = true; xpGap = 500;
level 0 = "0xp"
level 1 = "500xp"
level 2 = "1,000xp"
//...
level 50 = "25,000xp"
level 51 = "25,500xp"
level 52 = "26,000xp"
//...
level 90 = "45,000xp"
level 91 = "45,500xp"
level 92 = "46,000xp"
linear = false; growthMultiplier = 20;
level 0 = "0xp"
level 1 = "20xp"
level 2 = "80xp"
//...
level 50 = "50,000xp"
level 51 = "52,020xp"
level 52 = "54,080xp"
//...
level 90 = "162,000xp"
level 91 = "165,620xp"
level 92 = "169,280xp"
Object Structure
ConstructorOptions
interface ConstructorOptions {
linear?: boolean,
xpGap?: number,
growthMultiplier?: number,
startWithZero?: boolean,
returnDetails?: boolean
}
User
interface User {
xp: number,
level: number
}
Details
interface Details {
xpDifference: number,
levelDifference: number,
nextLevelXp: number,
currentLevelXp: number
}
AddSubtractReturnObject
interface AddSubtractReturnObject {
newLevel: number,
newXp: number,
hasLevelUp?: boolean, // Exists on addXp or addLevel
hasLevelDown?: boolean, // Exists on subtractXp or subtractLevel
details?: Details // This only exists when `returnDetails` is enabled
}
XpForNextReturnObject
interface XpForNextReturnObject {
xpNeeded: number,
currentLevel: number,
nextLevel: number,
currentLevelXp: number,
nextLevelXp: number
}
Public Instance Methods
If there are any questions about the methods, their parameters, their return types or anything thing else take a look at the Declaration file index.d.ts
or just join our Discord
xpForLevel()
A method that calculates the minimum amount of xp needed for a specific level.
Level.xpForLevel(<targetLevel - number>);
// Returns <number>
levelForXp()
A method that calculates the level for a specific amount of xp.
Level.levelForXp(<targetXp - number>);
// Returns <number>
xpForNext()
A method that calculates the amount of xp needed to reach the next level based on the current xp.
If returnDetails is true this will return an object of type XpForNextReturnObject.
Level.xpForNext(<currentXp - number>);
// Returns <number> | <XpForNextReturnObject>
setXp()
A method to set the amount of xp for a specific user inside a specific guild.
Level.setXp(<guildId - string>, <userId - string>, <value - number>);
// Returns <Promise<boolean>>
setLevel()
A method to set the level for a specific user inside a specific guild.
Level.setLevel(<guildId - string>, <userId - string>, <value - number>);
// Returns <Promise<boolean>>
addXp()
A method that adds a specific amount of xp to a specific user in a specific guild. Returns object of type AddSubtractReturnObject
If returnDetails is true the returned object will have a details property that looks like this.
Level.addXp(<guildId - string>, <userId - string>, <value - number>);
// Returns <Promise<AddSubtractReturnObject>>
addLevel()
A method that adds a specific amount of level to a specific user in a specific guild. Returns object of type AddSubtractReturnObject
If returnDetails is true the returned object will have a details property that looks like this.
Level.addLevel(<guildId - string>, <userId - string>, <value - number>);
// Returns <Promise<AddSubtractReturnObject>>
subtractXp()
A method that subtracts a specific amount of xp from a specific user in a specific guild. Returns object of type AddSubtractReturnObject
If returnDetails is true the returned object will have a details property that looks like this.
Level.subtractXp(<guildId - string>, <userId - string>, <value - number>);
// Returns <Promise<AddSubtractReturnObject>>
subtractLevel()
A method that subtracts a specific amount of level from a specific user in a specific guild. Returns object of type AddSubtractReturnObject
If returnDetails is true the returned object will have a details property that looks like this.
Level.subtractLevel(<guildId - string>, <userId - string>, <value - number>);
// Returns <Promise<AddSubtractReturnObject>>
getLeaderboard()
A method that returns the top users of a guild sorted by their amount of xp.
limit is an optional parameter to change the number of users that are being returned (Default: 10).
startingAt is an optional parameter to change where the list of returned users start (Default: 0).
(If startingAt is 2 for example it will start with the third place.)
Returns an array of arrays that contain a string being the userid and, an object of type User.
Level.getLeaderboard(<guildId - string>[, <limit? - number>, <startingAt? - number>]);
// Returns <Promise<[string, User][] | boolean>>
isUser()
A method to find out if a specific user exists in a specific guild.
Level.isUser(<guildId - string>, <userId - string>);
// Returns <Promise<boolean>>
getUser()
A method to get the data of a specific user in a specific guild.
If the user exists it returns an object of type User.
Level.getUser(<guildId - string>, <userId - string>);
// Returns <Promise<User | boolean>>
getUserRank()
A method to get the Rank of a specific user in a specific guild.
If the user exists it returns his rank, otherwise it will return 0 or throw an error.
Level.getUserRank(<guildId - string>, <userId - string>);
// Returns <Promise<number>>
createUser()
A method to create a new user in a specific guild.
Level.createUser(<guildId - string>, <userId - string>);
// Returns <Promise<boolean>>
deleteUser()
A method to delete a user in a specific guild.
Level.deleteUser(<guildId - string>, <userId - string>);
// Returns <Promise<boolean>>
deleteUserGlobal()
A method to delete a user in all guilds.
Level.deleteUserGlobal(<userId - string>);
// Returns <Promise<boolean>>
resetUser()
A method to reset a users xp and level inside a specific guild.
Level.resetUser(<guildId - string>, <userId - string>);
// Returns <Promise<boolean>>
resetUserGlobal()
A method to reset a users xp and level in all guilds.
Level.resetUserGlobal(<userId - string>);
// Returns <Promise<boolean>>
isGuild()
A method to find out if a specific guild exists.
Level.isGuild(<guildId - string>);
// Returns <Promise<boolean>>
getGuild()
A method to get all users of a guild.
Returns an object that uses the userid's as the key and has their user object of type User as their value.
Level.getGuild(<guildId - string>);
// Returns <Promise<boolean | object>>
createGuild()
A method to create a new guild.
Level.createGuild(<guildId - string>);
// Returns <Promise<boolean>>
deleteGuild()
A method to delete a specific guild.
Level.deleteGuild(<guildId - string>);
// Returns <Promise<boolean>>
resetGuild()
A method to delete all users of a specific guild
Level.resetUser(<guildId - string>);
// Returns <Promise<boolean>>
destroy()
A method that closes the MongoDB connection and clears the GuildXP model.
Level.destroy();
// Returns <Promise<boolean>>
Private Static Methods
Those methods are just for validating function arguments
_validateGuildId()
Level._validateGuildId(<guildId - string | number>);
// Returns <string>
_validateUserId()
Level._validateUserId(<userId - string | number>);
// Returns <string>