Scripting Resources
This is a starting page for the Roomle scripting knowledge base. It is intended for all content creators, that do involve themselves in the creation of the component definitions (scripts).
This guide is a work in progress and not everything has already been included. We appreciate any feedback if you find some errors, you have difficulties with understanding some topics, etc. Should this be the case, please contact your Roomle representative.
Getting Started
Although creating content in the Roomle platform does not require any specific knowledge, it can get complex. For Level 1 content (3D Viewer), please refer to the Rubens Admin documentation. Content creators for Level 2 should start with the first chapters linked to this page. Level 3 content creators should start with the Level 2 topics, and then continue with the Level 3 topics, where they will learn the full feature set of the configurator. Level 4 should start with Level 2 topics and then continue with select basic topics, as they are not required to know the full feature set of the platform, but Level 4 scripting brings different challenges, mainly in the form of how the data are handled.
Environment Setup
Material Configurators (Level 2)
Converting a Single Mesh for Use in the Rubens Configurator
Converting and Processing Multiple Meshes
Writing Component Definition
Default Value of Parameter
Testing the Component Definition
Uploading Component Definition to the Rubens Admin
Direct Link to Component
Setting Up Item Definition in Rubens Admin
Choosing a Default Value for Parameters
Product Configurators (Level 3 and 4)
Level 3 Component Definition Basics
Parameter attributes
Parameter's Relevant Values
Parameter Types and Unit Types
types
unitTypes
Working with Imperial Measurements - Inches and Feet
Value Objects
Example: Parametrized Table Value Combinations
Creating and Updating Values with Thumbnails
Variable parameters, parameterGroups and valueObject labels
Storing string literals for the label scripts
Ranges
Parameter Groups
Example: Parameter Grouping
Examples of Parameters and their UI Represenatations
Type: Boolean - Yes/No Option
Type: Integer and Decimal
Unit Type: Length
Material or Parameter with Thumbnails
Buttons vs Dropdown
Range
Object parameters
Example: Utilizing Parameter of Type Object
Arrays and Vectors as Parameter Values
RoomleScript Language Reference
Variables
Data Types
Keywords
Operators
Comments
Scope and Context of Variables
Internal values
Functions
Constants
Available Functions
Available Geometry Functions
Tools and Importer Meta Keywords
Attributes of SubComponent
Back-reference
SubComponents Use Cases Examples
External Geometry
Example: Using SubComponent's Geometry
Part List Entry
Example: Adding Mounting Parts to the Parametrized Shelf
Example: Part List Pattern
External Computation
Parameter Provider
ElementType Pattern
Minimum Docking Example
Example: Two-Way Docking of Parametrized Shelf
Docking Assignments
Example: Shared walls between the parametrized shelves
Docking Ranges
Multi-Selection Parameter Error Topic
Addons and Possible Children
Possible Child: itemId vs componentId - thumbnail, sort, category
Hiding Addons in the List
Addons in Parameter Groups
Docking Multiple Components
Global Parameters and Parameter Context
Parameter Context
Global Parameters
Global Parameter
Global and Local Parameter
Example: Adjusting global parameters in the parametrized shelf system.
Theory
AddMesh
Primitives, UV settings and Bevels
AddPrism
Example: Drawer Front with Handle from AddPrism
Example: Window Frame
AddExternalMesh
Pivot Convention
Scalable Mesh Example
Packaging
Component Label
Where are component labels used?
Aggregating part list entries using count
Part List Grouping
Part List Highlighting
Measurement Box
Example: Overriding measurements with the setBoxForMeasurement Function
Custom Dimensions
Advanced Docking Logic (work in progress)
Utilizing connection.isPreview Check
Storing Data in the
connectionContext inassignmentScriptsSibling Points
Example: Grid Shelf System
Example: Deciding Which of the Neighbours Should Draw a Post in the 4 Post Shelf System
Docking Ranges
Getting Connection Index
Limiting Amount of Children Docked in a Range
Docking Range Examples
Collision Detection in the Docking Ranges
Collisions Inside a Range
Example: Infills for the Parametrized Shelf
Collisions Between More Ranges
Example: Detecting Neighbouring Door in a Modular Garden Shed
Example: Interior Accessory Docking in a Modular Garden Shed
Docking Lines
Example: Stackable Shelving System
Docking Line Ranges
Applying the Tenant Settings
Modifying the Tenant Settings
Changing accent colour, light settings etc.
Setup Configurator Variants
Changing the "Variants" Label
Changing labels in the UI of the configurator
List of all examples json files that are mentioned in the Scripting Course
Scripting Reference Documentation
Content Production Process-related Topics
Scripting Examples
Scripting Templates and Case Studies
Sofa Systems
Simple Sofa - two armrest sofa with dockable footstool and pillows
Two-Parts Sofa System - consists of two sub-parts, has dockable footstool and pillows
Complex Sofa System - consists of dockable modules, utilizing elementType subcomponent template
Rubens Admin for Content Creators
Changelog
9.1.2024
new tutorial on a wardrobe with collision detection in a docking range
update of the RoomleScript reference with new functions
1.8.2023
update and formatting of the RoomleScript reference
3.7.2023
Updated mention of UV modifiers and scaling function in the meshes chapter.
2.6.2023
Added setup RubensCLI chapter
18.5.2023
Added the Tenant Settings chapter
3.4.2023
Added RoomleScript Language Reference Document
Added Rubens CLI to environment setup
22.7.2022
Fixed loader snippets (API's
RoomleConfigurator._kernelAccessis nowRoomleConfigurator._plannerKernelAccess)Changed link to VS Code extension some, fixes throughout the documentation
23.5.2022
Formatter is now in the VS Code extension marketplace.
Enhanced the chapter about loader snippets by new feature (debug text injection).
Added subchapters:
20.3.2022
Added new formatter version 1.6.2, which fixes
else ifcollapsing toelseifon some occasions.
15.3.2022
Added documentation on
else if,break,continue,return(which are new core features)Added new formatter version 1.6.1, which supports the above-mentioned keywords.
4.2.2022
Added Part List Highlighting subchapter.
Added formatter 1.5.0: New features, bug fixes.
20.11.2021
Added a chapter about processes
Roomle Component Formatter Version 1.4.2: Bug fixes, small incremental improvements.
30.10.2021
Roomle Component Formatter Version 1.4.0: Component code outline, incremental improvements.
28.8.2021
SubComponents:
improved example of the
External Computationusage pattern
Parameters:
added subchapter Example: Utilizing Parameter of Type Object
Advanced part list topics:
added subchapter Aggregating part list entries using count
improved example code for the packaging feature
add further information in the Part List Grouping
Added chapter How to Test Content
Roomle Formatter Version 1.3.0: Syntax Highlighting, language definition and some fixes
12.6.2021
Dimensioning: Improved subchapter about the
setBoxForMeasurementfunction
7.4.2021
Added a subchapter about part list grouping in the Advanced Part List Logic chapter.
Added notes on good practices to the Docking Basics chapter.
Added new loader snippet variants.
Roomle Formatter Version 1.2.1
Added "Storing Data in the
connectionContext inassignmentScripts" in the Advanced Docking Logic chapters
1.4.2021
Added an instruction on parameter thumbnails in the parameters chapter.
Deleted chapters How to import materials in Rubens Admin, When and how to use which CSV template for Rubens Admin data import, which moved to the Rubens Admin documentation section.
Roomle Formatter Version 1.2.0
22.3.2021
moved data import content to Rubens Admin documentation
20.3.2021
Roomle Formatter version 1.1.1
26.2.2021
changed the naming of Roomle Product Data Cloud (PDC) to Rubens Admin
updated Roomle Formatter 1.0.0
reorganized scripting documentation landing page in a way for the user to be more clear where to start
added a note about the Object parameter type
added a note about meshes upload
added a subchapter about component labels in the configurator
added a mention of how to integrate the price service
21.11.2020added the first part of the Advanced Docking Logic chapter * added extensive subchapter sibling on docking points and their utilization in a grid-patterned dock shelf system * added example on quad post shelf system * added wardrobe example
14.11.2020
reviewed the Docking basics chapter, added a subchapter about addons
added an example of an office table system
separated chapter Parameters from Component Definition Basics
added/updated examples of how parameters render in the UI
added information about switching units to inches and millimeters
7.11.2020
new example and template: simple color-changing product configurator
new example: 4 post shelf system with complex logic
added some notes in the "How to import materials in PDC" chapter
added a chapter about the GetMaterialProperty functionality
23.10.2020
added article on pricing in Roomle Configurator
16.10.2020
added real-world examples for chairs and sofa systems
fixed broken links
2.10.2020
added dimensioning chapter
25.9.2020
new chapter "3D Models & Meshes"
improved this index file by adding subchapters
Last updated