Roomle Script Language Reference

This document provides a reference for the RoomleScript language, which is used in the values of Roomle Component Definition JSON objects. RoomleScript is a proprietary scripting language interpreted by the Rubens Configurator core. The scripts themselves are stored as string values at various places in the component definition JSON structure. RoomleScript is therefore not the whole component definition, but only the script inside it.

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

RoomleScript is a dynamically typed language; there are no explicit type definitions. Types are inferred from the context and values. All value assignments are by-value, even for arrays and objects, with some exceptions where values are passed by reference.

Parameters, Internal Variables and Context

Within a component, every script has access to a list of variables that are internal to the component. We refer to these internal variables simply as "variables." All scripts can read these values, but only onUpdate, onValueChange, and assignment scripts are allowed to modify them. The list of variables includes all parameters, with the parameter key as the variable name. New variables are created upon first use (i.e., when a value is assigned to them). In scripts with write access to internal variables, those variables are also stored and accessible from all other scripts once they have been declared.

⚠️ Warning: If a variable is accessed before it is declared, its identifier will be interpreted as a string literal.

RoomleScript has no explicit type definitions, except for parameters, which have a type attribute. The type of a variable is inferred from the context and the assigned value.

Examples:

• Declare a variable:

width = 500; // width is declared in the self context and initialized to value 500

• Initialize a component variable on startup:

if (isnull(width)) {
  width = 500; // width is declared in the self context and initialized to value 500
}

if (isnull(inited)) {
  inited = true;
  // all other variables initialization
}

• Undeclare a variable:

setnull(width); // width is deleted

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

connection.i = xFromVector(connection.position) / self.dockStepX;
connection.j = zFromVector(connection.position) / self.dockStepZ;

Variable Context

Variables in RoomleScript can (and should) always be used with a specific context that defines their scope. Variables that are used temporarily only inside one script should always be defined with the local _.* prefix; this provides a significant performance benefit compared to variables in the component scope (self). The following is a list of all available context prefixes. Further information can be found under Connections, and a detailed list of all script access rights regarding the context prefix can be found under List of script access rights.

Prefix	Purpose and Availability
self.	read: all scripts, write: certain scripts. Read/Write value from the whole component context.
_.	Local context: Available only inside the scope of the current script. Variable is cleared after current script's execution finishes.
nothing	read: like self, write: like self in scripts with write access, like _ in other scripts + warning. Automatic evaluation of the context.
parameter.	In the onValueChange and onUpdate script of the parameter, provides the userTriggeredChange : boolean getter.
other.	Available in all scripts in connections (onUpdate, condition, assignmentScripts), useful for accessing values from the other component taking part in the connection. Read and write availability is the same as the self.
connection., other_connection.	Available in all scripts in connections (onUpdate, condition, assignmentScripts), provides index, position, isPreview. Provides persistent storage for values that are relevant in the connections. other_connection is the connection context from the other component's connection.
object.	read: all scripts, write: same scripts as self. This is the whole configuration ("global") context, and these variables are available in all scripts of all connected components and their subComponents.

⚠️ Warning: Assigning to a value in scripts without write access (e.g., geometry scripts) will either declare a new local variable or create a local copy of the variable. The core will throw a warning in such a case, but script execution is not interrupted. This is a backwards compatibility feature, but also a common source of performance loss. You should always use the _.* prefix for local variables to avoid such situations. Assigning temporary values (like a for loop counter) to a variable in the self or object context is a common mistake that can lead to performance issues, where the whole component might be marked as dirty and unnecessarily re-evaluated multiple times.

Connection, other and other_connection context

In some scripts you have access to more than one list of variables at once (for example in assignmentScripts). For that you can access variables via context.<variableName>. In any connection element (dockpoint, dockline, sibling) you can access the position of the current dockPoint via connection.position and the index within the dockRange via connection.index. Also, the context of the other side of the connection (if one is connected) is available in other_connection.*. In connection scripts with write access, you can persistently store values in the connection and other_connection contexts. These values are then available in the next call of the same script.

Global variable context (object scope)

