
                   1 ..... Introduction to XRacer
               2 ..... Building and installing XRacer
                       2.1 ..... Requirements
                        2.2 ..... Compiling
                         2.3 ..... Problems
                         2.4 ..... Running
                         2.5 ..... Controls
                        2.5.1 ..... Joystick
                        2.5.2 ..... Keyboard
                         2.5.3 ..... Mouse
                     3 ..... Submitting patches
                       4 ..... Help required
                5 ..... Creating scenery and tracks
                         5.1 ..... Overview
                      5.2 ..... Basic concepts
               5.3 ..... Step 1: Make the track model
              5.3.1 ..... Tips for making a good track
              5.3.2 ..... Tracks which go up and down
                  5.3.2.1 ..... Linear increments
                      5.3.2.2 ..... Sine waves
               5.3.3 ..... Track shape file reference
                 5.4 ..... Step 2: Add the scenery
           5.4.1 ..... Tips for creating scenery objects
        5.5 ..... Step 3: Create the track description file
                     5.5.1 ..... Basic outline
          5.6 ..... Step 4: Create the final XRacer track
                                  
1 Introduction to XRacer

   XRacer is a Wipeout clone. At the moment it is incomplete, but
   I will be working on the following areas over the next few
   weeks:
     * better game physics (eg. sometimes the craft turns over)
     * instrument panel (partially done)
     * scenery
     * time trial and arcade mode
     * weapons, powerups
     * LAN multiplayer mode
       
   I'm looking for people who want to design tracks. I estimate
   about 10% of the work involved in cloning Wipeout is the game
   engine and about 90% is track design. See section 5 for more
   details if you are interested in designing or building tracks.
   
   Distribution license is the GNU General Public License. Please
   see the file COPYING for details.
   
2 Building and installing XRacer

  2.1 Requirements
  
   For best results, this program requires Linux 2.2, X11, Mesa
   3.0, GLUT, libjpeg and a supported 3D accelerator card.
   
   Mesa 3.1 does not work with XRacer.
   
   An analogue joystick is highly recommended. In fact, it is the
   preferred way of controlling the game.
   
   Periodically, I add patches to support other operating
   systems, and periodically I break support for other operating
   systems. However, at time of writing, XRacer is (or has been)
   compiled on the following platforms:
     * Windows 95/NT with the Cygnus Cygwin library,
     * Sun Solaris for Sparc (requires 2.6 or above),
     * FreeBSD,
     * MkLinux and LinuxPPC,
     * IBM AIX,
     * SGI Irix.
       
   You should be able to use any OpenGL 1.1 compliant library. I
   have also compiled XRacer using the Matrox G200 GLX driver.
   
   The GLUT library is commonly distributed in the MesaDemos
   package. Note that you have to install this package as well as
   MesaLib to play XRacer.
   
   A 3D accelerator card is really required. It is unlikely that
   I will ever do a version of XRacer that can be played without
   3D acceleration. Sorry.
   
  2.2 Compiling
  
   Type:
./configure && make

   If the configure script fails to detect something about your
   system, then please tell me. The most common problem is that
   you have glut and a GL library installed, but in a strange
   place, and the configure script can't find them.
   
  2.3 Problems
  
   Before mailing me, check that you can get any GL program to
   compile and run on your system. If you can't do that, then
   please ask your local guru, or subscribe to a newsgroup such
   as 3dfx.glide.linux at news.3dfx.com.
   
   If you have an XRacer-specific compilation problem, then ask
   first on the xracer mailing list. Copy and paste all the
   compilation messages, not just the ones you think may be
   relevant.
   
  2.4 Running
  
   Set the XRACER_HOME environment variable to whereever you have
   unpacked the XRacer data files. For example:
export XRACER_HOME=/usr/local/lib/xracer-data

   Type:
src/xracer

   At the moment, you have to run XRacer from the directory in
   which it was built like this, otherwise it can't find its data
   files. This will, of course, be rectified in a later release.
   
   To run in time trial mode (no other players), add the -t
   option on the command line.
   
  2.5 Controls
  
    2.5.1 Joystick
    
joystick left      bank/turn left
   "     right     bank/turn right
   "     up        pitch nose down
   "     down      pitch nose up
   "     button1   fire weapon or use powerup
   "     button2   accelerate

    2.5.2 Keyboard
    
PAGE UP            accelerate
PAGE DN            brake
LEFT               bank/turn left
RIGHT              bank/turn right
UP                 nose down
DOWN               nose up
SPACE              fire weapon or use powerup
s                  take a screenshot
r                  reset position to beginning of track
f                  display frame rate
n                  invert mouse controls
d                  use mouse to control
.                  increase mouse sensitivity
,                  decrease mouse sensitivity
f                  toggle FPS display
ESC                quit game

    2.5.3 Mouse
    
   Move the mouse to the centre of the XRacer window and press
   'd' to activate it. Move the mouse around to go up, down, left
   and right.
   
3 Submitting patches

   Patches are most welcome. Please send them to my email
   address: Richard Jones <rich@annexia.org>.
   
   Please send me UNIFIED DIFFS only! I will ignore other types
   of patches. The FAQ explains how to create unified diffs.
   
4 Help required

     * How do I add rules to Makefile.am to build arbitrary files
       using my own commands (overriding all inbuilt build
       rules)?
       
5 Creating scenery and tracks

   This section describes how to use a modeller to create tracks
   and scenery.
   
   Currently, the only supported modeller is AC3D, which is a
   commercial program. However, I hope to change this in the
   future, and allow people to use other modellers. I'm
   particularly interested in Blender, even though it's interface
   is so baroque that I still haven't worked out how to create
   even the simplest triangle.
   
  5.1 Overview
  
  +----+
  |   \|       The track shape file defines
  |    |       the overall shape of the
  |    |       track.
  +----+

track.tsf

    |
    |
    v

mktrackmodel -v track.tsf

    |
    |
    v

  +----+
  |   \|       The AC3D modeller input file
  |    |       containing just the outline
  |    |       of the track.
  +----+

 track.ac

    |
    |
    v

  AC3D

    |
    |
    v

  +----+
  |   \|       The AC3D modeller output file
  |    |       containing the track, perhaps
  |    |       modified, and all scenery objects.
  +----+

track+scenery.ac

    |
    |          +----+
    |          |   \|      The track description file contains
    |          |    |      extra information about track and
    |          |    |      scenery components.
    |          +----+
    |
    |      track+scenery.tdf
    |
    |            |
    |            |
    v            v

mktrack -v track+scenery.ac

           |
           |
           v

        +----+
        |   \|       Resulting XRacer track file.
        |    |
        |    |
        +----+

    track+scenery.trk

           |
           |
           v

     Load into XRacer.

   The diagram above outlines the process of creating a new
   track. As you can see (if you have a colour browser) there are
   three tools involved, shown in red. The tools are:
     * mktrackmodel: Creates a model of the track for the 3D
       modeller.
     * AC3D: The 3D modeller.
     * mktrack: Combines the output of the 3D modeller and the
       track description file into a final XRacer track file.
       
   There are five files, shown in blue. The files are:
     * track.tsf: The track shape file, which you must write,
       which describes the overall shape of the track.
     * track.ac: The automatically generated file which you feed
       into the modeller.
     * track+scenery.ac: The modeller generates this file which
       contains the original track and scenery you have added.
     * track+scenery.tdf: The track description file, which
       contains extra information about scenery components,
       triggers on the track, power-ups and go-faster spots.
     * track+scenery.trk: The final track file which can be read
       into XRacer.
       
  5.2 Basic concepts
  
   XRacer divides tracks up into segments. A segment is thin
   cross-section of track about 10 units wide by 1 unit deep.
   When drawing the track, XRacer knows what segment the craft is
   currently in, and draws only a few segments in front of the
   craft.
   
   In addition to segments, a track consists of a number of
   scenery objects. Scenery objects are individual pieces of
   scenery. Like track segments, XRacer is careful only to draw
   the scenery objects which can be seen from the current
   segment, and to do this, it stores a list of scenery objects
   visible from each segment.
   
   Track segments can have associated triggers. A trigger causes
   some sort of event to happen when a player flys over that
   track segment. Typical triggers are:
     * Go-faster spots.
     * Power-up spots.
     * Crowd noises and other sound effects.
     * The start point on the track has its own trigger.
     * Checkpoints around the track have their own triggers.
       
  5.3 Step 1: Make the track model
  
   You could draw the track out by hand, but this would be
   tedious. The mktrackmodel tool allows you to generate a track
   automatically from a much shorter descriptive file called the
   track shape file (track.tsf). The track shape file contains a
   list of track sections, as in this simple example of a short
   flat oval track:
straight 1000      flat
rightcurve pi 500  flat
straight 1000      flat
rightcurve pi 500  flat

   This track consists of four sections (but many more segments):
   a 1000 unit long straight section, a 180 degree curve, a 1000
   unit long back straight and a 180 degree curve back to the
   start.
   
   Since the start of the track is always at segment 0, it makes
   sense to split one of the straights as follows to create a
   more realistic track:
straight 700       flat
rightcurve pi 500  flat
straight 1000      flat
rightcurve pi 500  flat
straight 300       flat

   If you feed this file into the mktrackmodel program like so:
mktrackmodel -v track.tsf

   you will end up with an AC3D modeller file for this simple
   track called track.ac.
   
    5.3.1 Tips for making a good track
    
   All curve angles are expressed in radians, not degrees. Use
   the following table to convert from degrees to radians:
degrees    radians
0          0
45         pi/4
90         pi/2
135        3.pi/4
180        pi
225        5.pi/4
270        3.pi/2
315        7.pi/4
360        2.pi

   Tracks must always join up. In the example above, this is
   obviously the case, but when you come to construct more
   complex tracks, you will need to fudge things. First remember
   that all the angles in the track should add up to 2 * PI (left
   curves count negative and right curves count positive, or vice
   versa). If the angles don't add up, you'll need to either add
   a curved section at the end to make up the difference, or else
   fudge one of the curves in the track.
   
   Secondly you should look at the track output in the modeller,
   and increase or decrease segment lengths until the two ends of
   the track meet (or are very close to meeting). If you get the
   two ends of the track within a hairs breadth of each other,
   you can adjust the ends by hand in the modeller.
   
   After creating a track, you should play the track in XRacer
   and adjust it until you are satisfied that it is correct. Once
   you start to add scenery to a track, it is impossible to go
   back and change the track shape. Therefore you must be
   satisfied that the shape is correct before starting to add
   scenery. To export the track into XRacer, you should do:
mktrack -v track.ac

   and load track.trk.
   
   [Editor's note: This isn't quite the correct procedure yet. At
   the moment you need to generate an outline track.tdf file as
   well. In the final game that file will be generated by
   mktrackmodel for you to edit.]
   
    5.3.2 Tracks which go up and down
    
   The tracks shown so far have been flat. To make tracks which
   go up and down, you need specify something else instead of the
   flat directive. The possible directives are: sine and linear.
   
      5.3.2.1 Linear increments
      
   The linear directive specifies that the track height over this
   section varies linearly with distance. The total distance to
   gain (positive) or drop (negative) is given as an argument.
   Hence a simple straight slope which is 400 units long and
   drops 50 units would be:
straight 400 linear -50

      5.3.2.2 Sine waves
      
   The sine directive specifies that the track height over this
   section varies as a partial sine wave. For this directive, you
   specify two angles and a distance.
^
| _-_
|/   \
+-----+-----+-> angle
|      \   /
|    pi -_- 2pi

