Skip to content

Commit 0950358

Browse files
MimickalMimickal
authored
Merge pull request #56 from Mimickal/develop
2 parents b0cd7d1 + 03caf98 commit 0950358

42 files changed

Lines changed: 4160 additions & 2874 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
node_modules/
22
todo.txt
3+
*.log
34
*.swp
45
dev.sqlite3
5-
dev-token
6+
dev-config.json

‎.replit‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
language = "nodejs"
2+
run = "node ."

COPYING.md renamed to LICENSE.md

File renamed without changes.

‎Procfile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
worker: node .

‎README.md‎

Lines changed: 115 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,38 @@
1-
## Overview
2-
A Discord bot that can assign roles based on message reactions.
1+
# Overview
2+
3+
<a href="LICENSE.md"><img align="right" alt="AGPL-3.0 Logo"
4+
src="https://www.gnu.org/graphics/agplv3-155x51.png">
5+
</a>
6+
7+
A Discord bot that can assign roles based on message reactions.<br/>
38
[You can invite my live instance of the bot to your server with this link](
49
https://discord.com/oauth2/authorize?client_id=692585944934514738&scope=bot&permissions=335881280
5-
)
10+
).
611

7-
## Why this bot?
12+
# Why this bot?
813
Several other popular role-react bots exist, but many of them have some annoying
914
catch. Some have uptime issues, some lock basic functionality behind premium pay
1015
walls, and some come with way too many other features that add bloat, requiring
1116
convoluted web APIs for configuration. In most cases the source code also isn't
1217
available, so we can't do anything about it.
1318

1419
This bot attempts to address these issues. It _only_ does role reacts, and is
15-
configured by typing to it in a Discord channel. Every feature of this bot is
16-
completely free to use, and always will be. It's also open source, so you can
17-
modify it to better suit your needs, or just download it and host your own
18-
instance. Basically, there's no bullshit.
20+
configured using slash commands. Every feature of this bot is completely free to
21+
use, and always will be. It's also open source, so you can modify it to better
22+
suit your needs, or just download it and host your own instance.
23+
24+
Basically, there's no bullshit.
1925

2026
# Usage
21-
You can interact with the bot by mentioning it (denoted here as `@bot`). The bot
22-
will currently only respond to users with the "Administrator" permissions.
27+
You can interact with the bot using slash commands.
2328

29+
The bot will always respond to users with the "Administrator" permission.
30+
Additional roles can be whitelisted to modify the bot config for your guild.
31+
32+
You write the post people can react to for their roles. The bot will not attempt
33+
to write its own posts for this (but will add its own emojis).
34+
35+
## Permissions
2436
The role automatically created for the bot needs to be ordered above any role
2537
you want the bot to be able to assign. That role also needs to have access to
2638
the channel with your role-react post, and have have following permissions:
@@ -30,150 +42,105 @@ the channel with your role-react post, and have have following permissions:
3042
* **Read Message History** - To see posts in the channel before it joined
3143
* **Use External Emojis** - To use your custom emojis in role reacts
3244
* **Read Text Channels & See Voice Channels** - To see the role-react post
33-
Note that these permissions may be inherited from your `@everyone` settings.
3445

