lumisjs 1.0.0

package/src/game/LevelingSystem.js

@@ -0,0 +1,194 @@
+'use strict';
+
+class LevelingSystem {
+  /**
+   * @param {import('../client/Client')} client
+   * @param {object} [options]
+   * @param {number} [options.baseXp=500]
+   * @param {number} [options.multiplier=1.2]
+   * @param {boolean} [options.autoTrack=true]
+   * @param {number} [options.minXpPerMessage=5]
+   * @param {number} [options.maxXpPerMessage=15]
+   * @param {number} [options.cooldown=60] Cooldown in seconds
+   */
+  constructor(client, options = {}) {
+    this.client = client;
+    this.baseXp = options.baseXp ?? 500;
+    this.multiplier = options.multiplier ?? 1.2;
+    this.autoTrack = options.autoTrack !== false;
+
+    this.minXp = options.minXpPerMessage ?? 5;
+    this.maxXp = options.maxXpPerMessage ?? 15;
+    this.cooldownSec = options.cooldown ?? 60;
+
+    if (this.minXp > this.maxXp) {
+      throw new RangeError('minXpPerMessage cannot be greater than maxXpPerMessage');
+    }
+
+    // Cooldown tracked per-user with timestamps instead of a Set — prevents
+    // memory accumulation if setTimeout fires late or is cleared.
+    this._cooldowns = new Map();
+
+    if (this.autoTrack) {
+      this._boundHandler = this._handleMessage.bind(this);
+      this.client.on('messageCreate', this._boundHandler);
+    }
+  }
+
+  _key(userId) {
+    return `level_xp_${userId}`;
+  }
+
+  /**
+   * Calculate level from total XP.
+   * @param {number} totalXp
+   * @returns {number}
+   */
+  calculateLevel(totalXp) {
+    if (totalXp < 0) return 0;
+    let remaining = totalXp;
+    let level = 0;
+    let threshold = this.baseXp;
+
+    while (remaining >= threshold) {
+      remaining -= threshold;
+      level++;
+      threshold = Math.floor(threshold * this.multiplier);
+    }
+
+    return level;
+  }
+
+  /**
+   * Get the XP required to reach the next level from the given level.
+   * @param {number} currentLevel
+   * @returns {number}
+   */
+  calculateNextLevelXp(currentLevel) {
+    if (currentLevel < 0) return this.baseXp;
+    let required = this.baseXp;
+    for (let i = 0; i < currentLevel; i++) {
+      required = Math.floor(required * this.multiplier);
+    }
+    return required;
+  }
+
+  /**
+   * Get total XP needed to reach a given level from 0.
+   * @param {number} targetLevel
+   * @returns {number}
+   */
+  totalXpForLevel(targetLevel) {
+    let total = 0;
+    let threshold = this.baseXp;
+    for (let i = 0; i < targetLevel; i++) {
+      total += threshold;
+      threshold = Math.floor(threshold * this.multiplier);
+    }
+    return total;
+  }
+
+  /**
+   * Get a user's XP and level stats.
+   * @param {string} userId
+   * @returns {Promise<{ xp: number, level: number, nextLevelXp: number, progress: number }>}
+   */
+  async getUserStats(userId) {
+    if (!userId) throw new TypeError('userId is required');
+
+    const val = await this.client.cache.get(this._key(userId));
+    const xp = val ? Number(val) : 0;
+    const level = this.calculateLevel(xp);
+    const nextLevelXp = this.calculateNextLevelXp(level);
+
+    // XP within the current level
+    const levelStartXp = this.totalXpForLevel(level);
+    const progressXp = xp - levelStartXp;
+    const progress = nextLevelXp > 0 ? progressXp / nextLevelXp : 0;
+
+    return { xp, level, nextLevelXp, progressXp, progress };
+  }
+
+  /**
+   * Add XP to a user.
+   * @param {string} userId
+   * @param {number} amount
+   * @returns {Promise<{ xp: number, level: number, leveledUp: boolean }>}
+   */
+  async addXP(userId, amount) {
+    if (!userId) throw new TypeError('userId is required');
+    if (typeof amount !== 'number' || isNaN(amount) || amount < 0) {
+      throw new RangeError('amount must be a non-negative number');
+    }
+
+    const stats = await this.getUserStats(userId);
+    const newXp = stats.xp + amount;
+    const newLevel = this.calculateLevel(newXp);
+
+    await this.client.cache.set(this._key(userId), newXp);
+
+    const leveledUp = newLevel > stats.level;
+
+    if (leveledUp) {
+      const user = this.client.users.get(userId) || { id: userId };
+      this.client.emit('levelUp', user, newLevel, stats.level);
+    }
+
+    return { xp: newXp, level: newLevel, leveledUp };
+  }
+
+  /**
+   * Set a user's XP directly.
+   * @param {string} userId
+   * @param {number} xp
+   * @returns {Promise<{ xp: number, level: number }>}
+   */
+  async setXP(userId, xp) {
+    if (!userId) throw new TypeError('userId is required');
+    if (typeof xp !== 'number' || isNaN(xp) || xp < 0) {
+      throw new RangeError('xp must be a non-negative number');
+    }
+
+    await this.client.cache.set(this._key(userId), xp);
+    return { xp, level: this.calculateLevel(xp) };
+  }
+
+  /**
+   * Reset a user's XP to zero.
+   * @param {string} userId
+   */
+  async resetXP(userId) {
+    if (!userId) throw new TypeError('userId is required');
+    await this.client.cache.set(this._key(userId), 0);
+  }
+
+  /** @private */
+  async _handleMessage(message) {
+    if (!message?.author || message.author.bot) return;
+
+    const userId = message.author.id;
+    const now = Date.now();
+    const lastMessage = this._cooldowns.get(userId);
+
+    if (lastMessage && now - lastMessage < this.cooldownSec * 1000) return;
+
+    this._cooldowns.set(userId, now);
+
+    const xpEarned =
+      Math.floor(Math.random() * (this.maxXp - this.minXp + 1)) + this.minXp;
+
+    await this.addXP(userId, xpEarned);
+  }
+
+  /**
+   * Remove the message listener and clean up cooldown map.
+   */
+  destroy() {
+    if (this._boundHandler) {
+      this.client.off('messageCreate', this._boundHandler);
+    }
+    this._cooldowns.clear();
+  }
+}
+
+module.exports = LevelingSystem;