- A lightweight and easy to use xp framework for discord bots, uses MongoDB.
- If you need help feel free to join our discord server to talk and help you with your code.
- If you encounter any of those fell free to open an issue in our github repository.
You can download it from npm:
npm i discord-xp
You can update to a newer version to receive updates using npm.
npm update discord-xp
-
25 August 2022 (v1.1.18):
WARNING: This version contains breaking changes in the way the package parses number input!
- The following methods now throw a TypeError if an invalid amount of xp was provided (xp is 0 or lower):
appendXp(), substractXp(), setXp()
- The following methods now throw a TypeError if an invalid amount of xp was provided (xp is 0 or lower):
-
07 August 2022 (v1.1.17):
- Adding cleanDatabase() method.
- Adding role rewards with the following methods:
createRoleReward(), deleteRoleReward(), fetchRoleReward()
-
27 May 2021 (v1.1.11):
- Adding deleteGuild() method.
-
3 April 2021 (v1.1.10):
- Adding TS typings.
-
25 February 2021 (v1.1.8):
- Preventing further deprection warnings to be displayed, if you encounter any of these deprecation issues, update the module.
-
22 November 2020 (v1.1.7):
WARNING: This semi-major version contains breaking changes in the way leaderboard computing function works.
- Added an optional
fetchPosition
argument to theLevels.fetch
which will add the leaderboard rank as theposition
property. Caution: Will be slower on larger servers. Levels.computeLeaderboard
is now asynchronous and can take in a third parameter calledfetchUsers
which will fetch all users on the leaderboard. This parameter does not require additional Gateway Intents. Caution: Will be substantially slower if you do not haveGuild_Members
intent and catch some users beforehand.
- 16 July 2020:
- Added
xpFor
method to calculate xp required for a specific level.
- Added
/* xpFor Example */
const Levels = require("discord-xp");
// Returns the xp required to reach level 30.
var xpRequired = Levels.xpFor(30);
console.log(xpRequired); // Output: 90000
First things first, we include the module into the project.
const Levels = require("discord-xp");
After that, you need to provide a valid mongo database url, and set it. You can do so by:
Levels.setURL("mongodb://..."); // You only need to do this ONCE per process.
Examples can be found in /test
createRoleReward
Creates a role reward entry in database for the guild if it doesnt exist.
Levels.createRoleReward(<GuildID - String>, <level - Number>, <roleId - String>);
- Output:
Promise<Object>
deleteRoleReward
Deletes a role reward entry in database for the guild.
Levels.deleteRoleReward(<GuildID - String>, <level - Number>);
- Output:
Promise<Object>
fetchRoleReward
Fetches a role reward entry in database for the guild.
Levels.fetchRoleReward(<GuildID - String>, <level - Number>);
- Output:
Promise<Object>
cleanDataBase
Cleans the database from unknown users for a guild.
Levels.CleanDatabase(<Client - Discord.js Client>, <GuildID - String>);
- Output:
Promise<Object>
createUser
Creates an entry in database for that user if it doesnt exist.
Levels.createUser(<UserID - String>, <GuildID - String>);
- Output:
Promise<Object>
deleteUser
If the entry exists, it deletes it from database.
Levels.deleteUser(<UserID - String>, <GuildID - String>);
- Output:
Promise<Object>
deleteGuild
If the entry exists, it deletes it from database.
Levels.deleteGuild(<GuildID - String>);
- Output:
Promise<Object>
appendXp
It adds a specified amount of xp to the current amount of xp for that user, in that guild. It re-calculates the level. It creates a new user with that amount of xp, if there is no entry for that user.
Levels.appendXp(<UserID - String>, <GuildID - String>, <Amount - Integer>);
- Output:
Promise<Boolean>
appendLevel
It adds a specified amount of levels to current amount, re-calculates and sets the xp reqired to reach the new amount of levels.
Levels.appendLevel(<UserID - String>, <GuildID - String>, <Amount - Integer>);
- Output:
Promise<Boolean/Object>
setXp
It sets the xp to a specified amount and re-calculates the level.
Levels.setXp(<UserID - String>, <GuildID - String>, <Amount - Integer>);
- Output:
Promise<Boolean/Object>
setLevel
Calculates the xp required to reach a specified level and updates it.
Levels.setLevel(<UserID - String>, <GuildID - String>, <Amount - Integer>);
- Output:
Promise<Boolean/Object>
fetch (Updated recently!)
Retrives selected entry from the database, if it exists.
Levels.fetch(<UserID - String>, <GuildID - String>, <FetchPosition - Boolean>);
- Output:
Promise<Object>
subtractXp
It removes a specified amount of xp to the current amount of xp for that user, in that guild. It re-calculates the level.
Levels.subtractXp(<UserID - String>, <GuildID - String>, <Amount - Integer>);
- Output:
Promise<Boolean/Object>
subtractLevel
It removes a specified amount of levels to current amount, re-calculates and sets the xp reqired to reach the new amount of levels.
Levels.subtractLevel(<UserID - String>, <GuildID - String>, <Amount - Number>);
- Output:
Promise<Boolean/Object>
fetchLeaderboard
It gets a specified amount of entries from the database, ordered from higgest to lowest within the specified limit of entries.
Levels.fetchLeaderboard(<GuildID - String>, <Limit - Integer>);
- Output:
Promise<Array [Objects]>
computeLeaderboard (Updated recently!)
It returns a new array of object that include level, xp, guild id, user id, leaderboard position, username and discriminator.
Levels.computeLeaderboard(<Client - Discord.js Client>, <Leaderboard - fetchLeaderboard output>, <fetchUsers - boolean, disabled by default>);
- Output:
Promise<Array [Objects]>
xpFor
It returns a number that indicates amount of xp required to reach a level based on the input.
Levels.xpFor(<TargetLevel - Integer>);
- Output:
Integer