Lycanobot/Doc/Hacker

Voici une description sommaire des fichiers source de Lycanobot. Il y a des chances qu'elle ne soit pas tout à fait à jour, car lycanobot évolue souvent. Vous pouvez aussi trouver des informations utiles dans certains longs commentaires descriptifs, mais ils sont en anglais.

Documentation basée sur la révision 380 (2009-05-09). (Mais ça n’a pas trop changé depuis.)

Fonctionnement général

Lycanobot est un programme basé sur les évenements. Il y a donc une simple boucle évenementielle (dans lycanobot.pl), des fonctions executées lorsque survient un évenement IRC (dans hooks.pl), qui elles mêmes appelent des tas d'autres fonctions diverses et variées qui font fonctionner le jeu. De par cette conception, le passage et stockage des informations fait appel à un certain nombre de variables globales introduites par le mot clé perl our.

Le code

actions.pl

Contient des description des variables globales de définition des actions (%actions et %actions_auth), et les fonctions relatives à la gestion, l'excution et l'autorisation des actions.

admin.pl

Historiquement ce fichier devait contenir les fonctions relatives à l'administration. Mais cette tâche étant très vague, c'est plus devenu un "fourre-tout" qu'autre chose. On y retrouve quelques helpers, et des fonctions relevant de tâches nécessitant un certain pouvoir...

basics.pl

Contient les définitions des données de base de description du jeu (phases, actions, votes). La fonction load_game_basics() initialise certaines variables globales de façon à avoir le jeu de base avec les phases de jour et nuit, les actions de base sur lesquelles les personnages spéciaux pourront s'attacher (hooks), les villageois et les loups, leurs votes. S'en suit le code de toutes les fonctions référencées dans load_game_basics().

commands.pl

Ce fichier contient toutes les commandes de base de lycanobot (d'autres pouvant être ajoutées par des personnages spéciaux), et une bonne description de la variable globale %cmdlist. Il l'initialise et définit toutes les fonctions qui y sont référencées, et aussi quelques helpers. Par convention on préfixe toutes les fonctions des commandes par cmd_. Lorsque certains messages sont indépendants de la langue (comme les paramètres de hlme), ils y sont définis directement. Sinon, on les retrouve dans les fichiers messages.

config.pl

Contient les fonctions de chargement/écriture/validation des fichiers de configuration XML. Il contient également les fonctions de chargement/écriture/validation spécifiques pour le fichier de configuration de lycanobot (config.xml), et sa version par défaut (qui est générée si aucun fichier n'est trouvé, et qui contient les valeurs par défaut).

game_sets.pl

Contient les fonctions de chargement/écriture spécifiques au fichier de settings (settings.xml).

games.pl

Contient les fonctions de chargement spécifiques au fichier de description de jeux (games.xml), ainsi que des fonctions pour utiliser ces descriptions de jeux.

hooks.pl

Contient toutes les fonctions executées lors d'évenements IRC (leurs nom commence par on_). Tout à la fin, il y a le code qui relie les fonctions aux évenements. Chaque évenement IRC produit (en plus de la fonction spécifique appelée) un appel à update_last_IRC_recv() qui participe à la vérification de la non-déconnection au serveur IRC.

jobs.pl

Contient le code qui charge les fichiers des personnages spéciaux (dossier jobs/) et leurs messages associés (dossier jobs/messages/). La fonction load_jobs() les charge tous en appelant les autres fonctions du fichier.

lycanobot.pl

Étant le fichier à executer pour lancer lycanobot, il contient toute la partie initialisation. Vous y trouverez aussi en commentaire des explications sur le contenu de certaines variables globales (dans la fonction reset_game_vars()).

Il charge tous les fichiers externes (autres fichiers .pl, config, settings, etc.) et se connecte au serveur IRC. Il entre ensuite dans la boucle évenementielle qui vérifie si des timers sont atteinds, et s'il y a des messages dans la file d'attente à envoyer. Après cette boucle, il y a le code de fin d'execution de lycanobot (sauvegarde des settings, puis arrêt ou reboot).

send.pl

Contient le code qui gère les files d'attentes d'envoi de messages IRC. Les variables globales %send_queue et %send_queue_time y sont décrites, tout comme les constantes de priorités de messages (PRIO_* et ses raccourcis P_*). La fonction push_on_sendqueue ajoute un message à envoyer dans la file d'attente, et check_send_queue() (appelée dans lycanobot.pl) retire un ou plusieurs messages qui seront alors envoyés pour de vrai.

speech.pl

Contient toutes les fonctions pour faire parler le bot ou envoyer des commandes IRC. Il y a aussi des fonctions pour les messages souvent utilisés, comme par exemple announce_targs() qui annonce une liste de pseudos possible comme paramètre à une commande à taper. De plus, il contient vers la fin les fonctions d'ajouts de messages de personnages spéciaux, comme add_job_name_message() ou add_generic_messages(). Ces fonctions sont appelés depuis les fichiers messages des personnages spéciaux.

steps.pl

Contient tout le code de gestion des phases. Il peut paraître assez obscur, mais en résumé il y a la fonction do_next_step(), qui sert à faire passer de la phase courante à la phase qui suit, en executant les presub, postsub et timeoutsub associées. Sachant que ces fonctions peuvent executer une action, faire changer de phase, ou encore produire un phasecut, il y a beaucoup de bazard pour gérer tout ça. Et il y a aussi la gestion des timeouts et des phases de vote.

timer.pl

Contient le code pour gérer les timers (ajout, suppression, check) avec une description de la variable globale %timers. Il y a aussi quelques fonctions qui servent à vérifier la non-déconnection du bot au serveur IRC.

users.pl

Contient le code pour mettre à jour toutes les informations sur les utilisateurs (variables globales %users et @userlist) et les salons (variable %chanusers). Ces fonctions sont appelées par des évenements IRC dans hooks.pl. Il y a aussi les fonctions de chargement et d'écriture de ces informations dans le fichier des utilisateurs (users.dat), et quelques helpers.

libs/

Le dossier libs/ contient des librairies spécifiques à lycanobot, notamment Net::IRC un peu modifiée. Ces modifications sont fournies sous forme de patches dans le dossier patches/.

patches/

Contient des patchs pour d'autres programmes utilisés dans lycanobot.

hideidle/

Contient des modules pour résoudre le problème de l'idle time.

messages/

Contient les fichiers messages internes.

jobs/

Contient les définitions des personnages spéciaux. Chaque fichier décrit un personnage spécial, et les messages qui lui sont associés sont dans jobs/messages/.

jobs/messages/

Contient les messages spécifiques à chaque personnage spécial. Ils sont de la forme jobs/messages/<perso>-<langue>.pl.