Comment créer un système d'économie et de niveaux (level) avec Discord.js ?
Dans ce guide, vous allez ajouter à votre bot discord.js v14 un système de niveaux (level) dans lequel les membres gagnent de l'XP (points d'expérience) en écrivant des messages, ainsi qu'une économie composée de commandes de récompense quotidienne, d'envoi de coins (monnaie virtuelle du serveur) et de classement. Les données étant conservées dans SQLite, elles ne sont pas réinitialisées au redémarrage du bot ; les protections contre le farm d'XP par spam, les soldes négatifs et la perte de données sont intégrées au code.
Avant de commencer
- Un bot fonctionnel : ce guide s'appuie sur la structure du guide Comment créer un bot Discord à partir de zéro avec Discord.js v14 : le dossier
commands/,deploy-commands.js,.env,npm startetnpm run deploydoivent déjà être en place. - Node.js : utilisez la version LTS actuelle (support à long terme) ; la version actuelle du paquet
better-sqlite3exige au moins Node.js 22 (node -v). - Chemin du projet : pour éviter tout problème si le paquet doit être compilé, la documentation de better-sqlite3 demande un chemin de projet sans espaces ; des caractères spéciaux comme
%ou$peuvent aussi poser problème. Exemples de chemins adaptés :C:\bots\discord-botsous Windows,/home/bot/discord-botsous Linux. - Permissions : « Voir les salons » dans les salons où l'XP est attribuée, « Envoyer des messages » pour l'annonce de niveau, et « Gérer les rôles » (Manage Roles) pour les rôles en récompense.
- Fonctionnement continu : l'XP ne se gagne que lorsque le bot est en ligne ; il est donc logique de faire tourner le bot sur un VDS. Les offres VDS pour bot Discord sont fournies avec 4 CPU, 2–4 Go de RAM et 30–40 Go de disque NVMe.
1. Installer better-sqlite3 et préparer la base de données
Les variables sont conservées en mémoire et effacées à chaque redémarrage du bot ; l'XP et les soldes doivent donc être écrits dans une base de données. better-sqlite3 fonctionne avec un seul fichier, ne nécessite pas de serveur de base de données séparé, exécute les requêtes de manière synchrone (le résultat est renvoyé directement, sans await) et prend en charge les transactions. Dans le dossier du projet, exécutez la même commande depuis PowerShell sous Windows ou depuis une session SSH sous Linux :
npm install better-sqlite3
Le paquet est fourni précompilé pour les plateformes courantes ; la plupart des installations ne nécessitent pas d'outils de compilation. À la racine du projet, créez le fichier db.js :
const path = require('node:path');
const Database = require('better-sqlite3');
const db = new Database(path.join(__dirname, 'data.db'));
db.pragma('journal_mode = WAL');
db.exec(`CREATE TABLE IF NOT EXISTS members (
guild_id TEXT NOT NULL,
user_id TEXT NOT NULL,
xp INTEGER NOT NULL DEFAULT 0, -- progression dans le niveau actuel
level INTEGER NOT NULL DEFAULT 0,
balance INTEGER NOT NULL DEFAULT 0,
last_xp INTEGER NOT NULL DEFAULT 0, -- horodatage (ms)
last_daily INTEGER NOT NULL DEFAULT 0,
PRIMARY KEY (guild_id, user_id)
)`);
const insert = db.prepare(`INSERT INTO members (guild_id, user_id) VALUES (?, ?)
ON CONFLICT (guild_id, user_id) DO NOTHING`);
const read = db.prepare('SELECT * FROM members WHERE guild_id = ? AND user_id = ?');
// Crée la ligne si elle n'existe pas et renvoie toujours la ligne à jour
function member(guildId, userId) {
insert.run(guildId, userId);
return read.get(guildId, userId);
}
module.exports = { db, member };
Une ligne distincte est conservée pour chaque membre dans chaque serveur Discord (guild) ; les économies ne se mélangent donc pas entre serveurs. Les identifiants Discord font 64 bits et les nombres JavaScript ne peuvent pas les représenter exactement : ils sont donc stockés en TEXT. Grâce à __dirname, le même fichier data.db est utilisé quel que soit le dossier depuis lequel le bot est lancé. WAL (Write-Ahead Logging, journalisation anticipée) est le mode que la documentation recommande pour les performances ; ne supprimez pas les fichiers data.db-wal et data.db-shm créés à côté. Pour les autres options, consultez le guide Bases de données pour bots Discord : SQLite, PostgreSQL, MySQL, MongoDB.
2. Attribuer de l'XP pour les messages
À la racine du projet, créez le fichier xp.js. Si le délai d'attente est écoulé, le code ajoute au membre entre 15 et 25 XP au hasard ; lorsque l'XP atteint le seuil requiredXp(s), il déduit le seuil, fait monter le membre d'un niveau et lui verse des coins :
const { Events } = require('discord.js');
const { db, member } = require('./db');
const SETTINGS = {
xpMin: 15,
xpMax: 25,
cooldownMs: 60_000, // XP au plus une fois par minute pour un même membre
levelReward: 50, // coins versés à chaque passage de niveau
roleRewards: { 5: 'Membre actif', 10: 'Habitué' },
};
const requiredXp = (s) => 5 * s * s + 50 * s + 100;
const save = db.prepare(`UPDATE members
SET xp = ?, level = ?, balance = balance + ?, last_xp = ?
WHERE guild_id = ? AND user_id = ?`);
async function handleMessage(message) {
if (message.author.bot || !message.inGuild()) return;
const now = Date.now();
const row = member(message.guildId, message.author.id);
if (now - row.last_xp < SETTINGS.cooldownMs) return;
let xp = row.xp + SETTINGS.xpMin + Math.floor(Math.random() * (SETTINGS.xpMax - SETTINGS.xpMin + 1));
let level = row.level;
while (xp >= requiredXp(level)) {
xp -= requiredXp(level);
level++;
}
const reward = (level - row.level) * SETTINGS.levelReward;
save.run(xp, level, reward, now, message.guildId, message.author.id);
if (level === row.level) return;
await message.channel
.send(`${message.author} a atteint le niveau ${level} et gagné ${reward} coins !`)
.catch(console.error);
const roleName = SETTINGS.roleRewards[level];
const role = roleName && message.guild.roles.cache.find((r) => r.name === roleName);
if (role && message.member) await message.member.roles.add(role);
}
function xpSystem(client) {
// Une erreur de base de données ou de permission ne doit pas faire planter le bot : on la journalise
client.on(Events.MessageCreate, (message) => {
handleMessage(message).catch(console.error);
});
}
module.exports = { xpSystem, requiredXp };
index.js : ajoutez GuildMessages à la liste des intents (autorisations d'événements), puis branchez le système avant la ligne client.login :
const { xpSystem } = require('./xp');
const client = new Client({
intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages],
});
xpSystem(client);
GuildMessages n'est pas un intent privilégié (privileged). Comme nous ne lisons pas le texte des messages, MessageContent n'est pas nécessaire non plus : sans cette autorisation, l'événement de message arrive quand même, seuls les champs de contenu sont vides. L'exemple officiel de système monétaire du guide discord.js n'utilise lui aussi que Guilds et GuildMessages. Si vous ajoutez un filtre qui examine le contenu, par exemple pour ne pas attribuer d'XP aux messages courts, vous devez ajouter GatewayIntentBits.MessageContent au code et activer l'interrupteur « Message Content Intent » dans la section « Privileged Gateway Intents » de la page « Bot » du Developer Portal. Tant que l'interrupteur est désactivé, un bot qui demande cet intent ne peut pas se connecter et renvoie l'erreur [DisallowedIntents] ; les bots présents sur 100 serveurs ou plus doivent obtenir l'approbation de Discord pour cette autorisation.
Les messages des bots ne sont pas comptés et un même membre reçoit de l'XP au plus une fois par minute ; 20 messages envoyés d'affilée en une minute comptent comme un seul. Le délai d'attente étant stocké dans la base de données, il n'est pas réinitialisé au redémarrage du bot. Comme il n'y a pas de await entre la lecture et l'écriture, deux messages reçus par le même processus du bot ne peuvent pas écraser la mise à jour l'un de l'autre. Une erreur non interceptée dans un écouteur d'événements (Promise rejetée) peut arrêter le processus Node.js ; c'est pourquoi les erreurs survenant dans handleMessage sont écrites dans le log avec .catch(console.error).
3. Configurer les rôles en récompense
roleRewards associe « niveau : nom du rôle ». Créez les rôles à l'avance sur le serveur ; le bot cherche le rôle dont le nom correspond dans le cache rempli par l'intent Guilds, donc si vous renommez le rôle, mettez aussi à jour son nom dans le code. Dans la hiérarchie des permissions de Discord, le bot ne peut attribuer que les rôles situés en dessous de son propre rôle le plus élevé. Dans la liste « Rôles » des « Paramètres du serveur », placez le rôle du bot au-dessus des rôles de récompense. Le rôle n'est attribué qu'au moment où le niveau est atteint ; une récompense ajoutée plus tard à la liste n'est pas attribuée automatiquement aux membres qui ont déjà dépassé ce niveau. Plus de détails dans la documentation de Discord sur les permissions.
4. Ajouter les commandes d'économie
Le chargeur de commandes du modèle lit chaque dossier situé sous commands ; créez le dossier commands/economy. daily.js verse 100 coins toutes les 24 heures et indique au membre qui doit attendre le temps restant, dans une réponse visible de lui seul (ephemeral) :
const { SlashCommandBuilder, MessageFlags, time, TimestampStyles } = require('discord.js');
const { db, member } = require('../../db');
const DAY = 24 * 60 * 60 * 1000;
const AMOUNT = 100;
const pay = db.prepare(`UPDATE members SET balance = balance + ?, last_daily = ?
WHERE guild_id = ? AND user_id = ?`);
module.exports = {
data: new SlashCommandBuilder().setName('daily').setDescription('Donne la récompense quotidienne en coins.'),
async execute(interaction) {
if (!interaction.inGuild()) return interaction.reply('Fonctionne uniquement sur un serveur.');
const row = member(interaction.guildId, interaction.user.id);
const now = Date.now();
if (now - row.last_daily < DAY) {
const next = time(new Date(row.last_daily + DAY), TimestampStyles.RelativeTime);
return interaction.reply({ content: `Prochaine récompense : ${next}`, flags: MessageFlags.Ephemeral });
}
pay.run(AMOUNT, now, interaction.guildId, interaction.user.id);
await interaction.reply(`${AMOUNT} coins ajoutés. Solde : ${row.balance + AMOUNT}`);
},
};
send.js effectue le débit et le crédit dans une seule transaction : si la fonction lève une erreur, better-sqlite3 annule toutes les modifications. La fonction de transaction ne peut pas être async ; n'utilisez donc pas await à l'intérieur. La condition balance >= ? empêche un solde négatif au niveau de la base de données ; setMinValue(1) empêche quant à lui la saisie d'un montant nul ou négatif côté Discord.
const { SlashCommandBuilder, MessageFlags } = require('discord.js');
const { db, member } = require('../../db');
const debit = db.prepare(`UPDATE members SET balance = balance - ?
WHERE guild_id = ? AND user_id = ? AND balance >= ?`);
const credit = db.prepare('UPDATE members SET balance = balance + ? WHERE guild_id = ? AND user_id = ?');
const transfer = db.transaction((guildId, sender, recipient, amount) => {
member(guildId, recipient);
if (debit.run(amount, guildId, sender, amount).changes === 0) throw new Error('INSUFFICIENT');
credit.run(amount, guildId, recipient);
});
module.exports = {
data: new SlashCommandBuilder()
.setName('send')
.setDescription('Envoie des coins à un autre membre.')
.addUserOption((o) => o.setName('user').setDescription('Destinataire').setRequired(true))
.addIntegerOption((o) => o.setName('amount').setDescription('Montant').setRequired(true).setMinValue(1)),
async execute(interaction) {
if (!interaction.inGuild()) return interaction.reply('Fonctionne uniquement sur un serveur.');
const target = interaction.options.getUser('user');
const amount = interaction.options.getInteger('amount');
const ephemeral = (content) => interaction.reply({ content, flags: MessageFlags.Ephemeral });
if (target.bot || target.id === interaction.user.id) return ephemeral('Destinataire non valide.');
try {
transfer(interaction.guildId, interaction.user.id, target.id, amount);
} catch (e) {
if (e.message !== 'INSUFFICIENT') throw e;
return ephemeral('Votre solde est insuffisant.');
}
await interaction.reply(`${interaction.user} → ${target}: ${amount} coins`);
},
};
profile.js et leaderboard.js ont la même structure que daily.js (data et execute) ; importez db et member avec require('../../db'). profile.js lit la ligne avec member() et affiche en réponse le niveau, la progression xp/requiredXp(level) et le solde ; importez requiredXp avec require('../../xp'). leaderboard.js utilise allowedMentions: { parse: [] }, ce qui évite d'envoyer une notification aux membres de la liste :
// commands/economy/leaderboard.js – dans execute
const rows = db
.prepare(`SELECT user_id, level, balance FROM members
WHERE guild_id = ? ORDER BY level DESC, xp DESC LIMIT 10`)
.all(interaction.guildId)
.map((r, i) => `${i + 1}. <@${r.user_id}> | niveau ${r.level} | ${r.balance} coins`);
await interaction.reply({ content: rows.join('\n') || 'Aucun enregistrement pour le moment.', allowedMentions: { parse: [] } });
Enregistrez ensuite les commandes avec npm run deploy et redémarrez le bot. Plus de détails dans le guide Ajouter des commandes slash (/) avec Discord.js v14.
5. Sauvegarder la base de données
La sauvegarde automatique n'est pas incluse avec les VDS ; si data.db est perdu, tous les niveaux et tous les soldes disparaissent. Au lieu de copier le fichier en cours d'utilisation, utilisez la méthode backup() ; selon la documentation, la base de données reste utilisable pendant la sauvegarde. index.js : ajoutez la ligne const { db } = require('./db'); (fs et path sont déjà définis dans le modèle) :
// à la fin d'index.js : une sauvegarde toutes les 24 heures
const backupFolder = path.join(__dirname, 'backups');
fs.mkdirSync(backupFolder, { recursive: true });
setInterval(() => {
db.backup(path.join(backupFolder, `data-${Date.now()}.db`)).catch(console.error);
}, 24 * 60 * 60 * 1000);
La première sauvegarde est effectuée 24 heures après le démarrage du bot. Supprimez régulièrement les anciennes sauvegardes et déplacez les copies hors du serveur ; les envoyer par SFTP vers votre espace de sauvegarde cloud est une solution pratique.
Exemples de réglages et courbe de niveaux
| Réglage | Valeur d'exemple | Effet |
|---|---|---|
xpMin / xpMax | 15 / 25 | XP par message compté ; 20 en moyenne |
cooldownMs | 60000 | Au moins 1 minute entre deux gains d'XP pour un même membre |
levelReward | 50 | Coins par niveau |
AMOUNT (daily.js) | 100 | Récompense quotidienne |
requiredXp(s) | 5s² + 50s + 100 | Vitesse à laquelle le seuil augmente avec le niveau |
Avec ces valeurs, la progression du membre le plus actif, dont un message est compté chaque minute, est approximativement la suivante :
| Niveau | Seuil de la dernière étape | XP total | Messages comptés | Durée minimale |
|---|---|---|---|---|
| 1 | 100 | 100 | ≈5 | ≈5 minutes |
| 5 | 380 | 1 150 | ≈58 | ≈1 heure |
| 10 | 955 | 4 675 | ≈234 | ≈4 heures |
| 20 | 2 855 | 23 850 | ≈1 193 | ≈20 heures |
| 30 | 5 755 | 67 525 | ≈3 376 | ≈56 heures |
Sur les serveurs animés, augmentez la valeur de cooldownMs ou les coefficients ; dans les petites communautés, abaissez les seuils.
Erreurs fréquentes
- L'XP n'augmente pas du tout : si
GuildMessagesest absent de la liste des intents ou si le bot n'a pas l'autorisation de voir ce salon, l'événement de message n'arrive pas. Si les deux sont en ordre, pensez au délai d'attente : pendant les tests, un seul message par minute est compté. TypeError: db.add is not a function: les anciens exemples, y compris la version précédente de cette page, utilisent l'ancienne API synchrone de quick.db. Dans la version actuelle de quick.db, une instance se crée avecconst { QuickDB } = require('quick.db'), les méthodes exigentawaitetbetter-sqlite3s'installe séparément. Le code de ce guide n'utilise pas quick.db ; plutôt que de porter l'ancien code, il est plus simple de passer à la structure présentée ici.- L'installation de better-sqlite3 renvoie une erreur node-gyp : cette erreur survient lorsqu'aucun fichier précompilé n'est trouvé et que le paquet tente de se compiler. Vérifiez la version de Node.js (22 au minimum) et le chemin du projet. Sous Windows, supprimez
node_modulesainsi que le dossier.node-gypde votre dossier utilisateur, puis réinstallez ; si les outils de compilation manquent, exécutez le fichierinstall_tools.batdu dossier de Node.js. DiscordAPIError[50013]: Missing Permissions: si elle apparaît lors de l'attribution d'un rôle, le rôle du bot est situé sous le rôle de récompense ou le bot n'a pas l'autorisation « Gérer les rôles » ; si elle apparaît lors de l'annonce, le bot n'a pas l'autorisation d'envoyer des messages dans ce salon.- Les données ont été réinitialisées : si le chemin est indiqué en relatif (
'data.db'), un nouveau fichier vide est créé lorsque le bot est lancé depuis un autre dossier. Utilisez__dirnameet déplacez l'ancien fichier au bon endroit. SQLITE_BUSY(database is locked) ou double message de niveau : deux copies du bot tournent en même temps (par exemple l'une dans PM2, l'autre dans un terminal ouvert). SQLite n'autorise qu'un seul processus d'écriture à la fois ; fermez la copie en trop.
Questions fréquentes
quick.db, better-sqlite3 ou MongoDB ?
Pour un bot qui tourne sur un seul VDS, SQLite suffit. quick.db fonctionne lui aussi par défaut sur better-sqlite3, mais son dépôt GitHub a été archivé (lecture seule) : il ne faut donc plus attendre de nouvelle version ni de correction de bug ; pour un nouveau projet, utiliser directement better-sqlite3 est plus solide. Si vous comptez faire tourner le bot sur plusieurs machines, passez à un serveur de base de données comme PostgreSQL, MySQL ou MongoDB.
Puis-je attribuer de l'XP pour le temps passé en salon vocal ?
Oui. Ajoutez l'intent GuildVoiceStates et écoutez l'événement Events.VoiceStateUpdate : enregistrez l'heure lorsque le membre rejoint le salon, puis ajoutez de l'XP par minute lorsqu'il le quitte. Si vous conservez l'heure d'arrivée dans la base de données plutôt qu'en mémoire, la durée n'est pas perdue au redémarrage du bot.
Comment ajouter une boutique (shop) ?
products et inventory : créez ces deux tables ; lors d'un achat, effectuez le débit du solde et l'ajout à l'inventaire en une seule transaction, comme dans /send. Le guide discord.js présente, dans son exemple officiel de système monétaire, la logique de boutique avec Sequelize. Pour faire choisir le produit dans une liste, vous pouvez utiliser la structure de menu du guide Comment utiliser les boutons et les menus déroulants (select menu) dans Discord.js v14 ?.
Guides associés
- Comment créer un bot Discord à partir de zéro avec Discord.js v14
- Ajouter des commandes slash (/) avec Discord.js v14
- Bases de données pour bots Discord : SQLite, PostgreSQL, MySQL, MongoDB
- Garder un bot Discord en ligne 24 h/24, 7 j/7 sur un VDS : PM2, systemd et NSSM
- Comment utiliser les boutons et les menus déroulants (select menu) dans Discord.js v14 ?
Les autres guides sur les bots se trouvent sur la page Guides bot Discord.
Commentaires0
Pas encore de commentaire
Soyez le premier à partager votre avis.
Veuillez vous connecter ou vous inscrire pour laisser un commentaire.