Home

The sky not really a limitation.

Introduction

This article explains how to create a controller, using an Onyx script that 'simulates' a controller. Really it does not simulate a controller, but it IS a controller.

Updated 14-3-2014.

Controller structure

Racer contains a controller engine, with 2 layers: the base layer is a controller that delivers analog and digital signals, much like a joystick. The 2nd (higher) layer is the attachment of context to the base layer. I.e. the 'x' analog signal can be the throttle signal for a car.

An Onyx script controller is a base layer controller, so it only supplies analog & digital values. Assigning meaning/context to that is done through a controller file. The files live in data/controls.

Data structure

The definitions required to create your own controller are in data/scripts/onyx/include/controls.oxh. The relevant part is shown below:

const int MAX_CONTROLLER_BUTTON=50;

class ControllerInput
{
  float x,y,z;              // Positional
  float rx,ry,rz;           // Rotational axes
  float slider0,slider1;  // More analog signals
  int button[50];        // Room for digital buttons
};

The controller inputs are 8 analog signals (x/y/z/rx/ry/rz/slider0/slider1), which ultimately derived from joystick definitions. There is room for 50 digital buttons.

Defining an Onyx controller

Normally, controllers are set up and defined through the menu system. To use an Onyx controller however, you'll need to manually create a controller .ini file, put it in data/controls, and select it in racer.ini.

The field to change is ini.controls. For example, if your controller definition is in data/scripts/test_onyx.ini, you'd use this in racer.ini:

ini
{
  ; Controls file
  controls=test_onyx.ini
...

The file data/controls/test_onyx.ini then for example contains this:

; Onyx scripted controller
controllers
{
  onyx_test
  {
    enable=1
    ; Time per update (ms)
    time_per_update_in=10
    time_per_update_out=1000
    ; What to run? (data/controls/mycontroller.oxs in this example)
    script=mycontroller.oxs
    ; From analog/digital to race controls
    throttle
    {
      axis=x
      min=0
      max=1000
    }
    brakes
    {
      axis=y
      min=0
      max=1000
    }
    steerleft
    {
      axis=rx
      min=-1000
      max=0
    }
    steerright
    {
      axis=rx
      min=0
      max=1000
    }
    change_camera
    {
      button=0
    }
  }
}

Note that this reference an Onyx script file named mycontroller.oxs.

Example script

Below is an example controller script in Onyx (save this in data/controls/mycontroller.oxs for example):

// Example Onyx-scripted controller
#include "racer.oxh"
#include "controls.oxh"

void OnOutput()
// Called to send any relevant information to the controller
{
   // Collect any output needed for the controller
   //...
}

void OnInput(ControllerInput input)
// Called to poll the controller state.
// Leave the controller state in 'input'.
{
   float t;
   input.y=0;

   // Create some analog signals
   t=GetSimTime()*0.001;
   input.x=0.3+sin(t*1.7)*0.5;
   input.rx=sin(t*1.0)*1.0;

   // Toggle digital control on and off
   float f=fmod(t,1.0);
   if(f>0.5)
     input.button[0]=0;
   else
     input.button[0]=1;
}

This script creates a few signals, based on the simulation time. A digital control just toggles on and off every second.

(last updated March 14, 2014 )