Home

Extend beyond the boundaries.

Introduction

Racer v0.8.39 started having the first incantation of Onyx. Onyx is a highly structured scripting language which will be used to glue the C++ world and scripting together. Since the scripts can be compiled during execution of Racer, the engine can be enhanced with user-defined logic without needing extra coding support inside the Racer engine itself (which is written in C++). This allows people to add logic to parts of the engine, where supported.

Why logic? Because data (parameters) can only go so far; being able to add logic (or code) will increase flexibility in ways that are as yet unforeseeable.

Onyx itself is merely a part of a bigger architectural feature; a game engine where you can define logic & data to create new entities, that behave in a certain way. The architecture for this is a Component-Entity system, and may represent a bit of a learning curve, but it is efficient in rapid prototyping and re-use of code. More information on the (higher level) component entity system can be found here. The Racer you know, with cars participating in a race, can be extended or even replaced entirely with another type of game.

There are 3 different types of textual interfaces/languages present in Racer; console commands (simple stuff like 'volume 15'), car/track scripting (named QScript; more friendly syntax with support for variables and a few types like cars and textures) and Onyx. Onyx is the most complex language of the 3, but also the most flexible. Features of this language are/will be:

• Support for variables, structures and interfacing to the C++ code and DLL's.
• Compiled to a stack-machine language, much like Java and other script languages.
• Virtual machine capable of running multiple scripts simultaneously (simulating multi-tasking).
• Highly structured type-safe code that resembles C++ a lot.
• Coroutine support will probably be added in the future; these are functions that can run for a long time, as if multi-threaded.

An example piece of code to illustrate the looks

#include "racer.oxh"   // Racer engine integration (loaded from data/scripts/onyx/include/racer.oxh)

int t;

void main()
{
  while(1)
  {
    t=t+1;
    echo(t);
    yield;
    if(t>=10)
     break;
  }
  echo(123);
}

Tutorials

You can read on below this list of tutorials, but you may want to jump in immediately and see some code.

If you're coming from the C++ world, the Onyx vs C++ article will be interesting.

Files involved

Onyx scripts have the extension .oxs (ox=Onyx, s=script). A compiled (thus 'executable') Onyx script has the extension .oxx. Compilation can be done implicitly; the engine will accept either .oxs or .oxx files and compile on the fly to .oxx for simplicity. Include files normally use the extension .oxh instead. They are parsed the same as the .oxs files, but the extension makes it clear the code may be shared amongst other scripts. Normally these .oxh files only contain interface definitions; constants, engine functions and so forth.

The default path where Onyx scripts are stored is data/scripts/onyx (relative to the Racer directory). Entering the console command 'run test.oxs' for example will try and find (and run) data/scripts/onyx/test.oxs.

Background information

You can skip this part if you want.

The name 'Onyx' is derived from the SGI Onyx machines from back in the day. These machines did a lot of things we've only now just seeing happening in regular PC's. Also, Onyx just sounds cool.

The language looks like C++; this may be considered a negative point, but the goal of this language is to be able to handle medium-difficult tasks. For such things, having a highly structured language helps in the end. Whereas console commands are lowest and easiest form of scripting in Racer, it is also the least flexible when you want to add custom behavior.

Goals of the language

Onyx has been setup with these goals in mind:

• Having a language that is suitable to realize quite complex tasks.
• Make the language look familiar to those who have programmed before. Likeliness to C++ was chosen for 2 reasons; Racer is built in C++, and it is a well-known language (and also looks a lot like Java).
• Being able to communicate with both the outside world and the Racer engine internals, to provide logic building blocks instead of relying on fixed built-in content features from the Racer engine.
• Provide multiple ways in to the engine to overrule fixed behavior.
• No pointers; in Onyx, everything is at most a reference. Pointers are THE reason for potential bugs in software, and although they certainly have their use, it goes too far to add them this scripting language.

That said, Onyx is a bit like Unreal's scripting functionality, or vertex/fragment shaders that sit at specific points in a graphics card's pipeline.

Keywords

Here is a list of reserved keywords. You should avoid any keywords that are familiar from other languages, mostly C++.

Events - OBSOLETE since 14-8-2012

Events are obsolete now; Onyx functions are called by the C++ engine instead. Coroutines may be created to allow for long-during scripts.

Events occur through the engine, and scripts can (and should!) wait for those. This makes efficient scripting possible without lots of busy polling of states. The wait command will wait for an event before the script continues.

Waiting for specific events can allow you to override some behavior. Currently defined waiting points are:

Callbacks

The Panthera game engine can call functions inside Onyx scripts, called 'callbacks'. For example, each frame, the function 'void OnFrame()' is called (if present) in each script. This makes it easy to add functionality that must be performed at specific points in the engine. More detailed information on these callbacks can be found on this page.

Currently defined callbacks are:

Types

The Onyx language looks a lot like C++, and also behaves similarly. The base expression types defined are:

• float - like 5.3
• int - like 123
• string - like "hello, onyx"
• const - a type modifier, meaning the symbol is a constant and cannot be modified.
• arrays - for example: int x[10];
• classes - for example: class A { int x; void f(){ x=5; } };
• handle - a 'magic value' that holds pointers to structures that are known to the C++ engine only.
• pointer - a generic pointer, which points to something. May disappear in the future, as explicit type-casting is possible.