0

  Sine wave

   The shape of a sine wave is shown above. The peak is at angle
   pi/2 and the trough at angle 3.pi/2. So, to specify a smooth
   down-curve, followed by a linear drop, followed by a smooth
   leveling off, you might do:
straight 200  sine pi/2 3.pi/4 -3
straight 600  linear -50
straight 200  sine 5.pi/4 3.pi/2 -3

    5.3.3 Track shape file reference
    
file            ::= line*
line            ::= track-type height-function "\n"
track-type      ::= straight-type | leftcurve-type | rightcurve-type
straight-type   ::= "straight" length
length          ::= number
leftcurve-type  ::= "leftcurve" angle radius
rightcurve-type ::= "rightcurve" angle radius
radius          ::= number
height-function ::= "flat" | linear-function | sine-function
linear-function ::= "linear" height-gain
height-gain     ::= number
sine-function   ::= "sine" start-angle end-angle height-gain
start-angle     ::= angle
end-angle       ::= angle
angle           ::= number | "pi/4" | "pi/2" | &c.

  5.4 Step 2: Add the scenery
  
   The second step is to load the modeller file into your
   modeller and add scenery. Before doing this, you should first
   make a copy of the file, like so:
cp track.ac track+scenery.ac

   Only edit and add scenery to the copy of the file, never to
   the original, which may be overwritten when you do make.
   
   You can now add scenery objects. Please read the following
   tips closely when you create new scenery objects.
   
    5.4.1 Tips for creating scenery objects
    
   The unit of visibility is a single object. A single object is
   either displayed or not displayed. Preferably you should
   create lots of small objects rather than few large objects.
   There is no penalty for creating lots of smaller objects
   unless you have to divide a surface or separate several common
   vertices.
   
   Each object should have a name of the form ``name_number''.
   The number part is the scenery object number. Number scenery
   objects serially, starting at zero. In AC3D, you can name an
   entire object or group of surfaces using the text box in the
   lower left part of the display. Here are some well-formed
   object names:
skyscraper_0
start_light_1
tunnel_mouth_2

   The unique object number is used when you refer to objects in
   the track description file (of which more below).
   
   XRacer can only draw convex polygons. In AC3D it is easily
   possible to create a concave polygon which will not display
   properly in XRacer. To get round this, call
   Surface->Triangulate on each concave surface.
   
   XRacer supports two types of animated scenery objects: (1) an
   object where only the surface texture is animated, or (2) the
   whole object moves in each frame. Both types of animation are
   described in section 5.5 below.
   
   NOTE: I'll add some more information about moving track
   vertices around, and what the different track polys mean, and
   changing track textures.
   
  5.5 Step 3: Create the track description file
  
   The track description file is used to add extra descriptive
   information about the track which is not contained inside the
   modeller file.
   
   Examples of such information include:
     * The location of go-faster and power-up spots on the track.
     * Crowd noises and other sound effect triggers.
     * The location of the start segment and checkpoint segments
       around the track.
     * The visibility of one segment from another and the
       visibility of scenery objects from segments.
     * Details about animated textures.
       
    5.5.1 Basic outline
    
   A track description file normally has a .tdf extension. It
   consists of three parts (which may come in any order and
   individual statements may even be interleaved arbitrarily):
     * The track description.
     * The scenery description.
     * Miscellaneous section.
       
   The track description consists of a list of segment
   statements, as in this example:
