DM Rewards - a-h-i/progress-bot GitHub Wiki
Page Content
What are formulas
When a player character is rewarded xp and gold their current xp and gold are added to the rewarded value to compute the new values. What about the DMs though? Some servers implement a system for rewarding the DMs. In order to do so using this bot you will need to set reward formulas. Before we get into how to set them, let's talk about how they work.
First a formula actually consists of two things. A variable name and method of computing it. The variable name is used for storage.
Let's take a look at an example. For this example we will assume that your reward system keeps track of two things. An xp pool that a DM can use on their characters as well as a gold pool.
For calculating the xp let's say the DMs get 500 * the average player level. With an additional 2000 xp if more than 5 players were involved in the quest, they also get 10% of the rewarded xp. Additionally we will say the variable name for this formula is xp
The formula would be xpPrevious + 0.1 * rewardedXp + 500 * averageLevel + numberOfCharacters > 5 ? 2000 : 0
This is not the only way one can represent this calculation. So you may be asking what are those variables used in the formula?
Well each formula is calculated with a set of variables. They are:
| variable name | value |
|---|---|
| rewardedXp | Amount of xp rewarded per character |
| rewardedGold | Amount of gold rewarded per character |
| averageLevel | Average of characters' level prior to reward |
| averageXp | Average of characters' xp prior to reward |
| characterLevels | Array of characters' level prior to reward |
| charactersXp | Array of characters' xp prior to reward |
| extraValue | An extra value that can be passed to reward command, defaults to zero if not passed. Can be a float |
| numberOfCharacters | Number of characters involved |
You may be asking what about xpPrevious ? Well in addition to the standard set of variables provided. The previous value of the calculated (Formula's) variable is provided. If we were calculating a formula for the gold variable we would have access to goldPrevious instead. If it were to someOtherFormulaVariable it would have been someOtherFormulaVariablePrevious
A formula variable's initial value is zero.
Managing Formulas
To manage formulas we use sub commands of the config command. You must be a server admin or have one of the config roles. Refer to this guide for info on configuration roles
Listing
To list current formulas and the variables they set use $config --reward-formulas-list
Remove
To remove a formula that resolves to variable someVariable use $config --reward-formulas-remove someVariable. You can specify a list of space separated variables as well.
Define Formula
To add a formula use the command $config --reward-formulas-add someVariable someVariablePrevious + rewardedXp
That would add a formula that uses the variable someVariable to accumulate rewarded xp.
Rewarding players
Usage
$reward @Player1 Player 1 Character Name @Player2 Player 2 Character Name --xp 1200 --gold 352.12 --extra-value 2
Rewards a list of players with 1200 xp and 352.12 gold. If the extra value is omitted it will have a value of 0 when processing the formulas. You must be a server admin or have a reward role to use this command. Refer to this for help with roles.
Using DM Rewards
Once a dm has rewarded some players, they get their own Rewards if the guild has reward formulas.
Listing DM Rewards
To list your own dm rewards use $reward To list a another user's dm rewards just ping them i.e $reward @OtherUser
Note that this will list based on defined pools. Alternatively you can use $dmreward to list your rewards and $dmreward @OtherUser to list their rewards
Using DM Rewards
By using, we mean a DM with accumulated DM rewards can transfer some xp or gold to one of their characters.
A DM can use their rewards based on predefined pools.
what is a pool? A pool is simply a list of variables.
Say for example, you had two reward formulas. One is standard XP which rewards DMs say 10 percent of the rewarded xp.
This can be defined as xpPrevious + 0.1 * rewardedXp But lets say you also allow anniversary or special quests that give Bonus XP for running them. This can be defined as bonusXpPrevious + extraValue == 2 ? 2000 : 0 Which would lead you to two variables in the DM rewards table. One corresponding to xp and another to bonusXp. Lets say we want to define a pool that uses the bonusXp first then the normal xp.
We would use the command $config --reward-pool-add xp bonusXp xp. If we wanted to swap the order to use xp first then bonusXp it would have been $config --reward-pool-add xp xp bonusXp. We named the pool xp which is the first parameter. We can use any other name though.
Refer to this guide for info on configuration.
A dm can then transfer rewards from reward pools to their characters. Using the command $dmreward xp 400xp CharacterName. This says to use the reward pool named xp. To transfer 400xp to their character called CharacterName. The character must already exist. to transfer 400 gold instead you would swap the 400xp to 400gold , You might have more than one reward pool or perhaps the same pool for both xp and gold. Though no restrictions are built in.