Rocketsoup 1 месяц назад
Родитель
Сommit
b2fcc4a06e
5 измененных файлов: 92 добавлений и 128 удалений
  1. 5
    5
      README.md
  2. 73
    103
      docs/commands.md
  3. 6
    6
      docs/patterns.md
  4. 3
    10
      docs/setup.md
  5. 5
    4
      rocketbot/cogs/bangcommandcog.py

+ 5
- 5
README.md Просмотреть файл

22
 
22
 
23
 See main document, [docs/commands.md](Commands).
23
 See main document, [docs/commands.md](Commands).
24
 
24
 
25
-* To see the list of commands, type `$rb_help`.
26
-* To get help on a specific command, type `$rb_help commandname` (don't prefix the command name you want help on). E.g. `$rb_help hello`.
27
-* To get help on a command group, type `$rb_help groupname`. E.g. `$rb_help config`.
28
-* To get help on a subcommand in a group, type `$rb_help groupname commandname`. E.g. `$rb_help config setwarningchannel`.
29
-* To see if the bot is alive, type `$rb_hello`.
25
+* To see the list of commands, type `/help`.
26
+* To get help on a specific command, type `/help /commandname`. E.g. `/help /hello`.
27
+* To get help on a command group, type `/help /groupname`. E.g. `/help /config`.
28
+* To get help on a subcommand in a group, type `/help /groupname commandname`. E.g. `/help config setwarningchannel`.
29
+* To see if the bot is alive, type `/hello`.

+ 73
- 103
docs/commands.md Просмотреть файл

4
 typically have a master switch to enable/disable it and some other configuration.
4
 typically have a master switch to enable/disable it and some other configuration.
5
 Configuration is specific to each server the bot is invited to.
5
 Configuration is specific to each server the bot is invited to.
6
 
6
 
7
-For all the examples here, I'm assuming the default command prefix of `$rb_`.
8
-If you set a different one in `config.py`, translate accordingly.
9
-
10
 ## Log channel
7
 ## Log channel
11
 
8
 
12
 The first thing you'll want to do is configure a channel where bot messages
9
 The first thing you'll want to do is configure a channel where bot messages
14
 type
11
 type
15
 
12
 
16
 ```
13
 ```
17
-$rb_config setwarningchannel
14
+/config setwarningchannel
18
 ```
15
 ```
19
 
16
 
20
 This ensures warnings will go somewhere appropriate.
17
 This ensures warnings will go somewhere appropriate.
23
 their attention. E.g. to tag the `@Mod` role type
20
 their attention. E.g. to tag the `@Mod` role type
24
 
21
 
25
 ```
22
 ```
26
-$rb_config setwarningmention @Mod
23
+/config setwarningmention @Mod
27
 ```
24
 ```
28
 
25
 
29
 Entering that will configure who to mention, and it will also mention them right
26
 Entering that will configure who to mention, and it will also mention them right
33
 ## Help!!
30
 ## Help!!
34
 
31
 
35
 I don't remember the commands for my own bot, so I don't expect you will either.
32
 I don't remember the commands for my own bot, so I don't expect you will either.
36
-The only thing you need to remember is `$rb_help`. The bot will reply with a
37
-summary of all the top-level commands available. As an example:
38
-
39
-```
40
-Auto Kick:
41
-  autokick       Automatically kicks all new users as soon as they join
42
-Configuration:
43
-  config         Manages general bot configuration
44
-Crosspost Detection:
45
-  crosspost      Manages crosspost detection and handling
46
-General:
47
-  deletemessages Mass deletes messages
48
-  hello          Simple test reply
49
-  shutdown       Shuts down the bot
50
-  testwarn       Posts a test warning
51
-Join Age:
52
-  joinage        Tracks recently joined users with options to mass kick or ban
53
-Join Raids:
54
-  joinraid       Manages join raid detection and handling
55
-Logging:
56
-  logging        Manages event logging
57
-Pattern Matching:
58
-  pattern        Manages message pattern matching
59
-URL Spam:
60
-  urlspam        Manages URL spam detection
61
-Username Pattern:
62
-  username       Manages username pattern detection
63
-No Category:
64
-  help           Shows this message
65
-
66
-Type $rb_help command for more info on a command.
67
-You can also type $rb_help category for more info on a category.
68
-```
69
-
70
-Each section is known internally as a "cog". If you're mucking around in the code,
71
-each cog is its own source file in the `rocketbot/cogs` directory. But you can
72
-just think of them as categories. Some of these are commands of their own (e.g.
73
-`hello`, invoked with `$rb_hello`) but most have subcommands. You can find out
74
-more using `$rb_help commandname`, e.g. `$rb_help config` will show subcommands for
33
+The only thing you need to remember is `/help`. Typing the command alone will show
34
+a top-level list of commands available. You can optionally search for commands
35
+or keywords by typing `/help <keywords>`. As you type, matching suggestions will
36
+appear in an autocomplete list. You can search for commands, subcommands, modules,
37
+or keywords.
38
+
39
+Each section is known internally as a "cog," though I try to refer to them as
40
+"modules" externally to be a little less jargony. If you're mucking around in
41
+the code, each cog is its own source file in the `rocketbot/cogs` directory.
42
+But you can just think of them as categories. Some of these are top-level commands
43
+(e.g. `/hello`) but most have subcommands. You can find out more using
44
+`/help <commandname>`, e.g. `/help config` will show subcommands for
75
 config.
45
 config.
76
 
46
 
77
-```
78
-$rb_config
47
+And then you can invoke a subcommand with `/commandname subcommandname`. e.g.
48
+`/config setwarningchannel`. To get more info about a subcommand, use `/help`
49
+again. e.g. `/help /config setwarningchannel`.
79
 
50
 
80
-General guild configuration command group
51
+## Configuration
81
 
52
 
82
-Commands:
83
-  getwarningchannel Shows the mod warning channel
84
-  getwarningmention Shows the user/role to mention in warning messages
85
-  setwarningchannel Sets the mod warning channel
86
-  setwarningmention Sets a user/role to mention in warning messages
53
+There are four top-level commands used for configuring most functionality.
87
 
54
 
88
-Type $rb_help command for more info on a command.
89
-You can also type $rb_help category for more info on a category.
90
-```
55
+- `/get <setting>` - Shows the current value for a configuration setting.
56
+- `/set <setting> <new_value>` - Sets a new value.
57
+- `/enable <module>` - Enables a module.
58
+- `/disable <module>` - Disables a module.
59
+
60
+You can also use
91
 
61
 
92
-And then you can invoke a subcommand with `$rb_commandname subcommandname`. e.g.
93
-`$rb_config setwarningchannel`. To get more info about a subcommand, use `$rb_help`
94
-again. e.g. `$rb_help config setwarningchannel`.
62
+- `/get all` - Shows all configuration settings and their current values.
95
 
63
 
96
 ## Cogs
64
 ## Cogs
97
 
65
 
98
-This section goes through each cog, what it does, and how to use it.
66
+This section goes through each cog, what it does, and how to use it. While I
67
+will try to keep this document up to date, the most authoritative info is via
68
+the `/help` command since that info lives right there with the code.
99
 
69
 
100
 ### Autokick
70
 ### Autokick
101
 
71
 
106
 supervise and disable as soon as the threat has passed.
76
 supervise and disable as soon as the threat has passed.
107
 
77
 
108
 Subcommands
78
 Subcommands
109
-- `enable`/`disable` - Toggle autokicking
110
-- `getbancount`/`setbancount` - If the same person keeps rejoining after being
79
+- `/enable` or `/disable autokick` - Toggle autokicking
80
+- `/get` or `/set autokick_bancount` - If the same person keeps rejoining after being
111
     kicked, ban them after this many rejoins.
81
     kicked, ban them after this many rejoins.
112
-- `getofflineonly`/`setofflineonly` - Whether to only kick users who join with
82
+- `/get` or `/set autokick_offlineonly` - Whether to only kick users who join with
113
     a status of offline. That's not impossible in ordinary use, but it's
83
     a status of offline. That's not impossible in ordinary use, but it's
114
     suspect and likely indicative of bots versus real users.
84
     suspect and likely indicative of bots versus real users.
115
 
85
 
118
 General config that isn't specific to one cog.
88
 General config that isn't specific to one cog.
119
 
89
 
120
 Subcommands
90
 Subcommands
121
-- `getwarningchannel`/`setwarningchannel` - Determines the channel where log
91
+- `/config get_warning_channel` or `set_warning_channel` - Determines the channel where log
122
     messages are posted. Setting the warning channel doesn't take an argument; it
92
     messages are posted. Setting the warning channel doesn't take an argument; it
123
     uses the current channel you typed the command in.
93
     uses the current channel you typed the command in.
124
-- `getwarningmention`/`setwarningmention` - The user or role you want tagged when
94
+- `/config get_warning_mention` or `set_warning_mention` - The user or role you want tagged when
125
     the bot needs to alert someone of suspicious activity. Needs to be a proper
95
     the bot needs to alert someone of suspicious activity. Needs to be a proper
126
     autocompleted @ mention, not just the name.
96
     autocompleted @ mention, not just the name.
127
 
97
 
98
+### Bang Commands
99
+
100
+Bang commands are one-word chat commands starting with an exclamation (a "bang")
101
+similar to what Twitch bots use. When a user types the command by itself in a
102
+message, the bot will respond with the configured text. E.g. a `!rules` command
103
+can be defined that summarizes the guild rules, and typing `!rules` in chat
104
+will get a reply with the list of rules.
105
+
106
+Subcommands
107
+- `/command define` - Defines a command or redefines an existing one.
108
+- `/command undefine` - Deletes a previously created command.
109
+- `/command list` - Lists all defined commands.
110
+- `/command invoke` - Silently invokes a bang command without typing anything visible in chat
111
+
128
 ### Crosspost detection
112
 ### Crosspost detection
129
 
113
 
130
 Detects an extremely common pattern we see of someone joining and copy/pasting
114
 Detects an extremely common pattern we see of someone joining and copy/pasting
134
 time span, it's ban hammer time.
118
 time span, it's ban hammer time.
135
 
119
 
136
 Subcommands
120
 Subcommands
137
-- `enable`/`disable` - Master toggle for this entire feature.
138
-- `getwarncount`/`setwarncount` - How many duplicate messages will cause a
121
+- `/enable` or /`disable crosspost` - Master toggle for this entire feature.
122
+- `/get` or `/set crosspost_warncount` - How many duplicate messages will cause a
139
     warning message to be posted that alerts the mods.
123
     warning message to be posted that alerts the mods.
140
-- `getbancount`/`setbancount` - How many duplicate messages should result in an
124
+- `/get` or `/set crosspost_bancount` - How many duplicate messages should result in an
141
     automatic ban. Should be greater than the warning count.
125
     automatic ban. Should be greater than the warning count.
142
-- `gettimespan`/`settimespan` - Sets the time window within which to look for
126
+- `/get` or `/set crosspost_timespan` - Sets the time window within which to look for
143
     duplicates. Value is in seconds. Spammers usually fire these off very quickly,
127
     duplicates. Value is in seconds. Spammers usually fire these off very quickly,
144
     so a minute or less is more than enough.
128
     so a minute or less is more than enough.
145
-- `getminlength`/`setminlength` - For text-only messages, sets the minimum length
129
+- `/get` or `/set crosspost_minlength` - For text-only messages, sets the minimum length
146
     to be considered for duplicate detection. Maybe a benign (but annoying) user
130
     to be considered for duplicate detection. Maybe a benign (but annoying) user
147
     posts "lol" at everything in multiple channels. Use this to filter for that
131
     posts "lol" at everything in multiple channels. Use this to filter for that
148
     case.
132
     case.
152
 These are just general top-level commands, not subcommands.
136
 These are just general top-level commands, not subcommands.
153
 
137
 
154
 Commands
138
 Commands
155
-- `deletemessages <@user> <timespan>` - Manually deletes a bunch of messages by a
139
+- `/delete_messages <@user> <timespan>` - Manually deletes a bunch of messages by a
156
     particular user. Useful if you banned but accidentally forgot to delete
140
     particular user. Useful if you banned but accidentally forgot to delete
157
     recent history, or to clean up after someone had a bit of a manic posting
141
     recent history, or to clean up after someone had a bit of a manic posting
158
     spree. The timespan is a value like "30s" for 30 seconds, "5m" for 5
142
     spree. The timespan is a value like "30s" for 30 seconds, "5m" for 5
159
     minutes, or "1h30m" for an hour and a half. NOTE: This only works for fairly
143
     minutes, or "1h30m" for an hour and a half. NOTE: This only works for fairly
160
     recent messages. You can't use it to delete things posted way back in the
144
     recent messages. You can't use it to delete things posted way back in the
161
     scrollback.
145
     scrollback.
162
-- `hello` - Just for testing bot responsiveness. Or a desperate need to be seen.
163
-- `shutdown` - Terminates the bot. I forgot this was here. I've never needed it.
146
+- `/hello` - Just for testing bot responsiveness. Or a desperate need to be seen.
147
+- `/shutdown` - Terminates the bot. I forgot this was here. I've never needed it.
164
     If somehow the bot goes rogue and you're not there to ctrl+C it, use this.
148
     If somehow the bot goes rogue and you're not there to ctrl+C it, use this.
165
-- `testwarn` - Posts a test mod warning in the configured warning channel with
149
+- `/testwarn` - Posts a test mod warning in the configured warning channel with
166
     the configured mention user/role.
150
     the configured mention user/role.
167
 
151
 
168
-### Join age
169
-
170
-This cog isn't really needed any more since the Members tab was added to Discord.
171
-It's used for seeing who joined most recently. The list of recent joins is only
172
-kept in memory, and it keeps a limited number, so it's really only useful for
173
-the past few days.
174
-
175
-Subcommands
176
-- `enable`/`disable` - Toggle join tracking.
177
-- `getjointime`/`setjointime` - How long to track a join, in seconds.
178
-- `search <timespan>` - Shows all users who joined in the last x length of time.
179
-    Values are like `30s` for 30 seconds, `5m` for 5 minutes, `1h30m` for an hour
180
-    and a half, etc.
181
-
182
 ### Join raids
152
 ### Join raids
183
 
153
 
184
 While not as common in the past year or two, we used to get a suspicious number
154
 While not as common in the past year or two, we used to get a suspicious number
187
 spikes in joins.
157
 spikes in joins.
188
 
158
 
189
 Subcommands
159
 Subcommands
190
-- `enable`/`disable` - Toggle the feature.
191
-- `getjoincount`/`setjoincount` - Sets the minimum number of suspicious joins.
192
-- `getjointime`/`setjointime` - Sets the span of time that number of joins must
160
+- `/enable` or `/disable joinraid` - Toggle the feature.
161
+- `/get` or `/set joinraid_joincount` - Sets the minimum number of suspicious joins.
162
+- `/get` or `/set joinraid_jointime` - Sets the span of time that number of joins must
193
     occur to be suspicious, in seconds.
163
     occur to be suspicious, in seconds.
194
 
164
 
195
 ### Logging
165
 ### Logging
201
 that, logging as many meaningful events as possible.
171
 that, logging as many meaningful events as possible.
202
 
172
 
203
 Subcommands
173
 Subcommands
204
-- `enable`/`disable` - You get the full firehose or you get nothing.
174
+- `/enable` or `/disable logging` - You get the full firehose or you get nothing.
205
 
175
 
206
 ### Patterns
176
 ### Patterns
207
 
177
 
210
 of complex and is detailed in its [own document](patterns.md).
180
 of complex and is detailed in its [own document](patterns.md).
211
 
181
 
212
 Subcommands
182
 Subcommands
213
-- `add ...` - Adds a new pattern to look for (see [Patterns](patterns.md)).
214
-- `remove <name>` - Removes a previously added pattern by name.
215
-- `list` - Show all configured patterns.
216
-- `setpriority <name> <priority>` - Alters the priority of a pattern. The
183
+- `/pattern add ...` - Adds a new pattern to look for (see [Patterns](patterns.md)).
184
+- `/pattern remove <name>` - Removes a previously added pattern by name.
185
+- `/pattern list` - Show all configured patterns.
186
+- `/pattern setpriority <name> <priority>` - Alters the priority of a pattern. The
217
     priority is a unitless value used to pick which pattern wins if a message
187
     priority is a unitless value used to pick which pattern wins if a message
218
     matches more than one. Patterns without priorities set have a default value
188
     matches more than one. Patterns without priorities set have a default value
219
     of 100. The highest value wins.
189
     of 100. The highest value wins.
241
 the `https://`). Our deceptive link detection catches these URL-like link labels.