35-
You write the post people can react to for their roles. The bot will not attempt
36-
to write its own posts for this. You can then tell the bot to select that post,
37-
and tell it which roles to map to which emoji reactions on that post.
38-
39-
**Selecting a post** - The bot tracks this on a per-user basis, so multiple users can
40-
interact with the bot at the same time.
41-
```
42-
# Command:
43-
@bot select <channel> <message_id>
44-
@bot select <channel_id> <message_id>
45-
@bot select <message_link> # Not yet supported!
46-
47-
# Examples:
48-
@bot select #role-assginment 123456789123456789
49-
@bot select 123456789123456789 1234556789123456789
50-
@bot select https://discordapp.com/channels/123456789123456789/123456789123456789/123456789123456789
51-
```
52-
53-
**Adding a role to the post** - The bot will add its own reaction to the selected
54-
post with the given emoji.
55-
```
56-
# Command:
57-
@bot role-add <emoji> <role>
58-
@bot role-add <emoji> <role_id>
59-
60-
# Examples:
61-
@bot role-add 🦊 @test-role
62-
@bot role-add 🦊 1234556789123456789
63-
```
64-
65-
**Removing a react-role from a post** - The bot will remove all reactions of
66-
this emoji from the selected post, without removing the associated role from any
67-
user who reacted to the post.
68-
```
69-
# Command
70-
@bot role-remove <emoji>
71-
72-
# Examples:
73-
@bot role-remove 🦊
74-
```
75-
76-
**Removing all react-roles from a post** - The bot will remove all reactions
77-
from the selected post, without removing any of the associated roles from the
78-
members who reacted to it. This is mostly useful to work around a limitation
79-
with Discord's API, since it treats admins removing reacts the same was as users
80-
removing reacts.
81-
```
82-
# Command
83-
@bot role-remove-all
84-
```
85-
86-
**Adding roles that can configure the bot** - By default, the bot will only
87-
listen to users who have the administrator permission. This command allows you
88-
to add additional roles that are allowed to configure the bot.
89-
```
90-
# Command
91-
@bot perm-add <role|role_id>
92-
```
93-
94-
**Removing roles that can configure the bot** - Removes a role from being
95-
allowed to configure the bot. The bot will always listen to users with the
96-
administrator permissions. This cannot currently be disabled.
97-
```
98-
# Command
99-
@bot perm-remove <role|role_id>
100-
```
101-
102-
**Add mutually exclusive roles** - Makes two roles mutually exclusive. If a user
103-
tried to add two roles that are mutually exclusive, the bot will automatically
104-
remove the first one they had.
105-
```
106-
# Command
107-
@bot mutex-add <role1|role1_id> <role2|role2_id>
108-
```
109-
110-
**Remove mutually exclusive roles** - Removes the mutually exclusive constraint
111-
from two roles.
112-
```
113-
# Command
114-
@bot mutex-remove <role1|role1_id> <role2|role2_id>
115-
```
116-
117-
**Printing command usage info** - If you'd rather the bot tell you how to use
118-
it, instead of looking at this page, you can use this command.
119-
```
120-
# Command
121-
@bot help
122-
```
123-
124-
You can also print the bot's description, version number, and link to the source
125-
code. This command is available to all users.
126-
```
127-
@bot info
128-
```
46+
**Note:** These permissions may be inherited from your `@everyone` settings.
47+
48+
## Selecting a Message
49+
You need to select a message to add react roles to it. Right click on a message
50+
and use Discord's fancy context menu to select it. This is tracked per-user, so
51+
multiple users can interact with the bot at the same time.
52+
53+
Due to current Discord limitations, context menus are not available on mobile
54+
devices (sorry). See below for an alternative.
55+
56+
![](docs/select.png)
57+
58+
## Selecting a Message on Mobile
59+
If you are on mobile, you might not have access to context menus. Don't worry,
60+
there's a workaround for you. Long-press the message, select
61+
"Copy Message Link", then use `/select-message-mobile` with the message URL
62+
instead.
63+
64+
| This is the Message | Long press and Share | Tap Copy |
65+
|---------------------------|---------------------------|---------------------------|
66+
|![](docs/mobileselect1.png)|![](docs/mobileselect2.png)|![](docs/mobileselect3.png)|
67+
68+
![](docs/mobileselect4.png)
69+
70+
## Adding a Role to the Message
71+
Use the `/role add` slash command to add a role to the message.
72+
73+
![](docs/roleadd.png)
74+
75+
You can also remove a role from the message using `/role remove`, or remove
76+
all roles from the message using `/role remove-all`. This will remove all
77+
reactions from the post, but **will not** unassign any roles.
78+
79+
## Making Two Roles Mutually Exclusive
80+
Use the `/mutex add` slash command to make two (or more) roles mutually
81+
exclusive. If a user tries to add two roles that are mutually exclusive, the bot
82+
will automatically remove the first one they had. You can have multiple mutually
83+
exclusive groups.
84+
85+
This setting is **server-wide**. If roles A, B, and C are all mutually
86+
exclusive, when a user with roles B and C tries to assign role A, the bot will
87+
automatically remove roles B and C from them **even if those roles were not
88+
assigned by the bot in the first place**.
89+
90+
Due to current Discord limitations, you can only add two roles per-command, so
91+
you'll need to run the command several times to make more than two roles
92+
mutually exclusive (once again, sorry).
93+
94+
![](docs/mutexadd.png)
95+
96+
Use `/mutex remove` to remove to mutually exclusive restriction on two roles.
97+
98+
## Adding Roles That Can Configure The Bot
99+
By default, the bot will only listen to users who have the "Administrator"
100+
permission. You can use `/permission add` to add additional roles that are
101+
allowed to configure the bot in your guild.
102+
103+
![](docs/permadd.png)
104+
105+
Use `/permission remove` to disallow a role from configuring the bot.<br/>
106+
**Note:** A user can remove their own permission to configure the bot if they
107+
are not an administrator!
108+
109+
## Delete All Configuration In Server
110+
You can use `/reset-everything` to remove *all* configuration the bot has for
111+
the guild the command was sent from. The bot does this automatically when it is
112+
kicked from a guild.
113+
114+
This does not clear any server-side logs for the guild.
115+
116+
## Printing Bot Info
117+
You can use `/info` to print the bot's description, version number, link to the
118+
source code, and some fun stats. This command is available to all users and
119+
posts **non-ephemeral** replies (i.e. visible to everybody).
120+
121+
![](docs/info.png)
129122

