THEGAMER20081 / discord-leveling-super

Easy and customizable leveling framework for your Discord bot.

Discord Leveling Super

Discord Leveling Super - Easy and customizable leveling framework for your Discord Bot.

Install

Please note:
Node.js 14.0.0 or newer is required.
All types in brackets mean the type of what the method or event returns.

npm i discord-leveling-super

Table of Contents

• Example Usage
• Constructor Options
• Module Methods
• Module Properties
• Module Events
• Changelog
• Useful Links

Example Usage

Before we start, I will show you a simple example usage for this module.

const { Client, Intents } = require('discord.js') // npm i discord.js
const bot = new Client({
    partials: ['CHANNEL', 'GUILD_MEMBER', 'MESSAGE', 'REACTION', 'USER'], 
    ws: {
        intents: Intents.ALL 
    } 
});

const botPrefix = '!';
const Leveling = require('discord-leveling-super');
const leveling = new Leveling(bot, {
    storagePath: './leveling.json', // Full path to a JSON file. Default: './leveling.json'.
    checkStorage: true, // Checks the if database file exists and if it has errors. Default: true.
    xp: 5, // Amount of XP that user will receive after sending a message. Default: 5.
    maxXP: 300, // Amount of XP that user will need to reach the next level. This value will double for each level. Default: 300.
    status: true, // You can enable or disable the leveling system using this option. Default: true.
    lockedChannels: [], // Array of channel IDs that won't give XP to users. Default: [].
    filter: msg => !msg.content.startsWith(botPrefix), // Callback function that accepts amessage, it must return a boolean value and it will add XP only to authors of filtered messages.; Use 'null' to disable the filter. Default: null.
    updater: {
        checkUpdates: true, // Sends the update state message in console on start. Default: true.
        upToDateMessage: true // Sends the message in console on start if module is up to date. Default: true.
    },
    errorHandler: {
        handleErrors: true, // Handles all errors on start. Default: true.
        attempts: 5, // Amount of attempts to load the module. Use 'null' for infinity attempts. Default: 5.
        time: 3000 // Time between every attempt to start the module. Default: 3000.
    }
});

leveling.on('levelUp', data => {
    data.sendMessage(`Congrats, ${data.user}, you just reached the level **${data.level}**!`)
})

bot.on('ready', () => {
  console.log(`${bot.user.tag} is ready!`);
});

bot.login('token') // https://discord.com/developers/applications

Now, let's start!

Constructor Options

Please note:
This module requires a Discord Bot Client as the first parameter. Options object is the seconds one.

• options.storagePath: Full path to a JSON file. Default: './storage.json.' (String)
• options.checkStorage: Checks for if database file exists and if it has errors. Default: true. (Boolean)
• options.updateCountdown: Checks for if storage file exists in specified time (in ms). Default: 1000. (Number)
• options.xp: Amount of XP that user will receive after sending a message. Default: 5. (Number)
• options.maxXP: Amount of XP that user will totally need to reach the next level. This value will double for each level. Default: 300. (Number)
• options.status: You can enable or disable the leveling system using this option. Default: true. (Boolean)
• options.lockedChannels: Array of channel IDs that won't give XP to users. Default: []. (Array)
• options.filter: Callback function that accepts amessage, it must return a boolean value and it will add XP only to authors of filtered messages.; Use 'null' to disable the filter. Default: null. (Function)
• options.updater: Update Checker options object:
  • options.updater.checkUpdates.: Sends the update state message in console on start. Default: true. (Boolean)
  • options.updater.upToDateMessage: Sends the message in console on start if module is up to date. Default: true. (Boolean)
• options.errorHandler: Error Handler options object:
  • options.errorHandler.handleErrors.: Handles all errors on startup. Default: true. (Boolean)
  • options.errorHandler.attempts: Amount of attempts to load the module. Use 'null' for infinity attempts. Default: 5. (Number)
  • options.errorHandler.time: Time between every attempt to start the module. Default: 3000. (Number)

Once the module starts, the update checker will show you a beautiful message in your console!

Module Methods

• rank(memberID, guildID): Fetches the user's rank. (Object)
• leaderboard(guildID): Returns a leaderboard array. (Array)


• setLevel(level, memberID, guildID): Sets the level to specified user. (Object)
• addLevel(level, memberID, guildID): Adds the level to specified user. (Object)


• setXP(xp, memberID, guildID): Sets the XP to specified user. (Object)
• addXP(xp, memberID, guildID): Adds the XP to specified user. (Object)


• setTotalXP(xp, memberID, guildID): Sets the total XP to specified user. (Object)
• addTotalXP(xp, memberID, guildID): Adds the total XP to specified user. (Object)


• all(): Returns the database contents. (Object)
• checkUpdates(): Checks for if the module is up to date. Returns a promise with data object. (Promise: Object)


• removeGuild(guildID): Fully removes the guild from database. (Boolean)
• removeUser(memberID, guildID): Removes the user from database. (Boolean)


• clearStorage(): Clears the storage file. (Boolean)
• kill(): Kills the Leveling instance. (Leveling Instance)
• init(): Starts the module. (Promise: Boolean)

Module Properties

• Leveling.version: Returns the module version. (Boolean)
• Leveling.options: Returns the options object that you put in the Constructor (Object)
• Leveling.LevelingError: Returns the error class that this module is using. (Class)
• Leveling.ready: Module ready status. (Boolean)
• Leveling.errored: Module errored status. (Boolean)
• Leveling.interval: Database checking interval. (NodeJS.Timeout)
• Leveling.errors: Module errors object. (Object)

Module Events

• Leveling.on('levelUp'): Emits when someone's reached a new level.
• Leveling.on('setLevel'): Emits when you set the level to someone.
• Leveling.on('addLevel'): Emits when you add levels to someone.
• Leveling.on('setXP'): Emits when you set the XP to someone.
• Leveling.on('addXP'): Emits when you add the XP to someone.
• Leveling.on('setTotalXP'): Emits when you set the total XP to someone.
• Leveling.on('addTotalXP'): Emits when you add the total XP to someone.

Changelog

1.0.0

• The first version of the module: added leveling methods, events, LevelingError class and type defenitions.

1.0.1

• Code optimization.
• Fixed typos.

1.0.2

• Code optimization.
• Fixed typos.
• Fixed bugs.
• Added an events example, updated and fixed other examples.
• Now every event is returning a guild ID and user ID with other properties and 'levelUp' event is also returns a guild ID.

Useful Links

• NPM
• Github
• Examples
• Discord Server

If you found a bug, please send it in Discord to ShadowPlay#9706.
If you have any questions or need help, join the Support Server.
Module Created by ShadowPlay.

Thanks for using Discord Leveling Super ♥