discord-simple-xp v1.0.1

Discord XP System

A simple and customizable XP system for Discord bots, allowing you to track and manage user XP, levels, and more.

Installation

To use this XP system in your project, you can install it via npm:

npm install discord-simple-xp

Usage

Import the XP System

Import the XpSystem class and initialize it with your configuration.

const { XpSystem, XpMode, XpCalculationLogic } = require("discord-simple-xp");

const xpConfig = {
  initialXP: 0, // Initial XP when a user starts
  xpMode: XpMode.PER_USER, // XP mode (per user or per guild)
  xpCalculation: XpCalculationLogic.LINEAR, // XP calculation logic
  customXpCalculation: undefined, // Custom XP calculation function
  mongoUri: "mongodb://localhost:27017/mydatabase", // MongoDB URI for database connection
  defaultMultiplier: 1, // Default multiplier
};

const xpSystem = new XpSystem(xpConfig);

Basic XP Operations

You can perform basic XP operations such as adding, removing, and setting XP for users.

const { Client, Guild, User } = require('discord.js');

const user = <User>; // User object from Discord.js
const guild = <Guild>; // Guild object from Discord.js

// Add XP to a user
xpSystem.addXp(user, guild, 100);

// Remove XP from a user
xpSystem.removeXp(user, guild, 50);

// Set the XP of a user
xpSystem.setXp(user, guild, 500);

Multipliers

The XP system allows you to apply multipliers for XP gain, both at the user and server level. You can set and retrieve multipliers using the following methods:

// Set a user-specific multiplier
xpSystem.setUserMultiplier(userId, 2);

// Get the user-specific multiplier
const userMultiplier = await xpSystem.getUserMultiplier(userId);

// Set a server-specific multiplier
xpSystem.setServerMultiplier(serverId, 1.5);

// Get the server-specific multiplier
const serverMultiplier = await xpSystem.getServerMultiplier(serverId);

Custom XP Calculation

You can implement a custom XP calculation function by providing the customXpCalculation property in your configuration. This function should take the current XP as input and return the new XP.

const xpConfig = {
  // ...
  customXpCalculation: (xp) => {
    // Your custom XP calculation logic
    return xp * 2;
  },
  // ...
};

Events

The XP system emits events when users level up or when their XP changes.

xpSystem.on("levelUp", (userXP) => {
  console.log(`User ${userXP.userId} leveled up to level ${userXP.level}`);
});

xpSystem.on("xpChange", (userXP) => {
  console.log(`User ${userXP.userId} now has ${userXP.xp} XP`);
});

Customization

You can customize the XP calculation logic, initial XP, and other parameters to fit your bot's requirements. The package provides flexibility to adapt to your needs.

License

This package is open-source and available under the MIT license.

Author

Created by Sebastian Mostert