*******************
                   *   Men Are Ants  *
                   *******************
                         [ API ]

Dernière modification:
$Id$

Sommaire:
1) Principe du jeu
2) Protocole
3) Particularités des commandes de positions
4) Modes
5) PLS
6) Etat d'une partie
7) Intelligence Artificielle
8) Entités Conteneurs
9) Meta serveur

1) Principe du jeu


2) Protocole
      a) Client -> Server
         - Général
              IAM <nick> <prog> <version>       :je me présente
              LSP                               :lister les parties
              CRE <nom>                         :créé une partie
              JOI [<nom>|.] [$]                 :joindre une partie ('$' signifie "créer le chan")
                                                 mettre '.' comme nom créé une mission
              STAT                              :request stats
              BYE                               :au revoir
              ADMIN <LOGIN|REHASH|KILL> [arg]   :commande en temps qu'admin
         - Dans une pré-partie
              SET <mode(s)> [params]            :met un paramètre (voir section 4. Modes)
              JIA <nom>                         :Créé une IA (par l'owner)
              KICK <nick> [raison]              :l'owner peut kicker
              LEA                               :partir
              GO!                               :l'owner lance le jeu
              MSG <message>                     :envoie un message à tous les joueurs
              AMSG <message>                    :envoie un message à ses alliés
              SMAP <map>                        :envoie une map
              EOSMAP                            :fin du SMAP
         - En cours de jeu
              ARM <nom> [+<nb>] [%<type>]       :modifier le status d'une armée
                  [/<nb>] [>] [^] [v] [<] [*<pos>]
              BP <+|-><pos> [message]           :rajoute un breakpoint sur la carte, montré uniquement à ses alliés
              SAVE <name>                       :faire une sauvegarde (reception d'un fichier)

      b) Serveur -> Client
         - Général
              HEL <prog> <version>              :welcome
              AIM <nick>                        :confirmation du IAM
              MOTD  <ligne>                     :motd
              EOM                               :fin du motd
              STAT <nbactco> <nbco> <nbch>      :stats sur le serveur
                   <chinwait> <chingame> <chtot> <uptime>
              LSP <nom> <+/-> <nbjoueurs>       :liste une partie
                  <nbmax> [map]
              EOL                               :fin de la liste
              MAJ <+|->                         :le client (ou le serveur) n'est pas à jour
              BYE [raison]                      :au revoir
              USED                              :pseudo déjà utilisé
              REJOIN <chan>                     :l'user est invité à rejoindre une partie à laquelle il a été déconnecté
              ADMIN                             :l'user est bien loggé comme admin
         - Dans une pré-partie
              ER1                               :ne peut pas joindre
              ER2 <nick>                        :le pseudo de l'IA a déjà été pris ou il y a trop de monde
              ER3                               :trop de connexions sur ce serveur
              ER4                               :impossible de créer la partie car il y en a déjà trop
              PLS <params> [...]                :liste des joueurs (voir 5. PLS)
              LSM <nom> <nbmin> <nbmax> <infos> :envoie la liste des cartes
              EOMAP                             :fin de la liste des maps
              :<nick> JOI <nom>                 :un user join
              :<nick> SET <mode(s)>             :un user met un paramètre (voir section 4. Modes)
              :<nick> LEA                       :un user part (ou a été kické)
              :<nick> MSG <message>             :message reçue
              :<nick> KICK <victime> [raison]   :un user est kické
              SMAP <map>                        :envoie la map
              EOSMAP                            :fin du SMAP
         - En cours de jeu
              INFO <ID> <args>                  :message envoyé par le serveur qui s'affiche à l'écran des joueurs
              :<nick>!<arm> ARM [+<nb>] [*<pos>]:montre le changement d'une armée
                          [%<type>] [<] [-] [.]
                          [=<arm>,<pos>,<movs>]
              :<nick> BP <+|-><pos> [message]   :montre un nouveau breakpoint
         - Lors des scores
              :<nick> SCO <killed> <shooted>    :score d'un joueur
                         <created> <score>

3) Particularités des commandes de positions
      Voici les arguments server -> client :
         +<nb>       :ajoute des unités (donne le nombre final)
         %<type>     :définit le type de l'armée
         =<O!E>,<x>, :change la position (on indique l'user dans le cas d'un * qui prendrait plusieurs senders)
          <y>,<[>][v][<][^]>
         *<pos>      :attaque
         <           :retour
         -           :suppression de l'armée
         .           :lock
         {           :deploiement
         }           :reploiement
         )<entité>   :s'envoyer dans une unité de conteneur (voir 8. Entités Conteneurs)
         (<entité>   :sortir d'une unité conteneur (voir 8. Entités Conteneurs)
         &           :la ligne n'est pas l'action principale (bien qu'elle soit la première envoyée)
         ~<type>,    :envoie une donnée particulière à l'entité, et qui doit donc etre interprétée par elle (RecvData).
          <data>
         U           :upgrade
         @           :investit
         |<niveau>   :changement de niveau de l'unité
      Et client -> server :
         >           :déplacement de un à droite
         v           :déplacement de un vers le bas
         <           :déplacement de un à gauche
         ^           :déplacement de un vers le haut
         *<pos>      :attaque une position
         !           :lors d'une attaque, force la case
         +           :création d'une entité
         =<pos>      : |- position de départ
         %<type>     : `- définit le type
         #           :deploiement.
         )<entité>   :s'envoyer dans une unité conteneur (voir 8. Entités Conteneurs)
         (<pos>      :sortir d'une unité conteneur (voir 8. Entités Conteneurs)
         U           :upgrader
         C           :annuler les déplacements
         $           :vendre une unité

4) Modes
      La commande SET nécessite l'utilisation de modes, semblables à l'IRC.
      Voici la liste :
        Mode pour le chan:
         +l <limite>         :paramètre la limite (serveur -> user uniquement)
         +o <user>           :met op un user
         +m <map>            :définie la map du jeu
         +b <money>          :l'argent de départ pour chaque joueur
         +r                  :partie rapide
         +W                  :pré-partie (WAITING)
         +S                  :envoie des infos (SENDING)
         +P                  :jeu (PLAYING)
         +A                  :animation (ANIMING)
         +Q                  :attente d'un joueur qui a perdu la connexion (PINGING)
         +E                  :fin du jeu (SCORING)
         +t <temps>          :temps par tours maximum pour jouer
         +s                  :compte les scores pour le meta-serveur
        Mode pour un user:
         +c <couleur>        :l'user se définie sa couleur
         +p <position>       :l'user définie sa position
         +n <nation>         :l'user définie sa nation
         +!                  :le joueur est READY
         +_                  :le joueur a perdu
         +$                  :l'argent du joueur (serveur -> user uniquement)
         +@ <country>        :l'user possède maintenant la terre <country>
         +a <nick>           :définie un user comme allié de lui
         +w                  :ce joueur a été déconnecté et on attend qu'il se reconnecte
         +v [nb]             :vote pour virer un user, pas besoin de nombre pour cl->serv, mais pour serv->cl
         +d <nb:user>        :donner de l'argent à un de ses alliés
         +e <country:user>   :donner une country à un de ses alliés

5) PLS
     La commande PLS a la particularité d'avoir une syntaxe plutot complexe et pas compréhensible
     sans document. C'est pourquoi je consacre ce cours paragraphe dans l'unique but de la détailler:

     PLS [@][!]<position>,<couleur>,<nation>,<pseudo> [...]
     [*]               :le joueur est owner
     [@]               :le joueur est op
     [!]               :le joueur est pret (Ready)
     <position>        :la position du joueur sur la carte
     <couleur>         :la couleur
     <nation>          :la nation
     <pseudo>          :le pseudo du joueur

6) Êtat d'une partie
     WAITING           :c'est la pré-partie
     SENDING           :le client créé la map physiquement et prépare toutes les données
     PLAYING           :les joueurs doivent jouer jusqu'à ce que tout le monde soit READY
     ANIMING           :animations commandées par le serveur

7) Intelligence Artificielle
     L'intelligence artificielle est implémentée dans le serveur de la manière suivante :
     - Son pseudo commence, pour la distinction, par IA_CHAR, définie dans lib/Channels.h, par default '&', étant un
       caractère non inclus dans NICK_CHARS.
     - Elle est considérée comme un client normal par le serveur qui ne fait quasiment pas la distinction
     - Chaque sendrpl() vers ce client est interprété ensuite par l'IA qui parse le message et le traite.
     - Chaque message que l'IA veut envoyer est en fait redirigé vers son parsemsg().
     - Maintenant, les IA s'allient entre elles au début de la partie, et quand un des joueurs humain
       s'allie avec une IA, celle ci se des-allie avec ses alliées IA, puis s'allie avec l'humain. Ensuite donc un nombre
       variable d'humains peuvent s'allier avec l'IA, mais quand plus aucun humain n'est allié avec l'IA, celle ci s'allie
       avec toutes les IA qui n'ont pas d'alliés humains.

     La problematique est la suivante:
     * Dans plusieurs fonctions ???Command::Exec() executées par une commande d'un client, il y a des messages envoyés aux
       joueurs en prenant en compte le fait qu'aucun traitement d'un éventuel message de retour ne sera effectué avant
       la fin de cette fonction. Le problème est que l'IA elle, lorsqu'elle reçoit le message qui a été envoyé
       avant la fin de la fonction en question, peut interagire et répondre tout de suite, ce qui entraine un autre
       traitement qui coupe le traitement en cours.
     * Pour remédier à ce problème, un système de "lock" a été trouvé du coté de l'IA. Ainsi, lorsqu'elle est positionée
       comme étant "locké", tous les messages reçus sont ajoutés dans une queue qui, une fois "delocké", sera traité
       d'un coup.

8) Entités Conteneurs
     Les unités conteneurs peuvent transporter une autre unité.
     * Le protocole pour la mise dans une unité est le suivant :
         - PLAYING:
         > ARM AA )AB
         < :NICK!AA ARM )NICK!AB =NICK!AA,x,y,<
         - ANIMING:
         < :NICK!AA ARM )NICK!AB =NICK!AA,x,y,<
     * Le protocole pour extraire une unité est le suivant:
         - PLAYING:
         > ARM AB (x+1,y
         < :NICK!AA ARM (NICK!AB =NICK!AA,x,y,>
         - ANIMING:
         < :NICK!AA ARM (NICK!AB =NICK!AA,x,y,>

     Concrètement, une classe de base EConteneur aurrait une variable avec un pointeur vers l'entité.
     * Lorsqu'on met dans le conteneur, l'unité est supprimée de la liste globale des unités et de celle des joueurs,
       et stockée dans l'unité ECounteneur. Les clients en font de même et stockent également dans EConteneur.
     * Lors d'une attaque d'un conteneur avec une unité, l'unité conteneur appelle celle contenue pour se battre.
     * Lors de l'extraction, l'unité est remise en bien commun et vidé du conteneur, et les clients la ressortent également.

     Il faut que le conteneur gère le fait que si celui ci bouge il faut que son contenu bouge aussi (seulement son pointeur
     case et non se mettre dans la liste des entités d'une case, vu qu'elle ne doit plsu exister).

     Il faut également que la taille maximale à contenir soit proportionnel au "nombre" du conteneur.

9) Meta serveur

     Le meta-server permet de constituer une liste des serveurs lancés. Chaque serveur au démarrage se connecte au meta-serveur et
     le restera jusqu'à son extinction. A chaque evenement il envoie des informations, tels que le nombre de joueurs connectés, le
     nom de la carte, etc.

     Le client, quant à lui, se connecte au meta-serveur pour obtenir cette liste.

     a) Meta-server -> Serveur
         HEL <prog> <version>                              :Dit bonjour, s'informe sur son type et sa version de protocole

         LOGGED                                            :L'infnorme qu'il est loggé comme serveur officiel

     b) Serveur -> Meta-server

        IAM <name> <prog> <version>                        :Donne son nom, son prog et sa version
        SET <modes> [<args> ..]                            :Change un paramètre
            +p <nb players>                                :- nombre de players actuellement
            +P <max players>                               :- max players
            +g <nb games>                                  :- nombre de jeux
            +G <max games>                                 :- max jeux
            +w <nb waiting games>                          :- nombre de jeux en attente
            +v <version du protocole>                      :- version du protocole
            +V <version>                                   :- version du serveur
            +i <port>                                      :- port
            +r <nick>                                      :- tel user peut rejoindre tel chan
            +u <uptime>                                    :- uptime

        USET <account> <modes> [<args> ..]                 :Paramètres d'un account
            +k <killed>                                    :- unités tués
            +d <deaths>                                    :- unités perdues
            +s <score>                                     :- score
            +c <creations>                                 :- créations
            +v                                             :- victoire

        JOI <name> <players> <map> <type>                  :Anonce la création d'une partie (servira à prévenir les services d'events, style un bot IRC)
                                                            type=1=mission, type=2=escarmouche, type=3=multi
        LEA <name> <map> <winers> <losers>                 :Anonce la fin d'une partie avec les gagnants et les perdants

     c) Meta-server <-> Client

        > HEL <prog> <version>                             :Dit bonjour, s'informe sur son type et sa version de protocole
        < IAM <name> <prog> <version> [cookie|pass]        :Donne son nom, son prog et sa version
        > STAT <nbtchan> <nbtusers> <nbregs>               :Statistiques
        > LSP <ip:port> <nom> <+/-> <nbjoueurs>            :liste un serveur
                     <nbmax> <nbgames> <maxgames> <proto>
                     <version> <totusers> <totgames> <uptime>
        > EOL                                              :fin du listing

        < SCORE
        > SCORE <nick> <deaths> <killed> <creations>       :score
                <scores> <best_revenu> <nbgames> <victories>
                <regtime> <lastvisit>

        > ERR NICKUSED                                     :pseudo déjà utilisé
        > REJOIN <ip:port> <game>                          :le joueur peut rejoindre une partie

        > ERR REGNICK                                      :le pseudo est enregistré
        < LOGIN <pass>                                     :login

        < REGNICK                                          :s'enregistrer
        > ERR LOGGED                                       :loggé

     d) Meta-server <-> IRC Bot

        > HEL <prog> <version>
        < IAM <name> IRCBOT <version>

        < STAT                                            :afficher les stats
        < LSP                                             :afficher la liste des serveurs

        > REGNICK                                         :event quand un user a reg son nick
        > MSG_IA_JOIN <serveur> <game> <player>           :creation de partie
        > JOIN <serveur> <game> <players> <map> <type>    :evenements concernant les maps
                                                           type=1=mission, type=2=escarmouche, type=3=multi
        > LEA <server> <name> <map> <winers> <losers>     :Anonce la fin d'une partie avec les gagnants et les perdants