By Gamall
Date: 03-10-2007
JKA JA+ Teleportation Scripts Generator (J+TSG)
by Gamall Ida
v. 1.0
gamall-ida.com & gamall.ida@gmail.com & conseiljedi.com
I. Introduction
II. Minimal example, mandatory variables
III.1 So-Called Advanced Features - Syntax.
III.2 So-Called Advanced Features - Getting the coordinates ingame.
IV. Licence
V. Contact
VI. Installation
VII. Versions history
I. Introduction
It is, I believe, quite common for Japlus admins to have a teleportation script, allowing them to teleport quickly to the strategic points of their favourite maps.
Although writing such scripts is not exceedingly difficult, a fair amount of concentration and a great deal of time are still required, and the written script is not easy to maintain at all (as is often the case with qscripts).
This program aims at making writing extensive teleportation scripts almost as easy as just... finding the strategic points in the game ;-)
It works basically the same way as my Map Cycles Generator does. You type a config file (usually in .ini) using my VDF syntax, which is minimal and easy to maintain, then you feed it to the program, which outputs one (or several) "compiled" file (typically in .cfg), ready to execute in-game.
The output file is a typical teleportation script : one or two binded keys for cycling through your maps, one or two others for cycling through the selected map's locations (points), one validation key to go there (if you have admin privileges for amtele of course).
This readme first explains the syntax of the input files thoroughly, and then tells you how to get the coordinates and location names directly from the game, meaning that there is hardly anything left for you to type once you get to know the program :-p
II. Minimal example, mandatory variables
Let us see the file named "mini.ini".
$ output = mini.cfg
$ key_next_map = HOME
$ key_next_point = PGDN
$ key_go = END
$()maps = acad
{ acad
$ name = The Academy
$()points = Bar ; 1274 3272 183 0
Ruines ; 3100 -1200 200 0
Salle Haute ; 49 3725 1000 270
Point de Départ ; 9 220 200 0
Salle de Duel ; 1254 -2374 200 0
Salle de Duel Acrobatique ; -1537 39 200 180
Cimetière des Bots ; 841 6639 200 0
Bar Secret ; 1000 2000 200 0
}
This is the less complex input file you can create for J+TSG.
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 information about it.
The subset of the VDF syntax which you will meet 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 to that of C++ comments. The braces '{...}' introduce a variables group. These groups are used for the maps, e.g. 'acad'. 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 J+TSG, the file mini.cfg will be created if is doesn't exist, or overwritten if it does. The in-game command ]/exec mini.cfg will make it ready to use. Here, it is quite silly, since there is only one map... take a look at the compiled output :
seta *next_map "vstr *map_select0"
bind HOME "vstr *next_map"
bind PGDN "vstr *next_point"
bind END "vstr *goto_map"
seta *map_select0 "echo The Academy;set *next_map vstr *map_select0;set *next_point vstr *acad_0;"
seta *acad_0 "echo Bar;set *next_point vstr *acad_1;set *goto_map amtele 1274 3272 183 0"
seta *acad_1 "echo Ruines;set *next_point vstr *acad_2;set *goto_map amtele 3100 -1200 200 0"
seta *acad_2 "echo Salle Haute;set *next_point vstr *acad_3;set *goto_map amtele 49 3725 1000 270"
seta *acad_3 "echo Point de Départ;set *next_point vstr *acad_4;set *goto_map amtele 9 220 200 0"
seta *acad_4 "echo Salle de Duel;set *next_point vstr *acad_5;set *goto_map amtele 1254 -2374 200 0"
seta *acad_5 "echo Salle de Duel Acrobatique;set *next_point vstr *acad_6;set *goto_map amtele -1537 39 200 180"
seta *acad_6 "echo Cimetière des Bots;set *next_point vstr *acad_7;set *goto_map amtele 841 6639 200 0"
seta *acad_7 "echo Bar Secret;set *next_point vstr *acad_0;set *goto_map amtele 1000 2000 200 0"
Note that you can very well put an absolute path there : I personally use
$ output = C:\Program Files\LucasArts\Star Wars Jedi Knight Jedi Academy\GameData\japlus\tele.cfg
to generate the cfg directly where it needs be.
key_next_map ; key_next_point ; key_go
$ key_next_map = HOME
$ key_next_point = PGDN
$ key_go = END
You must define these variables with a valid q3 key. Since it is fairly obvious the script won't make any sense if there is no key to select the map, or the points in a map, or actually teleporting to the selected point, the program won't run at all if these values ar not defined. Be wary though, that it won't test the validity of your input... a valid input is any input that would work with the /bind q3 command.
key_previous_map ; key_previous_point
Take a look at normal.ini and its output....
$ key_previous_map = BACKSPACE
$ key_previous_point = PGUP
I hope you've guessed what these do... They are not compulsory, but if you have many map and/or points you will find they come in handy... Not defining them makes the output much smaller though. Not that anyone should worry about this since I've defined the % max_lines feature (see the Advanced section below).
maps
This array is most important, since it lists the maps (here meaning sets of locations for a JKA map) that will be processed to the cfg output. If you put nothing in there, you won't have any useful output.
The maps are VDF groups :
{ acad
$ name = The Academy
etc.....
The syntax is clearly
{ internal_map_name
to begin a new map, and "}" to close it. The internal map name is of no consequence, it is used only in the 'maps' array and in the names of the vstr of the output. One thing though : never, ever, use any dot (".") in it. The dot is a special VDF character, separating groups and subgroups ( group.subgroup ). Therefore, if there is a dot in the name of the map, it will lure the program into thinking you are dwelling into a subgroup... and unexpected behaviour may result...
I'm telling you all this because I made this mistake myself with the map called "a1.2" ;-)
If you have many many maps in your input file which you don't need every day in your script, just comment out their names and recompile ;-). That way you don't have to cycle through many maps, and when you need them, you can just uncomment the name and recompile... Use "//" to comment a line.
name
$ name = The Academy
This is the name that will be displayed in-game, when you cycle through the maps. Any q3/jka color code will fit in there, but you might want to take a look at the automatic prefixing features before doing that...
points
$()points = Bar ; 1274 3272 183 0
Ruines ; 3100 -1200 200 0
Like 'maps', this is an array. Each of its entries follows the syntax
<location name> ; <x> <y> <z> <rotation>
The location name is the name that will be displayed in-game, when you cycle through the locations of any given map. Any q3/jka color code will fit in there, but, like I said for the maps, you might want to take a look at the automatic prefixing features before wasting your time doing that...
III.1 So-Called Advanced Features - Syntax
Other variables can be defined, which greatly influence the output. You can see most of them in action in 'tele.ini'. Please open this file now and browse through it before resuming your reading.
global_echo_(map/point)_prefix
$ global_echo_map_prefix = ^1* ^1
$ global_echo_point_prefix = ^2
These vars will be added to each 'echo' statement in the compiled output, respectively for maps and points. They are mostly intented to be used for colors : the above example makes the first word of the name of every map red, with a red star before it, and every first word of every name of every location, whatever the map it is in, green.
echo_point_prefix
$ echo_point_prefix = ^3
This one works the same way than the global versions above, but is local to a map. It must be defined in a map variables group. Note that it does not replace the global prefixes : it is added after them. In the case of colors, it makes no significant difference.
repeat_prefixes
% repeat_prefixes = 1
By default, colors affect only the first word of the names of the maps and locations. This is a consequence of the way the game handles cvars and vstr. A way around this is to repeat the prefixes before each new word. Just define this var to 1 and this will be done. Personally I like the color-white standard, it is easier to read (if the color blends in the background, white won't and viceversa). But this is chiefly a matter of taste.
max_lines
% max_lines = 75
This one might seem useless, but in truth it is most useful... If you have ever attempted serious qscripting with JKA, you've met with the infamous "12 Kb" limit. Any cfg weighting more than 12 Kb is ignored by the game. Which means that if your output cfg file is greater than that, which it will quickly become once you have a few maps with a good number of locations in it, all you will get when execing it will be an arcane "C_buf overflow" message... (Incidentally this is the same reason why you lose your whole JKA configuration from times to times ;-) )
There are only two ways to avoid that :
- Losing weight. You can un-define the 'previous' buttons for instance... The bottom line is you can't do that without losing functionnality. Besides, you will still meet the limit sooner or later, and then what else can you do ?
- Cutting the cfg file into a string of smaller chunks.
- Each chunk must weight less than 12 k
- Each chunk must exec the next chunk.
'max_lines' allows you to choose the second option. I recommand setting it to 75, which means the program will not let a chunk exceed 75 lines. That makes about 10 k with both previous keys defined. Take a look at 'tele.ini'. The output is huge. JA+TSG generates
-> tele.cfg
-> tele.cfg_1
-> tele.cfg_2
Just exec the first, and you will see that all three are executed, and the script works seamlessly. Basically it makes no difference whatsoever to the end user on JKA.
If the output is smaller that 'max_lines', then the parameter will have no influence.
random_suffix_length
% random_suffix_length = 5
Adds a random suffix to every output vstrs. Useful if and only if you want to make several teleportation scripts cohabitate. This will prevent them from using the same cvars and thus overlapping each other... For most uses, keep it to 0 (or not defined, it is the same thing in VDF).
terminate
% terminate = 1
If set to 1, the program will terminate right after generating the output files. If you are modifying existing scripts quite often (changing coordinates ever so slightly etc) you might not want to control the output, but just updating the cfg, "exec"ing it ingame and testing. This variable (and no_popup too) spares you the trouble of closing windows each time you do that.
no_popup
% no_popup = 1
If set to 1, the generated cfg file shall not be displayed after generation.
III.2 So-Called Advanced Features - Getting the coordinates ingame
Assuming you've read everything to that point, and done a minimal amount of testing on your own, you must have realized by now that the only irksome part left for you is typing the coordinates. Don't worry, you won't have to ;-)
The program's main purpose is to convert an input file, easily altered, into a cfg file destined to the game. However, it can also extract certain patterns from condump files. Let me explain how you will add new maps to your input file.
Let's assume you have a correct (empty or not) input file, that is to say that the output and compulsory key variables are correctly defined.
You want to add support for the map "mymap". Just follow the steps :
-> add "mymap" to the maps array.
-> create the group "mymap" :
{ mymap
$ name = My Awsome Map !
$()points =
}
-> Now, lauch the game, and your map.
-> If it is not done, bind a key to the command 'amtelemark' : /bind X amtelemark
-> clear your console : /clear
-> Find the strategic points of the map. What you call a strategic point is entirely up to you ;-) Then, for each one of them :
--> Jump a bit, and while you are in the air, press the binded key. This will record the coordinates slightly above the point. Why jump ? Because if you take the coordinates right on the ground, if two people go to the same location roughly at the same time, one of them will crush the other. By taking the coordinates into the air, you reduce greatly the probability of such tragic occurences ;-). You can also /amtele to it immediatly to make sure the fall does not hurt you.
--> Then, you must name the point you just recorded : just say (command /say or 'Y' button or whatever you use to talk...) the line : "$$$ Name of the point". You don't have to name every point you record : only the last coordinates you took will be recorded and named. Others, along with unnamed coordinates, will just be ignored.
-> Once you've taken every point, just type /condump condump.txt in your console, and quit/minimize the game. This will create the file 'condump.txt' in your gamedata/japlus directory.
-> Drag and drop this file onto the program (or feed it to the executable in any other way) and it will create and display a file named 'condump_extract.txt', which contains lines such as
Name of the point ; -639 2228 855 0
Just copy and paste that to the 'points' array... It is done ;-)
Example : on mp/ffa5 I had the following condump :
]\amvstr nobots
{<§>} Bot Bête was sabered by {<§>} Bot Stupide
{<§>} Bot Stupide: Die!
TELEPORT MARKER : (-639 2228 855)
{<§ Ida §>}: $$$ Côté Obscur
TELEPORT MARKER : (-1 7 210)
{<§ Ida §>}: $$$ Centre
TELEPORT MARKER : (23 -1199 740)
{<§ Ida §>}: $$$ Plate-Forme
Obtained Large Shield Booster
TELEPORT MARKER : (481 1744 1481)
{<§ Ida §>}: $$$ Heal
{<§>} Bot Con died.
TELEPORT MARKER : (-1668 -1103 700)
{<§ Ida §>}: Réacteur
{<§ Ida §>}: $$$ Réacteur
TELEPORT MARKER : (-48 3 -742)
{<§ Ida §>}: $$$ Base
{<§ Ida §>} died.
TELEPORT MARKER : (1642 -807 -86)
{<§ Ida §>}: $$$ Vue sur Lave
]\condump condump.txt
Dumped console text to condump.txt.
And this is what the program extracted from it :
Côté Obscur ; -639 2228 855 0
Centre ; -1 7 210 0
Plate-Forme ; 23 -1199 740 0
Heal ; 481 1744 1481 0
Réacteur ; -1668 -1103 700 0
Base ; -48 3 -742 0
Vue sur Lave ; 1642 -807 -86 0
So, after a copy-paste, and some formatting to give it a straight look, I had the following input :
{ ffa5
$name = Taspir FFA (ffa5)
$()points = Côté Obscur ; -639 2228 855 0
Centre ; -1 7 210 0
Plate-Forme ; 23 -1199 740 0
Heal ; 481 1744 1481 0
Réacteur ; -1668 -1103 700 0
Base ; -48 3 -742 0
Vue sur Lave ; 1642 -807 -86 0
}
Now, all was left to do was :
compiling it (less than one second with drag and drop, terminate and no_popup) ,
going back to the game (1 sec with a minimizer),
typing /exec tele.cfg (1.25 sec).
Testing and enjoying the result.
Perfectionnists will want to set the rotation so that people teleporting look into the right direction. It is not relevant to my program (there is no way as of yet to generate the angle ingame), but in a few words : the angle is in degrees to the left.
Soooo. I hope I've convinced you that making huge teleportation scripts with my program can be quite easy, fun and not really time-consuming.
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 ;-)
If you publish scripts generated by this program, remember to give credit and a link, if you remove the generated logo.
Better still, publish the input file and a link to the program. That way people can easily customize it (colors, locations, presence of 'previous' keys or not and so forth and so on). Compiling an already written ini file is as easy as drag 'n droping the input file's icon onto that of the program...
I would appreciate it if you took the time to post your input files on my forums once there are many maps in them, so that I can put together a database of locations for most maps out there, which will be the 'tele.ini' shipped with the program ;-).
Now, for the bad guys out there :
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 information 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 Windows system.
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.
{<§ Ida §>}
PS : Thanks to Shuyoru for his enthousiasm ;--)