Kiwi est un bot de serveur Urban Terror, c'est à dire un programme dont le but est de vous aider dans l'administration de votre serveur de jeu. Il permet notamment une gestion plus souple et sûre des droits d'administration, un accès rapide aux principales commandes serveur ou encore l'automatisation de certaines tâches, tout en étant très léger, discret, et simple d'installation et d'utilisation. Il a été développé par MathX et est distribué sous licence GNU/GPL, c'est à dire que vous pouvez le télécharger et le modifier librement; vous pourrez trouver plus d'informations sur le site officiel ou le sujet dédié sur le forum.

Installation

Pré-requis

Les développeurs se sont concentrés sur la facilité d'installation, c'est pourquoi cette dernière ne nécessite que deux choses :

• Python 2.4 à 2.6.

Le bot est développé en Python, l'interpréteur doit donc être installé sur votre serveur. Si c'est déjà le cas, vous pouvez sauter le paragraphe suivant, sinon pas de panique, tout est expliqué plus loin. Notez que les versions de Python 3.0 et supérieures ne sont pas compatibles.

• Un accès aux logs du serveur et son mot de passe RCON.

Pour se tenir au courant de ce qui se passe sur le serveur, le bot doit avoir un accès en lecture aux logs; pour cela vérifiez dans la config du serveur que la variable g_log est renseignée et que g_logsync est à 1. Pensez également à noter quelque part le mot de passe RCON du server.

Installation de Python

L'interpréteur Python est assez simple à installer, je vais détailler les étapes ici.

Si votre serveur utilise Windows, téléchargez-le ici : site officiel. Prenez Windows x86 MSI Installer (2.6.1) (sig) (ou Windows AMD64 MSI Installer (2.6.1) (sig) si vous utilisez un système 64 bits). Lancez le fichier téléchargé (python-2.6.1.msi) et suivez les étapes d'installation : installez pour tout les utilisateurs, dans le dossier par défaut C:\Python26, et laissez les paramètres par défaut sur la page Customize Python. Vous devriez rapidement voir le dernier écran vous invitant à cliquer sur Finish, Python est installé. :)