211
 the `https://`). Our deceptive link detection catches these URL-like link labels.
242
 
212
 
243
 Subcommands
213
 Subcommands
244
-- `enable`/`disable` - Toggle the feature.
245
-- `getjoinage`/`setjoinage` - Sets the length of time after joining when posted
214
+- `/enable` or `/disable urlspam` - Toggle the feature.
215
+- `/get` or `/set urlspam_joinage` - Sets the length of time after joining when posted
246
     links are considered suspicious, in seconds.
216
     links are considered suspicious, in seconds.
247
-- `getaction`/`setaction` - Action to take when a join age link is detected.
217
+- `/get` or `/set urlspam_action` - Action to take when a join age link is detected.
248
     One of these values:
218
     One of these values:
249
     - `nothing` - Ignore
219
     - `nothing` - Ignore
250
     - `modwarn` - Post a warning message in the log channel and tag mods.
220
     - `modwarn` - Post a warning message in the log channel and tag mods.
251
     - `delete` - Delete the message.
221
     - `delete` - Delete the message.
252
     - `kick` - Kick the user.
222
     - `kick` - Kick the user.
253
     - `ban` - Ban the user.
223
     - `ban` - Ban the user.
254
-- `getdeceptiveaction`/`setdeceptiveaction` - Action to take when a deceptive
224
+- `/get` or `/set urlspam_deceptiveaction` - Action to take when a deceptive
255
     link is detected. One of these values:
