A robust and customizable leveling system for Discord.js bots with multi-database support and beautiful rank cards.
npm install xp-flowbash
Install the core package
npm install xp-flow
Install ONE of the following database drivers
npm install sqlite3
OR
npm install mongoose
OR
npm install mysql2
`
---
š Quick Start Example
Here is a complete example of a Discord.js v14 bot using xp-flow with both message and slash commands.
See the full example code in example.js.
`javascript
// index.js (Your bot's main file)
const { Client, GatewayIntentBits, Partials, EmbedBuilder, AttachmentBuilder } = require('discord.js');
const { LevelingSystem, RankCardBuilder } = require('xp-flow');
require('dotenv').config(); // Use dotenv to manage your bot token
const client = new Client({
intents: [ / Your intents here / ]
});
// --- Database Configuration ---
// Choose ONE of the following.
const dbConfig = {
type: 'sqlite',
path: 'database.db'
};
/*
const dbConfig = {
type: 'mongodb',
uri: process.env.MONGO_URI
};
*/
/*
const dbConfig = {
type: 'mysql',
host: 'localhost',
user: 'root',
password: 'password',
database: 'my_database'
};
*/
const leveling = new LevelingSystem({
database: dbConfig,
xp: {
min: 15,
max: 25,
cooldown: 60000
}
});
client.on('ready', () => {
console.log(Bot is online as ${client.user.tag}!);
// Register slash commands here
});
// --- XP Handling on Message ---
client.on('messageCreate', async message => {
if (message.author.bot || !message.guild) return;
const xpResult = await leveling.addXp(message.author.id, message.guild.id);
if (xpResult.leveledUp) {
message.channel.send(š Congratulations, ${message.author}! You've reached level ${xpResult.newLevel}!);
}
});
// --- Command Handling ---
client.on('interactionCreate', async interaction => {
if (!interaction.isChatInputCommand()) return;
const { commandName } = interaction;
const user = interaction.options.getUser('user') || interaction.user;
if (commandName === 'rank') {
await interaction.deferReply();
const userData = await leveling.getUser(user.id, interaction.guild.id);
const leaderboard = await leveling.getLeaderboard(interaction.guild.id, 100);
const rank = leaderboard.findIndex(u => u.userId === user.id) + 1 || "N/A";
const card = new RankCardBuilder({
username: user.username,
discriminator: user.discriminator,
avatarUrl: user.displayAvatarURL({ extension: 'png' }),
status: interaction.member.presence?.status || 'offline'
})
.setLevel(userData.level)
.setRank(rank)
.setCurrentXp(userData.xp)
.setRequiredXp(leveling.xpForLevel(userData.level))
.setBackgroundColor("#2a2e35")
.setXpBarColor("#5865F2");
const imageBuffer = await leveling.createRankCard(card);
const attachment = new AttachmentBuilder(imageBuffer, { name: 'rank-card.png' });
interaction.editReply({ files: [attachment] });
}
});
client.login(process.env.BOT_TOKEN);
`
---
šØ Rank Card Customization
The RankCardBuilder makes customization incredibly simple and powerful.
`javascript
const { RankCardBuilder } = require('xp-flow');
const card = new RankCardBuilder({
username: user.username,
avatarUrl: user.displayAvatarURL({ extension: 'png' }),
discriminator: user.discriminator
})
// Set Data
.setLevel(10)
.setRank(3)
.setCurrentXp(1500)
.setRequiredXp(2500)
// Set Styles
.setBackgroundImage('https://your.domain/image.png')
.setOverlayColor('rgba(0, 0, 0, 0.7)')
.setPrimaryColor('#FFC107') // Yellow
.setXpBarColor('#FFC107')
.setStatus(member.presence?.status || 'offline'); // online, idle, dnd, offline
// To generate the card:
const imageBuffer = await leveling.createRankCard(card);
`
---
RankCardBuilder Methods
- setLevel(level): Sets the user's level.
- setRank(rank): Sets the user's rank.
- setCurrentXp(xp): Sets the user's current XP.
- setRequiredXp(xp): Sets the XP required for the next level.
- setStatus(status): Sets the status ring color (online, idle, dnd, offline).
- setBackgroundImage(url): Sets a custom background image.
- setBackgroundColor(hex): Sets the fallback background color.
- setOverlayColor(rgba): Sets the color and transparency of the main overlay.
- setPrimaryColor(hex): Sets the color for username, rank/level numbers, and XP text.
- setSecondaryColor(hex): Sets the color for the discriminator and rank/level labels.
- setXpBarColor(hex): Sets the color of the XP progress bar fill.
---
š API Reference
$3
Initializes the system.
options.database (Object): The database configuration.
- type: 'sqlite', 'mongodb', or 'mysql'.
- Other properties based on type (e.g., uri for MongoDB).
options.xp (Object, optional): XP gain configuration.
- min: Minimum XP per message.
- max: Maximum XP per message.
- cooldown: Milliseconds between XP gains.
$3
Adds XP to a user and handles level-ups.
Returns { leveledUp: boolean, newLevel: number|null }.
$3
Fetches a user's data. Creates a new user if they don't exist.
Returns { userId, guildId, xp, level }.
$3
Fetches the server's leaderboard. Returns an array of user objects sorted by rank.
$3
Takes a configured RankCardBuilder` instance and returns the image Buffer.