La dernière étape est d'ajouter Python à la variable %PATH%, pour pouvoir y accéder directement dans la console : clic droit sur Poste de travail, puis Propriétés. Allez dans l'onglet Avancé, trouvez le bouton Variables d'environnement; vous verrez une fenêtre contenant 2 listes s'afficher. Regardez dans la deuxième ("Variables système") et cherchez Path. Cliquez dessus, faites Modifier et à la fin du champs Valeur, rajoutez ";C:\Python26" (n'oubliez pas le point virgule pour séparer du reste). Voilà, vous pouvez fermer toute les fenêtres, cette étape est terminée.

Si votre serveur fait tourner une distribution Linux, installez le paquet propre à votre distribution, ou compilez les sources. Dans ce dernier cas, vous pouvez jeter un oeil sur cette page. Néanmoins, vérifiez d'abord que Python n'est pas déjà installé par défaut, c'est le cas sur un certain nombre de distributions (pour cela tapez simplement la commande python, si quelque chose comme "Python X;X;X ......." s'affiche, c'est installé; tapez Ctrl+D pour revenir à la ligne de commande).

Installation de Kiwi

Les étapes étant similaires sur Windows et Linux, je vais les expliquer parallèlement. Commencez par choisir où installer le bot. N'oubliez pas que le bot doit avoir accès aux logs du server. Pour ce tuto, je vais partir du principe que le serveur de jeu est installé dans /home/server/urt/, je vais installer le bot dans /home/server/kiwi/; bien sûr, vous adapterez à votre situation. Ensuite, il vous faudra une ligne de commande. Sur Linux, ouvrez un terminal ou un client SSH, sur Windows faites Démarrer > Exécuter, entrez "cmd" puis validez. Déplacez vous dans le dossier parent au dossier Kiwi, dans cet exemple /home/server/ :

• $ cd /home/server/

Sur Windows, le chemin du dossier ressemblera plus à C:\server\.

Maintenant, téléchargez et décompressez le bot. Sur Linux, utilisez directement les commandes système. Récupérez avant le lien vers la nouvelle version de kiwi sur la page téléchargements.

• $ wget LIEN_VERS_LA_VERSION
• $ unzip kiwi.zip
• $ rm kiwi.zip

Cela télécharge le fichier, le décompresse et supprime l'archive. Sur Windows, mettez simplement le zip téléchargé dans le dossier que vous avez choisi avec l'interface graphique, décompressez le et renommez le dossier ainsi créé en kiwi. Enfin, supprimez le zip. Le bot est maintenant bien en place sur votre serveur, il ne reste plus qu'à le configurer et le lancer! :) Quelque soit votre système, allez dans le dossier kiwi/ que vous venez de créer :

• $ cd kiwi/

Maintenant passons au fichier de configuration. Éditez le fichier kiwi.cfg avec votre logiciel de traitement de texte préféré, par exemple nano sous Linux.

• $ nano kiwi/conf/kiwi.cfg

Vous pouvez utiliser Bloc-Notes ou Notepad sous Windows. Vous aurez à l'écran quelque chose qui ressemble à ça :

[kiwi]
name = Kiwi
logfile = @kiwi/logs/kiwi.log
adminfile = @kiwi/logs/admins.log
lang = fr

[server]
ip = localhost
port = 27960
rcon = owned
log_game = /home/mathx/.q3a/q3ut4/urt.log

[plugins]
admin = on
ban = on

Voici à quoi sert chaque ligne :

• name : Le nom du bot en jeu.
• logfile : nom du fichier qui servira de log au bot. Y figureront les informations principales.
• adminfile : nom du fichier où sera stockée la liste des administrateurs ainsi que leurs niveaux de privilège. La gestion des droits est abordée plus loin.
• lang : nom de la langue utilisée, voir le dossier languages.
• ip : adresse ip du serveur. Si le bot et le serveur de jeu sont sur le même ordinateur, il est préférable d'indiquer //localhost// à la place de l'IP.
• port : port du serveur, par défaut 27960.
• logfile : chemin absolu vers le log du serveur.
• rcon : mot de passe RCON du serveur de jeu.
• plugins : liste des plugins installés. Pour l'instant, il n'y que admin. La gestion des plugins est expliquée plus en détails plus loin dans ce tutoriel.

Une fois que vous avez effectué les modifications nécessaires, sauvegardez puis quittez. Il y a également un deuxième fichier à éditer. Il se nomme admin.cfg et est dans le même répertoire que kiwi.cfg, ouvrez-le et vous aurez quelque chose comme la fois précédente. Rendez vous aux dernières lignes du fichier et il devrait y avoir une ligne commençant par « god ». Faites qu'elle soit identique à 'god = yes', cela vous permettre de devenir administrateur par la suite. Sauvegardez et quittez.

Pour démarrer le bot, sur Linux je vous recommande l'utilisation de la commande screen. Elle permet de lancer un processus en tache de fond, c'est à dire qu'il ne dépendra pas de vous pour fonctionner. Si vous administrez votre serveur à distance par SSH, vous pourrez fermer la connexion sans que le processus ne soit détruit.

• $ screen -S KIWI python run.py

N.B. : pour tuer le bot, faites screen -r KIWI, puis Ctrl+A suivit de 'k', et validez avec 'y'.

Sur Windows, tapez simplement :

• $ python run.py

Dans ce cas, le bot restera vivant tant que vous ne fermerez pas la fenêtre. Si tout se passe bien, vous devriez voir ''Kiwi lance.'' marqué en haut de la console. Si vous avez une série de lignes commençant par ''File'' précédés d'une ligne ''Traceback (most recent call last):'', il y a eu une erreur : regardez la dernière ligne pour essayer de la trouver. N'hésitez pas à aller sur le forum si vous avez des questions.

Pour que le bot commence à fonctionner, relancez le serveur Urban Terror (via la commande rcon reload).

Félicitations, vous avez maintenant un beau Kiwi en état de marche! Il ne reste plus qu'à lui dire que vous êtes admin. Pour cela, connectez vous sur votre serveur UrT, puis dites dans le chat la commande "!iamgod". Vous serez automatiquement enregistré en super-administrateur (niveau 10). Pour éviter que quelqu'un d'autre ne prenne les pleins pouvoirs de cette manière sans y être autorisé, modifiez le fichier de configuration admin.cfg pour mettre le paramètre god à no.

Mise à jour du bot

Le développeur travaille régulièrement à l'amélioration de Kiwi, c'est pourquoi il est conseillé de procéder régulièrement à une mise à jour. Pour cela, coupez le bot (tuez le processus ou terminez la session screen), rendez vous dans le dossier d'installation du bot (/home/server/kiwi/ dans ce tuto) puis utilisez la commande :

• $ python update.py

Cela va télécharger et installer automatiquement les nouveaux fichiers. Vous n'avez plus qu'à relancer le bot, en utilisant les commandes vues précédemment dans la partie Installation, puis à reload votre serveur UrT.

Commandes de base

Voici une liste exhaustive des commandes disponibles du plugin admin par défaut. Chaque commande peut être paramétrée pour n'être accessible qu'à un certain niveau d'utilisateurs. Il y a 11 niveaux d'utilisateurs, de 0 à 10. 0 correspond à un utilisateur non-enregistré, 10 à un super-administrateur. Lorsque vous tapez la commande !iamgod (ce que vous avez normalement fait dans la partie précédente), vous êtes enregistré avec le niveau 10. Le niveau d'accès de chaque commande est paramétrable dans le fichier conf/admin.cfg. Vous aurez compris que l'on peut se servir des commandes qui ont un niveau inférieur ou égal à son propre niveau de droit. Mettre le droit d'une commande à -1 désactive la commande.

N.B. : une commande de bot est reconnaissable car elle commence par un point d'exclamation, par exemple !help.

• !help [commande] : utilisée seule, la commande affiche la liste des commandes accessibles pour vous (à votre niveau). Associée au nom d'une commande en argument, elle affiche de l'aide sur cette commande.
• !teams : permet d'équilibrer automatiquement les équipes en forçant certains joueurs à changer de team.
• !list : affiche la liste des joueurs connectés, avec leur ID (un numéro unique associé à chaque joueur le temps de la partie) et leur niveau de droit.
• !admins : affiche la liste des joueurs connectés qui ont au moins le niveau 1.
• !status [nom|id] : affiche des informations sur un joueur comme son IP, son nom, son ID en jeu, son reverse DNS, … N.B. : Pour toute les commandes nécessitant la sélection d'un joueur, vous pouvez soit écrire son nom, soit indiquer son ID.
• !slap [nom|id] : inflige un slap au joueur précisé.
• !nuke [nom|id] : lance une sorte de missile sur le joueur.
• !mute [nom|id] : empêche le joueur de parler.
• !force [nom|id] [equipe] : force un joueur à rejoindre l'équipe spécifiée (blue, red ou spec)
• !veto : annule un vote en cours.
• !say [text] : demande au bot d'afficher un texte, pour parler en spectateur par exemple.
• !cyclemap : change la map pour la prochaine, dans l'ordre définit dans le cyclemap.
• !restart : redémarre la partie.
• !reload : contrairement au restart, la map est complètement rechargée.
• !map [nom_map] : change la map.
• !nextmap [nom_map] : change la prochaine map.
• !kick [nom|id] : expulse le joueur du serveur.
• !bigtext [texte] : affiche le texte au milieu de l'écran de tout les joueurs du serveur.
• !exec [nom_config] : exécute une config.
• !shuffle : mélange les équipes selon leurs scores afin de les équilibrer.
• !setlevel [nom|id] [niveau] : Change le niveau de droits du joueur passé en premier argument par le niveau passé en deuxième argument.
• !die : arrête complètement le bot.

Ces commandes sont celles de la beta 1 de Kiwi. Certaines commandes seront rajoutées en temps voulu comme !ban, !tempban ou !plugin. Vous pouvez également installer des plugins afin de rajouter des fonctions ou des commandes au bot.

Plug-ins

Introduction

Kiwi propose un système de plug-ins performant afin de le compléter si nécessaire. Actuellement, il n'y a que le plug-in admin et ban qui soient fournis avec le bot. Le premier offre une gestion de commandes et bien entendu, une liste des commandes les plus importantes (!slap, !nuke, !kick, !force …). Désactiver le plugin admin ou simplement le supprimer rend le bot inutilisable en jeu. En effet, il ne répondra plus à rien mais enregistrera tout de même les informations nécessaires (joueurs, actions, jeu, etc). Le deuxième gère les bans temporaires et définitifs. D'autres plugins seront développés à l'avenir (auto-teams, etc) et seront intégrés officiellement avec Kiwi. Nous allons nous intéresser ici dans l'installation de plugins.

Installation

Tout d'abord, cette partie ne couvre pas la conception mais uniquement l'installation de plugins. Tout le monde peut concevoir ses propres plugins et bien entendu, tout le monde peut les utiliser.

Il faut savoir qu'un plugin nécessite au moins un fichier Python (extension en .py) mais peut en disposer d'avantage si le fichiers principal en a besoin. Ce(s) fichier(s) se placent dans le répertoire plugins/ de kiwi/, lui-même situé dans le dossier d'installation du bot. Il y a logiquement déjà admin.py, mettez-y les fichiers nécessaires au bon déroulement du plugin. Certains fichiers seront peut-être aussi à placer à d'autres endroits, tels que dans conf/ ou languages/. Pour plus de renseignement, consultez la doc du plugin.

Il va falloir ensuite passer à la configuration de Kiwi pour qu'il prenne le fichier en compte. Ouvrez le fichier kiwi.cfg dans le répertoire conf/. Rendez vous à la section nommée « plugins » et ajoutez-y une ligne telle que « nomDuPlugin = 1 ». Le nom du plugin doit posséder le même nom que le fichier inséré dans le dossier plugins/. Si par exemple votre fichier est irc.py, la ligne dans le fichier de configuration ressemblera à « irc = 1 ». Le deuxième argument suivant le signe d'égalité ne sert à rien, vous pouvez y mettre ce que vous souhaitez mais il sera sûrement utilisé dans l'avenir.

Si vous avez effectué les étapes précédents, redémarrez Kiwi et reloadez le serveur, votre plug-in sera normalement installé !