Discord Guild Battle Tracking Bot - User and Admin Guide

Introduction

    Welcome to the documentation page of the Fluffy! This is an open source Discord bot that allows users to keep track of their hits for Cookie Run Kingdom. The bot is designed to streamline the process of tracking hits and provides accurate and real-time data to the leaders.
    With Fluffy, users can call out their hits using commands, and the bot will automatically track all their data, including the split status, total damage dealt, and more. The leaders can access this data in a CSV file, which can be used for analysis and decision making. Whether you are a guild member or guild leader, Fluffy provides an excellent tool for managing hits, tracking progress, and achieving your goals. In this documentation, we will cover everything you need to know to get started with Fluffy including installation, setup, and usage.

Refer to GitHub README for Installation and Code-Related Questions

While this documentation covers the basics of Fluffy's installation, setup, and usage, there might be additional information or specific details you are looking for. For comprehensive guidance on installation, troubleshooting, and understanding the code, we recommend referring to the Fluffy GitHub README.

The README provides in-depth information and is continuously updated by the Fluffy development team. You can also explore the GitHub repository to learn more about the project structure, view the source code, and even contribute to the project if you are interested.

If you have any questions, issues, or suggestions related to Fluffy, don't hesitate to open an issue on the GitHub repository discussions page here or reach out to the development team. Your feedback and contributions are always welcome and will help improve Fluffy for everyone.

Installation

Follow these steps to set up the bot for your Discord server:

  1. Step 1: Visit the Discord developer applications portal here.
    Pro Tip: Use this website to create your bot, set up its permissions/trust settings, and create links to your server.
  2. Step 2: Generate a token for the bot. DO NOT SHARE THIS TOKEN WITH ANYBODY. The token is essentially your bot's password to be able to run. If someone gets a hold of that token, they can run whatever code they want from your bot in any server it resides in.
  3. Step 3: Set up channels for callouts. By default, the bot's code is set up to run on the channel names "avatar", "living_abyss", and "dragon" for the respective in-game bosses. Create these channels in your server.
  4. Step 4: Follow the README to complete your setup. Change the IDs of certain variables in final_vars.txt, create a guild.txt file containing your Discord server's ID, and place the token from Step 2 in a file called tkn.txt (all in the same directory).
  5. Step 5: Keep your bot running using pm2 on a server. With your bot running, all the commands presented below with their use cases can be used to their fullest potential! Good luck, and happy hitting.


Commands

User Commands

  • /hit [damage] - Hits the current boss in the text channel for damage amount. This does consume a ticket on usage. It is recommended to separate damage values with _ (123_345_789).
  • /resume_hit [damage] - Hits the current boss in the text channel for damage amount. This does not consume a ticket on usage. It is recommended to separate damage values with _ (123_345_789).
  • /killed - Kills the current boss in the text channel. This does consume a ticket on usage.
  • /bonus_kill - Kills the current boss in the text channel. This does not consume a ticket on usage.
  • /hp - Sends the current boss's hp.
  • /boss_help - Sends link of documentation page to user

    • Admin Commands

  • /admin_hit [damage] - Hits the boss for damage HP. (Does not count as a real hit)
  • /admin_kill - Kills the boss and increments level. (Does not count as a real hit)
  • /admin_revive - Revives the boss and decrements the level. (Does not count as a real hit)
  • /insert_hit [user_id] [damage] [split] - Inserts a hit for another user
  • /create_boss [guild] - Creates a boss tied to the current text channel with a guild attribute from the guild family. Initializes boss to max hp of a level 1 boss.
  • /delete_boss - Deletes the current boss in the channel. Removes all hits linked to the current boss as well.
  • /insert_boss [guild] [level] [hp] - Usage same as /create_boss, but guild, level, and hp can all be specified upon creation.
  • /send_csv [guild] - Sends a sorted .csv file of the specified guild.
  • /send_backup_csv [guild] - Sends a sorted .csv file for the specified guild after backup json file is loaded.
  • /load_json - Will load the current JSON backup file into the bosses dictionary. Note: this will not make the previously saved bosses hittable. Check usage for more information.
  • /insert_hit [user_id] [damage] [ticket_used] - Inserts a hit for a specific user.
  • /insert_kill [user_id] [ticket_used] [split] - Inserts a kill for a specific user.

