Dueling Script

==Dueling Mode==
by @mike_the_monk
===Summary===
Challenge a friend to a duel! This script keeps track of the score automatically as you complete your tasks. 
Decide who you want to duel, how much GP you want to wager, and the score you are trying to reach. The first person to reach that score wins the GP you both wagered. For example, if you both wager 50 GP and set your goal at 25 duel points, you both immediately lose 50 GP when starting the duel and the first person to 25 duel points wins the pot of 100 GP (i.e. twice the 50 GP wager).
====Duel points====
Duel points are similar to boss damage except they ignore your level, equipment, buffs, stats, skills, and critical hits - basically, anything that would give veteran players an advantage over newer players. It's purely a battle of productivity. So, duel points take into account your tasks, their difficulty, and their value/color. Harder tasks score more duel points. Redder tasks also score more duel points. Negative Habits decrease your duel score but incomplete Dailies do not.
The formula is Task Difficulty * Multiplier * Task Value Delta 
* Task Difficulty = 2 for Hard tasks, 1.5 for Medium tasks, 1 for Easy tasks, and 0.1 for Trivial tasks
*Multiplier = 1 for To-Do's and Dailies, 0.5 for Habits. Habits earn half the duel points of an equivalent To-Do or Daily.
* Task Value Delta = 0.9747 ^ (Task Value prior to clicking the task). This is the same as for boss damage.
----
===Getting started - for duelists===
To get started with the duel script, you'll need to do two things, and possibly a third:
#Install this script using these instructions. Each player dueling will run their own instance of the script.
#Talk with your party's duel announcer bot to set up the duel parameters (if no one has set up the announcer bot yet, someone will need to do that as well by following these instructions)
#Recommended: when dueling, disable any other scripts you might be running by following these instructions. or install the mike_the_monk superscript (i.e. it's all his scripts combined). Using multiple third-party scripts at the same time can cause issues, especially if they are webhook-based scripts. 
#*This means you can't participate in two duels at the same time.
#*It also means that the Habitica profile running the announcer bot can't participate in duels. Therefore, if you're running the announcer bot, it's better if you set up a secondary account to be the bot. Instructions for how to do that are here.
----
==== Installing this script====
If you've use any of my scripts before, installation is the same. 
===== Code =====
* https://raw.githubusercontent.com/mike-the-monk/Habitica-customizations/main/Game%20Modes/Dueling%20Mode%20-%20scoring
===== Optional customizations =====
* NOTIFICATIONS_ON can be changed to a 0 so you don't get any private message notifications (except errors messages, you always get those). If you keep it at a 1, you will get all the usual notifications.
* TAG_FOR_DUEL_BUTTONS allows you to create your own tag for the three duel-related buttons (Duel Start, Duel Score, Duel End). Since the script deletes and re-creates the buttons as you start and end a duel, the only way to have a tag that persists is if you put it here. If you don't want to add a tag, simply leave this customization alone.
Once you've completed installing this script, you should see a button like the image on the right:
----
====Setting up a duel by talking to the announcer bot====
One Habitican in your party will set up a duel announcer bot (instructions for that person are here). The announcer bot will help you set up your duel. The best way to see how it works is to see an example - let's see it in action as @mike_the_monk talks with his party's announcer bot, @mike_the_bot. 
Below the screenshots is a list of all of the announcer bot commands.
===== Example of setting up a duel =====
----
=====List of all duel bot commands=====
You will talk to the announcer bot to set up your duel - just tag the bot with their @username and use one of the commands listed below.
The announcer bot can only help set up one duel at a time. If no duel is currently being set up, you can say the following commands: 
*I WANT TO DUEL - the bot will walk you through setting up the duel and will ask you for 1) your opponent, 2) how much you'll wager, 3) and the score needed to win. These three things are called the "duel parameters" and are listed below.
*I WANT TO DUEL AND I KNOW ALL THE PARAMETERS - if you already know the duel parameters, you can include them here to skip the walkthrough from the bot.
When setting up the duel, the bot is listening for all three of these parameters to be included in a single post: 
*OPPONENT: @username; and notice that it's followed by a semicolon, that's important
*WAGER: [a number] ;
*SCORE NEEDED: [a number] ;
When the Player initiating the duel is setting up the duel parameters, they are the only player allowed to respond. The bot can only help set up one duel at a time. If anyone else responds now, the bot will let them know to wait.
Once the parameters are set up, the bot will ask the opponent to respond:
*AGREE - if the opponent agrees, the duel begins with that wager and score needed to win.
*DISAGREE - if the opponent doesn't want to duel at all. The bot will ask them to confirm declining the duel by saying DECLINE.
* COUNTEROFFER - if the opponent wants to propose a different wager and/or score needed to win. The counteroffer, make sure to include WAGER and SCORE NEEDED in the same post, much like for setting up the duel parameters in the first place.
If it's a counteroffer, the bot will then ask the first player whether they agree, disagree, or counteroffer. This will continue until either both players agree or one of them decides not to duel. If both players agree, the announcer bot will give you some text to paste into your Duel Start button. 
While all of this is going on, these are the only two players who can respond because the bot can only help set up one duel at a time. It might happen where the duel initiator tagged the wrong person - for example, you wanted to duel @mike_the_monk and instead mistyped @mike_the_onkm. The bot is now waiting for @mike_the_onkm to respond (but that player doesn't exist!) and won't let anyone else respond. In cases like that, the player initiating the duel can use the following commands: 
*START OVER - they then begin again with setting up the duel parameters. 
*CEASE SETUP - if they decided they don't want to duel anymore at all, this is the command to use.
Once the duel is set up, the bot can help another player set up a duel.
At any time: 
* anyone can say HELP to get a list of all the commands the bot is listening for
* experienced duelists can use the FAST START DUEL command (detailed instructions here), even if the bot is helping someone else set up a duel.
----
===== Ensuring correct formatting for the duel parameters=====
If the bot didn't recognize your post with the duel parameters, here are a few things to check: 
*Did you include all of the duel parameters in a single post? You'll need OPPONENT: and WAGER: and SCORE NEEDED: 
**If it's a counteroffer, you'll only need WAGER: and SCORE NEEDED:
*Did you include a semicolon after each parameter? If not, the script won't be able to read it.
* Did you enter a number for WAGER and SCORE NEEDED?
----
=====How to use FAST START DUEL=====
Let's say the bot is helping someone else set up a duel, but you already know who you want to challenge, how much to wager, and the score needed to win. You've even talked to the other player and they already agree. That's the perfect scenario for the FAST START DUEL command.
Just like any of the bot commands, tag the announcer bot with their @username and then use the command. In that same post, include all the duel parameters without their labels (i.e. OPPONENT:, etc.), following each with a semicolon. For example, for a duel wagering 75 GP and a score needed to win of 50 duel points, you'd say @bot FAST START DUEL @opponent; 75; 50;
If you use this command, the bot will not be doing the normal quality checks on your duel parameters. For this reason, FAST START DUEL is not recommended for newer duelists. If there are any errors in how you typed your duel parameters, you'll need to try again.
----
====Starting your duel====
After you install this script, you should see a button that looks like the photo on the left. Once your duel's announcer bot gives you some text to paste, copy it (center photo) and paste it into the Notes section of this button (photo on the right).
File:Duel Start button basic.png|Duel Start button before
File:Copying duel setup text.png|Copy the setup text...
File:Duel Start button with parameters pasted.png|...and paste it into the button
When you click this button to start your duel and refresh the page, your wager will be deducted automatically, so make sure you have enough GP. After you click this button, the script will begin keeping track of your duel points. 
Now that your duel has started, you don't need the Duel Start button, so it automatically gets deleted. In its place, you'll see two additional buttons (see photo below left). If you kept notifications on when you installed the script, you will get a private message letting you know that your duel begins (see photo below right).
File:Duel Score and Duel End buttons.png|The Duel Start button gets replaced with these two buttons when the duel begins
File:Duel start optional message.png|If you kept notifications on, you will get a message like this when your duel begins.
.
----
====Disabling other third-party scripts during your duel====
Some Habiticans report issues if they try to use multiple third-party tools/scripts at the same time. You might want to disable other scripts during your duel so they don't interfere with each other, especially if they are webhook based scripts like this one is.
To do so, go to Settings > API on the web version of Habitica. For any webhooks that you have active, uncheck the box to temporarily disable them. Once your duel is done, recheck the box and they are enabled.
If you can't keep track of which webhook is for which scripts, you can use a tool such as the Habitica Webhook Editor to assign a name. You can disable and reenable webhooks using the tool as well.
----
===Checking your score===
To see your current duel score, click the Duel Score button and refresh the page. The Notes of this button will tell you your duel score at that moment in time.
It does not update automatically, so if you want to know your score later, simply click the button again and refresh the page, as seen in the photo on the left.
----
=== Ending your duel===
When your duel score exceeds the score needed to win, this script will update your Duel Score button to let you know you won, as seen in the photo on the right.
When either player wins, their script will automatically post a message to the party for the announcer bot to check. If the automated message passes the quality checks, the bot will declare the winner (see photo below left).
Both players will copy the text from the announcer bot (see center photo below), paste it into the Duel End button (see photo below right), click it, and refresh the page. The winner will automatically be awarded their GP. The script will delete the Duel Score and Duel End buttons and replace them with another Duel Start button.
File:Announcer bot declaring winner of the duel.png|Announcer bot declares a winner
File:Copying duel end text.png|To end the duel, copy this text...
File:Duel End button with text that ends duel.png|...and paste it into the Duel End button
If you disabled any webhooks prior to dueling, now that the duel is done, you can reenable them by following these instructions.
----
=== Troubleshooting errors - for the duelist ===
The script performs quality checks to make sure what you're pasting into the buttons matches what's expected. If there are any errors, you usually will get a private message.
==== For errors when the duel is ending ====
The most common time you might get an error is when the duel is ending. In that case, not only will the script send an error message to you as a private message, it will also post to the party chat. The image on the right is an example of what that message might look like.
At that point, you should:
* Contact the author of the script by sending him a private message in Habitica.
* Contact the player running your party's duel announcer bot - for any errors that happen at the end of the duel, the specific cause of the error isn't posted to the party, but instead is in the Console Log in the bot script.
If an error gets triggered will ending the duel, the script purposely stops working so that it doesn't spam the party chat with endless error messages. Once the issue gets solved, the script author will tell you which of the script's debug functions to run, which will reset things and reactivate the script.
If you want to immediately end the duel in case of errors, you can use the command ENDING DUEL: DEBUG END in the Notes section of the button. You won't win the duel if you use this, but it will end the duel.
==== For simpler errors ====
If you're experiencing issues with the two script, such as it suddenly stopped keeping score, please go through the steps listed on this page: Scripts Troubleshooting. Section 3 (Event-Driven (Webhook) Scripts) is especially useful.
If you're not able to resolve the issue, you can contact the author of the script at any of the following places:
*Aspiring Comrades Guild (tag @mike_the_monk)
*Open an issue on GitHub
----
=== Update Instructions - for the duelist ===
*If you already had an earlier version of the script set up previously and want to update to a newer version, do all three parts under Applying Updates to Streamlined Scripts
----
==Setting up the announcer bot==
All duelists in a particular party will use the announcer bot to help set up duels, as outlined above. But only one Habitican will set up and run the announcer bot. If that person is you, here's how to do it:
# Create a secondary (bot) account - If you use your main Habitica account as the announcer bot, you will get very many notifications as players set up tools and you probably don't want that.
# Install the announcer bot script - This is a separate script from the duel scoring script. Each player participating in a duel will run their own instance of the scoring script. You will be the only person in your party running the announcer bot script.
----
=== Creating a secondary (bot) account ===
It's not recommended that you use your main Habitica account as the duel announcer bot. Every time someone sets up a duel, you'd get multiple notifications. And, your main account wouldn't be able to participate in duels - running multiple scripts at the same time could cause issues (you would be running the announcer bot script and the duel scoring script).
Instead, you can create a secondary account just for running the announcer bot. You can create a new account with a new email address, or, if you have Gmail, you can use its "plus tags" feature. For example, if your email is yourUsualEmail@gmail.com, to add the tag "+bot", it would be yourUsualEmail+bot@gmail.com. All emails with a plus tag show up in the same inbox, which is nice.
It's a best practice that your secondary/bot account should indicate that it is under the control of your main account. Put it somewhere in your profile. Your main account should also list which secondary/bot accounts it controls. You can use the screenshots below as examples.
File:Screenshot of note in bot account profile.png|A note in your secondary/bot account profile mentioning your account
File:Screenshot of note in main account.png|A note in the main account profile mentioning that you have a secondary/bot account
----
=== Install the announcer bot script ===
If you've use any of my scripts before, installation is the same.
===== Code =====
* https://raw.githubusercontent.com/mike-the-monk/Habitica-customizations/main/Game%20Modes/Dueling%20Mode%20-%20announcer%20bot
===== Required customizations =====
Once you've successfully installed the script for the duel announcer bot, you should see the following post in your party. If you don't, then the script did not install correctly and you should follow the troubleshooting steps below.
----
===Troubleshooting - for the announcer bot===
If you're experiencing simpler issues with either of the two scripts (the duel scoring script or the announcer bot script), please go through the steps listed on this page: Scripts Troubleshooting. Section 3 (Event-Driven (Webhook) Scripts) is especially useful. 
If you're not able to resolve the issue, contact the author of the script at any of the following places: 
* private message in Habitica.
* Open an issue on GitHub
----
===Update Instructions - for the announcer bot=== 
*If you already had an earlier version of the script set up previously and want to update to a newer version, do all three parts under Applying Updates to Streamlined Scripts
----
==Footer==
===Credits and Acknowledgments=== 
*@CitizenPrayer for the idea of creating a duel script
Category:Extensions, Add-Ons, and Customizations