FRET is a multipurpose Javascript Discord bot whose purpose is to encourage discussion in a discord server by facilitating an organized environment using threads, self-moderating channels and by managing databases to store and retrieve information. FRET makes use of Mongoose JS to store and retrieve data from a MongoDB database. The goal is to encourage an active and organized community help forum similar to StackOverflow but on Discord. FRET also manages a self-sufficient weekly submission system that grants roles based on the number of weeks in a row a user has participated in. To encourage discussion, users can reward points to each other for helping them on the forum, which can be used to grant roles. Moderator-specific commands to change data in the database on-demand are also included. FRET is currently self-hosted and used in a guitar community Discord server Fingerstyle Central.
Your contributions are very welcome and appreciated. Following are the things you can do to contribute to this project.
-
Report a bug
If you think you've encountered a bug, please inform me by creating an issue here. -
Request a feature
You can request for a feature by creating an issue here. -
Create a pull request
If you improved the bot yourself and would like to contribute to this project, I really appreciate it!
If you are new to open-source, make sure to check read more about it here and learn more about creating a pull request here.
I'm making some gifs and videos that demonstrate this bot's functionality.
Clone this repository to your system, install Node.js v16.6+, npm, and Discord.js v13.
If you plan on using this FRET's code for contributing/testing, or for your own purposes, you need to create your Discord application here. Additionally, you can always lean on the documentation for Discord.js, or the guide.
Run FRET by using one of the following commands:
node .
npm start
-contribute
Shows links for users to help out with the development of FRET by reporting bugs, requesting features and developing code.
-help
Displays all the user commands for the channel it was invoked in (Forum or Weekly Submissions). If it was invoked anywhere else, it displays a list of usable help command variants (f, w, i) that are listed below.
-help c
Can be called in the Forum or Weekly Submissions channel to display a list of usable help command variants (f, w, i) that are listed below.
-help f
Displays all the user commands for the Forum channel.
-help w
Displays all the user commands for the Weekly Submissions channel.
-help i
Displays a description of FRET's purpose and links to this GitHub repository.
-q <your question>
Takes a question and creates a thread under the message that invoked the -q command. The thread is auto-archived in 24 hours and can be un-archived by anyone who writes a message in the thread. Automatically handles thread titling.
-thanks <@user>
-thank <@user>
-thanks <@user1> <@user2> <@user3>
-thank <@user1> <@user2> <@user3>
Takes any number of mentions. The math to divide the points between each user works exponentially (100/(users^0.5)). The person who uses this command gets placed on a short cooldown before they can use it again to avoid spam. The person who uses the command also gets 20% of the points they've awarded. Users cannot thank themselves to farm points.
-pin
Can only be used inside threads and by users with the Mentor role or above. Pins and unpins messages.
-rankup
Ranks up the user if they have enough points for a role. Otherwise, show how many more points needed. Also repairs the roles if any roles are added by a moderator on accident. Wont show anything if the user isn't recorded in the database.
-points
-points <@user>
Displays the number of points a user has.
-top
-leaderboard
-top <rows>
-leaderbaord <rows>
Displays a leaderboard of 10 rows by default, showing the users with the most amount of points first. The person who used the command also has their rank placement and points shown at the bottom of the leaderboard underneath a divider. If the user specifies a number for the rows, it will show that many rows. Maximum rows that can be shown, regardless of the rows specified, is the size of the set of users with pointdata documents in the database.
A CronJob task occurs every Sunday 11:59 PM EST to finalize the submissions for a week, creates the data for the users who submitted a weekly for the first time, updates the data of each user with an existing weekly submission history, and assigns temporary or permanent "trophy" roles if the user has submitted enough weeks in a row. If the user has a weekly submission history and a streak but they did not submit for that week, the streaks are reset and temporary roles are removed.
-w submit <link/file>
Submits a link or attachment for the Weekly Submissions. This logs the user's submitted date in the database which will be used to increase their streak at the weekly finalization. Also creates a thread under the message. The thread is auto-archived in 1 hour and can be un-archived by anyone who writes a message in the thread.
-w info
Displays the current time in EST, the next weekly finalization time in EST, and shows how many days, hours and minutes remain before the weekly finalization.
-w profile
-w profile <@user>
Displays a fancy user profile that shows the user's username, profile picture, temporary roles, permanent "trophy" roles, submission times of this week and last week, current streak and highest streak.
These happen automatically without any command being sent in the chat.
<link>
Only works in the channel whose ID is written in shareMusicChannel in the config.JSON file. Creates a thread under the message. The purpose of this is to avoid these promotional links from getting buried due to people who talk about the promoted link (usually a video). The thread is auto-archived in 1 hour and can be un-archived by anyone who writes a message in the thread. Automatically handles thread titling. Any message that isnt a link is removed and the user is reminded that discussion is only allowed in the threads.
<#channel> <message>
Only works in the channel whose ID is written in impersonateChannel in the config.JSON file. Impersonates yourself as FRET and remotely sends a message as FRET into another channel it has access to. FRET also checks to make sure it has permissions to view and send messages in the channel and will log an error in the impersonateChannel.
+help
Displays all the moderator commands listed here (except +help) and their intended use.
+points <@user> <amount> [options: set]
Increases, decreases or sets a user's points by a certain amount. The amount can be any valid integer, negative values will decrease the user's score while positive values will increase it. Specifying set at the end of the command will set the user's points to the exact amount specified.
+penalty <@user>
Penalizes user for 1000 points.
+w inv <@user>
+w invalidate <@user>
Invalidates a user's weekly submission such that that they haven't submitted this week. Doesn't account for previously submitted valid submissions in the same week, so the user needs to submit again after this command is invoked.
+w setstreak <@user> <streaks>
Sets a user's weekly submission streak to a specific amount.
+w reset <@user>
Resets a user's weekly streak and weekly rank.
If you want to use this bot for your own personal use, the method of deployment is up to you. I'm personally self-hosting FRET on a VPS.
Do note: Make sure FRET's role is higher than any of the roles you plan to give using FRET, I haven't yet made any error checking for this so your FRET will just terminate if it encounters this error. The hierarchy of FRET won't affect your server because it'll only have the permissions you set for it, no matter how high it is on the role hierarchy.
FRET needs the permission to manage messages since it will be deleting messages to clear up the chat whenever someone invokes a command incorrectly or sends a message in the wrong channel.
Under the folder configurations you'll notice a file named flux.prod.json. This file contains IDs used in Discord for your bot, guild, roles, channels, etc. You may create a flux.dev.json file in the same folder by copying flux.prod.json to change all of the IDs and test everything in your own server. This is your personal development configuration and it will be ignored. Be careful not to modify the flux.prod.json file. Any pull requests modifying it without explicit permission in the focal issue of the PR will be closed without merging.
- serverGuild
ID of your discord server - moderatorRoleId
ID of the moderator role in your server - everyoneRoleId
ID of the everyone role in your discord server - DBmanager
ID of a role. Anyone with this role will be able to use FRET's mod commands - shareMusicChannel
ID of the channel shareYourMusic.js passively runs in - helpForumChannel
ID of the channel where forum.js passively runs in can be invoked - impersonateChannel
ID of the channel that forwards messages to targeted channels - weeklyGuideChannel
ID of the channel where the weekly submission criteria are listed - weeklyChannel
ID of the channel for weekly submissions
In the module defined in commandHandler.js, you'll notice a property named isDebug, this should be set to true for local development, and false when deploying. This determines which flux configuration is loaded at runtime.
Since this was a personal project, my variables will be different from what you would need. There are two files you may need to customize for this bot to work on your local machine or server. config.json is provided for you to make changes to the prefixes, names, colors and leveled-ranks.
- userPrefix
The prefix used for user commands - moderatorPrefix
The prefix used for moderator commands - botName
The name the bot will refer to itself as - ...Color
The colors of embeds depending on their usage - rank1...6
Leveled forum rank names - rank1Points...6Points
Leveled forum rank point thresholds - wRank1...3
Temporary weekly submission rank names - wRank1Streak...3Streak
Temporary weekly submission rank streak thresholds - wRankPerma
Permanent "trophy" weekly submission rank name - wRankPermaStreak
Permanent "trophy" weekly submission rank streak threshold
FRET uses MongooseJS to store it's data in MongoDB as a JSON schema. You only need to provide a secrets.json (described below) your MongoDB database connection string to use the database, given that you've made one for free already. This code uses two tokens, "Token" and "Mongo", as described in secrets-example.json. Create a copy of this file and name it secrets.json, then, edit the fields:
- Token
The token your applications bot will be using to sign into Discord. - Mongo
The string used to connect to your MongoDB database.
If you are to use this code in your public github repositories, do not share your secrets.json file. It will give other people access to your Discord bot and your database. Though, github will likely recognize this and warn you before anyone does.
I will be further improving on FRET if something on the guitar community server needs to be automated.
See the LICENSE file for details.
- Robert Chen - robchendev
- Taco (タコス) - tacosontitan
See also the list of contributors who participated in this project.