# 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 platfrom does not require any specific knowledge, it can get really 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 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 challneges, mainly in the form of how the data are handled.
# Environment Setup
# Material Configurators (Level 2)
- Introduction
- Meshes Conversion and Upload
- Converting a Single Mesh for Use in the Rubens Configurator
- Converting and Processing Multiple Meshes
- Materials Set Up
- Level 2 Component Definition
- Writing Component Definition
- Default Value of Parameter
- Testing the Component Definition
- Uploading Component Definition to the Rubens Admin
- Direct Link to Component
- Set Up Product Entries
- Setting Up Item Definition in Rubens Admin
- Choosing a Default Value for Pararameters
- Level 2-4 Content Requirements for 3D Data <!--
# Efficient Workflows and Tools
(documentation creation in progress)
- Offline Loading
- Versioning
- rubens-cli
- Best Practices -->
# Product Configurators (Level 3 and 4)
- Prerequisities and expectations from the reader
- Level 3 Component Definition Basics
- Parameters
- Example: Adding Width and Depth Parameters
- On Update
- Geometry
- Article Numbers
- Parameters
- Parameters
- Parameter attributes
- Parameter's Relevant Values
- Parameter Types and Unit Types
- Example: Utilizing Parameter of Type Object
- Working with Imperial Measurements - Inches and Feet
- Value Objects
- Example: Parametrized Table Value Combinations
- Creating and Updating Values with Thumbnails
- Ranges
- Parameter Groups
- Example: Parameter Grouping
- Examples of Parameters and their UI Represenatations
- 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
- Example: Scripting a Parameterized Table and Implementing Client Feedback
- Example: Parametrized shelf system
- SubComponents
- 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
- External Geometry
- Debugging
- How to Test Content
- Docking Basics
- 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.
- 3D Models & Meshes
- Theory
- AddMesh
- Primitives, UV settings and Bevels
- AddPrism
- Example: Drawer Front with Handle from AddPrism
- Example: Window Frame
- AddExternalMesh
- Pivot Convention
- Scalable Mesh Example
- Advanced Part List Topics
- Packaging
- Component Label
- Where are component labels used?
- Aggregating part list entries using count
- Part List Grouping
- Part List Highlighting
- Dimensioning
- Measurement Box
- Example: Overriding measurements with the setBoxForMeasurement Function
- Custom Dimensions
- Measurement Box
- Pricing
- Using GetMaterialPropery Function
- Advanced Docking Logic
(work in progress)
- Utilizing connection.isPreview Check
- Storing Data in the
connection
Context inassignmentScripts
- Sibling 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
- Tenant Settings
- 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
- Roomle Content Project Data Structure AKA 'The GIT Convention'
- Naming Convention of Components, Items, Parameters, Variables
- Processes and Good Practices
# Scripting Examples
- Simple Colour Changing Product Scripting Example
- Chairs, Armchairs and Footstools
- Office Table System
- 4-Posts Shelving System
# 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
- Wardrobes
# Rubens Admin for Content Creators
# Changelog
- 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._kernelAccess
is nowRoomleConfigurator._plannerKernelAccess
) - Changed link to VS Code extension
- Some fixes thrgouhout the documentation
- Fixed loader snippets (API's
- 23.5.2022
- Formatter is now in the VS Code extension marketplace.
- Enhanced the chapter about loader snippets by new feautre (debug text injection).
- Added description of new Object, Vector and Array parameters
- Added subchapters:
- 20.3.2022
- Added new formatter version 1.6.2, which fixes
else if
collapsing toelseif
on some occasions.
- Added new formatter version 1.6.2, which fixes
- 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 above mentioned keywords.
- Added documentation on
- 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, incemental improvements.
- 28.8.2021
- SubComponents:
- improved example of the
External Computation
usage pattern
- improved example of the
- Parameters:
- added subchapter Example: Utilizing Parameter of Type Object
- Advanced part list topics:
- added subchapter Aggregating part list entries using count
- improved example code in packaging
- 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
- SubComponents:
- 12.6.2021
- Dimensioning: Improved subchapter about the
setBoxForMeasurement
function
- Dimensioning: Improved subchapter about the
- 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
connection
Context 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
- Updated Advanced Part List Topics: Where are component labels used?
- 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 Object parameter type
- added a note about meshes upload
- added a subchapter about component labels in the configurator
- added a mention on how to integrate the price service
- 21.11.2020
- added 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
- added first part of the Advanced Docking Logic chapter
- 14.11.2020
- reviewed the Docking basics chapter, added 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 colour-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 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