DiscordRewards 2.0.3

This plugin requires the Discord extension -> https://umod.org/extensions/discord
This plugin requires the Chaos extension -> https://chaoscode.io/resources/chaos.321/

The current version of DiscordRewards requires Oxide.Ext.Discord v3.x.x+.
If you are not running that version of the extension you can download DiscordRewards v2.0.2 from the history tab which uses the Oxide.Ext.Discord v2.x.x


Reward players with items, kits and commands for being a member of your Discord



Features
- Users claim a token via chat command which they then DM to your bot in Discord, or post in a specific channel of your Discord guild to gain access to the reward store
- Set re-validation times so users must regularly validate via your discord to continue receiving rewards
- Give players groups and permissions when validated, and remove them when the re-validation period has expired
- Give or remove players roles in your Discord when validated, and remove/add them when the re-validation period has expired
- Run commands when a user has been validated
- Give users token upon validation/revalidation which they can use to purchase rewards via the reward store, or disable it and only give groups/permissions or run commands
- Option for additional rewards for Nitro Boosters
- Add as many or as little items, kits and commands to the reward store as you want
- Set cool down times for each reward or use a global cool down that affects all rewards, which allows users to either select 1 reward at a time, or have access to multiple rewards
- Set a custom status message for your bot


Using the plugin
Users can sync their account by typing /discord in chat.
They will be prompted to verify using a unique 6 digit code which they must either DM to the bot, or post in a specified validation channel in your Discord guild

Upon confirming the token they will be granted the permissions, groups and Discord roles set out in the "Basic Rewards" section of your config file.
If the are a Nitro Booster they will also be granted the permissions, groups and Discord roles set out in the "Nitro Rewards" section of your config file.

If enabled they will also be given a number of tokens (defined in the config) for linking their Discord account which can be used to purchase items from the reward store.

To access the reward store they simply use the command /discord

For items that have a description a info icon will appear on the right hand side. Clicking that button opens a new dialog with the items description in it

The Reward Store
The reward store operates on tokens that are given to the player when they link their Discord account, and when that link is revalidated. All items in the store cost tokens.

You can customize 2 config options to determine how many tokens are given for these events:
"Amount of reward tokens to give by linking Discord account"
"Amount of reward tokens to give every time a linked account is re-validated"


Permissions
discordrewards.admin - Required to access the admin menu


Chat Commands
/discord - Opens the reward store and token menu depending on the users state
/discord.admin - Opens the admin menu to edit rewards


Console Commands
discord.admin purge - Clear all users with expired tokens from the data file
discord.admin wipe - Revoke rewards from all players and invalidate their tokens
discord.admin revoke <player ID> - Revoke all rewards from the target player and invalidate their token

Reward Add/Edit/Delete Commands
discord.rewards - Shows help menu

--- List Rewards ---
discord.rewards list <items | kits | commands> - Display a list of rewards for the specified category, which information on each item

--- Add Rewards ---
discord.rewards add item <shortname> <skinId> <amount> <cooldown> <opt:bp> - Add a new reward item to the store (add "bp" to add the item as a blueprint)
discord.rewards add kit <name> <kitname> <cooldown> - Add a new reward kit to the store
discord.rewards add command <name> <command> <cooldown> - Add a new reward command to the store

To limit the reward to Nitro Boosters only, simply add the word "nitro" to the end of the command.
ex. "discord.rewards add item rifle.lr300 0 1 600 nitro"

--- Editing Rewards ---
discord.rewards edit item <ID> <name | amount | cooldown> "edit value" - Edit the specified field of the item with ID number <ID>
discord.rewards edit kit <ID> <name | description | icon | cooldown> "edit value" - Edit the specified field of the kit with ID number <ID>
discord.rewards edit command <ID> <name | amount | description | icon | add | remove | cooldown> "edit value" - Edit the specified field of the kit with ID number <ID>
Icon field : The icon field can either be a URL, or a image saved to disk under the folder "oxide/data/DiscordRewards/Images/"
Command add/remove field: Here you add additional commands or remove existing commands. Be sure to type the command inside quotation marks

--- Removing Rewards ---
discord.rewards remove item <ID #> - Removes the item with the specified ID number
discord.rewards remove kit <ID #> - Removes the kit with the specified ID number
discord.rewards remove command <ID #> - Removes the command with the specified ID number

--- Important Note ---
Removing rewards may change each rewards ID number. Be sure to list your rewards before removing them


Creating a Bot account
In order to validate users in your Discord you must create a bot account. This is quite a simple task;

1) Make sure you are logged in on the Discord website -> https://discordapp.com/

2) Navigate to the Applications page -> https://discordapp.com/developers/applications/

3) Click "Create an application"


4) Name your application and save the changes

5) You should now see something like the picture below. Note the "CLIENT ID", this is the "Bot Client ID" field in your config


6) Click the "Bot" button on the left hand side, then click "Add Bot". This will create a bot for your application

7) Name your bot, toggle "Public Bot" to the off position, and give the bot the "Send Messages" permission and the "Manage Roles" permission if you are planning on giving Discord roles as rewards.

8) Scroll down to the section labelled "Privileged Gateway Intents" and toggle on both "Presence Intent" and "Server Members Intent"