225
     link is detected. One of these values:
256
     - `nothing` - Ignore
226
     - `nothing` - Ignore
257
     - `modwarn` - Post a warning message in the log channel and tag mods.
227
     - `modwarn` - Post a warning message in the log channel and tag mods.
272
 substring matched case-insensitively.
242
 substring matched case-insensitively.
273
 
243
 
274
 Subcommands
244
 Subcommands
275
-- `enable`/`disable` - Toggle the feature.
276
-- `add <pattern>` - Adds a substring to look for in usernames of newly joined members.
277
-- `remove <pattern>` - Removes a pattern.
278
-- `list` - Lists all tracked patterns.
245
+- `/enable` or `/disable username` - Toggle the feature.
246
+- `/username add <pattern>` - Adds a substring to look for in usernames of newly joined members.
247
+- `/username remove <pattern>` - Removes a pattern.
248
+- `/username list` - Lists all tracked patterns.

+ 6
- 6
docs/patterns.md Просмотреть файл

4
 complexity without needing to make code changes in the bot and redeploy it. A
4
 complexity without needing to make code changes in the bot and redeploy it. A
5
 guild can have any number of custom patterns. The commands are:
5
 guild can have any number of custom patterns. The commands are:
6
 
6
 
7
-* `$rb_pattern add <name> <statement>` - Add a new named pattern
8
-* `$rb_pattern remove <name>` - Remove a named pattern
9
-* `$rb_pattern list` - List all named patterns
7
+* `/pattern add <name> <statement>` - Add a new named pattern
8
+* `/pattern remove <name>` - Remove a named pattern
9
+* `/pattern list` - List all named patterns
10
 
