Rubescript - intro



Rubescript refers to the collection of functions and classes used to interact with a scene in R.U.B.E. By using these functions and classes you can write scripts to accomplish anything that can be done via the GUI but with more precision, flexibility and repeatability.

Rubescript is built on Angelscript which is a strongly typed language. The following native Angelscript types are commonly used in rubescript:
Both R.U.B.E and Angelscript use UTF8 strings so you can give items in your scene non-latin character names.
More about Angelscript data types (opens default browser).

Additionally, rubescript defines the following item classes specific to R.U.B.E scenes:
Instances of these classes are typically obtained either by using a global function to get them, or by creating them anew. Here is an example of using a global function to get a reference to an existing body named 'enemy' in the scene: 
    body enemy = getBody('enemy');
    if ( enemy.valid )
        //... do something with the body
Note that it is good practice to make sure the item you expected to find was actually found, by checking the 'valid' member. All item classes apart from vec2 have this 'valid' member.

If there is more than one item in the scene with the same name, you can get all of them in an array by using the plural form of the 'get' global function: 
    body[] enemies = getBodies('enemy');
    for (uint i = 0; i < enemies.length; i++) {
        body b = enemies[i];
        //... do something with the body
    }
This time we don't need to check validity of each item in the array.

Here is an example of creating a new body in the scene: 
    body b = addBody(-1, '{"name":"friendly","type":"dynamic"}');
Most creation functions take a JSON string like this as a parameter to define various characteristics, and these quickly become cumbersome and error-prone to write by hand. For this reason, creation of items in script is not intended to be a common practice - it is best done via the GUI.

Sometimes item instances can be obtained from other item instances: 
    joint neckJoint = getJoint('neck');
    body headBody = neckJoint.getBodyB();

The possibilities for scripting are endless. Here is a simple example which swaps the position of two bodies. 
    body b1 = getBody('tom');
    body b2 = getBody('jerry');
    vec2 tmp = b1.pos;
    b1.setPos( b2.pos );
    b2.setPos( tmp );
As well as functions to interact with items in the scene, there are some special functions which allow scripts to query the user for input:
These allow you to write a script in which some of the values used can be decided by the user when the script is run.

For further details on using rubescript please see the script reference pages:
Rubescript reference