9) Click to reveal the bots "Token". This is the "Bot Token" field in your config, so copy it to your config now.


10) Save your changes and exit. Your bot is now ready to join your Discord.


Inviting your bot to your Discord
Now you have created your bot you need to invite it to your Discord server.


Copy the link above and replace "YOUR_CLIENT_ID" with the client ID we saw in step 5. Paste this link in your browser and you will be prompted to select a server for the bot from the list of servers you own.

Select the server you want the bot to join and hit Authorize.


Thats it, your bot is now on your server. Make sure you have pasted the required details in to your DiscordRewards config so the plugin can communicate with your Discord server!


Adding/Removing/Editing Rewards
There are 2 ways to add rewards to the reward store.

The first is using the in game reward editor, which can be accessed by typing /discord.admin

The plus button allows you to add a reward, with each item having its own edit and delete buttons on the left hand side.




The second way is very similar to ServerRewards if you are familiar with it. Using the console commands provided below you can add/remove/edit your rewards.

Item icons are used retrieved automatically via ImageLibrary, and Kit/Command icons can be set if you specify a URL. You can also replace item icons with custom images the same way.

You can add or remove multiple commands in your command rewards after you have created the initial command by typing discord.rewards edit command edit <add/remove> "command"

Commands have 5 parameters you can insert in to them that will be replaced by the users information
$player.id - The users Steam ID
$player.name - The users display name
$player.x, $player.y, $player.z - The users position

By placing any of those in your command they will be replaced with the respective information of the player using the command

All rewards require a cooldown even if you are using the global cooldown option

To add rewards that only Nitro Boosters can claim, add the word "nitro" to the end of the add command


Alternative Rewards
Alternative rewards can include the user being added to specified user groups, giving them roles on your Discord, granting the user permissions, or running commands when the user has validated

Permissions, Groups and Discord Roles only last as long as the user has a valid token (see Revalidation Interval below). Once the validation time has expired users are automatically removed from the groups and the permissions are revoked until they perform the validation process again

To add Discord roles simply put the name of the role exactly as typed in Discord in the "Discord roles to grant on successful validation" section of your config

Commands are run 1 time when the user has completed validation. Like the commands available via the reward store there are 5 parameters you can insert in to them that will be replaced by the users information

$player.id - The users Steam ID
$player.name - The users display name
$player.x, $player.y, $player.z - The users position

Nitro Booster Rewards
Just like the alternative rewards, there are additional groups, permissions and commands that can be run on/given to nitro boosters.

To give rewards to Nitro Boosters simply enter the booster role name in the Settings/Nitro boost role name section of the config. You can then add groups, permissions and commands to the config.

If you want to give nitro specific item/kit/command rewards through the UI menu, simply add the word "nitro" to the end of any "add" command when adding the reward. The reward will appear in the UI with a pink button

Setting a custom bot status message
You can set a custom message for your bot by modifying the "Bot Status Message" option in the config. By default this is empty, and you can put what ever you like in there.

I have also included 3 variables that will get replaced with information when setting the message;
{playersMin} - Displays the current amount of players on your server
{playersMax} - Displays your server capacity
{rewardPlayers} - Displays the current amount of players who are receiving rewards from this plugin and have a valid token

ex 1. "Players Online {playersMin} / {playersMax}" will show "Players Online 10 / 100" if you have 10 players on a 100 slot server
ex 2. "Discord Members {rewardPlayers}" will show "Discord Members 500" if you have 500 users with valid tokens
ex 3. "Hello I am a bot" will show exactly that

Config Options
Token Lifetime (seconds) - This is the amount of time from when the Discord bot has sent a user their validation token until it expires

Revalidation Interval (seconds) - This is the amount of time from when a user has entered their validation token ingame until they will need to re-validate

Automatically try and re-validate users when their token has expired - When a users token has expired this will check to see if they are still in the Discord, if so it will automatically re-validate the user

Bot Token & Bot Client ID - Described above in the steps to set up your Discord bot

Bot Status Message - Allows you to set a custom status message for your bot (see above)

Use Global Cooldown - This will create a global cooldown on all items, so a user can only claim 1 reward at a time. If this is false then users can claim all rewards and will be limited by their individual cooldowns

Global Cooldown Time (seconds) - The cooldown time for a global cooldown

Enable Reward Menu - Enables the UI reward store. Set this to false if you only want to grant permissions/groups

Require Re-validation - Enable the re-validation process, forcing users to go through the validation process at the interval you specify

Add user to user groups - A list of user groups to add the player to upon validation.
Example usage: "Add user to user groups": [ "group1", "group2" ],

Permissions to grant on successful validation - A list of permissions to grant the user upon validation
Example usage: "Permissions to grant on successful validation": [ "rustnet.use", "grenadelauncher.spawn"],

Commands to run on successful validation - A list of commands to run when a player is validated
Example usage: "Commands to run on successful validation": [ "spawncar $player.x $player.y $player.z"],

Discord roles to grant on successful validation - A list of Discord roles to grant when a player is validated
Example usage: "Discord roles to grant on successful validation": [ "Test Role"],


Config