10
 
11
 The pattern `<name>` can be anything. If it contains spaces, enclose it in
11
 The pattern `<name>` can be anything. If it contains spaces, enclose it in
12
 double quotes, e.g. `"my filter"`.
12
 double quotes, e.g. `"my filter"`.
152
 Automatically delete a banned word:
152
 Automatically delete a banned word:
153
 
153
 
154
 ```
154
 ```
155
-$rb_pattern add "bad word" delete if content.plain contains "darn"
155
+/pattern add "bad word" delete if content.plain contains "darn"
156
 ```
156
 ```
157
 
157
 
158
 Ban anyone who posts a URL within the first 30 minutes of joining the server.
158
 Ban anyone who posts a URL within the first 30 minutes of joining the server.
159
 
159
 
160
 ```
160
 ```
161
-$rb_pattern add "url spam" ban if author.joinage < 30m and (content.plain contains "http://" or content.plain contains "https://")
161
+/pattern add "url spam" ban if author.joinage < 30m and (content.plain contains "http://" or content.plain contains "https://")
162
 ```
162
 ```
163
 
163
 
164
 Automatically reply to anyone asking when lunch is.
164
 Automatically reply to anyone asking when lunch is.
165
 
165
 
166
 ```
166
 ```
167
-$rb_pattern add "lunch" reply "Lunch is at noon." if content.plain == "When is lunch?"
167
+/pattern add "lunch" reply "Lunch is at noon." if content.plain == "When is lunch?"
168
 ```
168
 ```