It is possible to define globally available variables via the object keyword: object.<variableName>. These variables are available in all scripts of all connected components and subComponents/parts in scope of one configuration in the runtime of the configurator. These variables follow the same access rules as for self variables and so can be read from inside every script, but only specific scripts have the rights to write, see List of script access rights.

Assigning to the object context will not trigger recalculation of the configuration.

Internal variables

Some scripts have internal variables defined. See the table and their purpose:

Identifier	Availability	Purpose
articleNr	component.articleNr script	Sets the current component's article number
number	component/subComponent.numberInPartList script	Sets the subcomponent's count of entries in the part list
connection.isPreview	All docking types condition	Read-only, returns true if in docking preview state
connection.index	All scripts of docking range connection	Returns the index of the docking point in the range array
connection.position	All scripts of docking range and line connections	Returns Vector3f position of the child relative to the parent's coordinate system
condition	All conditions	Sets the result of the condition
label	All label scripts	Has value from the labels map in the current language. Overwrite with value based on the script
language	All label scripts	Getter for the language ISO code of the current locale the configurator runs with.
parameter.userTriggeredChange	parameter.onValueChange script	Getter to determine if the user has just interacted with this parameter. True if the user selected a value from this parameter in the last update call. False if the parameter's value has been changed after an assignment.

Data Types

Data types are assigned automatically. All types, including objects and arrays, are value types; there are no reference types in RoomleScript, which is in line with the basic concept of the component update process. However, you can declare component functions with a direction: inout parameter, which is a by-reference function parameter.

Basic Data Types

RoomleScript supports all basic data types (baseType) and follows the usual order of "powerfulness":

• Boolean

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

• Integer

Support for the integer data type in RoomleScript was introduced later in its lifetime and so requires a special suffix i to explicitly define an integer value to not break existing content, e.g. 500i. If only 500 is written, this value gets interpreted as a float value. However, RoomleScript was designed without integers in the first place and therefore, using explicit integer declarations is only necessary in specific cases. Indices of arrays and such are integers, but accept both i and non-i (float) suffix values. Some functions might promote integers to floats, for example when using floating point functions like fabs. This is important to realize when working with large numbers.

• Float

ℹ️ Float parameters are defined with the Decimal type attribute.

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 whose type is Integer.