130123
## Rate Limits
131124
If the bot is taking a few moments to respond to reactions, it is likely hitting
132125
Discord's strict rate limit. This happens most often with mutually exclusive
133126
roles, since the bot needs to make several requests to make them work. The bot
134127
is registering the actions. Give it a few seconds to catch up.
135128

129+
## @everyone
130+
Discord implements `@everyone` as a role under the hood. This means you can set
131+
up react roles for `@everyone` like you would for any other role. It's silly, it
132+
won't do anything, but you *could* do it...
133+
136134
## Hosting your own instance
137-
This bot is built on [discord.js](https://discord.js.org/#/) v12, so you'll need
138-
Node.js 12.0.0 (or newer) installed. You will also need your own Discord bot
139-
account.
140-
141-
The `resources` directory has a service file that can be used with Linux distros
142-
with systemd. If you're installing this on some other operating system, you're
143-
on your own.
144-
145-
### Running as a service
146-
The provided service file expects to find the bot code at
147-
`/srv/discord/ReactionRoleBot/`, and will want to create the sqlite database at
148-
`/srv/discord/rolebot.sqlite`. The easiest way to do this is to create a
149-
`/srv/discord` directory, and `chown` it so it belongs to the user running the
150-
bot.
151-
152-
The following will prepare the bot to run. Run this from `/srv/discord`:
153-
```
154-
git clone https://github.com/Mimickal/ReactionRoleBot.git
155-
cd ReactionRoleBot
156-
npm install
157-
NODE_ENV=prod npm run knex migrate:latest
158-
```
159-
160-
Create a file `/etc/discord/ReactionRoleBot/token` and paste your bot token in,
161-
in plain text.
162-
163-
Install `reactionrolebot.service` into `/etc/systemd/system/`.
164-
165-
Now you should be able to run `systemctl restart reactionrolebot.service` to
166-
start your bot.
167-
168-
### Running locally (in dev-mode)
169-
Run this wherever you want:
170-
```
171-
git clone https://github.com/Mimickal/ReactionRoleBot.git
172-
cd ReactionRoleBot
173-
npm install
174-
npm run knex migrate:latest
175-
```
176-
177-
Create a file containing your bot token in plain text.
178-
179-
Run this to start the bot: `node main.js path/to/your/token`
135+
[See the guide here](docs/hosting.md).
136+
137+
If you are upgrading from version 1.x, [see the migration guide](
138+
docs/migrate.md).
139+
140+
## License
141+
Copyright 2020 [Mimickal](https://github.com/Mimickal)
142+
143+
This code is licensed under the
144+
[AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0-standalone.html) license.
145+
146+
Basically, any modifications to this code must be made open source.

0 commit comments

Comments
 (0)