Traduit de l'anglais par Grammaire.

Advanced JKA Map Cycles Generator (AJMCG)
by Gamall Ida
v. 1.5

gamall-ida.com & gamall.ida@gmail.com & conseiljedi.com

I. Introduction
II. Exemple minimal, variables obligatoires
III. Fonctions dites ``avancées''
IV. Licence
V. Contact
VI. Installation
VII. Historique des versions


I. Introduction

Bien que la création d'un cycle de map pour Jedi Academy ou quelque autre jeu utilisant le moteur de q3, ne puisse pas être qualifiée de défi intellectuel, c'est sans nul doute une tâche très fastidieuse.
Cela devient encore plus pénible quand vous essayez de changer un cycle déjà écrit.

Ce programme a pour but de rendre plus faciles et plus fiables la création et la maintenance de cycles complexes ou multiples.

Au lieu de taper directement les commandes sur le serveur, vous créez un fichier spécial comprenant le minimum d'informations pertinentes dans une syntaxe claire, qui sera utilisé par le programme pour générer un fichier .cfg utilisable directement sur votre serveur.

Accessoirement, le programme peut générer des rapports détaillés que vous pouvez « copier-coller » sur votre site web et aussi des vstr listant les cycles et les maps, qui peuvent être utilisées par vos admins en cours de jeu.

La maîtrise du fonctionnement des vstr et des cycles de map sur JKA (moteur q3), est un prérequis pour l'utilisation de ce logiciel.

II. Exemple minimal, variables obligatoires


Regardons le fichier nommé ``mini.ini''.

$ output = mini.cfg

$()cycles = mini


{ mini

  $()maps =      mp/ffa1 
                  mp/ffa2
                  mp/ffa3
                  mp/ffa4
                  mp/ffa5          
}


C'est le fichier le plus simple que vous pouvez créer pour AJMCG

NOTE : Les fichiers sont écrits en syntaxe VDF. VDF (Versatile Data Format) est une alternative au format standard INI utilisé par de nombreux programmes et prévu pour être plus facile à utiliser que le XML. Il est pourtant assez puissant pour de nombreuses applications. Je développe actuellement VDF pour C++ . Si vous êtes programmeur C++, vous pouvez me contacter pour plus d'informations.


La syntaxe VDF est simple: $ signifie « chaîne de caractères », $() signifie « tableau de chaînes ». Vous utiliserez également % et %() désignant respectivement « nombres » et « tableau de nombres ». Il est clair que // et /* */ sont des commentaires. Les accolades `{…}' introduisent un groupe de variables. Ces groupes sont utilisés pour les cycles, par exemple `mini'. Les espaces et tabulations n'ont, en règle générale, pas de signification.



Maintenant, examinons les variables :

output :

Définit le chemin vers la version « compilée » du cfg. Ici, c'est « mini.cfg », ce qui indique qu'après le passage de mini.ini à travers AJMCG, le fichier mini.cfg sera créé, s'il n'existait pas encore, ou écrasé s'il existait, et contiendra les instructions décrivant le cycle de map au serveur JKA. Ici, mini.cfg contiendra :

set mini "vstr mini_1"

set mini_1 "map mp/ffa1;set nextmap vstr mini_2"
set mini_2 "map mp/ffa2;set nextmap vstr mini_3"
set mini_3 "map mp/ffa3;set nextmap vstr mini_4"
set mini_4 "map mp/ffa4;set nextmap vstr mini_5"
set mini_5 "map mp/ffa5;set nextmap vstr mini_1"

cycles :

Ce tableau dit au programme quels cycles il doit traiter, en effet, vous pouvez très bien définir plusieurs cycles différents dans le même fichier VDF, et cependant ne traiter que quelques uns d'entre eux.

$()cycles = un
                  deux

Ici, les cycles ``un'' et ``deux'' seront traités. Les autres seront tout simplement ignorés.

Pour définir un cycle, vous avez juste à écrire

{ le_nom_exact_du_cycle

et ensuite écrivez ce qui est nécessaire pour décrire le cycle. Après cela vous pouvez fermer le cycle en écrivant :

}

Vous pouvez alors commencer un autre cycle si vous le souhaitez. Il ne sera cependant pas pris en compte tant que son nom ne sera pas écrit dans « cycles ». Notez bien que le nom du cycle sera toujours le nom de la vstr qui le démarre, et que le nom de la vstr qui lance la nième carte du cycle X sera toujours X_n.

