Roomle Script Language Reference

This document provides a reference for the RoomleScript language, which is contained in the values of the Roomle Component Definition JSON objects and is a proprietary language for scripts interpreted by the Rubens Configurator core.

RoomleScript's syntax is loosely based on the JavaScript language and provides extensive possibilities to use in the component definitions.

Variables

Variables are declared automatically without any keywords. Type is also assigned automatically and there is no type declaration. To undeclare/delete a variable, which is not a parameter, you can use the setnull function. Functions ifnull and isnull can be checked if a variable is declared.

WARNING If a variable is accessed before the declaration, it will be interpreted as a String.

Variables can also be declared in the connection, other and other_connection contexts.

Parameters and superseded parameters are accessible by their key attribute in the same way as a variable.

The scope of variables is different for different scripts. See Scopes for details.

Example:

  • Declare a variable:

width = 500; /* width is declared and initialized to value  500 */

  • Undeclare a variable:

setnull(width); /* width is deleted */
if (isnull(width)) {
  /* isnull is true after width has been set to null */
  /* do something */
}

  • Check if components on both sides of the connection have a width declared and store information about it in this component:

self.widthDeclaredOnBothSides = !isnull(self.width) && !isnull(other.width);

  • Store indices i and j in the current connection (i.e. in a docking point of a docking range):

connection.i = xFromVector(connection.position) / 200;
connection.j = zFromVector(connection.position) / 200;

  • Work with the index from the other side of the connection:

if (!isnull(other_connection.i)) {
  /* do something */
}

Data Types

Data types are assigned automatically. All types are value types, there are no reference types in RoomleScript, which is in conformity with the basic concept of the component update process.

Example:

arr1 = [10, 20];
arr2 = arr1; /* no reference types => makes copy or arr1 */
pushBack(arr1, 30); /* arr1 is [10, 20, 30] */
pushBack(arr2, 40); /* arr2 is [10, 20, 40] */

Boolean

Values are true and false. These are internally handled as integers with values 1 and 0.

Example:

  • Boolean variables

isRoot = true;
if (isRoot) {
  /* ... */
}
hasRightArmrest = in(elementType, 'sofa', 'armchair', 'inlinearmrest_right', 'longchair_right');

  • using advantage of internal data type

totalWidth =
  hasLeftArmrest * armrestWidth + width + hasRightArmrest * armrestWidth;
/* which is the same as */
totalWidth =
  (hasLeftArmrest ? armrestWidth : 0) +
  width +
  (hasRightArmrest ? armrestWidth : 0);

Integer

Integers are internally handled as the long data type. Integers stay integers as long as there is no need to convert them to float, for example with floating point functions, like fabs. This is important to realize when working with large numbers.

New in 2023: In order to keep values stored in Integer type parameters as integers or for defining an integer as an internal value, you can use i suffix for numeric literals to force them as integers. Example:

{
    "id": "minexamples:integers",
    "label": "
        label = 'Float literal: ' | 100 | ' Integer literal: ' | 100i;
        // prints: Float literal: 100.00 Integer literal: 100
    ",
    "parameters": [
        {
            "key": "intConst",
            "type": "Integer",
            "defaultValue": 10,
            "label": "
                'intConst: ' | intConst
                // prints: intConst: 10
            ",
            "visible": true
        },
        {
            "key": "fltConst",
            "type": "Decimal",
            "defaultValue": 10,
            "label": "
                'fltConst: ' | fltConst
                // prints: fltConst: 10.00
            ",
            "visible": true
        }
    ]
}

float (data type)

Floats are internally handled as single precision floating point numbers (32 bits) and are precise up to about 7 digits.

Any number is considered to be a float by default, unless it has an i suffix (i.e. 100i) or comes from a parameter, which type is Integer.

You can use equality operation on floats safely up to three decimal spaces.

Example:

1.122 * 2 == 2.244; /* evaluates as true */
1.122 * 2 == 2.245; /* evaluates as false */
/* warning: following are not guaranteed to be precise */
1.12233 * 2 == 2.24466; /* evaluates as true */
1.1224 * 2 == 2.2447; /* evaluates as true (!) */
1.1223 * 2 == 2.2447; /* evaluates as false (!) */

String

Strings can be delimited by single ' or double " quotes. However, as the scripts in the JSON files are also delimited with double quotes, those must be escaped \".

It is highly recommended to use single quote delimited strings as the primary choice for obvious reasons.

Arrays

RoomleScript currently newly supports array of all data types. The type of array is determined by the strongest datatype stored inside at the time of initialization. Strength of data types is ascending as follows: boolean, integer, float, string.

You can insert a weaker datatype to an array, but you can not insert a value that has a stronger datatype than the array.

Array initialization:

arr1 = []; /* empty array */
arr2 = [10, 20]; /* array of consts */
offset1 = 100;
<