TUXEDO T. PENGUIN STARS IN TUXKART!

by Steve and Oliver Baker

Welcome to TuxKart for GoTM'ers!

If you are reading this then TuxKart is the HappyPenguin Game Of The Month - which means that a lot of people are going to swoop down and work frantically on it for a month or so.

This document is an effort to pass on a lot of knowledge in a small space in order to get you guys up to speed as quickly as possible.

I'll talk about CVS access, mailing lists, the structure of TuxKart, the directory layout, the source code and the models.

Access to TuxKart.

TuxKart's home page, CVS repository and mailing lists are on SourceForge at http://tuxkart.sf.net

All of the files are in the same repository.

Therefore, everyone who is planning to join in will need a SourceForge account, let me know your account name and I'll get you CVS access.

You have to subscribe to the tuxkart-devel mailing list in order to post there. The list is no moderated.

Run the 'reconf' script to set everything up right after a CVS checkout...end users can just run './config ; make' as always.

It may suprise you to learn that TuxKart is under 5500 lines of code. The reason for that brevity is that it uses a ton of library code from the PLIB library (http://plib.sf.net). Since PLIB is also one of my projects, we can make any changes to it that make sense from a general perspective.

I doubt any of you guys will need to dink around inside PLIB, but if you do, we'll get you developer access - and you'll need to sign on to THAT mailing list too.

Aside from PLIB, TuxKart only needs OpenGL. Keeping dependancies to a minimum is "A Good Thing" !

Directory Layout:

In the repository, you'll find the following directories:

contrib An empty directory where I can hold contributions until I decide to add them into the build. I don't think we'll want to use it for the GoTM process.
data The place where configuration files live. There is one master file called 'levels.dat' that lists all of the racetracks in the game and another called 'players.dat' that lists which kart models are used for which players.

levels.dat lists the base part of the filename of the track and the human-readable name. We append '.drv' and '.loc' to the filename to get to the two config files that each track uses.

The '.drv' file is a list of 2D coordinates that describe points along the track that the AI characters will try to follow. It has a couple of other uses that I'll describe later.

The '.loc' file contains the positions of all of the 3D object that make up the track. Generally, the first 3D object is the track itself, and the rest are decoration. You also set up the collectibles and the choice of music for the level.

There are better descriptions of all this in the 'doc' directory.

doc Yep - where the documents are. These are also the web site - everything in here ends up on the TuxKart web site, so all documents are in HTML.
fonts TuxKart uses a little text. It's rendered using the PLIB 'FNT' library which uses OpenGL to render the text. This keeps it portable - but requires fonts in '.txf' format. We have a tool to convert X fonts into TXF if needed.
images Contains all of the game textures, the splash screen, etc. These are all in '.rgb' format - which is easy to load and supported by PLIB. You can use GIMP, xv and most other image tools with '.rgb' files.
models These are in '.ac' format - as generated by the AC3D modeller. Getting from 'blender' to '.ac' - or writing a '.blend' loader for PLIB is something we'll need to consider because AC3D is a non-free program.
mods Music is in '.mod' format - a sequencer-based format. I used 'funktrackergold' to dink with these.
src The source code.
wavs Sound effects are in '.wav' format.

The configuration system is 'autoconf/automake'.

The TuxKart SourceCode:

start_tuxkart.cxx

The program starts off in 'main' (which is in 'start_tuxkart.cxx'). It draws the splash screen, sets up the GUI and has the PLIB 'PUI' GUI tool manage it. When the user hits the START button, control is transferred to the tuxkart_main() function in 'tuxkart.cxx'.

tuxkart.cxx

tuxkart_main() finds the configuration files, loads up the selected track, initialises the sound system, sets up the simple GUI used for the menu bar, loads up the player's kart models, the collectibles, and the projectiles then drops into tuxKartMainLoop() where the game proper is run.

tuxKartMainLoop() - is an infinite loop that updates the collectibles, the missiles, the players...then it tells the graphics, gui and sound subsystems to update themselves - swaps the buffers and goes around again.

Each of those things that tuxKartMainLoop updates is a separate C++ class - and most are in their own source files:

Vehicle Classes in Driver.h, Driver.cxx, KartDriver.cxx, PlayerDriver.cxx, AutoDriver.cxx, Traffic.cxx, and Projectile.cxx:

There is a class heirarchy of derived objects that move around on the race track in one way or another.

class Driver                      -- Any object that moves around the track.
  |
  +-- class Projectile            -- A driver for missiles and such like.
  |
  +-- class KartDriver            -- A driver for any goKart.
      |
      +-- class AutoKartDriver    -- A goKart driven by AI.
      |
      +-- class PlayerKartDriver  -- A goKart driven by the player.
      |
      +-- class NetWorkKartDriver -- A goKart driven from the network
      |                              (not operational yet).
      +-- class TrafficDriver     -- Intended for other vehicles that are not
                                     competing as players (not used at present).

In Explosion.h and Explosion.cxx:

class Explosion

Collectibles in Herring.h and Herring.cxx

(Could have a more meaningful filename!)

class Herring      -- A collectible herring model + animation
                      this is pointed at by multiple HerringInstance's.

class Shadow       -- The shadow of a spinning herring, etc.

class ActiveThingInstance    -- An instance of some object that a kart can
  |                             collide with and which will make it go faster
  |                             or explode or collect something.
  |
  +-- class HerringInstance  -- A specific herring.

Track Centerline data in Track.h and Track.cxx


class Track    -- A convenience class to represent an object's position
                  in "Track Space" - and to convert track space to
                  3D space and back again.

Aside: I should explain the concept of 'Track Space'....

Track space is a 'coordinate system' represented by a distance along the 'drive line' (remember 'data/{trackname}.drv'?), and a lateral offset from the drive line (how far away from the centerline of the track are you?). }

The GUI in gui.h and gui.cxx:

The GUI system is responsible for reading the mouse, keyboard and joystick - and also for setting up and maintaining the on-screen menu.

class GUI

3D Graphics in gfx.h and gfx.cxx:

The 3D graphics system is responsible for rendering the 3D scene. It manages the fog, lighting, etc. There isn't much code here because it's all in the PLIB scene graph library.

class GFX

Other files:

isect.h
isect.cxx
Deals with intersection testing - collisions between Karts and terrain - figuring out the height of things...that kind of stuff.
guNet.h
guNet.cxx
Network code (non-functional).
loader.h
loader.cxx
The code to parse the {trackname}.loc file, to load the 3D models, etc.
material.h
material.cxx
The '.ac' file format doesn't tell you everything you need to know about a polygon (eg it's coefficient of friction) - and it's convenient to be able to add that data somehow. There is a table that recognises certain textures as 'special' and sets their properties up particularly. Unrecognised 'materials' are defaulted. This table is read from 'data/materials.dat' on startup.
sound.h
sound.cxx
The sound system. Uses PLIB's sound library to play music and sound effects.
status.h
status.cxx
Manages status text on the screen. Help screens, 'about' screen, timing, speedometer, GameOver and 'WrongWay' signs.
utils.h
utils.cxx
Some handy math functions.

The Models:

These are generally clearly named, quite a few of the models are there from old versions, experiments, etc - don't be suprised if some of them are never used.