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:
Undeclare a variable:
Check if components on both sides of the connection have a width declared and store information about it in this component:
Store indices
i
andj
in the current connection (i.e. in a docking point of a docking range):
Work with the index from the other side of the connection:
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:
Boolean
Values are true
and false
. These are internally handled as integers with values 1
and 0
.
Example:
Boolean variables
using advantage of internal data type
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:
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:
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:
Use get
and set
functions for accessing array elements. Use stringToArray
to parse a string containing an array (as of 2023, only array of floats is supported in the stringToArray
function).
Vector2f
A struct for holding a 2D float value. Components of the vectors are accessible via the xFromVector
and yFromVector
. String containing a Vector2f can be parsed via the stringToVector2f
.
Usage:
Vector3f
Usage is the same as Vector2f, just with an extra component accessible via the zFromVector
function. A String containing a Vector3f can be parsed via the stringToVector3f
.
Keywords
if - else if - else
Usage:
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:
break
Useful in the for
loop to immediately exit the current loop.
Usage:
continue
Useful in the for
loop to immediately skip to the next iteration.
Usage:
return
Immediately terminates execution of the current script. If script has an internal value to store the result (like label
or condition
), you can use return to assign to it.
Usage:
In a
condition
script
In the
numberInPartList
script
In any script
Operators
Precedence | Operator | Description |
---|---|---|
1 |
| Unary plus and minus |
2 |
| Logical NOT |
3 |
| Suffix/postfix increment |
4 |
| Multiplication, division and modulo |
5 |
| Addition, subtraction and concatenation |
6 |
| Relational operators < and ≤ and > and ≥ respectively |
7 |
| Equality operators = and ≠ respectively |
8 |
| Logical AND |
9 |
| Logical OR |
10 |
| Ternary conditional |
Refer to the fmod for the floating point modulo 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 #
.
WARNING Using single line comments tends to break components while side loading from local drive for testing. For this reason, //
style comments are converted to /* */
style comments by the Roomle Component Tool / roomle-content-tool-api
format function.
Multi-line comments
Scope and Context of Variables
The default scope of any internal variable or parameter is the whole current component. Some scripts have read/write access to the component data, some scripts only have read access. To find out which scripts can access which context, you can refer to the [Script Access Rights] chapter.
RoomleScript also provides contexts on several occasions. This is an overview of them:
prefix | availability | purpose |
---|---|---|
nothing | current component if script has WRITE access, otherwise current script | |
| local - current script | Use this for local helper variables. Variable will be set to null after current script finishes. |
|
| provides |
| all scripts in connections ( | access to all parameters and internal vars of the component on the other side of the connection |
| all scripts in connections ( | actually is redundant, but helps to understand the code unambigously and should be used whenever |
| all scripts in connections ( | provides |
| all scripts in connections ( | Same as before, but targets the other side of the connection. |
Internal values
Some scripts have internal values defined. See the table and their purpose:
identifier | context | purpose |
---|---|---|
articleNr | articleNr script | sets the current component's article number |
| subComponent.numberInPartList | sets the subcomponent's count of entries in the part list |
| docking condition | read-only, returns true if in docking preview state |
| docking range | returns the index of the docking point in the range array |
| docking range, line | returns Vector3f position of the child relative to the parent's coordinate system |
| all conditions | sets the result of the condition |
| all label scripts | Has value from the |
| all label scripts | Getter for the language ISO code of the current locale the configurator runs with. |
|
| getter to determine if the user has just interacted with this parameter |
Functions
As of beginning of 2024, RoomleScript has a possibility to declare custom functions. As of Q2 2024, component scoped functions are provided.
Every function in RoomleScript is executed in the context of the script from which the function has been called. Therefore, functions can get or set values with the same 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.
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), but can not be recursive (function calls the itself directly or indirectly).
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. Let only the function's parameters stay without the context.
Component Functions
Functions can be declared in the component.functions
array. Such functions are then declared for the whole component and accessible based on their type
attribute. Based on core-provided functions or contexts in the function, either of the four types have to be specified. Complex functionality can be defined for the component, which can save a lot of repeating code and related coding problems and also enables an API-like design approach to component creation.
The attributes of a function
object are:
key
The identifier of the function that will be used for calling it.type
default
if not set, this is the default value. Useful for functions that do general computations.geometry
Required for functions containing geometry objects calls, like AddCube functionchangeable
SupportssetBoxForMeasurement
,setVisible
,setEnabled
onUpdate
Supports requestDockItem andchangeable
functionscollisionCondition
For accessing the collisionCondition functions are getters that are available in theconnection.collisionCondition
script:getBoxOrigin
,getBoxSize
,getBoxForMeasurementOrigin
,getBoxForMeasurementSize
arguments
Array of function parameters:key
The key to access the argument inside the functiondefaultValue
If set, the argument is non-mandatory in the function call (the defaultValue is used instead) and also allows using a keyword argument.
script
The body of the function. The keywordreturn
terminates the function and if a value follows, it is returned.
Following function Sum
can be called with any amount of arguments up until 5, i.e. Sum(1, 2)
or Sum(1, 2, 3, 4, 5)
.
Following function call uses the keyword arguments:
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. In this case, the functions should be prefixed with the subComponent's internalId
. See following example where the functions are referred and used by another component.
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.
Custom Local Functions
Local functions can be defined using the function
keyword, very similarly as it is done in JavaScript. Local functions are valid only in the script where they are declared and all calls of it must be done behind its declaration.
Examples:
Constants
Constant | Value | Meaning |
---|---|---|
|
| Euler constant |
|
| base 2 logarithm of |
|
|
|
|
|
|
|
|
|
|
| π |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Convert degrees to radians: a * M_PI / 180
Convert radians to degrees: a * 180 / M_PI
Available Functions
List of available functions in all RoomleScripts of the component definition.
acos
(a: float) : float
Arcus cosine (arccosine)
Parameters:
a
: float value between -1 and 1
Returns: arccosine of a
in radians.
Usage:
activeGroupInView
() : String
Queries the configurator UI to get the currently selected parameter group. This is useful for manipulating geometry based on what the user is configuring.
Returns: key
property of the current parameter group
Usage:
onUpdate:
geometry:
asin
(a: float) : float
Arcus sine (arcsine)
Parameters:
a
: value between -1 and 1
Returns: arcsine of a
in radians.
Usage:
atan
(a: float) : float
Arcus tangent.
Parameters:
a
: value between -1 and 1
Returns: arctangent of a
in radians.
atan2
(y: float, x: float) : float
Arcus tangent defined by ratio of opposite and adjacent side of the triangle.
Parameters:
y
: length of opposite sidex
: length of adjacent side
Returns: arctangent of the angle in radians.
ceil
(number: float, digits: float) : float
Nearest higher value
Parameters:
number
: the number to be ceileddigits
: count of decimal digits
Returns: Nearest higher value rounded to given amount of decimal spaces.
Usage:
cos
(valueRad: float) : float
Cosine
Parameters:
valueRad
: value in radians
Returns: cosine value of a
.
cosh
(valueRad: float) : float
Hyperbolic cosine
Parameters:
valueRad
: value in radians
Returns: hyperbolic cosine value of a
.
exp
(x: float) : float
Exponential function
Parameters:
x
: the exponent
Returns: Value of e powered to x
fabs
(x: float) : float
Absolute value
Parameters:
x
: value
Returns: x
if x
is positive or -x
if x is negative.
Usage:
float
(value: any) : float
Convert to float
Parameters:
value
the value to try to convert to float
Returns: If value
starts with number, returns the first parsed number, otherwise 0.
Usage:
floor
(number: float, digits: float) : float
Nearest lower value
Parameters:
number
: the number to be flooreddigits
: count of decimal digits
Returns: Nearest lower value rounded to given amount of decimal spaces.
Usage:
fmod
(dividend: float, divisor: float) : float
Floating point modulo
Parameters:
dividend
: floatdivisor
: float
Returns: Modulo as float.
Warning Works well only with integers that can be represented by single precision floating point numbers (32 bits, up to around 7 digits).
Usage:
get
(array: [float], index: Integer) : float
Reads an array element at a given index.
To write an array element, refer to set.
Parameters:
array
: the array you want to accessindex
: index of the element in the array, index of the first element is zero0
⚠️ float indices will floor to the next lower integer
Returns: The number from the array at the given index or 0 if fails.
Throws:
[1404]
Index out of bounds. Returns 0 in this case, execution continues
Usage:
getComponentProperty
(propertyKey: 'runtimeId' | 'externalId' | 'catalogId', runtimeId*: integer) : integer | string
Returns the unique runtime id, or component Id of the current component. If this function is used in a collisionCondition
script, such a property of another colliding component can be retrieved.
Note: parts of an ID are catalogId:externalId
Parameters:
propertyKey
eitherruntimeId
,externalId
orcatalogId
string valuesruntimeId
a runtime ID of a different component, only availabe in thecollisionCondition
Returns:
unique runtime ID as an integer
external or catalog ID as a string
Usage:
getDockPosition
() : Vector3f
Get position of child docking point in the coordinate system of the parent.
Returns: Vector from parent origin to child docking point or zero Vector3f if component is the root component.
See getPosition for more details.
getDockPositionRelativeToParentDock
() : Vector3f
Get position of the child docking point in the coordinate system of the parent relative to the parent docking point.
Returns:
point - point: ideally zero Vector3f or the offset if configuration doesn't reload properly
range - point: ideally zero Vector3f or the offset if configuration doesn't reload properly
line - point: Vector from the beginning of the dockLine to the child docking point
root: zero Vector3f
getMaterialProperty
(materialId: String, propertyName: String, fallback: String) : String
Retrieves additional material data defined in material properties. See Using GetMaterialPropery Function for detailed description.
Parameters:
materialId
: Id of the target materialpropertyName
: name of the property on the given materialfallback
: Value to return if material or property are missing
Returns: the value stored in the material property or fallback if no material is found or if the material doesn't have the property.
Usage:
exmaple material entry:
getPosition
() : Vector3f
Get position of the child component in the coordinate system of the parent.
Returns: Vector3f leading from parent component origin to child component origin or zero Vector if component is the root component.
Usage:
getUniqueRuntimeId
() : Integer
Returns unique runtime ID that has been assigned to this component instance in the configurator. Every root component, child component and subComponent will have an unique number. This number is not reused after for example deleting components. It is not persistent between configuration instances. Can be used to determine the timing order in which the components have been added to the configuration.
It is useful as a decision factor between two components connected via sibling points in cases that no other way to choose one component from more.
This number is not persistent between configurator instances (i.e. after configuration reload or between undo/redo actions) and in most cases, storing it as a parameter makes no sense and can lead to errors.
Example: See the Quadpost Shelf System template
Returns: Integer representing the unique runtime ID of the component in the configuration.
Usage:
ifnull
(variable: any, fallback: any) : any
Checks if a variable is undefined or null and returns the variable or fallback. Useful for making sure a variable is defined.
Parameters:
variable
: the variable to check for nullfallback
: a value to return if varialbe is null or undefined
Returns:
either the
variable
or thefallback
ifvariable
is null
Usage:
in
(valueToCheck: any, value1: any, value2: any, ...) : boolean
Useful for checking if a list of values containes a specific value.
Parameters:
valueToCheck
: the value that is being searched for in the listvalueN
: any number of arguments that will form the list
Returns
true
if valueToCheck is equal to at least one of the other values, otherwisefalse
Usage:
Most used to compare a variable to a list of constants, however you can also check a constant to a list of variables.
inArray
(searchedValue: float, array: [float]) : Boolean
Checks if array contains a value.
Arguments
searchedValue
: the value that is being looked forarray
: the array to check
Returns: True if array contains the value.
Usage:
indexOf
(searchedValue: float, array: [float]) : Integer
Find index of a value in an array.
Parameters:
searchedValue
: the value that is being looked forarray
: the array to search
Returns: Index of the first occurence of the value in the array or -1 if no occurence.
Usage:
insert
(array: [float], index: Integer, value: float | [float]) : void
Insert into array in front of the element at given index
Parameters:
array
: array into which the values are insertedindex
: index of the element before which the values will insertvalue
: value to be inserted, can be a number or an array of numbers
Throws:
[1404]
index out of bounds
Usage:
intersection
(a: [float], b: [float]) : [float]
Intersection of arrays
Parameters:
a
,b
: two arrays of numbers
Returns: Array with elements that are present in both arrays.
Usage:
isEnabled
(parameterKey: String) : Boolean
Returns if a parameter is enabled.
Parameters:
parameterKey
: key of the parameter
Returns: True if the parameter exists and its enabled
flag is true, false otherwise.
Usage:
isnull
(value: any) : Boolean
Checks for null values.
Parameters:
value
: identifier to be checked
Returns: True if identifier is undeclared, null or after setnull call.
Usage:
initialize on component load, at the beginning of onUpdate
in a connection script of a docking range:
isVisible
(parameterKey: String) : Boolean
Returns if a parameter is visible.
Parameters:
parameterKey
: the parameter key to get the visible flag value from
Returns: True if the parameter exists and its enabled
flag is true, false otherwise.
Usage:
length
(array: [float])
Length of array (for the length of a String, refer to size).
Parameters: * array
: array of floats
Returns: count of the array elements.
Usage:
like
(input: String, pattern: String) : Boolean
Returns true if input matches the pattern. The pattern is a String with placeholders for one any single character or any subString. This is the OPTION_LIKE
operator from the IDM 3.1 standard, which itself is based to be similar on the SQL's LIKE
operator.
Parameters:
input
: the String to check against the patternpattern
: a case sensitive String pattern, where_
is a wildcard for any single character and%
is a wildcard representing any subString at least 1 character longa_
- length 2, starts witha
a%
- any String starting witha
_a
- length 2, ends witha
%a
- any String that ends with a%a%
- any String that containsa
Returns: true
if String matches to the pattern, otherwise false
Usage:
log
(value: float) : float
Natural logarithm
Parameters:
value
Returns: Logarithm of the value with base of e
(~2.718)
Usage:
log10
(value: float) : float
Common logarithm
Parameters:
value
Returns: Logarithm of the value with base of 10
Usage:
popBack
(array: [float]) : float
Returns and removes last number from array.
Parameters:
array
Returns: Last number of array, original array has this value removed or 0 if [1405]
is thrown.
Throws:
[1405]
: popBack empty array
Usage:
pow
(value: float, exponent: float) : float
Power function
Parameters:
value
: the value to compute powerexponent
Returns: value powered to exponent.
pushBack
(array: [float], value: float) : void
Pushes a value at the end of an array.
Parameters:
array
: the array to which to pushvalue
: the value to push
Usage:
removeAt
(array: [float], index: Integer) : float
Remove element at index from an array and return the next.
Parameters:
array
: the array from which the element should be removedindex
: index at which to remove the element, first index is 0
Returns: Next element after the one that has been removed or 0 if the element is the last one or if [1404]
has been thrown.
Throws:
[1404]
: Index out of bounds
Usage:
requestDockItem
(configuration: string, parentDockPointPosition: Vector3f, childDockPointPosition: Vector3f)
Sends a docking request to the configurator. After the current update call will have been finished, a docking of the defined configuration will happen. Connection and child component will be available in the next update call. Because the docking does not happen in the configurator kernel, compatible version of the SDK has to be used in custom integration for this function to be available. You need to define which docking points to use on both side by their positions.
This function is only valid in the main onUpdate
script and must be inside an if-block.
Parameters:
configuration
Either an itemId or a stringified configuration JSON that should dock.parentDockPointPosition
Vector3f containing coordinates of a valid docking point on the parent side.childDockPointPosition
Vector3f containing coordinates of the child docking point.
Hint: To find out the correct arguments, you can do the docking manually and then check the configuration (which can be achieved by calling RoomleConfigurator.getCurrentConfiguration()
or by using the interface buttons of the Rubens CLI). The parent docking point argument is the dockPosition
of the child component, the child docking point is the dockChild
value of the child component.
Usage:
round
(number: float, digits: float) : float
Nearest rounded value
Parameters:
number
: the number to be roundeddigits
: count of decimal digits
Returns: Nearest value rounded to given amount of decimal spaces.
Usage:
set
(array: [float], index: Integer, value: float) : void
Sets value of an array element at a given index.
Parameters:
array
: the array you want to setindex
: index of the element in the array, index of the first element is zero0
⚠️ float indices will floor to the next lower integer
value
: the new value that will replace the old value
Throws:
[1404]
Index out of bounds.
Usage:
setBoxForMeasurement
(size: Vector3f, position: Vector3f) : void
Overrides the bounding box of the geometry in order to change the measurements.
⚠️ This is only valid if called in onUpdate
Parameters:
size
: defines the size of the bounding boxposition
: position of the left rear bottom corner of the box
Hint: This behaves like a combination of AddPlainCube and MoveMatrixBy. Refer to the Dimensioning chapter for more information and examples.
Usage:
setEnabled
(parameterKey: String, enable: Boolean) : void
Sets and overrides the enabled
flag of the parameter with the given key. This applies for the update loop in which this call is done.
Parameters:
parameterKey
: key of the parametervalue
: final status of theenabled
flag
Usage:
setnull
(variable: any) : void
Undeclares a variable of given name.
Usage:
setVisible
(parameterKey: String, enable: Boolean) : void
Sets and overrides the visible
flag of the parameter with the given key. This applies for the update loop in which this call is done.
Parameters:
parameterKey
: key of the parametervalue
: final status of thevisible
flag
Usage:
sin
(valueRad: float) : float
Sine
Parameters:
valueRad
: value in radians
Returns: sie value of a
.
sinh
(valueRad: float) : float
Hyperbolic sine
Parameters:
valueRad
: value in radians
Returns: hyperbolic sine value of a
.
size
(input: String)
Length of String.
Parameters: * input
: String
Returns: count of the String's characters.
Usage:
sqrt
(number: float) : float
Square root
Parameters: number
: zero or positive number
Returns: Square root of the number or nan
Usage:
string
(input: any, [decimalSpaces: Integer = 2]) : String
toString function - converts value to string.
Parameters:
input
value to stringifydecimalSpaces
if input is an Integer or float, defines the amount of decimal spaces of the number to show; default is 2note: not appliable to array, Vector2f, Vector3f, String
Returns: Value converted to string.
Usage:
stringPart
(input: String, delimiter: String, index: Integer, *fallback: String)
Splits a string with a delimiter and returns the part under the given index.
Parameters:
input
: the string intended to be parseddelimiter
: a string that will be used to separate the input stringindex
: index of the part that willfallback
: optional value to return if fails, empty string''
by default
Returns: part of the string or a fallback value (defined or ''
) if fails.
Usage:
stringToArray
(stringifiedArray: string) : [float]
Parses a string to array.
Parameters:
stringifiedArray
: stirng in a[number, number, ...]
pattern
Returns: The parsed array or null if failed.
Usage:
stringToVector2f
(stringifiedVector: string) : Vector2f
Parses a string as Vector2f.
Parameters:
stringifiedVector
: String in aVector2f{number, number}
or{number, number}
pattern
Throws:
[1301]
Error getting value
Returns: The parsed vector or null if failed.
Usage:
Vector parameter
stringToVector3f
(stringifiedVector: string) : Vector3f
Parses a string as Vector3f.
Parameters:
stringifiedVector
: String in aVector3f{number, number, number}
or{number, number, number}
pattern
Throws:
[1301]
Error getting value
Returns: The parsed vector or null if failed.
Usage:
Vector parameter
substring
(input: String, startIndex: Integer, length: Integer) : String
Returns part of string based on position and length.
Parameters:
input
: the string from which the substring is to be extracedstartIndex
: index where the substring starts, first index is 0length
: length of the substring
Returns: Part of string starting at the given index of the given length. Empty string is returned for every character that is outside of the string, rather than throwing an exception.
Usage:
tan
(valueRad: float) : float
Tangent
Parameters:
valueRad
: value in radians
Returns: tangent value of a
.
tanh
(valueRad: float) : float
Hyperbolic tangent
Parameters:
valueRad
: value in radians
Returns: hyperbolic tangent value of a
.
xFromVector
(v : Vector2f | Vector3f) : float
Get X component of a Vector
Parameters:
v
the vector
Returns: x component of the Vector or 0 if fails
Usage:
yFromVector
(v : Vector2f | Vector3f) : float
Get Y component of a Vector
Parameters:
v
the vector
Returns: X component of the Vector or 0 if fails
Usage:
zFromVector
(v : Vector3f) : float
Get Z component of a Vector
Parameters:
v
the vector
Returns: Z component of the Vector or 0 if fails
Usage:
getData functions
There are several functions that can retrieve data from a JSON contained in the component definition. This JSON is stored in the component.data
field.
You can read the data and use them as a value using get*
functions, or you can have the value of the JSON evaluated and treated as an expression using data context of your current script using the evaluate*
functions. See evaluateData functions
getSubComponentData*
and evaluateSubComponentData*
do the same, but in context of a subComponent defined with an internal ID.
Non-existent data values are handled with the triplet of functions: plain *Data
(like getData
) only throw an error, *DataOrNull
returns an actual null
when data is not found and *WithDefault
will return a fallback value, which is the last argument of the function.
See following with examples.
getData
(arg1 : String | Integer, ... argN: String | Integer) : String | float | null
Retrieves data from the data storage JSON object in the component.data
.
⚠️ This does not handle non-existing path and scripter needs to ensure that the requested path exists.
Attributes:
argN
: key name as String or array index as Integer
Returns: The retrieved data or null.
Throws:
[1308]
Data not found
Usage:
define the
data
in the component definition
retrieve them using the
getData
function
getDataOrNull
(arg1 : String | Integer, ... argN: String | Integer) : String | float | null
Retrieves data from the data storage JSON object in the component.data
or null
if data wasn't found.
Attributes:
argN
: key name as String or array index as Integer
Returns: The retrieved data or null.
Usage:
define the
data
in the component definition
retrieve them using the
getDataOrNull
function in thecondition
script of aparentDocking
getDataWithDefault
(arg1 : String | Integer, ... argN: String | Integer, fallback : any) : String | float | null
Retrieves data from the data storage JSON object in the component.data
and returns a fallback value if entry hasn't been found.
Attributes:
argN
: key name as String or array index as Integerfallback
: value to return if target path doesn't exist
Returns: The retrieved data or fallback.
Usage:
define the
data
in the component definition
retrieve them using the
getDataWithDefault
function in alabel
script:
Note: language
hold the ISO code of the current language. It can be es
for example, in which case the translation entry doesn't exist. Because elementType
has a list of validValues, the developer can make sure that the getData
will always return a value.
getSubComponentData
(subComponentInternalId : String, arg1 : String | Integer, ... argN: String | Integer) : String | float | null
Retrieves a component.data
from another component, that is being linked as a subComponent of this component. Works exactly same as the getData
counterpart, just in a different component.
Attributes:
subComponentInternalId
: internalId of a subComponent definitionargN
: key name as String or array index as Integer
Returns: The retrieved data or null.
Throws:
[1308]
Data not found
Usage:
getSubComponentDataOrNull
(subComponentInternalId : String, arg1 : String | Integer, ... argN: String | Integer) : String | float | null
OrNull counterpart of getSubComponentData
. See getDataOrNull
and getSubComponentData
.
getSubComponentDataWithDefault
(subComponentInternalId : String, arg1 : String | Integer, ... argN: String | Integer, fallback : any) : String | float | null
WithDefault counterpart of getSubComponentData
. See getDataWithDefault
and getSubComponentData
.
evaluateData functions
The sextet of evaluateData*
functions is the counterpart to the getData
functions. The difference is how the data are treated upon retrieval. While getData
functions just return them as value, evaluateData
will evaluate them as if they were expressions in the context of the current script. This is useful for storing computations that are different based on the configuration. Special care must be used if data values are strings or expressions. Use single quoted values in the JSON string value to force string data type, e.g.:
However, keep in mind, that getData
functions will always include the single quotes.
Function calls are allowed in the evaluated expressions, except any get/evaluateData
call in order to prevent cyclic references.
data entry |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
evaluateData
Same as getData
, but considers the value an expression and attempts to evaluate it. See evaluateData functions and getData.
evaluateDataOrNull
Same as getDataOrNull
, but considers the value an expression and attempts to evaluate it. See evaluateData functions and getDataOrNull.
evaluateDataWithDefault
Same as getDataWithDefault
, but considers the value an expression and attempts to evaluate it. See evaluateData functions and getDataWithDefault.
evaluateSubComponentData
Same as getSubComponentData
, but considers the value an expression and attempts to evaluate it. See evaluateData functions and getSubComponentData.
evaluateSubComponentDataOrNull
Same as getSubComponentDataOrNull
, but considers the value an expression and attempts to evaluate it. See evaluateData functions and getSubComponentDataOrNull.
evaluateSubComponentDataWithDefault
Same as getSubComponentDataWithDefault
, but considers the value an expression and attempts to evaluate it. See evaluateData functions and getSubComponentDataWithDefault.
Available Geometry Functions
The following functions may be only called in geometry
, environmentGeometry
, previewGeometry
and geometryHD
scripts.
You can also refer to the scripting course chapter 3D Models & Meshes.
Instantiation Functions
The following functions instantiate geometry objects.
Note: Some functions have overloads, usually they come either as simple functions or extended functions with UV modifiers and a bevel modifier. You can not use only some modifiers, for example, AddCube(Vector3f{1000, 100, 10}, Vector2f{1, 3});
, but rather you have to write the rest of the UV modifier arguments as well, even if their values do not have effect for being neutral to the computation: AddCube(Vector3f{1000, 100, 10}, Vector2f{1, 3}, 0, Vector2f{0, 0});
AddCube
(size: Vector3f) : void
(size: Vector3f, uvScale: Vector2f, uvRotation: float, uvOffset: Vector2f, [bevelSize : float = 2]) : void
Adds a cube of given size to the scene. Cube's origin is in the bottom rear left corner of the cube
Parameters:
size
size of the cubeuvScale
multiply UV values of the vertices - the higher the value, the smaller the materialuvRotation
rotate UV values of the vertices, in a left-hand directionuvOffset
increase UV values of the vertices -> moves the material in a negative directionbevelSize
default 2, size of the cube's bevel (measured parallel to its walls)
Usage:
AddCylinder
(radiusBottom: float, radiusTop: float, height: float, faces: Integer) : void
AddCylinder
(radiusBottom: float, radiusTop: float, height: float, faces: Integer, uvScale: Vector2f, uvRotation: float, uvOffset: Vector2f, [bevelSize : float = 2]) : void
Adds a cylinder or cone (based on if the two radii are same or different). Its origin is in the center of the bottom base.
Parameters:
radiusBottom
radius of the bottom baseradiusTop
radius of the topheight
height (distance of bottom and top)faces
number of faces that form the prism approximating the cylinder (3 - triangular prism, 6 - hexagonal prism etc.)uvScale
multiply UV values of the vertices - the higher the value, the smaller the materialuvRotation
rotate UV values of the vertices, in a left-hand directionuvOffset
increase UV values of the vertices -> moves the material in a negative directionbevelSize
default 2, size of the cube's bevel (measured parallel to its walls)
Usage:
AddExternalMesh
(meshId: String, boundingBoxSize: Vector3f, boundingBoxOffset: Vector3f) : void
(meshId: String, boundingBoxSize: Vector3f, boundingBoxOffset: Vector3f, uvScale: Vector2f, uvRotation: float, uvOffset: Vector2f) : void
Instantiate a mesh stored in RAPI (the Rubens Admin database). Has an overload for modifying UV settings.
Parameters:
meshId
the ID of the mesh in acatalogueId:meshName
patternboundingBoxSize
size of the bounding box of the mesh useful for measurements, camera position and preview cubeboundingBoxOffset
position of the bounding boxuvScale
multiply UV values of the vertices - the higher the value, the smaller the materialuvRotation
rotate UV values of the vertices, in a left-hand directionuvOffset
increase UV values of the vertices -> moves the material in a negative direction
When performing an export from Blender with the Roomle Blender Addon, you will get a txt
file with AddExternalMesh
functions accompanying the files you will be uploading to Rubens Admin. You can also get the function from the RuAd mesh entry page.
AddMesh
(vertices: [Vector3f], indices: [Integer], uvCoordinates [Vector2f], normals[Vector3f]) : void
Creates a mesh from list of vertices and triangles. Overload for UV modifiers is available.
Parameters:
vertices
list of the verticesindices
list of indices of the vertices forming the triangles, following a left-hand thumb rule⚠️ length of the indices array must be divisible by 3
uvCoordinates
multiply UV values of the vertices - the higher the value, the smaller the material⚠️ length of the array must be the same as the length of the
vertices
array
normals
rotate UV values of the vertices, in a left-hand direction⚠️ length of the array must be the same as the length of the
vertices
array
Usage:
Creates a mesh from list of vertices, triangles, UV and normal coordinates.
AddMesh
(vertices: [Vector3f]) : void
Creates a mesh from a list of vertices, always creating a triangle between triplet or vertices. UV mapping is automatically computed.
Parameters:
vertices
list of the vertices⚠️ length of the vertices array must be divisible by 3
Usage:
(vertices: [Vector3f], indices: [Integer]) : void
(vertices: [Vector3f], indices: [Integer], uvScale: Vector2f, uvRotation: float, uvOffset: Vector2f) : void
Creates a mesh from list of vertices and triangles. Overload for UV modifiers is available.
Parameters:
vertices
list of the verticesindices
list of indices of the vertices forming the triangles, following a left-hand thumb rule⚠️ length of the indices array must be divisible by 3
uvScale
multiply UV values of the vertices - the higher the value, the smaller the materialuvRotation
rotate UV values of the vertices, in a left-hand directionuvOffset
increase UV values of the vertices -> moves the material in a negative direction
Usage:
Creates a mesh from list of vertices, triangles, UV and normal coordinates.
AddPlainCube
(size: Vector3f) : void
A cube with sharp edges. A shortcut for an AddCube
with bevel size of 0. Does not have overloads for UVs.
Usage:
AddPrism
(extrusionLength: float, vertices: [Vector2f]) : void
AddPrism
(extrusionLength: float, vertices: [Vector2f], uvScale: Vector2f, uvRotation: float, uvOffset: Vector2f, [bevelSize : float = 2]) : void
Extrusion of a planar closed sketch in the Z direction. Bevel is not an actual geometric bevel like in cases of other primitive shapes, but is faked by adjustments of normals.
Parameters:
extrusionLength
length of the extrusionvertices
list of vertices forming the sketchuvScale
multiply UV values of the vertices - the higher the value, the smaller the materialuvRotation
rotate UV values of the vertices, in a left-hand directionuvOffset
increase UV values of the vertices -> moves the material in a negative directionbevelSize
default 2, size of the cube's bevel (measured parallel to its walls)
Usage: Example of a 90 degrees slice of a cirle.
AddRectangle
(size: Vector2) : void
AddRectangle
(size: Vector2f, uvScale: Vector2f, uvRotation: float, uvOffset: Vector2f) : void
Adds an up facing flat quad in the ground plane with origin in its center.
Parameters:
size
size of the quaduvScale
multiply UV values of the vertices - the higher the value, the smaller the materialuvRotation
rotate UV values of the vertices, in a left-hand directionuvOffset
increase UV values of the vertices -> moves the material in a negative direction
AddSphere
(size: Vector3f) : void
AddSphere
(size: Vector3f, uvScale: Vector2f, uvRotation: float, uvOffset: Vector2f) : void
Adds an ellipsoid (sphere if all components are equal). Origin is in the center.
Parameters:
size
size of the cubeuvScale
multiply UV values of the vertices - the higher the value, the smaller the materialuvRotation
rotate UV values of the vertices, in a left-hand directionuvOffset
increase UV values of the vertices -> moves the material in a negative direction
Usage:
Copy
() : void
Adds a copy of the last instantiated object and switches the target of all modifiers to this last instantiated object.
Usage:
SubComponent
(subComponentInternalId: String) : void
Instantiates a geometry of the subComponent with its current values. The subComponent must have its active
flag set to true. Any modifiers will apply to the whole subComponent geometry as if it was in a group.
For detailed explanation, refer to the SubComponents chapter.
Usage:
Modifiers
Modifiers are functions called after an object or object group. There are transformations (position, rotation and scale of the object), UV transformations (modify texture mapping) and set material. These functions are indented by an extra space.
Recommended order of transformations (and the most intuitive):
Scale
Rotate
Move
MoveMatrixBy
(move: Vector3f) : void
Applies translation transformation to the last object or group. The position will be added (not overriden) to any previous transformation.
Parameters:
move
: addition to the position vector of the last object or group
Usage:
RotateMatrixBy
(axis: Vector3f, origin: Vector3f, degrees: float) : void
Applies the rotation transformation to the last object or group around a defined axis by an amount of degrees of angle in a clockwise direction. Hint: This is a left hand rule. If you place your left hand thumb in the direction of the axis, fingers will show the positive direction of the rotation.
Parameters:
axis
: a direction vector of the axis around which you rotateorigin
: a point definiing the position of the axis (together withaxis
defines the line)degrees
: amount of rotation in degrees
Usage:
ScaleMatrixBy**()
(scale: Vector3f, [origin: Vector3f = Vectorf3{0, 0, 0}]) : vo
**()
(scale: Vector3f, [origin: Vector3f = Vectorf3{0, 0, 0}]) : voApplies a scale transform to the last object or group. Neutral value is 1.
Parameters: scale
: amount of scale to apply (multiply to previous, not override) origin
: pivot point of the scaling operation
Usage:
SetObjSurface
(materialId: String) : void
Applies a material from RAPI to the last object or group.
Parameters: materialId
: string in format catalogue:externalId
leading to an existing material entry in RAPI
Usage:
SetObjSurfaceAttribute
(attributeName: ['color', 'alpha', 'roughness', 'metallic'], attributeValue) : void
Modifies the last object's material shader values. This is especially useful if you intend to have one normal map material which you can afterwards colourize in multiple possible colours.
Parameters:
attributeName
: either of'color'
,'alpha'
,'roughness'
,'metallic'
string valuesattributeValue
:0.0f
to1.0f
ifattributeName
isalpha
,rougness
ormetallic
if attributeName is color, then a JavaScript compatible color definition, such as:
#ffffff
rgb(255, 0, 128)
rgb(50%, 0%, 100%)
Usage:
UV Modifiers
Modifiers for UV transforms to modify the mapping of the material. These functions are indented by an extra space.
MoveUvMatrixBy
(move: Vector2f) : void
Addition to the mesh's UV coordinates. Positive values bring the texture to the left and to down on a cube.
Parameters:
move
the amount to move
Usage:
RotateUvMatrixBy
(degrees: float) : void
Rotation of the mesh's UV coordinates. Positive values rotatet the texture clockwise.
Parameters:
degrees
the amount to rotate
Usage:
ScaleUvMatrixBy
(scale: Vector2f) : void
Multiplication of mesh's UV coordinates. Higher values make the texture smaller. Neutral value is 1.
Parameters:
scale
the amount to scale
Usage:
SetUvTransform
(uvScale: Vector2f, uvRotation: float, uvOffset: Vector2f : void
Sets the UV trasnforms to a given values. This overrides any previous modifiers.
Parameters:
uvScale
multiply UV values of the vertices, neutral value is 1uvRotation
rotate UV values of the vertices, in a left-hand directionuvOffset
increase UV values of the vertices
Grouping Functions
BeginObjGroup
() : void
Starts an object group. All further geometry objects until the EndObjGroup();
call will be in the same group and will be affected by all other modifiers at once.
BeginObjGroup();
will indent furher code by 4 spaces. Every BeginObjGroup();
must match to an EndObjGroup();
. Can be nested in any way and combined with SubComponent
or CSG operator calls.
Parameters:
there are no arguments, but it is a common to pass a String argument defining the name of the group, however this serves more like as a comment and is ignored by the core.
Usage:
EndObjGroup
() : void
Closes the group started by BeginObjGroup. Removes 4 spaces from indentation.
CSG Boolean Operators
These functions provide boolean operation on meshes. You can for example subtract a cylinder from a cube, making a hole through the cube.
⚠️ Those operators are expensive and should not be used unless a different approach can be utilized. They work best with primitives, the performance on meshes is not good.
AndOperator
() : void
Interserction of the last two objects or meshes.
Usage:
MinusOperator
() : void
Subtracts the geometry of the last object from the penultimate object. Intersection plane will have imprinted the last object's UV map values.
Usage:
OrOperator
() : void
Union of two last geometry objects. Works similarily to an object group, but bakes the meshes in one, removing vertices inside the internal volume.
Usage:
Miscellaneous
hasEqualGeometry
Tools and Importer Meta Keywords
The following features are ignored by the Roomle Rubens Configurator core, but provide different functionalities in other development tools and importers.
TODO
A comment starting with TODO will appear in the VS Code Outline. This is a function provided by the VS Code extension and roomle-content-tool-api
Usage:
FIXME
A comment starting with FIXME will appear in the VS Code Outline. This is a function provided by the VS Code extension and roomle-content-tool-api
Usage:
#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:
#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:
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:
Last updated