This document is written prior the source code of the library that will manage resource files. So informations written here may not describe exactly resources files. I hope so, this will mean that the specifications of a resource file has been strong enough very early...If you find here information that is no more relevant for Stuntux, please let me know (where in this book, and why (by indicating the source file / method)).
The resource files are used to store data of many kind:
A resource file can include any other file.
The version entry prevent reading recent resource files by old stuntux versions. This entry prevents stuntux to either crash (hey : this may not happen if it is well written!), or to display strange things / bad frames etc...
A vertex is a 3D point having three coordinates. x (horizontal left to right), y (vertical) and z (horizontal back your head to front of your head (then far far from you :-))).
The grammar of a vertex is
vertex_name x y z;
where vertex_name is an identifier that begins with the letter v. x,y and z are floats.
For yet, let say that 1 is one meter long, even if this convention has not been defined at the time of this document creation.
Notice that a vertex may appear either in a vertices set or alone in a resource file.
v_135 1.2 2 4;
Here is perhaps the most complex part of a resource file: the bloc.
The reader may refer to the bloc.h and bloc.cpp source files to have more information (especially about limits that are given here and that may be broken with recent releases of stuntux).
bloc.h contains also important information on how vertices are used. You may consider four vertexes v1 v2 v3 and v4, a rectangle R1 built with v1..v4 in this order, and a rectangle R2 built with v2 v3 v4 v1 in this order to understand things.
Now remember that R1 and R2 are not the same for a bloc.
Also, keep in mind that the rectangle MUST BE FLAT ! Thus, v1 ... v4 must belong to the same plane ! Unless, strange graphics effects and/or strange behaviour may occur ! You are warned ! Stuntux will not may any test on coplanar points needs (not yet) ! Finally, v1..v4 must not define a cross path. (drawing a line v1->v2->v3->v4->v1 must not show a cross).
bloc entity in resource file
The bloc entity refers directly to the bloc class of the C++ code source. So anything is is not yet possible.
A bloc is composed by
The front rectangle
Two open/close flags (front and rear).
The invisible flag.
See bloc.h code source for more information about how the direction is defined. The direction is usedby the IA. Hey, it will not be fair if the computer went in the wrong way !!!
In the resource file, the direction is simply indicated by the order of the blocs in the map.
This is a abstract property of a bloc that must be described to understand the open/close flags.
A bloc has a front side and a back side. Those sides are automatically determined by the stuntux engine. The top rectangle is used for that. see mrr (rear or back rectangle) and mrf (front rectangle).
Sometimes, and it was the case with stuncar under Atari/Amiga, roads are stopped and a jump are possible. Generally, a road is continuous, and the car has only to keep its tires on it :-)
But in our 3D stuntux world, cars can fly and the roads may have disruptions !
Top rectangles defines the road itself and *MUST* be contiguous from one bloc to the following one. When there is a jump, the 3D engine must draw a wall on the either the front side or the back side of the bloc. The open/close flags defines this drawing behaviour.
Hey, writting this book, I can imagine that once again, the stuntux road engine may be able to automatically determine the values of the open/close flags. These flags may so disapear, and thus, a level editor will not have to handle these flags :-)
The rear open flag is represented using either 'rear' or 'r' in resources files meaning, when present that the rear is closed (drawn).
The front open flag is represented using either 'front' or 'f' in resources files meaning, when present that the rear is closed (drawn).
There is a very important thing about bloc: to form a road, stuntux needs consecutives blocs. Two blocs are consecutives if they have at least one vertex identical. There is another condition, because bloc are oriented, the identical vertexe(ices) must belong to the front side of the first bloc and the back side of the second bloc.
So you may have a question : if all blocs for a given road must be contiguous, so how to design a jump with two consecutives bloc ? Simple, use the invisible flag. The engine needs absolutely consecutives blocs to know where the road is, even if the road is in the air ! See the invisible flag.
The invisible flag is used for blocs that are needed to join visible blocs (for a jump).
You won't find the Invisible member of the class bloc, but only Visible.(see bloc.h).
The invisible flag is represented using either 'invisible' or 'i' in resources files.
Cars are following roads. Roads are described using blocs. So a bloc is simply a small part of a road. Let say yet that a bloc is approximatively 2 meters long. Take care, this value may changes (hum...read the file xxx but what file to read, I really don't know yet), just remember that the length of a block has a minimum and a maximum.
Yes, a bloc is a part of the road, but what kind of road can exists with stuntux ? And how to describe a road ?
The bloc resource data is designed to allow any kind of road. Simple roads, multi way roads, elevating, looping roads,cross road (under or over, even through), helicoids.
A road is normally closed. (To be defined !!!)
A road is directly represented in resources files as a succession of many blocs.
The road itself is defined by the rear rectangles of the blocs (i.e bloc entries).
The first rectangle of the road entry is the rear rectangle of the first bloc of the road.
The next one is both the front rect of the first bloc and the rear rect of the 2nd bloc.
And so on...a simple road is a list or bloc entries.
As described before, a road can have many paths.
A map is a set of things that can be displayed on the screen during the race except cars, scores and radar map.
Here is the grammar of resource files. Yep, this grammar is certainly not well written, I mean for purists. But it is at least readable and will be very helpful for who wants to write a level editor (anybody there ?).
resource_file:=version [ vertexes | road ]*
comment:='//' ....... <cr>;
version:=version [0-9]*'.'[0-9]*;
road:='road' road_name { bloc_entry* [path]*};
road_name:='road_'alphanumeric*;
road_entry:=bloc_entry [ path_entry ]*;
path_entry:='path path_name {' bloc_entry* '}';
path_name:='path_'alphanumeric*;
bloc_entry:=rectangle ['invisible' | 'i'] ['front' | 'f'] ['rear' | 'r'];
rectangle:=vertexe vertexe vertexe vertexe;
vertices:='vertices' { vertices_entry* };
vertex_entry:=vertex_name x y z ';' ;
vertex_name:='v'[alphanumeric]*;
alphanumeric=0-9 | a-z | A-Z | '_';
version 0.1
vertices
{
va1 0 1 0;
va2 0 1 1;
va3 0 0 1;
va4 0 0 0;
vb1 1 1 0;
vb2 1 1 1;
vb3 1 0 1;
vb4 1 0 0;
}
road m_level_1
{
va1 va2 va3 va4 r;
vb1 vb2 vb3 vb4 f;
}
Symbols are global for all files. doesn't matter the order and when the file is read. Using twice the same name for two variables will produce an error. The parser will not forget, once read, any variable. For example, if a vertexe is stored with the name 'v01', it will exist until the program ends (or crashes :-)
Roads concept is powerful (I think) but depends directly of the bloc class abilities. So read carefully the bloc description in 'data description chapter'. Keep an eye also on the bloc class.
The circuit class is intended to implement a list of bloc that may represent as many roads as wanted
TO BE CONTINUED...
This document was generated using the LaTeX2HTML translator Version 2002 (1.62)
Copyright © 1993, 1994, 1995, 1996,
Nikos Drakos,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999,
Ross Moore,
Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -split 0 -show_section_numbers resources_files.tex
The translation was initiated by Francois Biot on 2003-01-25