racer home

Programming Active Differentials


Home Go for the GT5 look using vertex and fragment shaders!

Dolphinity Organiser - free planning, project management and organizing software for all your action lists



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:

The workflow for testing then becomes:

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)

  // Push towards equal velocities
  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.


Dolphinity Organiser - free planning, project management and organizing software for all your action lists

(last updated November 13, 2012 )