Vous êtes TO online, et vous êtes intéressés pour déléguer des tâches pénibles à un bot tout en améliorant l'expérience des joueurs ? Peut-être bien qu'A.T.O.S. (Automated Tournament Organizer for Smash). est fait pour vous. Je vais essayer autant que possible de vous aider dans la démarche d'installation.

Résumé

Certain(e)s parmi vous auront suivi l'aventure depuis un moment ! Si ce n'est pas le cas, je vous invite à consulter les autres articles de ce blog, particulièrement celui-ci. Mais pour la forme, je recommence une explication des principes. A.T.O.S. est donc tout simplement un bot Discord qui utilise Challonge comme gestionnaire de brackets, et peut entre autres :

  • Créer un tournoi régulièrement, ou en fournissant un lien.
  • Prendre en charge les inscriptions, le check-in, les DQ, etc.
  • Lancer les sets : chaque set disposera de son propre channel volatile.
  • Gérer la stream queue des streamers : plus besoin d'envoyer des DM.
  • Transmettre les scores en temps réel à Challonge.
  • Seeder la liste de participants d'après un ranking Braacket.
  • Et quelques commandes utiles !

Contexte de création : c'est le confinement (et au-delà les rassemblements probablement temporairement limités), avec du coup l'avènement du online qui est la solution par défaut de continuer l'entraînement. Qui dit avènement dit affluence, qui dit affluence dit travail pour des TOs. L'idée d'A.T.O.S. est d'aider les TOs à gérer cette affluence tout en gardant une cadence d'évènements intacte.

À propos de l'auteur : Wonderfall, 21 ans, joueur Smash strasbourgeois, peut-être pire main Zelda de France, un peu à l'aise avec les ordinateurs même s'il n'en a pas fait ses études (il est passionné par trop de domaines pour se décider). Il fait ça bénévolement et ne demande rien en retour donc soyez indulgents (en plus il parle à la troisième personne de lui-même, chaud).

À propos d'A.T.O.S. : bot Discord utilisant Challonge pour la gestion de brackets, écrit en Python, asynchrone, et reposant  sur discord.py et apychal (module pychal modifié par Wonderfall). Le code est gratuit, libre, et ouvert :

Wonderfall/ATOS
Automated Tournament Organizer for Smash (ft. Discord, Challonge). - Wonderfall/ATOS

Pré-requis

Pour installer A.T.O.S., il vous faut :

  • Un cerveau fonctionnel.
  • Du temps, de la patience aussi !
  • Un serveur Discord dont vous êtes administrateur.
  • Un compte Challonge si ce n'est pas déjà fait.
  • Avoir ajouté un compte bot à votre serveur.
  • Un serveur où faire tourner le bot.

Les deux dernières étapes vous font peut-être flipper, mais on y vient très vite.

Organisation du serveur Discord

Pour qu'A.T.O.S. puisse mener à bien sa mission, il faut que vous disposiez sur votre serveur d'une organisation précise. Si vous devez créer un nouveau serveur, vous pouvez partir du template utilisé par le tournoi Smash Void :

Create a server based on ATOS
ATOS

Autrement, suivez bien ces étapes de création :

Channels

  • D'un channel pour les annonces.
  • D'un channel pour les résultats.
  • Optionnel : un channel pour les attributions de rôles.
  • Optionnel : un channel blabla, bref général quoi.
  • Un channel pour le staff (les TOs).
  • Un channel pour les streamers.
  • Un channel pour le ruleset.
  • Un channel pour les inscriptions.
  • Une catégorie nommée "Tournoi".

Cette catégorie Tournoi dont contenir ces différents channels :

  • Un channel de discussion générale.
  • Un channel de check-in.
  • Un channel pour les sets à lancer.
  • Un channel pour la rentrée des scores.

Note : les contenus (messages) de ces 3 derniers channels sont supprimés régulièrement par le bot pour des raisons de clarté.

C'est un exemple : en dehors de la catégorie "Tournoi", vous pouvez être créatifs.

Rôles

Quant aux rôles, il faudra créer :

  • Un rôle TO : ce rôle a accès aux commandes élevées du bot.
  • Un rôle Streamer : explicite.
  • Un rôle Challenger : c'est le rôle des joueurs d'un tournoi.
  • Un rôle Tournoi : comme "Tournoi", ou "SSBU", pour ping.
  • Optionnels : Casters, autres rôles pour chaque jeu, rôles 1v1, etc.