maps

Ce tableau est manifestement le coeur du cycle. Ses entrées suivent la syntaxe suivante :

<name of the q3 map> ; <timelimit> ; <fraglimit> ; <q3 command 1> ; <q3 command 2> ; <q3 command 3> ; ......... ; <q3 command n> ;

Il n'est pas obligatoire de renseigner les items en italiques. Comme vous l'avez vu dans le précédent exemple, cela fonctionne parfaitement avec seulement le nom de la map. La meilleure façon de voir comment cela marche en réalité est d'observer cet exemple :

$ output = mini.cfg

$()cycles = mini


{ mini

  $()maps =      mp/ffa1 ; 10 ; 20 ; g_motd FFA1;kick allbots ;  
                  mp/ffa2 ; ; ; kick allbots;
                  mp/ffa3 ; ; 10 ;
                  mp/ffa4 ; ; 30
                  mp/ffa5 ; 40
                  mp/ffa1 ; 30 ; ; g_motd FFA1;                     
}
__________________________________

set mini "vstr mini_1"

set mini_1 "g_motd FFA1;kick allbots ;timelimit 10;fraglimit 20;map mp/ffa1;set nextmap vstr mini_2"
set mini_2 "kick allbots;map mp/ffa2;set nextmap vstr mini_3"
set mini_3 "fraglimit 10;map mp/ffa3;set nextmap vstr mini_4"
set mini_4 "fraglimit 30;map mp/ffa4;set nextmap vstr mini_5"
set mini_5 "timelimit 40;map mp/ffa5;set nextmap vstr mini_6"
set mini_6 "g_motd FFA1;timelimit 30;map mp/ffa1;set nextmap vstr mini_1"

Notez que, comme les commandes ``carte par carte'' viennent après les commandes locales, elles peuvent écraser à la fois les commandes locales et globales si le cas se présente. ( cf plus bas ).


III. Fonctions dites ``avancées''

On peut définir d'autres variables qui ont une grande influence sur le fichier compilé. Vous pouvez voir la plupart d'entre elles en action dans « cycles.cfg ». Veuillez ouvrir le fichier maintenant et parcourez-le avant de reprendre votre lecture.

cycles_list

$ cycles_list = cycles

Cela veut dire qu'une vstr nommée ``cycles'' listant tous les cycles prévus sera écrite.

set cycles "say ^2Cycles : ^5cy_STANDARD, cy_FUN, cy_CHRISTMAS, cy_DUEL, cy_SIMPLE, cy_CTF, cy_TFFA"

Ainsi, vos admins peuvent afficher à l'écran un message énumérant tous les cycles disponibles sur le serveur en utilisant amvstr cycles en JaPlus, ou rcon vstr cycles en base. Ensuite, ils peuvent démarrer un cycle en tapant amv/rc vstr cycle_nom.

maps_list_suffix

$ maps_list_suffix = SUFFIX

Cette ligne de code signifie que, pour chaque cycle, une vstr nommée ``cycle_nameSUFFIX'' sera créée, affichant les maps du cycle « cycle_nom ». Ainsi, votre admin sait exactement quelle map sera la suivante. Voici un exemple :

set cy_STANDARD_l "^2Cycle cy_STANDARD : ^75 maps : ^5adana, killbill, christmas_final, matrix_reloaded_final, mp/ffa4"

Notez que si un cycle comporte plus de cinq maps, celles-ci seront numérotées, ce qui facilite l'accès à une map spécifique.

report_path

$ report_path = report.txt

Si elle est définie, cette variable force le programme à créer un fichier contenant une vue d'ensemble des cycles programmés, par exemple:

{<§ Report Generated by Gamall Ida's Advanced JKA Map Cycles Generator §>}

 The cycles can be listed ingame by use of the following vstr : 'cycles'
 For each cycle 'X', the maps can be listed ingame by use of the following vstr : 'X_L'

Cycle : norm , 5 maps. Total time : 265 minutes.

   1: mp/ffa1           timelimit : 40
   2: mp/ffa2           timelimit : 50
   3: mp/ffa3           timelimit : 60
   4: mp/ffa4           timelimit : 55
   5: mp/ffa5           timelimit : 60

Vous pouvez alors ``copier-coller'' ce rapport sur votre site web, ou le poster sur votre forum, de telle sorte que tout le monde sache exactement quelles maps sont sur le serveur, et combien de temps elles y restent.

Vous n'êtes pas autorisés à enlever ou à modifier la première ligne : ``{<§ Report Generated by Gamall Ida's Advanced JKA Map Cycles Generator §>}" de quelque manière que ce soit.