169
 
169
 
170
 ## Grammar
170
 ## Grammar

+ 3
- 10
docs/setup.md Просмотреть файл

62
 setting files are a good candidate for timely backups, btw, if that influences
62
 setting files are a good candidate for timely backups, btw, if that influences
63
 your choice. Maybe a synced cloud folder?)
63
 your choice. Maybe a synced cloud folder?)
64
 
64
 
65
-If you'd like, you can also change the command prefix. The bot recognizes commands
66
-by looking for messages that start with this prefix. E.g. if the prefix is `$rb_`
67
-(the default) then typing the message `$rb_help` will invoke the `help` command
68
-and respond with a list of other commands.
69
-
70
 ## Run the script
65
 ## Run the script
71
 
66
 
72
 I wrote this for Python 3.9, and its only dependency is the Discord.py library.
67
 I wrote this for Python 3.9, and its only dependency is the Discord.py library.
86
     python main.py
81
     python main.py
87
     ```
82
     ```
88
 
83
 
89
-It will take a few seconds to connect and when you see output like this it means
90
-it's ready and listening for things to happen.
84
+It will take a few seconds to connect and set itself up, and when you see output like this
85
+it means it's ready and listening for things to happen.
91
 
86
 
92
 ```
87
 ```
93
-[2025-12-11T16:30:51|-|-] Bot initializing...
94
-[2025-12-11T16:30:51|-|-] Type $rb_help in Discord for available commands.
95
 [2025-12-11T16:30:52|GeneralCog|-] Connected