You can use equality operations on floats safely up to three decimal places. Docking points coordinates are stored with two decimal places precision. To-string operations also convert floats with two decimal places.

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. Because RoomleScripts are stored as values inside a JSON structure, double quotes must be escaped with a backslash (\") when using double quotes as string delimiters. It is highly recommended to use single quote delimited strings as the primary choice for obvious reasons.

For legacy and backward compatibility reasons, strings can also be defined without quotes, but this is deprecated and should be avoided. Using an undeclared variable is interpreted as a string literal until it is declared.

Strings can contain new line characters. Multi-line strings are possible, but the indentation spaces are part of the string, breaking the formatting.

Example:

    "onUpdate": "
        _.myString1 = 'This is a string with \'single\' quotes';
        _.myString2 = \"This is a string with double quotes\";
        _.myString3 = \"You can have unescpaded 'single' quotes if this string is delimited with backslash double quote.\";

        // Multi-line strings. Notice how the indentation works, because indentation spaces would be part of the string:
        _.myString4 = 'Multi
line
string literals
are possible.
';

        // NOT RECOMMENDED, but possible due to backward compatibility:
        _.PossibleButAvoid = aLiteralThatIsNotDeclaredYet; // interpreted as string until declared
    "

Vector2f and Vector3f

RoomleScript supports two built-in object types: Vector2f and Vector3f, which are used to represent 2D and 3D vectors. Their components are accessible via the xFromVector(v), yFromVector(v), and zFromVector(v) functions.

You have two ways to declare vectors:

v2a = {100, 200};
v3a = {100, 200, 300};

v2b = Vector2f{100, 200};
v3b = Vector3f{100, 200, 300};

Objects

In internal computations and for assignments, the object type can be used. There is no native way to create or instantiate an object, but objects can be a result of some functions. Objects can be assigned in the same way as variables. There is a parameter Object type, but such a parameter must be set invisible in the user interface (otherwise, a warning is shown).

Custom objects can be created with the utilization of the getData function family, where you can create an interface within the component.data:

{
    "id": "example:object",
    "onUpdate": "
        function newObject() {
            obj = getData('interfaces', 'MyObject');
            // perform further cleanup or data init
            return obj;
        }

        obj = newObject();

        obj.someInt = 42;
        obj.someString = 'Hello World';
        obj.someObject.key1 = 'X';
    ",
    "data": {
        "interfaces": {
            "MyObject": {
                "someInt": 0,
                "someString": "a",
                "someBoolean": false,
                "someObject": {
                    "key1": "a",
                    "key2": "a"
                }
            }
        }
    }
}

The obj is then:

{"someBoolean":0,"someInt":42.00,"someObject":{"key1":"X","key2":"a"},"someString":"Hello World"}

⚠️ Important warning: Although they are objects, they are not reference types. If you assign them to another variable, you get a deep copy of the object.

Arrays

RoomleScript supports array of all data types and vectors. The type of array is determined by the most "powerful" data type stored inside at the time of initialization. "Power" of data types is ascending as follows: boolean, integer, float, string.

ℹ️ Info: Before 2023, RoomleScript only supported arrays of floats.

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

RoomleScript does not support the array access operator [] as in many other programming languages and doesn't support object member functions. To access or modify arrays, you must use the built-in array functions:

• get, set, length

• pushBack, popBack

• see further functions Built-in Functions Reference

Empty array is initialized as an array of floats. To create an empty array of a specific type, you can declare it with one value of the desired type and pop it:

stringArr = [''];
popBack(stringArr); /* stringArr is [] as empty string array */

Array initialization:

arr1 = []; /* empty array of floats */
arr2 = [10, 20]; /* array of floats */
num1 = 100;
num2 = 150;
num3 = 200;
arr3 = [
  num1,
  num2,
  num3,
]; /* arrays initialized by variables by values (not by reference) */
num1 = 200; /* arr3 stays [100, 150, 200] */

You can declare and use arrays of vectors:

arrV2 = [
    {10, 20}, 
    {30, 40}
];
// ----------
if (isnull(arrV2)) {
    arrV2 = [{0,0}];
    popBack(arrV2); /* arrV2 is now [] as empty Vector2f array */
}
pushBack(arrV2, {50, 60});
vertex = get(arrV2, 0); /* get the first vector from the array */

Constants

There are various constants available in roomle script, accessible via a specific keyword.

Name	Key	Value
Math Constants
e	M_E	2.71828182845904523536028747135266250
log2(e)	M_LOG2E	1.44269504088896340735992468100189214
log10(e)	M_LOG10E	0.434294481903251827651128918916605082
loge(2)	M_LN2	0.693147180559945309417232121458176568
loge(10)	M_LN10	2.30258509299404568401799145468436421
pi	M_PI	3.14159265358979323846264338327950288
pi/2	M_PI_2	1.57079632679489661923132169163975144
pi/4	M_PI_4	0.785398163397448309615660845819875721
1/pi	M_1_PI	0.318309886183790671537767526745028724
2/pi	M_2_PI	0.636619772367581343075535053490057448
2/sqrt(pi)	M_2_SQRTPI	1.12837916709551257389615890312154517
sqrt(2)	M_SQRT2	1.41421356237309504880168872420969808
1/sqrt(2)	M_SQRT1_2	0.707106781186547524400844362104849039
Other Constants
null	NULL_VALUE	null

Convert degrees to radians: a * M_PI / 180

Convert radians to degrees: a * 180 / M_PI

Keywords

The following keywords are reserved in RoomleScript and cannot be used as variable names:

if - else if - else

Usage:

if (condition1) {
  /* ... */
}
else if (condition2) {
  /* ... */
}
else {
  /* ... */
}

for

Standard for loop. If script in which the loop is used has a write access, it is recommended to use the local _ scope prefix.

Usage:

for (_.i = 0; _.i < iterations; _.i++) {
  /* ... */
}

break

Useful in the for loop to immediately exit the current loop.

Usage:

for (_.i = 0; _.i < 100; _.i = _.i + 1) {
  if (_.i == 20) {
    break;
  }
}

continue

⚠️ Warning: As of 2025, the continue keyword is not supported in RoomleScript, but it is reserved for future use and should not be used as a variable name. It will be used as the for-loop continue statement in the future.

return

Immediately terminates execution of the current script. If script has an internal value to store the result, you can use return to set the result and exit the script. Such scripts are:

• condtition

• articleNr

• numberInPartList, sortInPartList

• visible, enabled, visibleAsGlobal, visibleInPartList

• valid

• price, retailPrice

Operators

Precedence	Operator	Description
1	- a, + a	Unary plus and minus
2	!a	Logical NOT
3	a++	Suffix/postfix increment
4	a * b, a / b, a % b	Multiplication, division and modulo
5	a + b, a - b, a | b	Addition, subtraction and concatenation
6	a >= b, a <= b, a > b, a < b	Relational operators < and ≤ and > and ≥ respectively
7	a == b, a != b	Equality operators = and ≠ respectively
8	a && b	Logical AND
9	a || b	Logical OR
10	a ? b : c	Ternary conditional

The Roomle script supports the % (modulo) operator and also has the fmod(float):float function.

Comments

Commented code is ignored. Meta directives and commands exist. To learn more, refer to Tools and Importer Meta Keywords

Single line comments

Single line comments can start with // or #.

// this is a single line comment
# this is a single line comment as well

Single line comments were unrecommended because they lead to problems when testing content on local machines. This is not the case anymore and can be safely used.

Multi-line comments

/* 
this is a 
multiline comment 
*/

Functions

RoomleScript provides a variety of built-in functions for operations, geometry instantiation etc. As of 2024, custom functions can be defined in RoomleScript. There are script functions that can be defined with the function keyword and are available within the same script. Component definition can define fucntions in the component.functions array, which are available within the scope of the current component and they can also be called from main components.

Functions can be overridden (a warning is thrown in such a case). Function priority: last custom script function, then component function, then built-in function.

ℹ️ Info: Calling an unknown function logs an error in the Script Analyzer but if you call a function from another component it is not possible to determine availability of this function during compile time, so the Script Analyzer will not log an error, but you get an error during runtime (Browser console log). The only exception for this is the self.context-prefix, because this can be checked in its own scope.

Built-in Functions

To get a reference of the built-in functions, please refer to RoomleScript Built-In Functions Reference article.

Custom Script Functions

In the scope of a single script, you can define custom functions with the function keyword. These functions are only available within the same script. Local variables (e.g.: _.a) are only available inside the function and get deleted when out of scope (not being available in the parent script). The function is avaialable anywhere in the same script after its declaration. If a parameter shadows an existing variable by using the same name, the parameters value gets used inside the function and a warning message gets raised. If a function shadows an existing, internal function by using the same name, the custom defined function overrules the existing, internal one and a warning message gets raised.

function add(a, b) {
    return a + b;
}
// ...
c = add(10, 20); /* c is 30 */

function DrawHexNut() {
    AddCylinder(6.5, 6.5, 5, 6, bevelWidth = 0.5);
    AddCylinder(2.75, 2.75, 20, 16);
    MoveMatrixBy({ 0 , 0 , -5 });
    MinusOperator();
}
DrawHexNut();

Custom Component Functions

Functions can be defined in the component.functions array. These functions are available in all scripts of the current component.

{
    "id": "example:functions",
    "functions": [
        {
            "key": "addOrIncrementByOne",
            "arguments": [
                { 
                    "key": "a",
                },
                { 
                    "key": "b",
                    "defaultValue": 1
                }
            ],
            "script": "
                return a + b;
            "
        }
    ],
    "onUpdate": "
        c = addOrIncrementByOne(10, 20); /* c is 30 */
        d = addOrIncrementByOne(c); /* d is 31 */
    "
}

Functions can be accessed in any script inside the component using its key attribute as the function name. Function's arguments are defined in the arguments array and are available in the body of the function (script attribute) as variables with the same name as the key attribute of the argument.

Custom component functions are evaluated in the context of the script from which the function has been called. Therefore, functions can get or set values with the same access rights as the script from which the function has been called. If a variable or a parameter exists and gets assigned in the scope of the function, its value is overwritten. Based on the access rights of the script, the variable is either changed for the current script only or for the whole component (the self context). If the script doesn't have write access rights, the parameter or variable get shadowed with a local variable. If no parameter or no variable in the scope of the function exists and there is an assignment to a new variable, it will be declared as an internal varaible of the function.

Be aware of the script access rights where the function is used, so if you create a component function that writes to a parameter or accesses members from other or connection or something, it is not possible to call this component function inside a script that does not have the corresponding access rights. So for example if your component function writes to a parameter it is not possible to call this functions inside of a geometry script. The highest access of a component function gets determined during compile time and throws an error if access rights got violated.

Function's parameters are always declared for the function and should not shadow variables or parameters in the scope where the function resides (be it a component.function or local function). A warning will be thrown if this is the case.

Functions can be nested (functions called within other functions).

Functions can not be recursive. This is evaluated at runtime and if recursion is detected, a warning is thrown and 0 is returned instead the recursive call of the function.

Component functions can have default values for parameters. If a parameter is not passed when calling the function, the default value is used. Default values can be any valid RoomleScript expression, including function calls.

Recommendation: Always use the context when working with function. Always use _. or self. prefixes inside the functions. This will avoid errors caused by suddenly adding a conflicting variable in the future.

Component function parameter direction

It is possible to also define the direction of a parameter. This means if it is only an input parameter (default) or an input/output parameter that can also be written to. For this simply add the direction property "direction": "inout" to a parameter and you can write to it inside the function. Keep in mind that only variables can be passed as function argument for such parameters, it is not possible to pass values or expressions (e.g: func(5) or func(var + 1).

Available values for direction are:

• in (default) - Parameter is read-only, can not be changed

• inout - Parameter is assigned by reference and any assignment to the parameter will change the value outside the function.

So a complete component definition could look like this example:

{
    "id": "catalog_id:component",
    "parameters": [
        {
            "key": "result",
            "type": "String"
        }
    ],
    "functions": [
        {
            "key": "foo",
            "arguments": [
                {
                    "key": "a",
                    "direction": "inout"
                },
                {
                    "key": "b",
                    "direction": "inout"
                },
                {
                    "key": "c",
                    "direction": "inout"
                }
            ],
            "script": "
                a = 'this';
                b = 'is a';
                c = 'test';
            "
        }
    ],
    "onUpdate": "
        x = 0;
        y = 0;
        z = 0;
        foo(x, y, z);
        result = x | ' ' | y | ' ' | z;
    "
}

This would result in the parameter called result having the value this is a test.

Component Function Scope

The function call is always in the scope of its caller. So if, for example, there is a variable x in the script and afterwards a component function gets called it has access to x. However, the function has only access to functions defined in the same component! So if you have a function A() in ComponentA and a function B() in ComponentB, this function B() can not access function A() because it is defined in a different component that is not included as a sub component. But it is possible to pass function A() as a parameter to function B() of the sub component.

Component Function Types and Availability

Some scripts in roomle script have special functions available, like AddCube in geometry. These special functions are not available in default component functions, but it is possible to define the type of a component function to make these functions available. The available function types are:

• default

• onUpdate

• changeable

• collisionCondition

• geometry

• export

A function without a specified type is considered as default. These types can be defined by setting it via the key type inside the function definition:

"functions": [
    {
        "key": "foo",
        "type": "default",
        "arguments": [
            {
                "key": "myArg",
                "defaultValue": 0
            }
        ],
        "script": "
            return myArg * 2;
        "
    }    
],
...

Functions of the type default can be called from everywhere, all others can only be called inside the corresponding scripts. It is also possible to call functions inside functions of a different type, but validity is depended of the context of the calling script. So for example it is possible to call a default function that calls a geometry function (and vice versa) inside a geometry script, but not inside an onUpdate script. The special functions inside the scripts and corresponding typed functions are:

• collisionCondition

  • getBoxOrigin

  • getBoxSize

  • getBoxForMeasurementOrigin

  • getBoxForMeasurementSize

• changeable

  • setBoxForMeasurement

  • setEnabled

  • setVisible

• onUpdate

  • AddAbsoluteDimensioning

  • AddAbsoluteDimensioningAxis

  • requestDockItem

  • setBoxForMeasurement

  • setEnabled

  • setOrigin

  • setVisible

• geometry

  • BeginObjGroup

  • Cube

  • Cylinder

  • Sphere

  • Prism

  • Mesh

  • Rectangle

  • MoveMatrixBy

  • RotateMatrixBy

  • ScaleMatrixBy

  • SetObjDimensionPoint

  • Copy

  • EndObjGroup

  • SetObjSurface

  • SetObjSurfaceAttribute

  • SetUvTransform

  • ScaleUvMatrixBy

  • RotateUvMatrixBy

  • MoveUvMatrixBy

  • SubComponent

  • AddCube

  • AddPlainCube

  • AddCylinder

  • AddSphere

  • AddPrism

  • AddMesh

  • AddExternalMesh

  • AddRectangle

  • AndOperator

  • OrOperator

  • MinusOperator

  • IntersectWithWalls

  • ReverseFaces

  • AddDimensioning

  • AddDimensioningAxis

• export

  • getBoxOrigin

  • getBoxSize

  • getBoxForMeasurementOrigin

  • getBoxForMeasurementSize

  • getPosition

  • getAbsolutePosition

So a complete component definition could look something like this:

{
    "id": "catalog_id:subComponent",
    "functions": [
        {
            "key": "doubleValue",
            "type": "default",
            "arguments": [
                {
                    "key": "value"
                }
            ],
            "script": "return value * 2;"
        },
        {
            "key": "createCube",
            "type": "geometry",
            "arguments": [
                {
                    "key": "size"
                }
            ],
            "script": "
                AddCube(Vector3f{doubleValue(size), doubleValue(size), doubleValue(size)});
                SetObjSurface('isdt:black');
            "
        },
        {
            "key": "evaluate",
            "type": "collisionCondition",
            "script": "return false;"
        }
    ]
}

{
    "id": "catalog_id:component",
    "subComponents": [
        {
            "internalId": "library",
            "componentId": "catalog_id:subComponent"
        }
    ],
    "geometry": "
        library.createCube(600);
    ",
    "parentDockings": {
        "points": [
            {
                "mask": "mask1",
                "position": "{1000, 500, 500}",
                "collisionCondition": "library.evaluate();"
            }
        ]
    }
}

SubComponent Functions

If component.functions are defined, they can be accessible in the subComponent. Keep in mind, that the functions are evaluated not in the subComponent, but in the current component, as if they were just copied to the current component's functions array. To access a subComponent function, use the internalId of the subComponent as the context prefix. See following example where the functions are referred and used by another component.

{
    "id": "tests:subcomponentfunctions",
    "subComponents": [
        {
            "internalId": "Functions",
            "componentId": "tests:subcomponentfunctions",
            "active": false
        }
    ],
    "onUpdate": "
        self.sum = Functions.Array_Sum([100, 400, 500]);
    ",
    "geometry": "
        Functions.AddBoardWithHole(self.sum, 'isdt:black', 400, 'isdt:white');

        Functions.AddBoardWithHole(self.sum);
         MoveMatrixBy(Vector3f{self.sum, 0, 0});

        Functions.AddBoardWithHole(self.sum, holeColor = 'isdt:yellow');
         MoveMatrixBy(Vector3f{2 * self.sum, 0, 0});
    "
}

Notice, that the subComponent is not active. If a subComponent only carries functions or data and is not expected to be a part list entry or a geometry subComponent, there is no point for it to remain active.

Such feature allows you to create a component with a library of functions that can be linked to other components.

However, if the functions in the subComponent are nested, they need to be called in the correct context, which is a complication and will be solved with a feature in the future.

Keyword Arguments

RoomleScript has support for the keyword arguments feature. Keyword arguments are widely used and inspired by the Python language and are very useful for functions that have many parameters, where only some of them are used in a specific call. Keyword arguments are available in built-in functions and can be also defined in Component functions. For built-in function, see which parameters are marked with the asterisk * in the documentation. For component functions, all parameters (except the first one) that are marked with defaultValue are available as keyword arguments.

Example:

AddCube(
    // the size parameter is mandatort, can not use a keyword argument
    {100, 200, 300},
    // other parameters are optional and can be used as keyword arguments
    material = 'isdt:wood_oak',
    uvRotation = 90,
    bevelWidth = 10
);

For technical reasons, the first function parameter cannot be used as a keyword argument. If you want to use the keyword arguments, you must use the first function argument, which is not a keyword argument.

{
    "functions": [
        {
            "key": "keywordArgsFunction",
            "type": "default",
            "arguments": [
                {
                    "key": "noKeywordArg",
                    "defaultValue": 1
                },
                {
                    "key": "keywordArg1",
                    "defaultValue": 10
                },
                {
                    "key": "keywordArg2",
                    "defaultValue": 100
                }
            ],
            "script": "
                return noKeywordArg + keywordArg1 + keywordArg2;
            "
        }
    ],
    "onUpdate": "
        keywordArgsFunction(5); // OK, returns 115
        // keywordArgsFunction(keywordArg1 = 20); // NOT POSSIBLE, the first argument cannot be a keyword argument and keyword argument can't be used as the first argument
        keywordArgsFunction(2, 20, 200); // OK, returns 222
        keywordArgsFunction(7, keywordArg2 = 700); // OK, returns 717
    "
}

Tools and Importer Meta Keywords

The following features are ignored by the Roomle Rubens Configurator core, but provide different functionalities in development tools and importers.

TODO

A comment starting with TODO will appear in the VS Code Outline and Problems Panel as an Info entry. This is a function provided by the VS Code extension and roomle-content-tool-api.

Usage:

    // TODO this needs some code

FIXME

A comment starting with FIXME will appear in the VS Code Outline and Problems Panel as a Warning entry. This is a function provided by the VS Code extension and roomle-content-tool-api

Usage:

    /* FIXME gap if size > 200 */

#tag

This is used by the Roomle Component Tool extension for Visual Studio Code. This must be commented out, because it is unknown to the Roomle Core.

Defines a tag that will show in the Outline pane.

Usage:

"onUpdate": "
    ...
    #tag THIS WILL APPEAR IN THE CODE OUTLINE
    ...
"

"parentDockings": {
    "points": [
        {
            "mask": "
                #tag Top Left Connector
                'connector'
            ",
            "position": "{-width / 2, 0, height}"
        }
    ]
}

#region and #endregion

This is used by the Roomle Component Tool extension for Visual Studio Code. This must be commented out, because it is unknown to the Roomle Core.

Defines a tag that will show in the Outline pane. Defines a code folding region for organizing code and displays the #region in the Outline pane in the same way as a tag

Usage:

#region Docking variables
if (elementType == 'straight_left_armrest') {
    leftDock_allowed = false;
    rightDock_allowed = true;
    rightDock_position = Vector3f{520, 0, 0};
    ...
}
...
#endregion

BEGIN CUSTOM CODE and END CUSTOM CODE

This is used by the IDM importer.

Commented out in the onUpdate script, provides an importer directive to keep the code in between those markers.

Usage:

/* BEGIN CUSTOM CODE */
/* This code will remain after a reimport into this catalog. */
if (isnull(inited)) {
  inited = true;
  myCustomVariable = 'some value';
}
myCustomVar_isLeather = idmFeature2 == 'LE';
/* END CUSTOM CODE */

RSDocs

Inspired by JSDocs, RSDocs are comments that start with /** and end with */. They can be used to document functions, parameters, variables, etc. RSDocs are supported by the Roomle Component Tool extension for Visual Studio Code and are ignored by the Roomle Core.

The RSDocs are visible in the autocomplete suggestions and in the hover tooltip.

Usage example:

/** 
 * With no other keywords, this fills the documentation of the 'var' variable
 */
var = 10;

/**
 * This very line will not appear anywhere, but you can add single-line documentation like follows:
 * @doc var This will appear in the documentation of the 'var' variable
 * @doc parameterKey will document a parameter key
 * @doc functionKey will document a function key
 */

/**
 * RSDocs will project to the following variable, which is also a parameter key.
 */
parameterKey = 'abcd';