C'est un exemple.

Permissions (suggestions)

  • Catégorie Tournoi : visible et accessible au rôle Challenger.
  • Channel inscriptions : enlever les permissions d'envoi de message (si utilisation du mode "réaction" pour les inscriptions, sinon laissez !), et d'ajout de réaction (n'affecte pas la possibilité de boost une réaction déjà existante).
  • Channel des sets à lancer : enlever les permissions d'envoi de message.
  • Channel scores : enlever les permissions d'ajout de réaction (empêche les rigolos d'ajouter des fausses réactions partout !).
  • Pour les channels staff, casters, streamers : permissions adaptées pour restreindre ces channels aux rôles respectifs.

Ajouter un compte bot sur votre serveur

Vous pouvez suivre ces instructions détaillées en images : https://discordpy.readthedocs.io/en/latest/discord.html

Pensez à nommer le bot "A.T.O.S." (vous pouvez changer le surnom plus tard, si vous le voulez), à ajouter un avatar si vous voulez. Et décochez "Public bot", pas la peine et ce n'est pas envisageable.

Enfin, au moment des permissions donnez les permissions Administrateur au bot. On pourrait faire une par une les permissions nécessaires, mais la réalité est que le bot a de toute façon besoin de permissions élevées pour créer des channels, gérer les rôles, etc. De toute façon : le code source est ouvert donc vous pouvez toujours le lire pour voir qu'il ne vous veut rien de mal.

Au terme du tutoriel, si tout s'est bien passé, vous avez un compte Bot sur votre serveur ! Plus qu'à faire "tourner" le code derrière.

Où installer le bot ?

Un compte bot a beau avoir été créé et invité sur votre serveur, cela ne veut pas dire que le bot proprement dit est encore installé. Il doit en effet fonctionner quelque part. Ce "quelque part" peut être :

  • Votre ordinateur (je le déconseille).
  • Un serveur à domicile (pourquoi pas un Raspberry Pi ?).
  • Un serveur dédié.
  • Recommandé : un VPS (Virtual Private Server).

Configurer un serveur

Choix du serveur

En effet, le bot doit préférablement tourner H24. Un ordinateur personnel n'est donc pas adapté, même si techniquement rien n'empêche le bot de tourner dessus.

Un VPS est parfait dans la mesure où la connexion est constante, 24h/24, et que vous ne devez rien gérer d'autre. Voici les services que je recommande et qui sont peu onéreux (on peut tourner à du 2 voire 3€/mois) :

Écosystème cloud scalable pour les développeurs & les entreprises de toutes tailles - Scaleway
Scaleway Elements permet chaque jour à des dizaines de milliers d’entreprises de construire, déployer et faire grandir leurs infrastructures dans le cloud.
SSD VPS Servers, Cloud Servers and Cloud Hosting by Vultr
Vultr Global Cloud Hosting - Brilliantly Fast SSD VPS Cloud Servers. 100% KVM Virtualization
Truly thrifty cloud hosting - Hetzner Online GmbH
Cloud servers starting at € 2.49. A little money gets you lots of cloud. Our flexible billing model and clever interface make it easy to use our cloud servers for all your IT needs.
Amazon EC2
Amazon Elastic Compute Cloud (Amazon EC2) is a web service that provides secure, scalable compute capacity in the cloud. Launch your EC2 instance today.

Si vous optez pour un serveur d'un des prestataires ci-dessus, je vous conseille une image Debian simple (c'est une distribution Linux).

Installation via Docker (recommandée)

Nous allons suivre une installation via Docker. Docker est, pour vulgariser, la méthode de prédilection pour faire fonctionner A.T.O.S. car vous pouvez le lancer dans le même environnement que moi-même, en s'assurant que tous les pré-requis seront présents d'office. C'est une sorte de mi-chemin entre un "micro-système" et un "package", je peux comprendre que ce soit compliqué au début mais vous me remercierez plus tard !

Vous devez donc avoir installé Docker, que ce soit pour Windows, macOS, ou je l'espère Linux dans le cas d'un VPS :

Get Docker
Home page for Get Docker