report_format

$ report_format = phpbb

Cette variable peut être utilisée pour créer des ``sorties'' plus sophistiquées que le « texte brut » proposé par défaut. Les valeurs suivantes agissent ainsi :

``phpbb''  : Le rapport sera prêt à être « copié-collé » dans un forum phpBB.
``ipb''             : Idem pour un forum Invision Power Board. En fait, la syntaxe est exactement la même que pour un forum phpBB
``vb''              : Idem pour un tableau vBulletin. La syntaxe est la même, sauf pour la BBCode 'size'.
``smf''             : Idem pour un forum Simple Machines.

Les commandes qui suivent sont locales, ce qui signifie qu'elles n'ont de sens que si elles sont employées à l'intérieur d'un cycle.

report_special_color

$ report_special_color = orange

Si le rapport est publié dans un format qui admet des couleurs, vous pouvez changer la couleur principale en modifiant ces variables. Le résultat dépendra du 'report_format' que vous aurez choisi.


comment

Cette variable n'a d'objet que si vous voulez créer un rapport. Ce qu'elle contient sera utilisé pour ajouter un commentaire dans le rapport. Il n'est pas nécessaire de s'étendre sur le sujet, mais cette option peut cependant se révéler utile.

{ mini

  $comment = This is a commentary...
// etc.......
___________________________________________

Cycle : mini , 5 maps. Total time : never-ending.
# This is a commentary...

   1: mp/ffa1           timelimit :
   etc...

init_command


{ mini
  $ init_command = g_gametype 0;

  $()maps =      mp/ffa1 
                  mp/ffa2
                  mp/ffa3
                  mp/ffa4
                  mp/ffa5          
}
________________________________

set mini "g_gametype 0;vstr mini_1"

set mini_1 "timelimit 0;map mp/ffa1;set nextmap vstr mini_2"
//etc...

Chaque commande dans « init_command » sera éxécutée une unique fois quand le cycle est lancé. Ceci est utile si vous êtes certain que personne ne démarrera un cycle en l'appelant directement depuis une vstr de changement de map. Si cette commande n'est pas renseignée, la vstr X qui démarre le cycle a exactement le même effet que la vstr X_1 qui démarre la première map.



global_command

$ global_command = sv_timeout 500;

Toutes les commandes ou séries de commandes que vous stockerez dans cette variable seront ajoutées à chaque vstr de changement de map dans tout le fichier de sortie, ce qui signifie que tous les cycles seront modifiés. Par exemple:

set cy_CTF "vstr cy_CTF_1"

set cy_CTF_1 "sv_timeout 500;g_gametype 8;timelimit 60;map mp/ctf1;set nextmap vstr cy_CTF_2"
set cy_CTF_2 "sv_timeout 500;g_gametype 8;timelimit 60;map mp/ctf2;set nextmap vstr cy_CTF_3"
set cy_CTF_3 "sv_timeout 500;g_gametype 8;timelimit 60;map mp/ctf3;set nextmap vstr cy_CTF_1"

set cy_TFFA "vstr cy_TFFA_1"

set cy_TFFA_1 "sv_timeout 500;g_gametype 6;timelimit 20;map mp/duel1;set nextmap vstr cy_TFFA_2"
set cy_TFFA_2 "sv_timeout 500;g_gametype 6;timelimit 20;map mp/duel4;set nextmap vstr cy_TFFA_3"
set cy_TFFA_3 "sv_timeout 500;g_gametype 6;timelimit 20;map mp/duel5;set nextmap vstr cy_TFFA_4"
set cy_TFFA_4 "sv_timeout 500;g_gametype 6;timelimit 20;map mp/duel6;set nextmap vstr cy_TFFA_5"
set cy_TFFA_5 "sv_timeout 500;g_gametype 6;timelimit 20;map mp/duel10;set nextmap vstr cy_TFFA_1"

Vous avez remarqué que sv_timeout 500 ; a été ajouté à chaque ligne de commande.

local_command

$ local_command = g_gametype 0;

Elle a à peu près la même fonction que « global_command », mais elle modifie seulement le cycle pour lequel elle est définie, d'où le qualificatif de « locale ». Vous remarquerez que les commandes locales sont ajoutées après les commandes globales.
Cela signifie qu'une commande globale donnée peut être annulée par une commande locale. Mais, normalement, pour faire cela, vous vous heurterez aux limitations de JKA. Le plus souvent, quand une cvar est redéfinie deux fois d'affilée, la deuxième modification est ignorée. Par exemple, supposons que nous ayons :

$ global_command = g_gametype 0;

parce que tous vos cycles sont en FFA sauf un, et

$ local_command = g_gametype 8;

définie dans le seul cycle supposé être en mode CTF, alors le résultat ressemblera à peu près à cela :

....g_gametype 0; g_gametype 8;....

et le serveur ignorera la deuxième commande, laissant le gametype à 0. Pour résoudre ce problème, tapez seulement, par exemple :

$ local_command = wait 10;g_gametype 8;

L'attente (``wait'') doit donner au serveur un peu de temps pour assimiler le fait que g_gametype vient d'être modifié. Cela vous permet d'écraser la valeur malgré tout. Je ne m'étendrai pas plus longuement sur ce sujet, cela ne concerne pas AJMCG. Mais n'incriminez pas immédiatement mon petit programme si le script compilé n'a pas le comportement espéré : cela peut venir du jeu ;-).


