Emcee

A Discord bot to facilitate organising Yu-Gi-Oh! tournaments online using Challonge and verify submitted decks. Special thanks to Joseph Rothschild aka MBT for sponsoring the development of Emcee.

Emcee automates the tedious tasks of the sign-up process, deck checks, and tracking match scores for tournament hosts. This frees up hosts to focus on the overall flow of the tournament and any disputes instead of a lot of repetitive work. It currently supports hosting Swiss tournaments of up to 256 participants (a limitation of Challonge's standard tier) with an optional single-elimination top cut of configurable size. Submitted deck files (.ydk) or ydke:// URLs are automatically verified against the current TCG card pool and Forbidden & Limited List, or a tournament host-provided custom card pool. This was used for the Chalislime Monthly tournament series.

A secondary manual mode only provides a tournament registration workflow independent of Challonge. Prospective participants submit screenshots of their deck, such as from Yu-Gi-Oh! Master Duel, and tournament hosts manually approve or reject these submitted decks. The registered participant list may be downloaded at any time for use with other tournament software. This was used for the Master Circuit Series. Please contact us in the support server to enable the manual mode in your server.

❗ Request for Comments: Emcee's future is uncertain. Your input is appreciated!

Discord permissions

Please make sure you use an invite link that automatically grants the following permissions.

• Manage Roles: Emcee creates a role to designate Tournament Organisers upon joining a server and will create and delete participant roles for each tournament.
• Send Messages
• Manage Messages: Emcee automatically removes reactions from "reaction buttons" if participants are dropped via commands.
• Embed Links: Emcee sends deck profiles in the form of a Discord rich embed.
• Attach Files: Emcee attaches a YDK file to deck profiles.
• Read Message History
• Add Reactions: Emcee uses a "reaction button" for tournament registration.

Privileged gateway intents required:

• Server members intent: Emcee removes participants from tournaments if they leave the server.

Usage

After Emcee joins your server, you can ping it to confirm that it is working. You can set permissions for Emcee so it is allowed to access only specific channels and locked out of the rest. If you do not want people to use Emcee in a channel, deny Emcee access to the channel. However, if Emcee does have access to a channel, make sure it has the full range of permissions listed above.

When Emcee joins your server, it will automatically create an MC-TO role to identify tournament hosts. Give this role to anybody who needs to be able to control Emcee to host tournament. Only users with the role will be allowed to list all tournaments on the server and create new ones. For developers, the name of the role can be changed by the EMCEE_DEFAULT_TO_ROLE environment variable. In the future, the name and colour of this role will be configurable per server. For now, please do not delete the role, rename the role, or create another role with the same name — Emcee will lose track of the role and recreate it, or worse, identify authorised hosts with the incorrect role.

The default prefix for all Emcee commands is mc!. For developers, this can be changed by the EMCEE_DEFAULT_PREFIX environment variable. In the future, this will also be configurable per server. We may add support for Discord slash commands in future when the feature is stable in Discord.

• Commands for tournament hosts
• Commands for participants

Support server

Development

Emcee is written in TypeScript. It targets Node.js 20+ and can be run with or without Docker. It uses Discord.js to talk to Discord and PostgreSQL for persistence.

1. Install Docker with Docker Compose, or install PostgreSQL.

2. Start Postgres. You can start up just the Postgres container with docker-compose up -d postgres.

3. Create a .env file with the required credentials and configuration. Examples below:

   • In Docker:

     POSTGRES_HOST_PORT=127.0.0.1:5432
     POSTGRES_USER=
     POSTGRES_PASSWORD=
     POSTGRES_DB=
     DISCORD_TOKEN=
     CHALLONGE_USERNAME=
     CHALLONGE_TOKEN=
     OCTOKIT_TOKEN=
     EMCEE_DEFAULT_PREFIX=mc!
     EMCEE_DEFAULT_TO_ROLE=MC-TO
     

   • Outside Docker:

     NODE_ENV=development
     DEBUG=emcee:*
     POSTGRESQL_URL=postgresql://USER:PASSWORD@localhost:5432/DBNAME
     DISCORD_TOKEN=
     CHALLONGE_USERNAME=
     CHALLONGE_TOKEN=
     OCTOKIT_TOKEN=
     EMCEE_DEFAULT_PREFIX=mc!
     EMCEE_DEFAULT_TO_ROLE=MC-TO
     

4. Start Emcee.

   • In Docker: docker-compose up --build and wait for the image to build.
   • Outside Docker: yarn && yarn build && node --enable-source-maps dist.

Please use Australian English spellings.

Licence

Copyright © 2020–2024 Luna Brand, Kevin Lu. See COPYING for more details.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.