Tournaments¶
This is the guide for the tournaments
cog. Everything you need is here.
[p]
is considered as your prefix.
Tip
If you’re a french user, you should check the website of my public Red instance : https://atos.laggron.red/, the documentation for Tournaments is way more detailed towards end users.
Installation¶
To install the cog, first load the downloader cog, included in core Red.:
[p]load downloader
Then you will need to install the Laggron’s Dumb Cogs repository:
[p]repo add Laggrons-Dumb-Cogs https://github.com/retke/Laggrons-Dumb-Cogs
Finally, you can install the cog:
[p]cog install Laggrons-Dumb-Cogs tournaments
Warning
The cog is not loaded by default. To load it, type this:
[p]load tournaments
Usage¶
The tournaments cog provides advanced tools for organizing your Challonge) tournaments on your Discord server!
From the beginning to the end of your tournament, members of your server will be able to join and play in your tournaments without even creating a Challonge account.
The cog supports the registration and check-in of the tournament, including seeding with Braacket.
Then, once the game starts, just sit down and watch ~~the magic~~ the bot manage everything:
For each match, a channel will be created with the two players of this match.
They have their own place for discussing about the tournament, checking the stage list, banning stages/characters…
The bot checks activity in the channels. If one player doesn’t talk within the first minutes, they will be disqualified.
Once the players have done their match, they can set their score with a command.
Players can also forfeit a match, or disqualify themselves.
As the tournament goes on, outdated channels will be deleted, and new ones will be created for the upcoming matches, the bot is constantly checking the bracket.
The T.O.s, short for Tournament Organizers, also have their set of tools:
Being able to see all the channels and directly talk in one in case of a problem makes their job way easier
If a match takes too long, they will be warned in their channel to prevent slowing down the bracket
They can directly modify the bracket on Challonge (setting scores, resetting a match), and the bot will handle the changes, warning players if their match is cancelled or has to be replayed. A warning is also sent in the T.O. channel.
Players can call a T.O. for a lag test for example, and a message will be sent in the defined T.O. channel
Add to all of this tools for streamers too!
Streamers can add themselves to the tournament (not as a player) and comment some matches
They will choose the matches they want to cast, and also provide informations to players (for example, the room code and ID for smash bros)
If a match is launched but attached to a streamer, it will be paused until it is their turn. They will then receive the informations set above.
The streamer has access to the channels, so that they can also communicate with the players.
This was tested with tournaments up to 256 players, and I can personally confirm this makes the organizers’ job way easier.
Setting up the cog¶
There are multiple settings to configure before starting your tournament.
Most of these settings are optional, unless told.
First, set your Challonge credentials! This is specific to your server.
Use [p]challongeset username <your_challonge_username>
, then
[p]challongeset api
. Do not directly provide your token with the
command, the bot will ask for it in DM, with the instructions.
Warning
Your token must stay secret, as it gives access to your account.
Then you can set the following channels with [p]tset channels
:
announcements
, where the bot announces registration, start and end of the tournament.checkin
, where members will have to check (includes announcement). If this isn’t set, members will be able to check everywhere.queue
, where the bot announces the started matches.register
, where members will be able to register (includes a pinned message with the count of participants updated in real time). If this isn’t set, members will be able to register everywhere.ruleset
, a channel given for the rules of the tournament.scores
, where participants will use the[p]win
command to set their score. If this isn’t set, participants will be able to use this command everywhere.stream
, where sets going on stream will be announced.to
, where the bot warns the T.O.s about important info (bracket modifications, participants asking for help). Setting this is required.
Next step, the roles with [p]tset roles
:
participant
, the role given to all participants when they register. Setting this is required.player
, the role pinged when the registrations are opened. If you set up a registrations channel, it will be unlocked for that role.streamer
, the role that gives access to the streamer commands.to
, gives access to the T.O. commands. This does not include the ``[p]tset`` command.
Attention
The to
role is available if your T.O.s aren’t
moderators in your server. If your T.O.s are moderators or
administrators, use the core commands [p]set addmodrole
and
[p]set addadminrole
instead, which will adapt the permissions of
the entire bot to your mods and admins.
Some additional settings you can set:
[p]tset delay
defines when a player is considered AFK and must be disqualified. This only listens for their first message in their channel, once someone spoke, they’re safe. Defaults to 10 minutes.[p]tset start_bo5
defines at what point you want to move from BO3 format to BO5.[p]tset warntime
customize the warnings sent for match duration.[p]tset register
defines when the registration should start and stop. See details in the registrations section.[p]tset checkin
defines when the check-in should start and stop. See details in the registrations section.[p]tset autostopregister
if registrations should be closed when filled. See details in the registrations section.[p]tset twostageregister
defines a second start for registrations. See details in the registrations section.[p]tset ranking
uses a Braacket ranking for seeding the participants.[p]tset stages/counters
defines a list of legal stages or counters.[p]tset baninfo
define a ban mode (ex: 2-4-1) given to the participants in addition to a player picked for beginning the bans.
Registration and check-in phases¶
The cog handles registrations and check-in, automatic or manual.
Type [p]register start
to start registrations. An announcement will be
sent, and the command [p]in
will be available.
If you configured a registrations channel, the bot will open that channel to your game role and the
[p]in
command will be locked to the channel. There is also a message pinned with the number of participants.
Then type [p]register stop
to end this phase. You can resume it later.
It’s pretty much the same thing for check-in, but you have to keep some things in mind:
The check-in requires all registered participants to confirm their presence by typing
[p]in
again.When ending the check-in, all unchecked participants will be removed.
If you configured a closing date, the bot may send reminders, pinging and/or DMing remaining members. This can be done manually with
[p]checkin call
.
Automatic opening/closing¶
You can configure opening and closing dates for both, based on tournament’s start date.
You have to calculate the number of minutes before the scheduled start time.
Here’s an example situation:
Your tournament starts on Saturday at 3:00 PM
You want registrations to start on Friday at 7:00 PM
You need a check-in on Saturday betweeen 2:00 and 2:40 PM
Registrations should end on Saturday at 2:45 PM
You will have to run the following commands:
[p]tset register 20h 15m
: opens 20 hours and closes 15 minutes before tournament’s start time.[p]tset checkin 1h 20m
: opens 1 hour and closes 20 minutes before tournament’s start time.
Tip
If you’re unsure, the bot will give you the exact date and time calculated for both phases when setting up a tournament, asking for confirmation.
Even with this configured, you can still use the commands to manually start and stop.
Close when complete¶
For large scale tournaments, you may not want to keep the registrations ongoing forever with everyone spamming for a place.
You can make the bot automatically close registrations when the limit of
participants (defined on Challonge) is reached by enabling the setting with
[p]tset autostopregister
.
Two-stage registrations¶
Once again useful for big tournaments that uses the previous setting, you can give a second opening time for registrations.
The bot will try opening registrations if they’re closed, else nothing happens.
Configure that second time with [p]tset twostageregister
.
Let’s use our previous example. Registrations end very soon due to the number of participants, but you want to have last-minute registrations for the places left by check-in. So, as soon as the check-in ends, registrations are re-opened. Then type this :
[p]tset twostageregister 20m
reopens 20 minutes before tournament start.
The configured closing time is still applied.
Manage multiple configurations¶
You can decide to save multiple configurations for the same server, useful if you need different roles, channels, delays or other settings for specific games or rulesets.
You can do that with the [p]tset config
group command.
Create a config with [p]tset config add "Your config"
, then you can edit
settings for that config with the --config
or -c
“flag” at the end
of your command.
Examples:
[p]tset delay 20m --config "Super Smash Bros."
[p]tset roles player League player --config LoL
[p]tset channels ruleset #2v2-smash -c "Smash 2v2"
See the other commands under [p]tset config
for managing them.
See those settings with [p]tset settings --config "Config name"
. If there
are settings not set, the bot will fall back to the default config.
Then, to use that config with your tournament, use [p]setup
with the same
flag as usual.
Tip
If you use the exact name of the game for your config, it will be automatically used when you add the tournament if the name on Challonge matches.
All good! We went across all settings, you can check those with the
[p]tset settings
command.
Add a tournament¶
You can then create a tournament on Challonge.
Make sure the format is correct (single/double elimination), game name set, and start time configured.
Then you can run [p]setup
with the link of your tournament. Check that
all informations are correct then confirm.
Start and manage the tournament¶
Once you consider everything is good (check the bracket online to make sure),
start the tournament with [p]start
.
You may want to make sure participants are uploaded to the bracket with
[p]upload
before (clears previous list and seeding).
Multiple things will occur: first the tournament will be marked as started on Challonge, then the bot will send all the initial messages in the defined channels, and finally, the matchs will be launched.
The beginning is pretty impressive, because a lot of channels will start being created. If you host a 128 players tournament, except 64 new channels in new categories.
First thing to note: if a player does not talk in their channel within the 10
first minutes after the channel creation, they will be disqualified (you can
customize or disable this delay with [p]tset delay
). You are warned of this
in the T.O. channel.
If the bot somehow fails to create a channel, the match will be moved in DM (the bot announces the set in DM, timers and AFK check are therefore disabled).
Players are able to use the [p]lag
command, asking for a lag test. A
message will then be sent in the T.O. channel.
If a set takes too much time, the players will be warned first, then if it is
still not done, a message is sent in the T.O. channel (customizable with
[p]tset warntime
).
You can edit things in the bracket yourself, such as setting a score or even resetting a match. The bot should handle all changes, resulting in matches being terminated (score set), relaunched (score reset) or even cancelled (score reset with child matches ongoing). This will also be announced in the T.O. channel.
The winner of a match will set their score with the [p]win
command, inside
the scores channel if set.
Players can use at any time [p]ff
for forfeiting a match (they can still
continue depending on the tournament mode, such as the usage of a loser
bracket), or [p]dq
for completly disqualifying themselves.
T.O.s can disqualify players with [p]rm
.
Tip
To re-enable a disqualified player (because of an AFK check, or the
[p]dq
/[p]rm
commands), do this directly on the bracket.
On Challonge, go to the participants tab, and click on the “Reactivate” button.
If you need to restart the tournament, use the [p]resetbracket
command.
Channels will be deleted, and the tournament will fall back to its previous
state. You can then either start again with [p]start
or just remove it
with [p]reset
.
Manage streams¶
The cog comes with streaming support, aka managing a stream queue for streamers
who want to share and comment a match. The [p]stream
command is accessible
to anyone, displaying the links of the current streamers. However, the sub
commands are only accessible to mods, T.O.s and streamers (role defined with
[p]tset roles streamer
).
Here are the steps for adding a streamer to the tournament (only accessible once the tournament has started):
Initialize your stream with
[p]stream init <link>
, where<link>
is the URL of your Twitch channel.(Optional) Smash Bros. Ultimate streamers can setup the info of their room (ID + code) that will be shared to the players once it is their turn with
[p]stream set <id> <code>
.Add matches to your stream queue with
[p]stream add
. You can add sets that will start in the future, or even sets that already started (the bot will ping them, either for telling them to go on stream or to stop playing and wait for their turn). You can add multiple sets at once. Example for scheduling the top 4 of a 128 players tournament:[p]stream add 251 252 253 254 255
(the number of the sets can be found on Challonge).Remove scheduled matches with
[p]stream remove
followed by the sets. You can clear your queue with[p]stream remove all
.See the infos about your stream (such as the queue) with
[p]stream info
.Reorder your stream queue with the following commands:
[p]stream swap <set1> <set2>
for swapping the position of two sets in your queue.[p]stream insert <set1> <set2>
for inserting set 1 right before set 2 in the queue.[p]stream reorder
for giving the entire order. This will add or remove sets if they’re different from the previous stream queue.
End your stream with
[p]stream end
, cancelling your queue and sending players back to the game.
You can type [p]stream list
for seeing all streamers. Note that a set
going on stream will be announced in the channel defined with [p]tset
channels stream
.
Tip
Any T.O. or streamer can edit anyone’s stream by providing their channel as the first argument of the command. Examples:
[p]stream add https://twitch.tv/el_laggron 254
[p]stream info el_laggron
This allows you to setup a stream for someone yourself, then transferring
the ownership of this stream with [p]stream transfer
, making things
easier for them.
Additional resources¶
Common Challonge error codes¶
The bot will usually provide an explaination for the most frequeunt error codes from Challonge. Here’s a table in case of:
Error |
Explaination |
---|---|
401 |
|
404 |
|
422 |
Can mean multiple things…
If there’s a case I didn’t mention, error means “Unprocessable entity”, so you’re trying to do something inconsistant for Challonge. Check directly what could be wrong on the bracket. |
502 |
A sadly very common error, meaning Challonge is being unstable again. Just try again later. |
Troubleshooting¶
Having a critical bug in the middle of your tournament can be very annoying,
so this cog provides you advanced tools to attempt a fix while the
tournament is running with the [p]tfix
command.
Warning
Those commands are high-level, and not knowing what you do can
ruin your entire tournament, so please make sure to read the description
of each command with [p]help tfix <your command>
.
First, the commands with the lowest risk level.
One thing to note, the bot fetches informations about the tournament only
during inital setup with [p]setup
. If you changed things like the limit
of participants or the tournament’s name, use [p]tfix refresh
.
Attention
The following things will not be updated with
[p]tfix refresh
:
The game of the tournament (settings are based on this)
Custom URL (the bot will return 404 if you do this, so don’t try)
The tournament’s start date and time. Since registration and check-in opening and closing times are already calculated on this, redoing this process would be too hard to implement, with the ton of additional checks that comes with it.
If anything doesn’t work correctly, try [p]tfix reload
first. This is the
command that does the most: save, delete all objects we have in memory, then
rebuild the objects from what’s saved on disk. Sounds like a lot, but this one
of the most stable functions since I kept spamming reloads when coding and
testing, so any issue with this was quickly fixed. However, if something wrong
happens, don’t panic, and use the next command.
[p]tfix restore
can be used to attempt loading a tournament that is
saved on disk but not on the bot. If your bot suddenly tells you “There is
no tournament setup” (or the previous command failed), then you’re looking for
this. If there are more issues, check the details in the logs, or ask a bot
administrator to help you.
Before explaining the next commands, let me explain what is the background loop task. This is a task launched when you start your tournament that runs every 15 seconds, and does the following things :
Update the internal list of participants
Update the internal list of matches
Launch pending matches
Check for AFK players (someone didn’t talk within the first 10 minutes in their channel, configurable with
[p]tset delay
), and delete inactive channels (score reported and no message sent for 5 minutes)Call streams
If too many errors occur in this task, it will be stopped, and you may not be
aware of this until you see that new matches stop being launched. You can
check the status of the task with [p]tinfo
.
Suppose you want to edit a lot of things in the bracket yourself, and you don’t
want the bot to create 25 new channels and immediatly delete them, so you want
to pause this background task. Use [p]tfix pausetask
and the bot won’t
start new matches or look for bracket changes anymore.
You can then either use [p]tfix runtaskonce
to only refresh matches and
launch matches once to check, or use [p]tfix resumetask
to fully resume
the task. You can also use this last command to restore a task that bugged.
Finally, the danger zone. Those commands will perform a hard reset and cannot restore what you had, depending on what you chose.
During registration and check-in, you can use [p]tfix resetparticipants
,
which will remove all participants from memory (not from the bracket if already
uploaded). If you want the bot to also remove the members’ participant role,
call [p]tfix resetparticipants yes
, else everyone will keep their roles.
During the tournament, you can use [p]tfix resetmatches
which removes all
matches and participants objects from memory. If the background task is still
running, the list of participants and matches will quickly be fetched back
from the bracket, re-creating fresh objects and new channels. Note that all
match channels existing when you run this command will be forgotten by the bot
and unusable. Like the command above, you can call [p]tfix resetmatches yes
to make the bot delete all channels.
At whatever phase of the tournament, you can use [p]tfix hardreset
. See
this as the latest possible option, as this will simply delete all
internal objects, without trying anything else. It’s like a factory reset,
put the bot back to its initial state, regardless of the current state (does
not reset settings). There is no announcement, no DM, no channel
cleared/removed, the bot will just say “There is no tournament” on commands.
Channels and roles will still be in place, everything will just stop. No API
call is sent to the bracket, it will stay as it is.
Before considering this, you must be sure of the consequences. Try to look
into other options first, like [p]reset
, [p]resetbracket
or other
[p]tfix
commands.