By Gamall
Date: 03-10-2007
Advanced JKA Map Cycles Generator (AJMCG)
by Gamall Ida
v. 1.5
gamall-ida.com & gamall.ida@gmail.com & conseiljedi.com
I. Introduction
II. Minimal example, mandatory variables
III. So-Called Advanced Features
IV. Licence
V. Contact
VI. Installation
VII. Versions history
I. Introduction
Although creating map cycles for Jedi Academy or any q3-based game is not what one would call an intellectually challenging process, it certainly is a tedious, irksome task. It becomes even more of a pain when you attempt to alter an already written cycle.
This program aims at making creation and maintenance of multiple complex cycles easier and more foolproof.
Instead of typing directly the commands destined to the game engine, you create a special file embedding the minimal relevant informations in a clear syntax, which will be used by the program to create a .cfg file to be put directly on your server.
Additionally, the program can generate detailed reports to paste on your website, and vstr listing the cycles and maps which can be used ingame by your admins.
Having a clear understanding of how vstr and map cycles work for JKA (q3 engine) is a prerequisite to using this software.
II. Minimal example, mandatory variables
Let us see the file named "mini.ini".
$ output = mini.cfg
$()cycles = mini
{ mini
$()maps = mp/ffa1
mp/ffa2
mp/ffa3
mp/ffa4
mp/ffa5
}
This is the less complex input file you can create for AJMCG.
NOTE : The input files are written in VDF syntax. VDF (Versatile Data Format) is a replacement to the standard INI format used by many programs, intended to be easier to use than XML and still powerful enough for many applications. I am currently developing VDF for C++, so if you are a C++ programmer you can contact me for more informations about it.
The VDF syntax is simple : $ means "string", $() means "array of strings". You may also meet % and %(), meaning "number" and "array of numbers" respectively. The comments // and /* */ are pretty straightforward since they work in a way very similar C++ comments. The braces '{...}' introduce a variables group. These groups are used for cycles, e.g. 'mini'. The spaces an tabulations have generally no meaning.
Now, let us examine the variables :
output
Defines the path to the "compiled" .cfg output file. Here it is "mini.cfg", meaning that when mini.ini is passed through AJMCG, the file mini.cfg will be created if is doesn't exist, or overwritten if it does, with the instructions describing the map cycles to the JKA server. Here, mini.cfg will contain
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
This array tells the program which cycles it must compute. Indeed, you can very well define many different cycles in the same VDF file, and yet compute only a select few into the output file.
$()cycles = one
two
Here, the cycles 'one' and 'two' will be computed. The others will just be ignored.
To define a cycle, you just have to write
{ exact_name_of_the_cycle
then write what is needed to describe the cycle. After which you must close the cycle by writing
}
You can then begin another cycle if you wish. They won't be taken into account until their name is written in 'cycles', though... Please note that the name of the cycle will always be the name of the vstr starting it, and that the name of the vstr launching the nth map of a cycle X will always be X_n.
maps
This array is obviously the heart of a cycle. Its entries have the following syntax :
<name of the q3 map> ; <timelimit> ; <fraglimit> ; <q3 command 1> ; <q3 command 2> ; <q3 command 3> ; ......... ; <q3 command n> ;
The slanted entries are not compulsory. As you saw in the previous example, it works fine with just the name of the map. The best way to see how it actually works is through an example : options.ini
$ 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"
Note that since the 'map by map' commandes come after the local commands, they can override both local and global commands if need be. (cf below)
III. So-Called Advanced Features
Other variables can be defined, which greatly influence the output. You can see most of them in action in 'cy_CJ.ini'. Please open this file now and browse through it before resuming your reading.
cycles_list
$ cycles_list = cycles
This means that a vstr named 'cycles' will be written, listing all the computed cycles :
set cycles "say ^2Cycles : ^5cy_STANDARD, cy_FUN, cy_CHRISTMAS, cy_DUEL, cy_SIMPLE, cy_CTF, cy_TFFA"
So your admins can, using amvstr cycles in JaPlus, or rcon vstr cycles in base, display a screen message enumerating all the cycles available on the server. Then, they can start said cycles by typing amv/rc vstr cycle_name.
maps_list_suffix
$ maps_list_suffix = SUFFIX
This code line means that, for each cycle, a vstr named 'cycle_nameSUFFIX' will be created, displaying the maps in the cycle 'cycle_name'. So, your admins know exactly which maps will be next... Example of computed output :
set cy_STANDARD_l "^2Cycle cy_STANDARD : ^75 maps : ^5adana, killbill, christmas_final, matrix_reloaded_final, mp/ffa4"
Note that if there are more than five maps in a cycle, the maps will be numbered, wich makes it easier for an admin to jump to a specific map.
report_path
$ report_path = report.txt
If defined, this variable will make the program create a file containing a complete overview of the computed cycles. For instance
{<§ 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
You can then paste this report on your webpage, or post it in your forum, so everyone knows exactly which maps are onto your server, and how long they last.
You are not entitled to remove or alter the first line : "{<§ Report Generated by Gamall Ida's Advanced JKA Map Cycles Generator §>}" in any way.
report_format
$ report_format = phpbb
This variable can be used to generate a more sophisticated output than the default "brut text". The following values have an effect :
"phpbb" : The report will be ready to copy-paste to a phpBB forum.
"ipb" : Idem for an Invision Power Board forum. As a matter of fact, the syntax is exactly the same than phpBB's.
"vb" : Idem for a vBulletin board. The syntax is the same but for the 'size' BBCode.
"smf" : Idem for a Simple Machines Forum.
The commands that follow are local, which means they only make sense inside a cycle.
report_special_color
$ report_special_color = orange
If the report is generated in a format that supports colors, you can change the main color of the report by altering this variable. Its behaviour will depend upon the chosen 'report_format'.
comment
This variable has a purpose only if you create a report. Its contents are then used to add a comment about the cycle in the report . Not anything to write home about, but it can prove convenient nonetheless.
{ 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...
Any command in 'init_command' will be executed once, when the cycle is launched. This is useful if you are certain nobody will start the cycle by calling directly one of the map-changing vstr. If this is left blank, the vstr X starting the cycle has exactly the same effect as the vstr X_1 launching the first map.
global_command
$ global_command = sv_timeout 500;
Any command or series of commands you store into this variable shall be added to each map-changing vstr of the output, which means that all cycles will be affected. For instance,
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"
you'll notice that the sv_timeout 500 ; has been added everywhere.
local_command
$ local_command = g_gametype 0;
This works roughly the same way 'global_command' does, but it affects only the cycle it is defined in, hence the epithet 'local'. You'll notice that the local commands are added after the global commands. This means that a given global command can be overridden by a local one. But in order to do this, you'll have to deal with JKA's limitations : more often than not, when a cvar is redefined two times in a row, the second modification is ignored. For instance, supposing you have
$ global_command = g_gametype 0;
because all your cycles but one are in FFA, and
$ local_command = g_gametype 8;
defined in the only cycle supposed to be in CFT mode, then your output will yield something like
....g_gametype 0; g_gametype 8;....
and the server will likely ignore the second command, leaving the gametype to 0. To solve this problem, just type for instance
$ local_command = wait 10;g_gametype 8;
The wait should give the server some time to assimilate the fact that g_gametype has just been altered, allowing you to override it straightaway. I won't discuss that further since it is irrelevant to AJMCG. Just don't blame my little program for something that's broken in the game ;-)
As you can see, these features are all really easy to use, and devoted to saving your time. And mine. There are some other minor variables :
terminate
% terminate = 1
Is set to 1, the program will terminate right after generating the output files.
no_popup_cfg
% no_popup_cfg = 1
If set to 1, the generated cfg file shall not be displayed after generation.
no_popup_report
% no_popup_report = 1
If set to 1, the generated report file shall not be displayed after generation.
IV. Licence
You are free to use this program as you see fit.
If you are satisfied by this program, putting a link to conseiljedi.com or gamall-ida.com in your website will be a nice touch ;-)
However, if you use the report function, don't remove the first line. Don't remove the header in the .cfg file either, unless it is very heavy and you need the space badly (servers won't handle too big cfg files...)
You are not free to perform any kind of reverse-engineering on this program, claiming credit for it wrongfully, or or or or... I guess you should have gotten the general picture by now, so let's move on to greener pastures :p
V. Contact
You can contact me on either conseiljedi.com or gamall-ida.com, and post in the relevant threads.
I'll welcome constructive criticism with open arms. Feel free to ask for new features and such...
Avoid PMing or emailing me unless you have highly confidential informations to divulge. That is to say never PM or email me, unless I specifically ask you to. A question answered by PM answers one person's concerns. A question answered on a public forum thread answers everyone's concerns...
VI. Installation
No installation per se is needed, the executable should run right out of the box on any system (tested on Win XP and Win 98SE).
Should you have trouble making it run, please contact me. Taking a screenshot of the error message is a good idea. (use the png compression format for that kind of screenshots, that's what works best).
VII. Versions history
1.0
First released version.
1.5
Arrays %()time and $()command replaced by new syntax for array $()maps.
Report system improved. Added formated reports.
Maps lists vstr improved : now adding numbers if the cycle is long.
Added $comment.
Added terminate, no_popup_cfg, no_popup_report.
Compiled with static links so as to avoid dependencies.
{<§ Ida §>}