88
 [2025-12-11T16:30:52|GeneralCog|-] Connected
96
 [2025-12-11T16:30:54|GeneralCog|-] Bot done initializing
89
 [2025-12-11T16:30:54|GeneralCog|-] Bot done initializing
97
 ----------------------------------------------------------
90
 ----------------------------------------------------------
122
 
115
 
123
 ## Configure bot for your server
116
 ## Configure bot for your server
124
 
117
 
125
-You can verify the bot is working by typing `$rb_hello` in chat on that server
118
+You can verify the bot is working by typing `/hello` in chat on that server
126
 and it should reply to you.
119
 and it should reply to you.
127
 
120
 
128
 The bot has a number of "cogs" (a term the Discord.py library uses) for distinct
121
 The bot has a number of "cogs" (a term the Discord.py library uses) for distinct

+ 5
- 4
rocketbot/cogs/bangcommandcog.py Просмотреть файл

43
 			bot,
43
 			bot,
44
 			config_prefix='bangcommand',
44
 			config_prefix='bangcommand',
45
 			short_description='Provides custom informational chat !commands.',
45
 			short_description='Provides custom informational chat !commands.',
46
-			long_description='Bang commands are simple one-word messages starting with an exclamation '
47
-							 '(bang) that will make the bot respond with simple informational replies. '
48
-							 'Useful for posting answers to frequently asked questions, reminding users '
49
-							 'of rules, and similar.'
46
+			long_description='Bang commands are simple one-word chat messages starting with an exclamation '
47
+							 '(a "bang") that will make the bot respond with simple informational replies. '
48
+							 'This functionality is similar to Twitch bots. Useful for posting answers to '
49
+							 'frequently asked questions, reminding users of rules, and similar canned responses. '
50
+							 'Commands can be individually made mod-only or usable by anyone.'
50
 		)
51
 		)
51
 		BangCommandCog.shared = self
52
 		BangCommandCog.shared = self
52
 
53
 

Загрузка…
Отмена
Сохранить