Comme vous pouvez le voir, ce programme est vraiment très facile à utiliser, et il est conçu pour épargner votre temps. Et le mien…


terminate

% terminate = 1

Si cette variable est définie à 1, le programme se terminera juste après la production des fichiers de sortie.

no_popup_cfg

% no_popup_cfg = 1

Si cette variable est définie à 1, le fichier cfg ne sera pas affiché après sa production.

no_popup_report

% no_popup_report = 1

Si cette variable est définie à 1, le fichier de rapport ne sera pas affiché après sa production.


IV. Licence

Vous êtes libre d'utiliser ce programme comme bon vous semble.

Si vous êtes satisfait de ce programme, ajouter un lien pointant vers conseiljedi.com ou gamallida.com sur votre site web serait une charmante attention ;-)

Toutefois, si vous utilisez la fonction de rapport, vous ne devez pas enlever la première ligne, ni l'en-tête du fichier cfg, sauf si le fichier est particulièrement lourd et que vous avez terriblement besoin de place (les serveurs ne supportent pas de trop gros fichiers cfg....)


Vous n'avez pas le droit de décompiler le programme, de le modifier illégalement, de, de, de,..... Je suppose que vous devez avoir saisi l'idée, donc passons à quelque chose de plus réjouissant.

V. Contact

Vous pouvez m'écrire sur conseiljedi.com ou gamall-ida.com, en postant dans les sujets adéquats.

J'accueillerai à bras ouverts toute critique constructive. N'hésitez pas à proposer de nouvelles fonctions, etc.....

Evitez de m'adresser un mail ou un message personnel sauf si vous avez des informations hautement confidentielles à me communiquer. En clair, ne m'envoyez jamais de mail ou de message personnel que je ne vous aurais pas expressément demandé. Un problème résolu par PM ne l'est que pour une seule personne. Une question et sa réponse sur un forum public sont accessibles par tous….

VI. Installation

Aucune installation n'est à proprement parler nécessaire. L'exécutable devrait fonctionner directement sur n'importe quel système ( testé sur Win XP et Win 98SE).

Si vous avez des problèmes pour faire fonctionner ce programme, ayez l'obligeance de me contacter. Faire une photo d'écran avec le message d'erreur est une bonne idée (utilisez le format de compression .PNG pour ce type de capture d'écran, c'est ce qui marche le mieux).

VII. Historique des versions

1.0

Première version mise en ligne.

1.5

Tableaux %0time et $0command remplacés par une nouvelle syntaxe de $0maps.
Amélioration du système d'édition de rapports. Ajout de rapports formatés.
Amélioration des vstr de listes de maps : ajout de numéros de maps pour les cycles comportant beaucoup de cartes.
Ajout de $comment
Ajout de terminate, no_popup_cfg, no_popup_report.
Compilation avec liens statiques pour éviter les dépendances.



{<§ Ida §>}