Roomle Script Built-in Functions

This is an overview of native RoomleScript functions provided by the core. These functions can be used directly and provide functionalities that are not achievable through standard scripting.

The functions are grouped by their availability in different script contexts. Some functions are available everywhere, some only in specific scripts like onUpdate, connection, collision condition or geometry.

How To Read This Document

The function documentation follows a specific format to ensure clarity and consistency. Each function is documented with its name, signature, parameters, return type, usage examples, and any exceptions it may throw. The documentation is structured to help you quickly understand how to use each function effectively.

This documentation is also available in our VS Code extension in the autocomplete and hover tooltips, making it easier to access while coding.

The function signatures are written in a TypeScript-like syntax to enhance readability and understanding of the function's structure, an example follows:

functionName(
    parameter1: type,
    *optionalParameter: type[ = defaultValue],
    **keywordParameter: type[ = defaultValue],
) : returnType

Parameters without any asterisks (*) are required. Parameters with a single asterisk are optional parameters, and are identified by their order in the parameter list. Parameters with double asterisks (**) can be used as keyword arguments, meaning they can be provided in any order and are identified by their name.

Optional and keyword parameters of these build-in functions can (but don't have to) have default values, which are used if the parameter is not provided when the function is called.

The types used in the signatures are internal RoomleScript types, which are a subset of JavaScript/TypeScript types, as well as the default values, with following exceptions, that are not part of the RoomleScript syntax and have no meaning and are no keywords in RoomleScript:

• any: can be anything (TypeScript-any-like)
• null: null value; null itself has no meaning in the RoomleScript language
• [type]: array of the given type
• [[type]]: array of arrays of the given type

General Functions

These functions are universally available and you can utilize them in any script context.

Math

These are mathematical functions.

asin

Arcus sine (arcsine)

Parameters:

• a: value between -1 and 1

Returns: arcsine of a in radians.

Usage:

acos

Arcus cosine (arccosine)

Parameters:

• a: float value between -1 and 1

Returns: arccosine of a in radians.

Usage:

atan

Arcus tangent.

Parameters:

• a: value between -1 and 1

Returns: arctangent of a in radians.

atan2

Arcus tangent defined by ratio of opposite and adjacent side of the triangle.

Parameters:

• y: length of opposite side
• x: length of adjacent side

Returns: arctangent of the angle in radians.

ceil

Nearest higher value

Parameters:

• number: the number to be ceiled
• digits: count of decimal digits

Returns: Nearest higher value rounded to given amount of decimal spaces.

Usage:

cos

Cosine

Parameters:

• valueRad: value in radians

Returns: cosine value of a.

cosh

Hyperbolic cosine

Parameters:

• valueRad: value in radians

Returns: hyperbolic cosine value of a.

exp

Exponential function

Parameters:

• x: the exponent

Returns: Value of e powered to x

fabs

Absolute value

Parameters:

• x: value

Returns: x if x is positive or -x if x is negative.

Usage:

floor

Nearest lower value

Parameters:

• number: the number to be floored
• digits: count of decimal digits

Returns: Nearest lower value rounded to given amount of decimal spaces.

Usage:

fmod

Floating point modulo

Parameters:

• dividend: float
• divisor: 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:

log

Natural logarithm

Parameters:

• value

Returns: Logarithm of the value with base of e (~2.718)

Usage:

log10

Common logarithm

Parameters:

• value

Returns: Logarithm of the value with base of 10

Usage:

pow

Power function

Parameters:

• value: the value to compute power
• exponent

Returns: value powered to exponent.

round

Nearest rounded value

Parameters:

• number: the number to be rounded
• digits: count of decimal digits

Returns: Nearest value rounded to given amount of decimal spaces.

Usage:

sin

Sine

Parameters:

• valueRad: value in radians

Returns: sie value of a.

sinh

Hyperbolic sine

Parameters:

• valueRad: value in radians

Returns: hyperbolic sine value of a.

sqrt

Square root

Parameters:number: zero or positive number

Returns: Square root of the number or nan

Usage:

tan

Tangent

Parameters:

• valueRad: value in radians

Returns: tangent value of a.

tanh

Hyperbolic tangent

Parameters:

• valueRad: value in radians

Returns: hyperbolic tangent value of a.

Data Type Conversions

Functions to convert between data types.

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:

string

toString function - converts value to string.

Parameters:

• input value to stringify
• decimalSpaces if input is an Integer or float, defines the amount of decimal spaces of the number to show; default is 2

  • note: not appliable to array, Vector2f, Vector3f, String

Returns: Value converted to string.

Usage:

stringToArray

Parses a string to array.

Parameters:

• stringifiedArray: stirng in a [number, number, ...] pattern

Returns: The parsed array or null if failed.

Usage:

stringToVector2f

Parses a string as Vector2f.

Parameters:

• stringifiedVector: String in a Vector2f{number, number} or {number, number} pattern

Throws:

• [1301] Error getting value

Returns: The parsed vector or null if failed.

Usage:

• Vector parameter

stringToVector3f

Parses a string as Vector3f.

Parameters:

• stringifiedVector: String in a Vector3f{number, number, number} or {number, number, number} pattern

Throws:

• [1301] Error getting value

Returns: The parsed vector or null if failed.

Usage:

• Vector parameter

typeOf

Returns the RoomleScript type name of a value.

Parameters:

• value: the value for which the type should be returned

Returns: One of Null, Integer, Decimal, String, Boolean, Array, Object, Vector2 or Vector3. Missing values and null values return Null.

Usage:

Array Operators

Functions that operate on arrays, like accessing and setting values, searching, inserting etc.

get

Reads an array element at a given index.

To write an array element, refer to set.

Parameters:

• array: the array you want to access
• index: index of the element in the array, index of the first element is zero 0

  • ⚠️ 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
• [1113] Negative index value. Returns 0 in this case, execution continues

Usage:

inArray

Checks whether an array contains a specific value. Takes exactly two arguments — the value first, the array second. To test a value against a plain list of values instead of an array, use in.

Arguments

• searchedValue: the value that is being searched for in the array
• array: the array to check

Returns

• true if searchedValue is equal to at least one element of array, otherwise false

Usage:

indexOf

Find index of a value in an array.

Parameters:

• searchedValue: the value that is being looked for
• array: the array to search

Returns: Index of the first occurence of the value in the array or -1 if no occurence.

Usage:

insert

Insert into array in front of the element at given index

Parameters:

• array: array into which the values are inserted
• index: index of the element before which the values will insert
• value: value to be inserted, can be a number or an array of numbers

Throws:

• [1404] index out of bounds

Usage:

intersection

Intersection of arrays

Parameters:

• a, b: two arrays of numbers

Returns: Array with elements that are present in both arrays.

Usage:

length

Length of array (for the length of a String, refer to size).

Parameters: * array: array of floats

Returns: count of the array elements.

Usage:

popBack

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:

pushBack

Pushes a value at the end of an array.

Parameters:

• array: the array to which to push
• value: the value to push

Usage:

removeAt

Remove element at index from an array and return the next.

Parameters:

• array: the array from which the element should be removed
• index: 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:

set

Sets value of an array element at a given index.

Parameters:

• array: the array you want to set
• index: index of the element in the array, index of the first element is zero 0

  • ⚠️ 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:

String Operators

Functions that operate on strings, like checking for patterns, getting length, splitting etc.

like

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 designed to be similar on the SQL's LIKE operator.

Parameters:

• input: the String to check against the pattern
• pattern: a case sensitive String pattern, where _ is a wildcard for any single character and % is a wildcard representing any subString at least 1 character long

  • a_ - length 2, starts with a
  • a% - any String starting with a
  • _a - length 2, ends with a
  • %a - any String that ends with a
  • %a% - any String that contains a

Returns: true if String matches to the pattern, otherwise false

Usage:

size

Length of String.

Parameters: * input: String

Returns: count of the String's characters.

⚠️ Warning: size converts its argument to a String first. Applied to an array it returns the length of the array's string representation, not the number of elements — size([10, 20, 30, 40]) is 25, the length of [10.00,20.00,30.00,40.00]. Use length for arrays.

Usage:

stringPart

Splits a string with a delimiter and returns the part under the given index.

Parameters:

• input: the string intended to be parsed
• delimiter: a string that will be used to separate the input string
• index: index of the part that will
• fallback: optional value to return if fails, empty string '' by default

Returns: part of the string or a fallback value (defined or '') if fails.

Usage:

stringSplit

Splits a string with a delimiter and returns the parts as an array.

Parameters:

• input: the string intended to be parsed
• delimiter: a string that will be used to separate the input string

Returns: Array of string parts or an empty array if input is an empty string.

Usage:

substring

Returns part of string based on position and length.

Parameters:

• input: the string from which the substring is to be extraced
• startIndex: index where the substring starts, first index is 0
• length: 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:

Component Data Functions

Component definitions can provide static non-changeable data in the JSON format. These functions allow to access and query this data and even evaluate them as expressions. There are several versions of these functions. Functions starting with get return the data as is, evaluate functions evaluate the data as RoomleScript expressions and find functions return arrays of data that match a certain criteria. In the basic form, these functions query the data of the current component definition. There are variants for accessing the data of a subComponent. If data is not found, there are variants of the functions that differ in the way they handle this case. Functions with OrNull suffix return null if data is not found, functions with WithDefault suffix return a default fallback value passed as an argument. Without any suffix, the functions return null and display an error message in the console.

These can return not only values, but also objects and arrays. The elements of the objects can be accessed with the . (member access) operator. Multidimensional arrays or lists of arrays are not supported because the RoomleScript does not support multidimensional arrays at all, not even for basic data types.

getData

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:

• key: path parts as String keys or Integer array indices; path segments are separate arguments, e.g. getData('a', 'b', 0, 'c') to access data.a.b[0].c

Returns: The retrieved data or null if data wasn't found, accompanied by an error message in the console.

Throws:

• [1308] Data not found

Usage:

• define the data in the component definition

• retrieve them using the getData function

getDataOrNull

Retrieves data from the data storage JSON object in the component.data or null if data wasn't found without emitting any error message.

Attributes:

• key: path parts as String keys or Integer array indices; path segments are separate arguments, e.g. getData('a', 'b', 0, 'c') to access data.a.b[0].c

Returns: The retrieved data or null.

Usage:

• define the data in the component definition

• retrieve them using the getDataOrNull function in the condition script of a parentDocking

getDataWithDefault

Retrieves data from the data storage JSON object in the component.data and returns a fallback value if entry hasn't been found.

Attributes:

• key: path parts as String keys or Integer array indices; path segments are separate arguments, e.g. getData('a', 'b', 0, 'c') to access data.a.b[0].c
• defaultValue: 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 a label 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

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 definition
• key: path parts as String keys or Integer array indices; path segments are separate arguments, e.g. getData('a', 'b', 0, 'c') to access data.a.b[0].c

Returns: The retrieved data or null.

Throws:

• [1308] Data not found

Usage:

• Data subComponent:

• Main component:

• Retrieve the data:

getSubComponentDataOrNull

OrNull counterpart of getSubComponentData. See getDataOrNull and getSubComponentData.

getSubComponentDataWithDefault

Same as getSubComponentDataWithDefault, but considers the value an expression and attempts to evaluate it. See evaluateData functions and getSubComponentDataWithDefault.

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.

findData

Parameters:

• key: path parts as String keys or Integer array indices; path segments are separate arguments, e.g. findData('a', 'b', 0, 'c', 'myFilterFunction') to access data.a.b[0].c; this is the path to an object or an array of objects, which will be filtered
• filterFunction: name of the criteria function as a string; this function is called for each key-value pair in the target object or for each element in the target array

The filter function has following header filterFunction(key: String | Integer, value: any) : boolean and has to be available at the time of the findData call. The filterFunction is accessed by its name as a string argument. It can be either a local function or a component function.

The findData functions are useful for finding data based on a criteria function. The result of this function is an array of retrieved data objects that match the criteria. The criteria function is a function available in the same context where the findData function is called. It has two arguments (one for the key, the other for the value) and returns a boolean value indicating whether the key-value pair matches the criteria. This function is called by its name as a string argument. The Roomle Component Tool provides a code snippet to help you retrieve the data, giving you a template for the find function, criteria function, and the code comes nested in a wrapper function. See the example below for more details and good practice recommendations.

The findData function is somewhat similar to the filter function in JavaScript (returns an array of matching objects), but it is specifically designed to work with the Roomle Component Tool's data structure. To have an actual find counterpart, you can retrieve the first element of the array returned by findData and return it as a value, as in the following example.

The findData function returns an array of objects that meet the criteria function. If there is no match, the array is empty (length is 0). The return value of the function has the following structure:

Example usage:

• Let's say we have the following data and a length parameter, based on which we want to retrieve the data entry:

It is recommended to encapsulate the findData call in a helper function in order to keep the code clean. Example for a recommended pattern for the findData function usage:

Hint: You can use the findData code snippet provided by the Roomle Component Tool. It generates a wrapper function, a criteria function, and the findData call. You just need to fill in the criteria logic and the data path.

Filter the data at the path by a criteria function. This is a getData counterpart.

findAndEvaluateData

Filter the data at the path by a criteria function and evaluate them. Works like findData, but string scripts are considered to be script expressions and the result contains their resulting values. The difference is like between getData and evaluateData counterpart.

findSubComponentData

Filter the data at the path in a subComponent by a criteria function. See the findData and getSubComponentData counterpart.

findAndEvaluateSubComponentData

Filter the data at the path in a subComponent by a criteria function and evaluate them. This is an findData and evaluateSubComponentData counterpart.

findDataKey

Returns: Array of keys of the data objects that match the criteria.

Similarly to the findData family of functions, which return the objects themselves, the findDataKey functions return an array of keys of the data objects that match the criteria. The keys are either numerical indices for the cases where an array is searched, or the keys of the object in the data object. This is useful in cases where the data contains a mix of data that you would retrieve with the getData, but also a few entries that you would like to evaluate, as in the following example:

findSubComponentDataKey

Counterpart of findDataKey for searching in subComponents.

Miscellaneous Functions

Functions that do not fit in the categories above.

activeGroupInView

Queries the configurator UI to get the currently selected parameter group. This is useful for manipulating geometry based on what the user is configuring.

⚠️ Warning: This function can query the open group into a variable which can be used in the whole component. This is dangeours and can cause serious errors, because it is possible to change configuration based on the user interaction. The values retrieved by this function should only be used in the geometry script to change the view to hide walls, open doors etc. or to remove certain docking previews in the parentDocking condition if used together with the connection.isPreview getter. It is especially important to note, that this function IS NOT intended to project its value into the article number, label, pricing or docking points coordinates.

Returns: key property of the current parameter group

Usage:

• geometry:

• parent docking condition:

getAbsolutePosition

Only in collisionCondition: (componentRuntimeId: int) : Vector3f

Returns the position of the current component in the coordinate system of the root component. This is the absolute position of the component withing the configuration, because the root component is always placed at the zero.

Inside of the collisionCondition script it is possible to optionally pass a componentId to the function to retrieve the absolute position of another component in the configuration.

⚠️ Warning: This function does not consider rotation of the docking points. It always returns the position of the component origin, regardless its rotation.

getComponentProperty

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:

• key either runtimeId, externalId or catalogId string values
• componentId a runtime ID of a different component, only availabe in the collisionCondition

Returns:

• unique runtime ID as an integer
• external or catalog ID as a string

Usage:

getDockPosition

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

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

getEnvironmentProperty

Gets the environment property of the current configurator session. These properties can be set in the url arguments or behind the configuratorId in the Tenant Settings.

Returns:

• country -> the ISO 3166-1 alpha-2 country code, e.g. 'us', 'de'
• currency -> the ISO 4217 currency code, e.g. 'USD', 'EUR'
• language -> the ISO 639-1 language code, e.g. 'en', 'de'
• unit -> mm, cm, inch, inchfeet
• level -> the current value/parameter restrictionLevel

getObjectProperty

Returns the value for the given property-key from the plan object.

wallthickness: Returns the thickness of the wall to which the plan object is attached if the object is used as a construction element. Otherwise, the default value or, if not present, 0 is returned.

configurationLoaded: Returns if the initial loading process of the configuration is completed.

getMaterialProperty

Retrieves additional material data defined in material properties. See Using GetMaterialPropery Function for detailed description.

Parameters:

• materialId: Id of the target material
• propertyName: name of the property on the given material
• fallback: 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

Only in collisionCondition: (componentRuntimeId: int) : 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:

Scheme of getPosition functions operation.

getListOfPolygonsFromSvg

An alternative way to get a list of 2D points from an SVG to getPointlistFromSvg is the getListOfPolygonsFromSvg function. This function returns a list of polygons, where each polygon is a list of points. The output of this function can be directly uesed with the AddPrism function to create a 3D geometry from an SVG input, including holes.

prism from SVG with holes

Example - Prism from SVG with holes

getPointlistFromSvg

Converts SVG path data to a list of 2D points. This can be further used to pass to the AddPrism function to create an three dimensional object from an 2D SVG input.

This function supports all the basic functionality of SVGs but is limited to the geometrical shape related properties. It can create a pointlist (contour) from the SVG, but does not read any color values (color, gradient, etc.) or any advanced functiality (animations, etc.).

It is also possible to read multiple shapes defined in a single SVG file. It is necessary to pass the index of the desired shape. If not, the first shape is always returned by default.

It is also possible to define the pointlist resolution for curves, called "curve point density". If a shape consist of a straight line, only the start and end points get added to the list. If the shape is a curve it adds the amount of points defined by the value on that curve depending on the curve-point-density parameter, including the start and end points. Therefore, the minimum value is 2. If none is provided it defaults to 8, which was chosen to be a good value for use cases in RoomleScript.

The following table shows the outcomes when using different values for the curve point density parameter.

2	4	8 (default)	16

The provided SVG data has to be a string and can not be loaded directly from a file. It is necessary to paste the SVG file contents into a component definition, preferably into the data structure.

The function is memoized, so if you call it multiple times with the same SVG data and curve point density, the pointlist is only calculated once and cached for later calls. This makes it possible to call this function multiple times with different indices without a performance impact.

The outcome of this example looks like this:

3D geometries created from an SVG-file input

Notice how the offset definition in the SVG content also affects the position of the geometry in the 3D scene.

getUniqueRuntimeId

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

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 null
• fallback: a value to return if varialbe is null or undefined

Returns:

• either the variable or the fallback if variable is null

Usage:

ℹ️ Since null is interpreted as false in boolean contexts (see NULL in boolean contexts), this initialization check can also be written as if (!initialized) { ... }.

in

Useful for checking if a list of values containes a specific value.

Parameters:

• valueToCheck: the value that is being searched for in the list
• valueN: any number of arguments that will form the list

Returns

• true if valueToCheck is equal to at least one of the other values, otherwise false

Usage:

Most used to compare a variable to a list of constants, however you can also check a constant to a list of variables.

isEnabled

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

Checks for null values.

Parameters:

• value: identifier to be checked

Returns: True if identifier is undeclared, null or after setnull call.

ℹ️ In boolean contexts null is interpreted as false (see NULL in boolean contexts), so a plain if (!initialized) works as well. isnull remains the reliable explicit check — an equality comparison like foo == 'null' is not a null check.

Usage:

• initialize on component load, at the beginning of onUpdate

• in a connection script of a docking range:

isVisible

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:

setnull

Undeclares a variable of given name and sets it to null.

Usage:

ℹ️ After setnull(x) the variable is null and therefore evaluates to false in boolean contexts (see NULL in boolean contexts).

xFromVector

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

Get Z component of a Vector

Parameters:

• v the vector

Returns: Z component of the Vector or 0 if fails

Usage:

onUpdate Script Functions

Functions available in the main onUpdate script of the component definition. Attempt to call these functions in other scripts will result in an error. Calls from an onUpdate type component function is possible.

AddAbsoluteDimensioning

Dynamic possibility to add a component dimensioning object from the onUpdate script. Values for the axis are x, y and z by default and you can add more axes using the AddAbsoluteDimensioningAxis. See Dimensioning for more detailed description.

AddAbsoluteDimensioningAxis

Dynamic possibility to add a component dimensioning object from the onUpdate script. See Dimensioning for more detailed description.

requestDockItem

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:

• item Either an itemId or a stringified configuration JSON that should dock.
• parentPostion Vector3f containing coordinates of a valid parent docking point on the parent side.
• childPostion Optional: Vector3f containing coordinates of a valid child docking point. If not provided, the first valid child docking point will be used.

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. Both these vectors are equal to the evaluated position values of the docking points.

Hint: It is better to not hardcode the catalogId of the current component, because the component could be published into a draft catalog. You can retrieve the catalogId by calling the getComponentProperty('catalogId') function, in which case the docked component will always be from the same catalog as the parent component.

Usage:

setBoxForMeasurement

Defines the box to be used for calculating the measurements of this component. This overrides the bounding box of the geometry in order to change the measurements.

⚠️ This is only valid if called in onUpdate

Parameters:

• Box: defines the size of the bounding box
• Offset: 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

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 parameter
• value: final status of the enabled flag

Usage:

setOrigin

For computing the position in the Room Planner and the Rubens Configurator, the origin of a component is always the center of bounding box of the current geometry. This however can cause movement relative to the floor while changing dimensions or animating. This function allows to set a custom origin for the component, anchoring it to a specific point.

See Origin of Components for more details.

setVisible

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 parameter
• value: final status of the visible flag

Usage:

Collision Condition Script Functions

Functions are only available in the collisionCondition script of a docking point, range or line. Attempt to call these functions in other scripts will result in an error. To learn more about collision detection and how it works in RoomleScript, see Collision detection of docked components.

Note: Inside the collisionCondition script, there are variants of the getAbsolutePosition, getPosition and getComponentProperty functions that allow to pass a component runtime ID to retrieve information about the other component in the collision.

collidingComponentIDs

This is not a function, but a getter available in the collisionCondition script. It contains list of other components that collide by their bounding boxes or by their boundingGeometry. You can iterate over elements of this list and check other collision condition script functions to evaluate the collision condition value.

Example:

getBoxForMeasurementOrigin

Returns the (local) origin position of the measurement box of this component relative to its own root (not global!). ONLY Inside of the collisionCondition script it is possible to optionally pass a componentId to the function to retrieve the data from the corresponding component.

getBoxForMeasurementSize

Returns the size of the measurement box of this component. ONLY Inside of the collisionCondition script it is possible to optionally pass a componentId to the function to retrieve the data from the corresponding component.

getBoxOrigin

Returns local origin position of the bounding box of the (other) component with the given runtimeId (or of this/self component if no runtimeId is given) relative to the root of this/self component.

getBoxSize

Returns size of the bounding box of the (other) component with the given runtimeId (or of this/self component if no runtimeId is given).

Geometry Functions

These functions are available in the geometry, boundingGeometry, previewGeometry and geometryHD scripts and in functions of type geometry.

Geometry functions are of two kinds: instantiation functions and modification functions. The modification functions always apply to the last call of the instantiation function of to the last group that was started with a BeginGroup() call and ended with an EndGroup() call. CSG operators apply to the last two instantiation function calls or groups and provide a new modification target.

There are certain enumerations that are used in some of the geometry functions argument. See:

• EdgeStyle

Keyword Arguments of Geometry Functions

In order to be able to fulfill various requirements, like bevel styles and sizes or material mappings, there are many optional parameters for the geometry functions. To avoid confusion and to make the geometry functions easier to use and read, some geometry functions support these parameters to be passed as keyword arguments.

See the function signatures to see which parameters can are optional and can therefore be passed as keyword arguments. See their datatype to determine if a single value or an array of values can be passed.

If the parameter is an array, this array follows a specific index scheme to apply the values to the respective face of the geometry. The overview of the indices is shown in the respective function documentation below.

If these arrays are shorter than the number of faces, the first value at index 0 is applied to the rest of the faces.

Material Parameters

All basic geometry functions support passing a list (array) of material IDs directly in the constructor, either via array of strings or keyword arguments. If different materials get passed, the geometry gets created with the provided different materials. The order of the IDs inside the array is defined as mentioned above in the section Geometry faces indices.

If a material for a side gets provided via keyword arguments but no base material ("material") was given an error message will be logged and the base material gets set to the default value (empty string which results in plain white in the renderer). Some geometries, like prism or cylinder, have no left, right, front and back, but only a side/mantle that goes all around. In this case the material for the side has to be set via the 'materialFront' property or corresponding index in the array, all other provided side materials will be ignored.

If SetObjSurface(...) function gets called after component creation, all previously defined materials get overridden.

Example:

For the AddCube function, the materials parameter can be used as follows:

which is equivalent to:

The result is a cube with a green bevel, a blue top, black bottom, cyan front, magenta back, yellow left side and white right side. The first member in the array is always the base material, so if not all sides are explicitly set to a material these sides get the base material assigned.

Edge Style and Width Parameters

See Edge Style for more details and examples.

UvTransform parameters

Similar to the multi-material arrays for geometry construtor functions it is possible to pass multiple different UV-transforms for all basic geometries. That means that all three different UV-transforms can be passed via a single value, to apply the same UV-transform to all faces, or as arrays of values, to apply different UV-transforms to different faces. So for example a uvScale can be passed as single value like Vector2f{2, 2} to apply a 2-times scaling to all faces of the geometry, or as multiple value array [{2, 2}, {3, 3}, {4, 4}] to apply different UV-scalings to different faces of the geometry. The order of the transforms inside the array is defined the same way as it is for the multi material arrays, see the individual function reference documentation for details.

If SetUvTransform(...) function gets called after component creation, the transform gets added to the existing one.

EdgeStyle Parameters

With the edgeStyle keyword argument it is possible to set the edge style of the geometry. The available values are edge, chamfer, fillet or defeult.

value	description
edge	Creates a sharp edge, no beveling.
chamfer	Creates a chamfered edge, where the edge gets cut off at an angle of 45°.
fillet	Creates a rounded edge, where the edge gets rounded with a radius of the bevel width.
default	Default edges for backward compatibility. Creates a chamfer edge with fillet normal vectors.

edge style

Cube

cube with edge style

Example - cube with edge style

Prism

prism with edge style

Example - cube with edge style

Cylinder

cylinder with edge style

Example - cube with edge style

Cone, truncated Cone

cone geometry

cone with edge style

Example - cube with edge style

Individual edge Style and Width Paramameter

It is possible to define the edge style and width for each side of the geometry individually. This can be done with the keyword arguments edgeStyleTop, edgeStyleBottom, edgeStyleSide and edgeWidthTop, edgeWidthBottom, edgeWidthSide. The allowed values for the edge styles are the same as for the edgeStyle keyword argument, so edge, chamfer, fillet or default. However, unlike with edgeStyle the value for edgeStyleTop, edgeStyleBottom, edgeStyleSide cannot only be a single value but also an array of values, where the index of the value inside the array defines the edge of the geometry it gets applied to. If the value is not an array but a single value, it applies to all edges in the area. In addtion a spcific edge cann be addressed by using the keywords edgeStyleTopyN, edgeStyleBottomN, edgeStyleSideN, edgeWidthTopN, edgeWidthBottomN, or edgeWidthSideN, wher N is the index of the edge. This allows the edge style and width to be defined in a structured manner. For example, the general edge style and the general edge width can be defined with edgeStyle and bevelWidth and additionally a different style and/or width for the top can be defined with edgeStyleTop or edgeWidthTop and on top a specific edge can be defined with edgeStyleTop0, edgeStyleTop1, etc. or edgeWidthTop0, edgeWidthTop1, etc. This allows for a very flexible definition of the edge style and width for each side of the geometry.

Instantiation Functions

AddCube

Parameters:

• Size: Vector3f defining the size of the cube in width (x), depth (y) and height (z) direction
• uvScale: Vector2f defining the scaling of the UV coordinates in U and V. The higher the value, the more often texture repeats (it appears smaller).
• uvRotation: float defining the rotation of the UV coordinates in degrees
• uvOffset: Vector2f defining the offset of the UV coordinates in U and V direction
• bevelWidth / edgeWidth*: float defining the width of the bevel on all edges of the cube. If set to 0, edges are sharp.
• material*: materialId of the material to be applied to the base or to the specific face of the cube
• materials: array of materials applied to the faces of the cube:
• edgeStyle*: style of all edges of the cube. See EdgeStyle for possible values.

Adds a beveled or plain cube (depending on the argumnets) to the scene, placed by the left rear lower corner. Its origin is in the center of the cube and an internal transformation is applied to move the cube to instantiate at the mentioned corner. This makes it easier to position the cube in the scene, but has the side effect that animated rotation is applied around the center of the cube.

Array indices:

Parameters that have a possibility to pass an array will follow these indices to apply the values to the respective face of the cube. If the array has less than 8 entries, the first entry at index of 0 is applied to the rest of the faces.

Geometry Face	Array Index	Example keyword argument
BASE	0	material
BEVEL	1	materialBevel
TOP	2	materialTop
BOTTOM	3	materialBottom
FRONT	4	materialFront
BACK	5	materialBack
LEFT	6	materialLeft
RIGHT	7	materialRight

Example:

Shelf from AddCube

AddCube with Keyword arguments

AddCylinder

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 base
• radiusTop radius of the top
• height 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 material
• uvRotation rotate UV values of the vertices, in a left-hand direction
• uvOffset increase UV values of the vertices -> moves the material in a negative direction
• bevelWidth default 2, size of the cube's bevel (measured parallel to its walls)

Array indices:

Geometry Face	Index	Keyword
BASE	0	material
BEVEL	1	materialBevel
TOP	2	materialTop
BOTTOM	3	materialBottom
SIDE	4	materialSide
SIDE #N		materialSide0, materialSide1, materialSide2, ...

Usage:

Cone made with the AddCylinder function example.

AddDimensioning

Adds a Geometry dimensioning object to the scene. See the chapter linked chapter to learn about the feature.

Parameters:

• axis: Name of the dimensioning axis to use. Must be defined with the AddDimensioningAxis function prior to use.
• from: Start point of the dimensioning line along the axis in mm.
• to: End point of the dimensioning line along the axis in mm.
• level: Level of the dimensioning line in mm. Similar to dimensioning level.
• context: Context in which the dimensioning is applied. Possible values are component (default) and scene.
• parameterKey: Optional parameter key to link the dimensioning to a parameter. If provided, the dimensioning will be interactive, providing an input field in the 3D scene.
• parameterFunction: Optional parameter function to link the dimensioning to a parameter function. If provided, the dimensioning will be interactive, providing an input field in the 3D scene, which takes the value of the interactive dimensoning and passes the returned value into the parameter function.

An existing axis name must be provided, which must be defined with the AddDimensioningAxis function first.

AddDimensioningAxis

Defines a free dimensioning axis for the AddDimensioning function that can be used with a dimensioning object.

Parameters:

• key: Unique key of the axis to be used in the AddDimensioning function.