To begin with, it is necessary to understand how the assignment of achievements and ranks works. When the LevelManager is instantiated, an object with options is passed to it, including ranks and achievements, which are arrays. In ranks, an object like {} or an instance of RankBuilder can be used, and the same goes for achievements but with AchievementBuilder. To create an object of RankBuilder or AchievementBuilder, their respective classes are used.

An example of how these classes and objects would look like is as follows:

const { LevelManager, RankBuilder, AchievementBuilder, AchievementType } = require('discord-xplus')

const manager = new LevelManager({
  mongoUri: 'mongodb://localhost:27017/database',
  ranks: [
    new RankBuilder()
      .setNameplate('Bronze')
      .setColor('#CD7F32')
      .setPriority(1)
      .setMin(1)
      .setMax(10),
    {
      nameplate: 'Gold',
      color: '#FFD700',
      priority: 2,
      min: 11,
      max: 20
    }
  ],
  achievements: [
    new AchievementBuilder()
      .setName('First Message')
      .setDescription("You've sent your first message!")
      .setThumbnail('https://i.imgur.com/0X2uqfT.png')
      .setReward(10)
      .setType(AchievementType.OneTime)
      .setProgress([0, 1]),
    {
      name: 'Second Message',
      description: "You've sent your second message!",
      thumbnail: 'https://i.imgur.com/0X2uqfT.png',
      reward: 10,
      type: AchievementType.OneTime,
      progress: [0, 2]
    }
  ]
})

How Ranks and Achievements Work

Ranks

Ranks are obtained when the user has a level that falls within the level range of the rank. In the above example, the Bronze rank has a minimum level of 1 and a maximum level of 10. Therefore, the user will have the Bronze rank when their level is between 1 and 10. If the user has a level greater than 10, they will have the Gold rank, as the Gold rank has a minimum level of 11 and a maximum level of 20.

The priority property determines the order of the ranks (it must be unique), as this is used to store them in the database in order.

Achievements

Achievements are obtained when the user meets the defined progress. In the above example, the First Message achievement has progress [0, 1], where the first position in the array represents the current progress and the second position represents the maximum progress. Therefore, the First Message achievement will be unlocked when the user sends one message.

It should be noted that the package provides functions for creating achievements and unlocking achievements, but it does not provide a system for obtaining achievements. For example, if you want to implement an achievement that is obtained when the user sends 100 messages, you will need to create a system that counts the user's messages and unlocks the achievement when it reaches 100 (this may change in the future, but not anytime soon).

The reward that will be given to the user upon unlocking the achievement is defined in the reward property. This value represents the XP that will be given to the user. The type of achievement is defined in the type property, which can be either AchievementType.OneTime or AchievementType.Progressive. The OneTime type is used for achievements that have a progress range of [0, 1], meaning they only require one action to be obtained. On the other hand, the Progressive type is used for achievements that have a progress range greater than 1, for example [0, 100], which requires 100 actions to be obtained.

What happens if I change my achievements after users have already earned them?

Well, if you have achievements and you change them later, users who have already earned those achievements will not lose them unless they have not unlocked them yet. For example, if you have an achievement that is earned when a user sends 100 messages and later you change it to be earned when a user sends 200 messages, users who have already earned the achievement will not lose it.