Implicit type conversions are used in assignments and function calls, such as:

float f;
int n;
const int MY_CONST=456;
int a[10];

t=123;
n=5.3;
n=sin(4);  // 2 type conversions: '4' from int to float for sin(), and 'n=' from float back to int.
n=MY_CONST;   // 'n' becomes 456
a[5]=124;

Compared to C++, these notable differences exist in expressions:

• No support for ++ and -- (x++, --n etc)
• <<, >>, &, &&, ||, ^ not supported (yet)

The $ keyword

The keyword '$' can be used to end compilation explicitly. This can be useful when testing a few things; instead of commenting out all the ending lines, you can just place a '$' where compilation should stop. An example:

Implicit type conversions are used in assignments and function calls, such as:

float f;
f=123;
echo(f);  // Prints '123'

$ // end compilation

f=f+1;
echo(f);   // We'll never get here

The script above will compile upto the line with the dollar sign, but will not see 'f=f+1'. It will stop compiling, so syntax errors and such in the rest of the code will not be found.

Built-in variables

Here are the predefined variables that are available in Onyx:

Built-in macros

Here are the predefined macros that are available in Onyx (actually, macros don't currently exist in Onyx, so these can also be thought of as predefined variables). v0.9.0RC9+.

Built-in functions

Some functions come with the base compiler. The Racer engine adds Racer-specific functions on top of the base compiler. Here is a list of base Onyx internal functions that are always present (whether running inside Racer or just in onyx_run.exe).

For a complete list, see this page.

Engine functions

These functions call into the C++ engine to perform more complex operations mostly, or to extract information from the game engine.

For a complete list of the Onyx engine functions, see this page.

Arguments and local variables

It is possible to define (local) variables when you want to use them; they don't need to be defined at the top of the function. For example:

int f(int n)
{
  int a=2,b=4;
  int c;

  c=a+b;

  int d;
  d=c+3;
  return n+d;
}

int x=f(5);
echo(x);

The script above will output '14'.

Pass by Reference

Unlike C++, where values are always passed by value unless you explicitly use pointers, Onyx implicitly passes class instances by reference. For example, the following example will print 100 and 123. In C++, it would print 100 and 100, as 'vt' is copied onto the stack. Onyx will only pass the pointer (address) to 'vt' when it calls function 'f'.

class Vector3
{
  float x,y,z;
};

void func(Vector3 v)
{
  v.x=123;
}

Vector3 vt;
vt.x=100;
echo(vt.x);
func(vt);
echo(vt.x);

Classes

Classes are used for an object-oriented approach to solving problems. An object exhibits functionality, which is normally abstracted a bit away from the actual implementation. Also, all member functions in the class are 'public' by default; any function can be called directly. In the future you may see private functions (functions that can only be called from within other member functions of that class).

Classes in Onyx differ from Onyx in the way that variables need all to be declared before they are used. An example:

// BAD - 'x' referenced before being defined (will generate a compiler error)
class Vector3
{
  void f()
  {
     x=5;
  }
  float x,y,z;
};

// GOOD
class Vector3
{
  float x,y,z;
  void f()
  {
     x=5;
  }
};

Preprocessor (Racer v0.9.0RC8+)

A bit like C++, there is a small preprocessor in the lexical analyzer of Onyx. This allows you to conditionally compile code or leave it out (which is faster than using runtime if/then/else).

• #define <symbol> - defines a symbol, i.e. '#define OPT_ABC'
• #undef <symbol> - undefines a symbol. This can be useful sometimes (although using it too often probably needs you need to rethink the code).
• #ifdef <symbol> - will compile the following section if <symbol> is defined.
• #ifndef <symbol> - will compile the following section if <symbol> is NOT defined. As with all programming, try to avoid negative programming to make things clearer (i.e. don't code '#ifndef DONT_WARP').
• #else - the 'else' part of an ifdef.
• #endif - closing an #ifdef command
• #error <string> - outputs an error and stops compilation.

An example use of conditional compilation in Onyx:

#define USE_ABC

void main()
{
#ifdef USE_ABC
  echo("USE_ABC is defined");
#else
  echo("USE_ABC is not defined");
#endif
}

Note that #ifdef can be nested.

Caveats

The following quirks exist in Onyx. Their behavior or existence may change in the future.

• A special 'stringdata' keyword and type is defined. Strings actually come in 2 kinds; as a string and as a stringdata. The latter can be compared to a 'char*' in C++, the 'string' type is really more of a C++ string type object ('qstring*'). The have a few special cases to allow strings and stringdata to be mixed more or less freely.
• handles and pointers; both currently exist as a type, as a means to talk to the C++ world. For example: handle h=UDPOpen("127.0.0.1",7000); and pointer p=&info. Handles and pointers are not mixable, so h=p won't work.
• Local variable scope; if you define this in Racer v0.8.41:
  void f()
  {
  int n;
  if(1)
  {
  int x;
  }
  }
  The 'x' will be defined in the scope of 'f', rather than in the scope of the 'if'. This can be a problem if you define duplicate symbol names (int n and int n), which is not a problem in C++. This is still an unresolved problem, although defining variables with the same name like this is considered poor programming style.
• 
  

Advanced

Mostly for people familiar with C or C++, the advanced article describes some more complex features of Onyx.

(last updated March 17, 2014 )