segment 0       lookahead 50 start
segment 1-35    lookahead 50
segment 36-116  lookahead 50
segment 117-153 lookahead 50
segment 154-159 lookahead 50
segment 160-169 lookahead 50 left-powerup right-fast
segment 170-235 lookahead 50
segment 236-329 lookahead 50
segment 330-335 lookahead 50 left-faster right-faster
segment 336     lookahead 50 left-faster right-faster checkpoint
segment 337-339 lookahead 50 left-faster right-faster
segment 340-491 lookahead 50
segment 492-518 lookahead 50
segment 519-587 lookahead 50
segment 588-623 lookahead 50
segment 624-629 lookahead 50
segment 630-639 lookahead 50 left-fast right-powerup
segment 640-677 lookahead 50
segment 678-721 lookahead 50
segment 722-772 lookahead 50
segment 773-795 lookahead 50

   Each segment statement describes either a single segment or a
   number of segments. For each segment or list of segments,
   there are a number of possible fields:
     * lookahead: Defines the lookahead parameter. This specifies
       how many segments ahead of this one that the car can see.
       In the example above, each segment has a lookahead
       parameter of 50, but in complex tracks, it makes sense to
       vary the lookahead (reducing it at corners in tunnels,
       increasing it on straight open roads) for efficiency. The
       lookahead parameter is required.
     * start and checkpoint: These define a segment which is
       either a start point of a checkpoint. Each track must have
       exactly one start segment, and can have as many
       checkpoints as required (normally these should be evenly
       spaced around the track).
     * left-fast, left-faster, left-powerup, right-fast,
       right-faster, right-power: These denote a trigger point on
       the track. The trigger point is either a single arrow
       (fast), a double arrow (faster) or a star (powerup).
       Trigger points may appear on either side of the track, and
       you can mix trigger points on both sides of the track
       arbitrarily. NOTE: Trigger points must be aligned to
       segments with numbers multiple of 10, as in the example
       above. So:
segment 630-639 lookahead 50 left-fast
       is permitted, but:
segment 635-641 lookahead 50 left-fast
       is forbidden. Because of limitations in the current game
       engine, the actual trigger point always lies on the
       segment numbered (n % 10) + 4.
       
   The scenery description section allows you to define
   visibility of scenery objects from track segments. Normal,
   non-animated scenery objects look like this:
scenery 3 visible 720-795,0-8

   This object, called ``name_3'' in the model, is visible from
   segments 720 through 795 and segments 0 through 8 only. When
   the craft is in one of these track segments, the scenery
   object is drawn. Otherwise it is not drawn.
   
   To do scenery objects with simple animated textures, you would
   do:
scenery 0
scenery 1 copy 0 texture images/tex2.jpg
scenery 2 copy 0 texture images/tex3.jpg
animator 3 visible 720-795,0-8 nr-frames 3 frames 0 1 2 ftime 0.5 0.5 0
.5

   In this case the track only contains a single real scenery
   object, called ``name_0''. The three objects 1, 2 and 3 are
   virtual objects created by the mktrack utility (see
   section 5.6) below.
   
   We assume that the real scenery object has texture
   images/tex1.jpg. The second line creates a copy of scenery
   object 0 (called scenery object 1) and changes the texture to
   images/tex2.jpg. Similarly the third line creates another copy
   called scenery object 2. Notice that scenery objects 0 - 2 are
   not visible.
   
   The fourth line creates the animated scenery object, and
   stipulates that it is visible from segments 720-795 and 0-8.
   It says that the scenery object contains 3 frames, namely
   scenery objects 0, 1 and 2, and that each frame is displayed
   for 0.5 seconds.
   
   To create an animated scenery object where what is animated is
   more than just a texture, you use a similar principle. In this
   case, we create three real scenery objects in the actual
   modeller file. These are the three animated frames in the
   correct positions. Now only the following lines are required
   in the track description file:
scenery 0
scenery 1
scenery 2
animator 3 visible 720-795,0-8 nr-frames 3 frames 0 1 2 ftime 0.5 0.5 0
.5

  5.6 Step 4: Create the final XRacer track
  
   Once you have created a scenery file and a track description
   file, use the mktrack utility to finally create an XRacer
   track file.
   
   Assuming you have track+scenery.ac and track+scenery.tdf and
   wish to create track+scenery.trk, you would do:
mktrack -v track+scenery.ac
     _________________________________________________________
   
   
    Richard Jones
    
   Last modified: Tue Jul 20 19:41:39 BST 1999
