Home

Go for the GT5 look using vertex and fragment shaders!

Introduction

THIS TEXT IS THERE FOR AN EXPERIMENTAL FEATURE IN RACER 0.9.0RC5+

Active differentials can be created that behave in a more custom way than the standard differentials allowed (LSD/Salisbury/Viscous/Locked/Open). More information on differentials and their function can be found in this article.

In Racer, an active differential requires a script (written in Onyx) that defines the behavior. More concretely, based on any number of inputs, the script will determine the output locking torque of the diff. This then gets passed on as the output of the diff.

How to setup an active differential

To add an active differential to a car, perform these steps:

• In the car's car.ini file, set differentials.diff<n>.type to 5 (for active).
• Set differentials.diff<n>.script to the filename of the diff's code, for example 'mydifferential.oxs'. This is an Onyx script.
• Code the behavior of the diff.

The workflow for testing then becomes:

• Run a race with the car.
• Enter the console command 'debug 8' or press Ctrl-8 to see differential debug output.
• Modify the diff code according to your findings.
• Reload the diff code using the console command 'reload car'. This will reload the differential code. Test and go back to the previous step for any changes.

If the debug readout shows 'no script loaded', then check QLOG to make sure the code compiled ok.

Coding an active differential in Onyx

This part assumes you have some experience in programming. Onyx looks a lot like C++ so for those who already know the language, this section will not be too hard to follow.

At every physics step (so normally at 1000Hz, or 1kHz), the function OnDifferential is called within the script. The full prototype of the function is float OnDifferential(int diffIndex). Here, the diffIndex ranges from 0 to NUMBER_OF_DIFFERENTIALS-1 (so the number of differentials in your car minus one). This allows your code to differentiate between the different differentials, if applicable. The function returns a floating point number, which is the locking torque in Nm.

So how could the code look?

My First Active Differential

The smallest possible active differential script could look like this the code below. Note that it doesn't function as an active differential should; it just puts out a constant locking torque, so the car will just pull to one side. A real active differential can only transfer torque from one side to the other, so this script really generates energy (which is not realistic).

The code of the framework (i.e. data/cars/<mycar>/differentials.oxs):

/*
 * Active Differential
 */

#include "racer.oxs"

float OnDifferential(int diffIndex)
{
  return 2000.0;
}

This has the effect of pulling the car to one side. Try running the car like this to grasp what it is doing.

A viscous differential

One of the easiest types of differentials is the viscous diff. This acts on the difference of the wheel (differential output) velocities, and tries to get them to rotate at the same speed. One parameter is required, which indicates how 'stiff' the diff is. In Onyx it could go like this:

[CAVEAT: the example below uses "car0" to directly choose the first car; this needs to improve to work with any car. Other than that, probing the system tree using strings like this is relatively slow]

/*
 * Viscous Differential
 */

#include "racer.oxs"

float OnDifferential(int diffIndex)
{
  const float coeff=2000.0;
  float v1,v2;
  float torque;

  // Velocities of the wheels (rad/s)
  v1=GetSystemFloat("car0.wheel2.rotvel");
  v2=GetSystemFloat("car0.wheel3.rotvel");

  // Push towards equal velocities
  torque=-coeff*(v2-v1);
  return torque;
}

Note that this really is exactly the same as using a standard viscous diff directly, but this time, the logic is in your hands!

With the above script, you should experience a much more understeering car than with an open diff.

(last updated November 13, 2012 )