Usage

User Usage

  • You will only need to understand how to use 4 commands:
    • /hit, /resume_hit, /killed and /bonus_kill

Note: the command /bonus_kill can be thought of as solo by some, and /killed can also be thought of as sweep by some.

It is recommended to separate damage numbers with underscores to ensure you type the correct number. Ex: /hit 123_456_789 is equivelant to /hit 123456789.

The main differences you'll need to understand as a user interacting with the bot is one key feature: "Does this command use a ticket or not?" The commands /hit and killed will both use a ticket when called. The commands /resume_hit and /bonus_kill will not use a ticket when called.
Because of this difference, you want to use /hit and /killed on attacks when you do not resume the hit. If you do resume the hit, use the respective commands: bonus_kill and resume_hit.

Usage Examples:

  • You hit the boss and do 23,500,000 damage: /hit 23_500_000
  • You kill the boss and do 3,250,000 damage on the resumed hit: /killed then /resume_hit 3_250_000
  • You killed the boss twice and did 500,000 damage on the final resumed hit: /killed then /bonus_kill then /resume_hit 500_000 (note bonus_kill's main usage is clearing multiple boss levels with a single ticket)

Note: most cases, you will either have this sequence: /killed -> /resume_hit [damage] or simply /hit [damage]. The use case for using /bonus_kill will most likely be limited to players who solo a boss.

Visual Usage Guide

To reference a visual guide made by a community member (Yuzu), please check out this link.

Admin Usage

Boss Creation/Deletion in a Channel

To initialize a boss in the specified channels, follow these steps:

  1. Use /create_boss to initialize the boss at level 1 with max HP.
    Tip: It is recommended to use this command during tally day to initialize the bosses when they're available to be hit.
  2. Alternatively, use /insert_boss [guild] [level] [hp] to insert a boss at a specific state if the bot went down.
    Warning: Do not use this command to change the HP or level. This will result in the loss of all hit data for that boss. Use admin-prefixed commands instead.

To delete a boss from a channel along with its data (hits), use /delete_boss. At the end of a season, delete all bosses from their respective channels and recreate them.

Admin Prefixed Commands + Inserting a Hit

Admin-prefixed commands (/admin_hit, /admin_kill) work the same as their non-admin prefixed counterparts (/hit, /killed), but they do not log a hit in the hit list. Note that /admin_hit can also accept negative numbers to heal the boss.

Follow these steps to revive a boss and adjust its HP:

  1. Use /admin_revive to restore the boss at the previous level if it was accidentally killed.
  2. Use admin-prefixed commands to adjust the boss's HP to the correct value.

To insert a hit or kill for a user that should be recorded, use /insert_hit [user_id] [damage] [split] or /insert_kill [user_id] [ticket_used] [split]. You will need their Discord user ID, damage/kill values, and a true/false value for whether the hit was split and if a ticket was used.

Data Aggregation

/send_csv [guild] will send a CSV file containing sorted data from the specified CRK guild bosses. This will most likely be used at the end of each season. This data can then be sorted in Google Sheets or Microsoft Excel.


(EMERGENCY COMMANDS)

The /load_json command should be used only in a very specific scenario. It loads the last backup of the database into the boss_dictionary so that you can call /send_backup_csv [guild] to get the data before the bot went down. After using /load_json, follow these steps:

  1. Use /send_backup_csv to get the data from before the crash.
  2. Note that this will not set up the bosses in the channel. To set up the current boss(es), use /insert_boss [guild] [level] [hp].

Contribution

If you would like to contribute to this project: we ask that you first build/run it yourself so that you have a model in which you can test your contributions. Please first check out the Github Issues page to see if the issue is there. If you see it, leave a comment that you want to take care of it. If the contribution idea is not there: please make a post in the Github Discussions page. If the feedback is well-heard: we will add an issue and assign you to it.


Any and all contributions are welcome! If you are a new contributor and not sure what to do: check out the Github's issue tab and see if any are marked 'good first issue.'

MIT License

MIT License Copyright (c) 2022 c0nD
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.