Home

Don't just jump in developing for Racer, but read this page first.

Introduction

Development for Racer can be a daunting task at first; there is a LOT of information. That is the hard thing and also the fun thing about Racer; you can go very deep.

Here I'll outline what you can do to ease development. This document will assume you're using the latest development version, which can be obtained from the beta download pages.

The RACER.INI file

Most settings global to Racer are stored in racer.ini. This is a structured ASCII file, which uses '{' and '}' to indicate the beginning and end of variable trees. An example follows below:

  resolution
  {
    x=50
    y=10
    samples
    {
      aa=16
    }
  }

It's a bit like XML, only it only supports unique paths. Settings in racer.ini are referred to on this website using dotted paths. For example, for the above we say that resolution.samples.aa=16. In case of duplicate value names, the first one is used, so if you have:

  resolution
  {
    x=50
    x=20
  }

In this case, resolution.x will be 50, not 20. It's better to comment out the 2nd resolution.x variable to avoid confusion though:

  resolution
  {
    x=50
    ;x=20
  }

Other ini files exist; they are used for cars (data/cars/<mycar>/car.ini) for example, or track descriptions (data/tracks/<mytrack>/track.ini). They all use the same layout.

Ingame reviewing of game state

There are a bunch of variables you can check out while racing; use Ctrl-1 upto Ctrl-9 for various informational lists that display anything from tire forces upto network clients (some keys have multiple screens, indicated in the top with '1/2' for example; tap Ctrl-1 twice for example to toggle both screens). Use Ctrl-0 to turn the debug view off. You can also use the script command 'debug <n>' to set the same screen.

The QLOG warning/error file

Racer will output error, warning and some informational message to QLOG.txt. The file can be found after a run in the Racer executable directory. Open the file in a text editor and scroll down to see the latest run messages (all messages are appended, with a maximum of 10Mb, at which point the file is renamed to QLOG_OLD.txt and QLOG.txt is restarted).

A lot of people ignore QLOG, but especially when developing content it's important to keep track. Racer v0.7.4+ has an option in racer.ini to specifically save the last run's text to QLOG_LAST.txt. Set racer.ini's dev.log_last option to 1, and Racer will save all latest run messages in the separate file (as well as QLOG.txt) and upon exiting, it will run notepad (it's Windows only, this option) with QLOG_LAST.txt, so you immediately see any error messages. If only informational messages were output during the last run, notepad will not be run, so you only will see a window come up if there was a real problem.

I'll say it another time: don't ignore QLOG warnings, even if things work. They are a pointer that something is wrong and needs fixing.

Catching debug message output

Racer hardcore messages can be tracked by setting dev.terminal to 1 in racer.ini. Be prepared that a lot more technical stuff is printed there, but it can help catching errors & warnings early on while developing cars & tracks (use 'reload car' and 'reload track' to quickly check changes). You can also use the terminal console command while inside Racer to spawn a terminal window which will print out messages from that moment on.

Racer can also output these messages directly to a network UDP location, which can be local or on the netwerk. In racer.ini, search for the dev.udp_out option and specify a host and port number. For example: dev.udp_out=192.168.0.102:7000

In this case, any QLOG message will immediately go to that host & port combination. You need a UDP terminal to read these messages, but fortunately Racer comes with udpterm, which you can run using 'udpterm 7000' for example (run a command prompt, go to the Racer directory using 'cd \sims\racer' for example, then run 'udpterm 7000'). This can be on the same computer as where Racer is running (in that case, set dev.udp_out to 127.0.0.1:7000), or on a different computer on the same network.

Try to use port 7000, as it isn't used elsewhere in Racer.

Not only QLOG messages are sent to the UDP port; there are usually a lot of extra messages that you can watch this way. In fact, it's the way I do a lot of debugging. Sending UDP messages doesn't take a lot of processing power.

Increasing the amount of debug output

Some features you can turn on while developing:

• Starting from v0.8.9, you can set dev.strict to 1. When enabled, this 'strict mode' will nag whenever errors occur in a track or car. It will collect them, so it only pops up after loading a track or car (and if errors or warnings appeared). It's a bit like log_last (see below) but more strict. Also, strict mode might in the future nag even more about problems, such as Cg shaders not being defined (a plan for v0.9.0 final - most graphical effect really require Cg shaders).
• Set dev.note_ini_fallback to 1 to get warnings in QLOG whenever a car.ini uses a value from data/cars/default/car.ini rather than from the car's car.ini file. This may indicate a value you may want to explicitly set yourself, instead of relying on a default.
• Set dev.note_ini_unused to 1 to get warnings in QLOG.txt about car.ini values which were never visited by Racer. For example, if you make a typo (say you use 'rollbar.count' instead of 'antirollbar.count'), Racer will note that rollbar.count was never referenced. It does generate a few false positives, such as general car information, but for the rest, any parameters that are not used are often a sign of something wrong.
• Set dev.log_last to 1. This stores all warnings and errors in a separate QLOG_LAST.txt file. If any warnings/errors are generated during a run, Notepad is automatically run on exit, immediately notifying you of any problems.

Visual debugging and development tools

The built-in console language of Racer supports some handy commands to visually check things when developing cars and tracks. Most 'show' commands have a corresponding 'hide' version. None of these commands are persistent (in that they survive a restart of the program) - most script command do nothing persistent actually.

• Use show aero to see a representation of the aerodynamic airflow behind the car. This is a relatively simple triangle which falls off in 2 directions: longitudinally behind the car, and laterally as it nears the edges of the triangle. The visual representation using transparency doesn't entirely match with the calculation (which is a limitation of OpenGL when drawing colored triangles); it really should become fully transparent as it moves away longitudinally from the car.
  Use hide aero to hide the slipstream again. Note that this setting is not persistent.
• Use show carpoints to see a lot of car and wheel points. For the car, you can see the nullpoint (in white), the CG (center of gravity, in cyan), the roll center plane. For the wheels, you can see suspension points such as spring start, bumpstops/reboundstops and the current length.
  It also paints the car light frustum (in wireframe). Note that you must turn the lights on (normally key L) for the frustum to move with the car.

Axis systems

Racer uses the OpenGL axis system. This means +Z = forward, +Y = up and +X = left. This means a right-handed coordinate system. See also the image below; the Y dot points up through the roof of the car.

Normally, all units in Racer are specified as SI (Systeme Internationale). This means meters, kilograms and such. Angles are an exception; those are normally expressed in degrees (whereas in SI you would use radians).

Quick exits

You can get rid of the fading if things don't go quick enough, although it is possible to stay in Racer for long amounts of time using 'reload track' and 'reload car'. Just set racer.ini's dev.fast_fade to 1 (in v0.8.34+) and the fading will be lots quicker, making for a faster exit.

File formats

Racer supports a number of file formats. For audio, this are all that FMod supports, but .wav is the most common file format. MP3's are also possible, but you want to cleanest possible sound quality, since you're pitch-bending and mixing anyway.

For graphics, there are a number of formats possible:

• JPEG - useful for backgrounds, but the format is lossy so I don't recommend it for any car or track work.
• TGA - the format of choice upto v0.8.2. 24 or 32 bits (32 bits is with alpha channel), possibly compressed.
• DDS - available since v0.8.2, this supports uncompressed, DXT1, DXT3 and DXT5 compression. This will probably the format of choice from now on, since it incorporates mipmaps. When generated offline (in Adobe Photoshop for example), the filtered maps can be of higher quality compared to generating them on the CPU/GPU. Also note that they probably load faster.

(last updated February 15, 2013 )