Vous devez également avoir installé docker-compose (un outil d'orchestration), qui sur macOS et Linux, s'installe avec la commande suivante :

pip install docker-compose

Si ce n'est pas déjà fait, vous devez avoir installé git sur votre système (apt install git sur Debian). Enfin, placez-vous dans un dossier au choix, puis clonez le code source d'A.T.O.S., et placez-vous dedans :

git clone --branch VERSION https://github.com/Wonderfall/ATOS
cd ATOS

VERSION doit être remplacé par la version d'ATOS que vous souhaitez télécharger. La dernière version en date est la 5.15.

Enfin, pour lancer le bot (configurez d'abord, cf. plus bas) il suffira de faire cette commande :

docker-compose up -d

Voici d'autres commandes utiles :

docker-compose stop # Arrêter le bot
docker-compose restart # Redémarrer le bot
docker-compose down # Arrêter et supprimer l'instance
docker-compose logs # Obtenir des logs

Installation basique

Personnellement, je vous recommande Docker car c'est une "micro-image" qui s'assure que vous disposez de tous les pré-requis, ce qui permet une grande reproductibilité des installations.

Python 3.7 et 3.8 sont les seules versions supportées.

Download Python
The official home of the Python Programming Language

Cela dit, si vous avez une allergie à Docker, il est bien entendu possible d'installer le bot sans. Il faut d'abord télécharger son code source (git est requis) :

git clone --branch VERSION https://github.com/Wonderfall/ATOS
cd ATOS

VERSION doit être remplacé par la version d'ATOS que vous souhaitez télécharger. La dernière version en date est la 5.15.

Par la suite il faudra installer les pré-requis avec pip.

pip install -r requirements.txt

Enfin, pour lancer le bot (après avoir configuré) :

python bot.py

Comme dit, je vous conseille quand même la méthode ci-dessus avec Docker.

Configuration et déploiement

Dans le dossier d'ATOS, je vous invite directement à vous intéresser au dossier config car c'est lui qui contient les dossiers qui nous intéressent pour la configuration. Le dossier config contient lui-même 4 fichiers :

  • auto_mode.yml : pour le mode automatique de création de tournoi.
  • config.yml : les paramètres indispensables au fonctionnement du bot.
  • gamelist.yml : liste des jeux supportés par le bot.
  • preferences.yml : paramètres modifiables sans redémarrage du bot.

Les .yml sont des fichiers YAML, ce sont comme des fichiers texte qui suivent une syntaxe simple et intuitive, je l'ai choisie pour que vous puissiez modifier et comprendre sans difficultés. Vous pouvez éditer chaque fichier avec un éditeur de texte, comme nano ou vi en ligne de commande, ou Sublime Text/Notepad++ sur votre ordinateur.

Le plus important est d'abord le config.yml.

config.yml

C'est le fichier qui contient les paramètres indispensables au fonctionnement du serveur. Il détermine quels sont les channels, rôles, catégories, etc. que vous aviez configurés au préalable. Je vais aborder chaque partie :

system:
  debug: True
  greet_new_members: True
  manage_game_roles: True
  language: fr_FR

Je vous conseille de laisser tel quel, mais je vais expliquer :

  • debug : affiche des informations de log divers, peut-être utile au début.
  • greet_new_members : se traduit littéralement par "accueillir les nouveaux membres". Le bot le fera sur le channel "blabla", et enverra aussi un DM à la personne. En changeant True par False, vous pouvez désactiver cette fonction.
  • manage_game_roles : activer ou non la gestion des rôles par réaction dans le channel des rôles.

Si elle est activée, vous aurez à créer un channel "rôles", y désactiver les permissions d'envoi/d'ajout de réaction, puis créer un message et ajouter les réactions souhaitées pour que le bot ajoute le rôle pour chaque "boost" de réaction détecté une fois qu'il sera en ligne :

  • language : à ne pas toucher, de toute façon il n'y a que le français.
paths:
  tournoi: data/tournoi.json
  participants: data/participants.json
  waiting_list: data/waiting_list.json
  stream: data/stream.json
  ranking: data/ranking.csv
  gamelist: config/gamelist.yml
  auto_mode: config/auto_mode.yml
  preferences: config/preferences.yml

Ce sont les chemins vers les différents fichiers utilisés par le bot (en dehors de config.yml qui sera toujours config/config.yml), je vous conseille de ne pas y toucher en dehors d'une installation particulière et/ou en connaissance de cause.

discord:
  secret: xxxxxxxxxxxxxxxxxxxxx
  guild: 000000000000000000
  prefix: '!'
  channels:
    blabla: 000000000000000000
    annonce: 000000000000000000
    check_in: 000000000000000000
    inscriptions: 000000000000000000
    scores: 000000000000000000
    stream: 000000000000000000
    queue: 000000000000000000
    tournoi: 000000000000000000
    deroulement: 000000000000000000
    faq: 000000000000000000
    resultats: 000000000000000000
    roles: 000000000000000000
    to: 000000000000000000
  categories:
    tournoi: 000000000000000000
  roles:
    challenger: 000000000000000000
    to: 000000000000000000
    streamer: 000000000000000000
  emojis:
    logo: <:logo:000000000000000000>
Les valeurs servent d'exemple, il faudra remplacer par les vôtres.

C'est la partie où vous allez définir des choses intéressantes.

secret : c'est le token, ou le code si vous voulez, utilisé par le bot pour s'authentifier sur le compte bot que vous avez invité sur votre serveur juste avant. Si vous avez bien suivi le tutoriel, vous avez copié de côté un "token", et c'est celui-ci qui doit être rentré pour secret. Attention, ce code doit rester secret, ne le partagez à personne.

Pour tout le reste, il va falloir tout d'abord passer votre compte Discord en mode développeur (User Settings > Appearance > dans "Advanced", activer "Developer Mode"). Le mode développeur vous rajoute une option quand vous faites un clic droit sur un élément Discord (l'icône de votre serveur, un channel, un rôle, une catégorie...) : celle de pouvoir copier/coller l'ID de cet élément.

guild : vous devez faire un clic droit sur l'icône de votre serveur (par ailleurs, "guild" veut dire "serveur" dans le langage Discordien), puis copier et enfin coller l'ID dans le config.yml.

prefix : c'est le préfixe des commandes, par exemple !commande si le préfixe est !, ou .commande si le préfixe est ., le but étant d'éviter les conflits avec d'autres potentiels bots sur votre serveur. Pensez à bien entourer, comme dans l'exemple, le préfixe de guillemets simples ('préfixe') ; autrement le bot pourrait mal interpréter.

Pour tous les channels, faites un clic droit sur le channel concerné et collez l'ID. De même pour la catégorie Tournoi, de même pour les rôles (depuis les paramètres du serveur, clic droit sur un rôle), etc.

Note : deux valeurs de channel peuvent être identiques si vous ne souhaitez pas deux channels séparés (imaginons le channel "F.A.Q.", il peut avoir la même valeur que le channel "blabla"), à vous de voir.

Le logo est en fait un emoji custom, le logo de votre serveur qui doit être uploadé en tant qu'emote sur votre serveur. Il sert à des fins esthétique, on va dire. Mais ce n'est pas son ID qui doit être rentré, c'est son code complet qui s'obtient en tapant et en envoyant ceci dans n'importe quel channel de votre serveur :

\:logo:

Notez bien le backslash \ (qui n'est pas un slash simple /).

Dans mon cas, c'est "<:smashvoid:689537348689592354>" que je vais mettre dans le config.yml.

Enfin, la dernière partie à configurer :

challonge:
  user: user
  api_key: api_key

user : c'est votre nom utilisateur sur Challonge.
api_key : c'est votre clé secrète pour accéder à l'API, peut être obtenue dans vos paramètres de compte Challonge.

gamelist.yml

Ce fichier contiendra la liste des jeux que votre bot va supporter. La ponctuation est importante :

  • Super Smash Bros. Ultimate : pour supporter SSBU.
  • Project+ : pour supporter Project+.

Voici la structure pour supporter, par exemple, SSBU :

Super Smash Bros. Ultimate:
  ruleset:
  role:
  role_1v1:
  icon:
  icon_1v1:
  ranking:
    league_name:
    league_id:
  starters:
    - Stage 1
    - Stage 2
    - Stage 3
    - Stage 4
    - Stage 5
    - Stage 6
  counterpicks:
    - Stage 1
    - Stage 2
  • ruleset : c'est l'ID de votre channel qui contient le ruleset à lire.
  • role : c'est l'ID du rôle pour les personnes intéressées par des tournois.
  • role_1v1 : c'est l'ID du rôle pour les personnes intéressées pour du 1v1.
  • icone : c'est l'emoji custom (à obtenir avec backslash) du jeu en question.
  • icone_1v1 : c'est l'emoji qui servira pour la réaction du rôle 1v1 (doit être un emoji de base, comme ⚔️ ou 🥊 ou encore 🎮, etc.).
  • ranking : informations utilisées par le bulk_mode pour récupérer les rankings depuis braacket. Il faudra compléter league_name et league_id :
  • starters : liste des stages légaux (pas counterpicks)
  • counterpicks : liste des stages légaux counterpicks.

Ce qui est en gras est obligatoire, ce qui est en italique ne l'est pas et doit être retiré du fichier si vous ne souhaitez pas utiliser la fonction associée.

auto_mode.yml

Ce fichier est utile si vous activez l'auto-mode. L'auto-mode permet de créer des tournois pré-programmés, de façon régulière, et gère la création du tournoi à votre place. Il est conseillé de ne maintenir qu'un tournoi, mais il n'y a pas de limite : sachez cependant que c'est toujours le tournoi qui arrive le plus tôt qui a priorité (bientôt je réglerai une priorité pour les monthlies).

Super Tournoi:
  capping: 48
  days:
  - Tuesday
  - Thursday
  description: 'Ma jolie description : invitation Discord'
  edition: 14
  game: Super Smash Bros. Ultimate
  start: '20:30'

Je vous propose cet exemple pour un tournoi Super Tournoi :

  • capping : limite du nombre de joueurs.
  • days : jour(s) où se tient le tournoi. Si c'est un jour de la semaine (en anglais par ailleurs) c'est une weekly, si c'est un jour en nombre entier c'est une monthly.
  • description : explicite.
  • edition : explicite.
  • game : un jeu présent dans gamelist.yml.
  • start : heure de début du tournoi, doit suivre ce format précis.

Dans cet exemple : le Super Tournoi est un tournoi pour SSBU capé à 48 joueurs, qui a lieu chaque semaine le mardi et le jeudi, dont la prochaine édition sera la 14e.

Adaptez cet exemple à vos besoins !

preferences.yml

Ce fichier est modifiable à chaud avec les commandes !settings et !set :

Faisons le tour de ces paramètres :

  • auto_mode : activer ou non la création automatique de tournoi (auto-mode.yml doit être valide et complété). Désactivé par défaut.
  • bulk_mode : activer ou non le mode bulk. Le mode bulk consiste à prendre les inscriptions dans la mémoire du bot sans les ajouter directement à Challonge, mais seulement à la fin des inscriptions pour permettre un seeding basé sur le ranking braacket (ranking doit alors être présent dans gamelist.yml). Par défaut (désactivé), le bot prend les inscriptions une à une et ajoute au fur et à mesure sur Challonge (il faudra seeder à la main, c'est possible - mais ne surtout pas DQ quelqu'un directement depuis l'interface !).
  • reaction_mode : déterminer si le bot utilise les réactions ✅ pour les inscriptions/désinscriptions, ou bien des commandes in et out. Par défaut c'est activé, mais pour des gros tournois à plus de 64 joueurs, je recommande de le désactiver pour utiliser des commandes (ajustez les permissions d'envoi de message selon le mode utilisé, bien sûr).
  • use_guild_name : cela dépend du format des peudos que vous voulez utiliser, mais il faut une cohérence avec les pseudos de votre ranking. Par défaut, ce sont les pseudonymes du serveur qui sont inscrits. Si ce mode est désactivé, alors ce sera le pseudonyme général Discord (user#0000, vous voyez).
  • check_in_opening : ouverture en minutes du check-in avant le début du tournoi.
  • check_in_closing : fermeture en minutes du check-in avant le début du tournoi.
  • inscriptions_opening : utilisé uniquement par l'auto-mode si activé, c'est l'ouverture en heures des inscriptions avant le début du tournoi.
  • inscriptions_closing : fermeture en minutes des inscriptions avant le début du tournoi.

Let's go!

  • Vous avez créé la bonne hiérarchie des channels/rôles.
  • Vous avez installé le bot sur un serveur (avec/sans Docker).
  • Vous avez invité un compte bot sur votre serveur Discord.
  • Vous avez configuré les fichiers dans le dossier config.

Vous pouvez lancer le bot selon la méthode d'installation choisie !

Note : avec Docker, vous pouvez accéder aux logs avec docker-compose logs -f si le mode debug est activé dans config.yml. C'est utile pour voir s'il y a un problème, mais si vous n'y comprenez pas grand chose, c'est normal, je pourrai toujours vous aiguiller mais il me faut des informations précises que seul le mode debug peut fournir...

Is it dead, or alive?

Tel un chat de Schrödinger, on pourrait se poser la question. Normalement le bot doit être "en ligne" dans la liste des membres Discord, et avoir comme statut : A.T.O.S.version. Enfin, utilisez la commande !help pour voir s'il répond bien.

Les commandes ?

Je ne vais pas m'étaler dessus, j'ai tout indiqué dans une commande !help :

La commande !help affiche les commandes en fonction de vos rôles.

Cette notice servira plus ou moins de guide d'utilisation. En effet, le bot est pensé pour être simple d'utilisation. Si quelque chose n'est pas clair, merci de m'en faire part.

Merci d'avoir lu !

Que vous ayez ou non installé le bot, merci d'avoir montré de l'intérêt pour ce travail ! Je compte faire un article qui présente en détails chaque fonction du bot d'un point de vue "moins technique" et "davantage grand public", qui servira de vitrine technologique mais aussi de notice d'utilisation destinée aux joueurs, TOs, et streamers. Cet article s'adressait plutôt à l'installation pure et dure pour les premiers courageux désireux de se lancer dans une nouvelle aventure...

It's dangerous to go alone!

En effet... Si besoin, vous pouvez me contacter par différents moyens :

Mieux encore, et je vous le conseille, j'ai créé un Discord dédié pour cela :

Join the A.T.O.S. Discord Server!
Check out the A.T.O.S. community on Discord - hang out with 1 other members and enjoy free voice and text chat.

Notez que j'aimerais me reposer en ce moment donc essayez de vous débrouiller un maximum par vous-même avant de me contacter même si j'essaie de répondre à toutes les questions quand je peux !

Ces liens de contact peuvent également être utilisés pour proposer des suggestions, même si le mieux pour moi de gérer vos idées est d'ouvrir une issue sur le projet GitHub :

Wonderfall/ATOS
Automated Tournament Organizer for Smash (ft. Discord, Challonge). - Wonderfall/ATOS

Enfin, n'oubliez pas que c'est une première version publique (vous pouvez la voir comme une bêta) et qu'elle est entre autres sujette à :

  • Des bugs que je n'ai pas encore trouvés. J'ai encore notamment des doutes sur la montée en charge une fois les 64 joueurs dépassés.
  • Des évolutions qui seront probablement majeures et nécessiteront une réinstallation. Suivez donc régulièrement ce blog.

N'utilisez pas ce bot pour des tournois critiques sauf si vous êtes sûrs de ce que vous faites, je ne veux pas être responsable d'une catastrophe. Le bot a été créé à la base pour la communauté de Strasbourg, et il sert bien son rôle ; partager ce travail n'est que du bonus, n'oubliez pas !

Ce bot est loin d'être parfait, ni terminé, mais si vous avez à peu près la même idée de moi de ce qu'un TOing online devrait être, je pense que vous pourrez y trouver la même satisfaction que notre équipe de TOs au Smash Void dont je me permets de faire la publicité si vous voulez vous détendre un peu sur SSBU ou Project+ (en plus de bêta test le bot) :

Join the Smash Void Discord Server!
Check out the Smash Void community on Discord - hang out with 225 other members and enjoy free voice and text chat.

Je profite de cette fin d'article pour souligner encore une fois que A.T.O.S. est un concept très simple conçu pour un besoin précis. J'encouragerai volontiers des personnes plus compétentes que moi de reprendre l'idée et de créer une meilleure version. De mon côté, j'essaierai de l'améliorer tout en apprenant. Je suis en ce moment-même en train d'établir une roadmap pour la prochaine version majeure (6.x), mais je trouve qu'en l'état la version actuelle peut avoir son utilité si elle vous intéresse.

À bientôt.