=== Experience tracking

This feature contains the ability to track experience of users on the server and award roles based on the level they reach.
The experience is awarded once per minute and is calculated by asciimath:[`\text{rand}(\text{minExp}, \text{maxExp}) * \text{expScale}`].
Currently, members only have their highest earned role assigned.

==== Necessary bot permissions
`MANAGE_ROLES` in order to award members with roles

==== Relevant system configuration
`minExp` The lower bound of the awarded base experience. Default: 10.

`maxExp` The upper bound of the awarded base experience Default: 25.

`expScale` The multiplier applied after the experience amount was determined. Default: 1.0.

`expCooldownSeconds`: The seconds between members gaining experience. Default: 60

==== Feature modes
`levelUpNotification`:: if enabled, users receive a notification when they level up. The notification can be toggled by each user individually. Disabled by default.
`levelAction`:: if enabled, enables you to perform various actions when members reach/are above levels. Disabled by default.


==== Top level slash commands:
* `experience`: These are the publicly available commands for users to check general information, and rankings
* `experienceconfig`: Configuration slash commands

==== Commands
Changing the experience scale of the server::
* Usage: `expScale <scale>`
* Slash command: `experienceconfig expscale <scale>`
* Description: Changes the value of `expScale` on this server to `value`.

Showing the current rank of a user::
* Usage: `rank [member]`
* Slash command: `experience rank [member]`
* Description: Shows the experience amount, level, message count, experience until next level, server rank and level progress of the executing user, or the user provided as a parameter.

Showing the leaderboard of the server::
* Usage: `leaderboard [page]`
* Slash command: `experience leaderboard [page]`
* Description: Shows the leaderboard of the server in a paginated format.
If no parameter is provided, it will show message count, level, experience and rank of the top 10 members.
Additionally, the same information for the executing user is shown, regardless whether the user is already shown on the given leader board page.
If a `page` is provided, it will display the leaderboard of the ranks `page * 10` until  `(page + 1) * 10` instead. If `page` is beyond the member count, the last members are shown. This also contains a button with a link leading to the leaderboard of the server (if enabled).


Setting a role to be awarded at a certain level::
* Usage: `setExpRole <level> <role>`
* Description: Sets `role` to be awarded at the given `level`. If the role was previously assigned,
this will cause to remove this assignment and recalculate the roles for all users previously having this role.
A status image indicating the progress will be shown. It will not award this role to users which qualify for this, a `syncRoles` is necessary for this.  Requires you to confirm the command.
* Example: `setExpRole 50 @HighLevel` in order to award the role `HighLevel` at level `50` (the @HighLevel is a role mention)

Syncing the roles of the members with the configuration::
* Usage: `syncExpRoles`
* Description: Recalculates the appropriate levels for all users on the server and awards the roles appropriate for the level.
There will be a message indicating the current status of the progress, and it is highly advised to not execute this command while another instance is still processing. Requires you to confirm the command.
This command can run for a longer period of time, depending on the amount of members in the guild.

Remove a role from being awarded at a certain level::
* Usage: `unSetExpRole <role>`
* Description: Removes this role from the experience tracking, removes the role from all members previously owning it and recalculates their new role according to the configuration. Requires you to confirm the command.
This will provide a status update message displaying the process.

Disable experience gain for a certain role::
* Usage: `disableExpForRole <role>`
* Slash command: `experienceconfig disableexpforrole <role>`
* Description: Disables any experience gain for members with this role. They will not gain any experience until the role is removed or it is possible for the role to gain experience again.
If a member has *any* role of the ones for which experience is disabled, the member will not gain experience. This command has a slash command

Enable experience gain for a certain role::
* Usage: `enableExpForRole <role>`
* Slash command: `experienceconfig enableexpforrole <role>`
* Description: Enables experience gain for `role`.

List roles for which experience gain is disabled::
* Usage: `listDisabledExperienceRoles`
* Slash command: `experienceconfig listdisabledexperienceroles`
* Description: Lists the roles for which experience gain is disabled in this server.
* Aliases: `lsDisEpRoles`

Disable experience gain for a specific member::
* Usage: `disableExpGain <member>`
* Slash command: `exeprienceconfig disableexpgain <member>`
* Description: Disables experience gain fpr `member`.

Enable experience gain for a specific member::
* Usage: `enableExpGain <member>`
* Slash command: `experienceconfig enableexpgain <member>`
* Description: Enables experience gain for `member`.

Show the currently configured experience roles in the server::
* Usage: `levelRoles`
* Slash command: `experience levelroles`
* Description: Shows the current configured experience roles, and the level they are awarded at.

Toggle the level up notification::
* Usage: `expLevelUpNotification <newValue>`
* Slash command: `experience explevelupnotification <newValue>`
* Description: Toggles for the executing user, if they receive level up notifications. Only `true` really enables the notification, any other value disables the notification.
* Mode Restriction: This command is only available when the feature mode `levelUpNotification` is enabled.

Add a level action::
* Usage: `addLevelAction <action> <level> <parameter> [member]`
* Slash command: `experienceconfig levelAction add <action> <level> <parameter> [member]``
* Description: Adds an `action` to be executed at `level` with the given `parameter`. If a `member` is provided, the action is restricted to be executed for only this member. The parameters `action` uses auto complete to show the currently available actions. The combination of `action`, `level` and `member` (if provided), is considered unique. If such a combination already exists, an error is shown. Each action then requires a different `parameter` passed. The actions `add_member_to_channel_above_level` and `remove_member_from_channel_above_level` require a channel mention/name/id, and `add_role_above_level` and `remove_role_above_level` require a role mention/name/id.
* Mode Restriction: This command is only available when the feature mode `levelAction` is enabled.

Viewing the current configured level actions::
* Usage: `showLevelActions`
* Slash command: `levelAction show`
* Description: Shows the currently configured level actions, this includes the level they are active at, the type of action and if
* Mode Restriction: This command is only available when the feature mode `levelAction` is enabled.

Removing a level action::
* Usage: `removeLevelAction <action> <level> [member]`
* Slash command:  `experienceconfig levelAction remove <action> <level> [member]`
* Description: Removes an action to be executed at a certain level. Such an action is identified by a combination of `action`, `level` and optionally `member`. If no identifiable combination is found, an error is shown.
* Mode Restriction: This command is only available when the feature mode `levelAction` is enabled.

==== Level actions

Level actions are custom actions, which are performed when: a member reaches a new level, a user with pre-existing experience re-joins the server. Currently these actions include: `add_member_to_channel_above_level`, `remove_member_from_channel_above_level`, `add_role_above_level` and `remove_role_above_level`. `add_member_to_channel_above_level` and `remove_member_from_channel_above_level` adds/removes the member to a configured channel once they reach the configured level. `add_role_above_level` and `remove_role_above_level` adds/removes a role from a member once they reach the configured level. All the actions which fit the current level of the user are evaluated sorted by the level they are configured for.

The actions are combined, and only the result at the end is then applied to the user. For example a rule at level 5 to add role "Test", would get nullified by a role at level 10 that removes the role "Test". The entire list of actions is evaluated for each level change, which has the effect that actions configured for a level lower than a user has only take effect once the user changes level next time.

Level actions can be an alternative way of have a completely separate list of roles awarded at varying levels, without impacting the main experience roles.