Roomle Component Formatter

This is not only a formatter and language support extension for creation of Roomle Rubens Configurator components, but also a development environment which provides further functionalities. Read through this file to learn about features and tools this extension provides.

Known Issue - Local Textures

Chrome-based browsers (Chrome, Edge, Opera etc.) block requests from online pages to localhost, which prevents the Rubens Local Content Server from serving local texture files in those browsers. Firefox does not enforce this restriction. See the texture note in the Rubens Local Content Server section for details and the available workaround setting.

Features and Documentation

All commands start with the Roomle: label or roomletool. key prefix. All settings start with Roomletool and can be filtered.

RC-JSON Language Support

• The extension provides a new language, the RC-JSON. If a JSON file is open, the language is automatically switched if the file is in a parent folder of a name components and there is a folder called content in the path. This can be changed in the settings under Open JSONs as RC-JSON setting.

• The RC-JSON language is proprietary and is derived from the JSON. It differs mainly in using newlines in string values, which is not a defined JSON feature and therefore, all JSON features break. However, if you wish, you can still apply operations for JSONs provided by VS Code or other languages, if you switch the language between the JSON and RC-JSON using buttons in the status bar that say >JSON and >RC-JSON. This converts the component definition by switching newline characters to \n and back and switching the language.

  • Note: The native language switch using the language panel will not work. VS Code treats the language change in the same way as file opening, which is already used to autodetect, if the file is a Roomle component definition. This causes immediate switch to the RC-JSON language.

• If the language is switched to RC-JSON, problem panel shows static code errors, syntax highlighting, formatting and code snippets are provided.

• You can control most of the extension features using VS Code commands from the Command palette (Ctrl+Shift+P / Cmd+Shift+P). All commands provided by this extension start with Roomle in the label or roomletool in the key. All settings also start with roomletool.

• You can format code by using the key combination to format a document (Alt+Shift+F or Cmd+Shift+F) or with RML-format button at the lower right corner in the status bar, if allowed in the Show format button setting or automatically on file save if Autoformat on save mode is set. Formatting applies formatting both to the JSON structure and to the values of the script or expression type in the component definition.

• There is another format mode, the normalize operation. This applies the formatting as usual, but also sorts the attributes of all objects in the JSON in an unified way, so that versioning systems do not show a change of order as a difference. This highly declutters work and is a recommended operation before every commit. You can normalize by the key combination (Alt+Shift+N or Cmd+Shift+N), automatically on save depending on the Autoformat on Save setting or with the RML-norm status bar button if Show format and normalize button is set. Normalizing also removes attributes with empty string, array or object values.

• The squash feature can be used to minify the scripts and expressions, considerably lowering file size. This removes all non-semantic whitespaces, but keeps newlines, comments etc. In certain cases, this can reduce loading times of the Rubens configurator (less download size, less parsing). This operation is fully reversible by formatting. You can squash using the Roomle: Squash component JSON command.

• The deformat feature goes further than the squash. It removes all newlines from the code and effectively minifies the scripts. Since the newlines are removed, this operation is partially reversible with the rescript operation. You can deformat with the command Roomle: Deformat component JSON.

• The rescript feature removes all newlines and returns them after semicolons, opening and closing braces etc. This partially reverses the deformat and is highly useful when analysing components that are generated, like the ones that are converted from the IDM data.

• The sort parameters operation reorders parameters, parameterGroups and animations in the JSON to match their order in the Rubens Configurator: parameterGroups by their own sort, and each parameter/animation by its parameter group's sort first, then by its own sort within that group. A parameter or animation with neither a resolvable group nor its own sort is moved to the end, keeping its existing relative order among other such entries. This is a distinct, opt-in operation - it reorders array elements based on their data rather than sorting object keys, and can therefore produce a large diff, so it's best committed as an isolated change. You'll be asked to type yes to confirm before it runs. Use the Roomle: Sort parameters, groups and animations by configurator order command, or the sortParameters operation wherever a list of operations can be picked (see mass-apply below).

  • Since group is technically a RoomleScript field, resolving it doesn't require a fully executed script - a group is considered resolvable in three ways, in order of preference: a single-quoted string literal ('grpBoard'), a bare unquoted word (grpBoard - a common convention in practice even though group is typed as a script), or, for a computed/decider script (e.g. someCondition ? 'basic' : 'other'), a best-effort guess using the first quoted string literal found anywhere in the script. A guess can be wrong for a decider script, but it's used for a cosmetic outline label or an approximate physical sort position, so that's an acceptable trade-off over treating it as fully ungrouped. To force a specific group regardless of what the script would actually evaluate to at runtime, prefix it with a comment containing your desired group as the first quoted literal, e.g. /* 'myGroup' */ someCondition ? 'basic' : 'other'.

• You can mass-apply the format, normalize, squash, deformat, rescript and sortParameters operations by right-clicking a folder called components (applies to every component JSON file inside), or a .json file (or a multi-selection of them) directly, in the VS Code file explorer, then picking the operations from the list that shows up. A MASS PROCESSING label shows at the right end of the status bar while it runs; if there are many components or it takes a lot of time, a progress counter is displayed next to it. You can also use Roomle: Run a modifier on all components in current workspace for the whole workspace, or Roomle: Process component JSON to apply the same operations picker to just the currently open component.

• If a blank file is open in the RC-JSON language, a simple component definition is scaffolded. If you want to create a new component, simply create a file in a components folder and call it with the externalId part of the id and use the .json extension.

• Component definitions will fill the VS Code native code outline for an easy navigation through the file. You can tag code by using a #tag ${tag name} comment in a script to display it as an outline entry. You can mark your individual features in the code like this. You can create code folding regions by using the #region ${region name} / #endregion comments. The begin of the region is shown in the outline, as well as the TODO and FIXME words in the comments.

  • The Show Parameters in Outline setting additionally lists parameters under the parameters outline entry: No (default) shows nothing extra, Yes lists every parameter key, Only Group Boundaries shows a marker wherever one parameter group transitions into the next (plus a trailing ungrouped marker for any parameters without a resolvable group), and All With Group Boundaries shows both. Groups are resolved the same way as for the sort parameters operation above (including the best-effort guess for computed/decider scripts). Since a group boundary can only be detected between physically contiguous parameters of the same group, a group that reappears non-contiguously is only marked on its first occurrence.

  • The Show Functions in Outline setting (off by default) lists every component.functions entry under the functions outline entry by its key, plus its declared type when set (e.g. computeWidth (geometry)) - handy for spotting at a glance which of your custom functions are geometry/onUpdate/etc.-typed.

• Autocomplete works in three ways: The autocomplete for the JSON structure, autocomplete for RoomleScripts and code snippets.

  • To use autocomplete for the JSON structure, apply the formatting first and then start typing the attribute key. Do not write the commas, they are already included in the autocomplete results and are therefore entered automatically for you. The autocomplete will show possible attributes based the cursor position in the component definition.
  • Autocomplete for RoomleScripts analyses the whole component for identifiers and functions you already have in the current component definition. There is a documentation about origin of the entry in the dropdown with the autocomplete entries. All used identifiers are shown in all scripts, including unavailable _. context keys etc. This will be improved in undisclosed future.
  • Code snippets provide native RoomleScript function calls. In some cases, it will insert more than just the function in order to help you with the coding as much as possible.
  • Built-in code snippets are parsed from the Roomle built-in functions documentation page. The documentation for the functions is shown in the autocomplete dropdown.
  • Autocomplete also provides content labels of parameters, parameter groups and value objects in the preview. You can set the preferred Autocomplete Label Language in which those labels are shown.

• If you are using loader snippets or single line comments pose a different problem, you can set Convert Single-Line Comments to Multi-Line Comments to convert all // style comments to /* */ style comments.

Analysis features

• The extension provides content analysis messages in the VS Code Output channel under the name roomletool. You can activate it in the menu View / Output and then switch to it using the dropdown at the top right corner of the output panel. Errors, analysis results and error messages coming from a mass operation are printed there. Certain commands that print out results to the channel automatically open the channel. Show Output Channel on Start is a VS Code setting that controls this.

• Errors and problems are shown in the Problems panel. The list of the errors is updated after every format operation or on file open. A red highlight will appear at the position of where the error happened, if the position is relevant and available.

• If you are not interested in seeing certain problems, you can ignore errors by their error code in the Ignore Error settings.

• To show a dependency tree of your current open component, you can use the Roomle: Get SubComponent Dependencies command, which will print out a dependency tree to the output channel. This command will automatically perform a static code analysis and print out any errors found. The dependencies include subComponents and possible children with componentId and itemId. Item definitions should be available in the json files or in the general items response file, which you can get by downloading data from the Rubens Admin (see below).

  • Warning: If you are using the requestDockItem function to dock a component which cannot be accessed via subComponents or possible children, you should add all possible dependent components into the possible children list with a false condition. The static code analysis will warn you about this, but cannot detect if the components are actually missing or not. It is a responsibility of the content creator to ensure that all dependencies are listed in the component definition.

Content Project Settings (Metadata)

• The current content project settings are stored in the ./content/metadata.json file. This file contains tenant information for accessing Rubens Admin, project compilation settings and server-side settings for the Rubens Local Content Server. The extension includes a JSON schema for providing autocomplete and validation for the metadata file.

{
  /*
   * Set tenant account name under which the catalogs reside in the Rubens Admin.
   * If missing, your workspace folder name is used.
   */
  "tenant": "your_tenant_account_name",
  /*
   * If you hold catalogs that reside in different tenants, you can define
   * a different tenant account for each of those catalogs. Drafts of the
   * catalog are also affected.
   */
  "catalogToTenantOverride": {
    "someCatalog": "another_tenant_account_name"
  },
  /*
   * Information about individual projects for compilations, which means
   * building a ready-to-upload ZIP file.
   */
  "projects": [
    {
      /*
       * OPTIONAL
       * List of target catalogs of the compiled project. If used, all items'
       * and components' catalogIds will be changed. If more are defined,
       * one copy for each of those catalog entry will be generated.
       * This is useful if you want to publish to a draft.
       *
       * Cross-catalog component dependencies are not supported - everything
       * will end in one catalog.
       *
       * Other content than items and components is unaffected.
       */
      "compileCatalogs": ["your_catalog", "your_catalog_draft6"],
      /*       
       * Define your project entry components. Dependencies of the components
       * will be crawled and necessary IDs are collected.
       */
      "rootComponentIds": [
        "your_catalog:shelf_root",
        /*
         * if unreachable through possibleChildren or subComponents, like
         * when using requestDockItem, add them to this list
         * At least either of rootComponentIds or listOfIds is REQUIRED.
         */
        "your_catalog:component_docked_by_request"
      ],
      /*
       * Define a list of all possible dependent components and items, which are not reachable through the rootComponentIds. This is useful when you are using functions like requestDockItem.
       * Or define a project without rootComponentIds and only with this list, if you don't want to define a root component, but just a list of components and items to be included in the bundle.
       * At least either of rootComponentIds or listOfIds is REQUIRED.
       */
      "listOfIds": {
        "componentIds": ["your_catalog:shelf_root", "your_catalog:component_docked_by_request"],
        "itemIds": ["your_catalog:shelf_item"],
      },
      /*
       * OPTIONAL
       * Name of the project to show in the selection list.
       * If missing, first rootComponentId is used.
       */
      "name": "Shelf",
      // OPTIONAL, If true, will be preselected in the list or target of the quick build command
      "quickBuild": true
    }
  ],
  // Server side settings for Rubens Local Content Server
  "contentServer": {
    // Change in the files of matching patterns will not trigger hot reload.
    "excludedComponentIdPatterns": ["templates:*"],
    // Server port to use. The server can auto-start on VS Code launch if this is different from the default port in settings.
    "port": 55002
  }
}

Rubens Admin interaction features

• If you have projects defined in your metadata.json file, you can use the Roomle: Compile Projects for Upload to Rubens Admin or Roomle: Quick Compile Marked Projects for Upload to Rubens Admin to quickly build a ZIP file with components and CSVs which you can drop into the components section of the target catalog.

  • You can also use this without setting the project in the metadata. Then, the currently open component is taken as the root component.
  • You can build the project using the first of the two presented commands. A selection will show up, giving you the possibilities to select what should be bundled.
  • All projects flagged with the quickBuild will be preselected.
  • When you confirm the operation, a pop up will show in the lower right corner once this is finished. You can open the import/export page of the target catalog, reveal the folder in the file explorer or both.
    • By default, the target folder is _upload in your open project. You can change this in Compile Output Path to a different path, absolute or relative (i.e. ../_uploads)
  • The second presented command (Quick Compile) automatically performs all the above mentioned steps without any further action. Projects marked with the quickBuild will be compiled.

• When using the compile project commands, you can change the catalogId using the target catalog lists. If these are present in the project settings, all components and items will change the catalog to the target catalog. You can build more copies into different catalogs at once. If this is used and components and items are from multiple catalogs, all will end up in the single target catalog.

• Another option to prepare components upload ZIP file is via the right click at the context menu of components folders in the file explorer. You will be prompted to define a prefix by which all components should get into the bundle. You can use nothing to target all components. In the second step, a regex based on the previous step is created. You can use this to further modify the components selection. A ZIP file will be generated in the catalog folder, containing a components uploader CSV and the component JSON files. Maximum limit of files count can be defined in the Max Components in ZIP setting. If this limit is reached, the payload is split into more ZIP files. As of 2024, Rubens Admin should be able to accept even huge payloads of components. Adjust this as needed.

• Similarly, you can prepare an items upload CSV file in the right-click context menu at a folder called items. A CSV with the item_id and configuration column will be generated.

• You can define the tenant account name for your open project using the Roomle: Set tenant account for this project. This will set the tenant value in the metadata.json. Similarly, you can set a catalogToTenantOverride using the Roomle: Set tenant account for catalogue of current open component command. If you don't do this, your workspace parent folder name is used as the tenant account in all operations that open Rubens Admin entry pages in the web browser.

• If a component JSON file is open, you use Roomle: Open Import/Export page of the current component's catalogue to open the uploads section of a catalog in your web browser.

• If a component JSON file is open, you can open its Rubens Admin page by the Roomle: Open component definition entry in the Rubens Admin command. If you use this often, you can enable a button in the status bar with this function with the Show Open Component in Rubens Admin Button setting.

• Hovering over an ID in the code will attempt to guess the type of the ID and offer you a possibility to open the Rubens Admin item, material, component or mesh entry from the mouse hover. ComponentIds also offer you to navigate to the their component definition JSONs in a new tab of VS Code.

• You can download components and items from a catalogue from the Rubens Admin with the Roomle: Download catalogue data command. You will get prompted for the catalogId and then you get prompted, if you want to fill your components and items folder with the JSON definition files. Because this overwrites your existing files, you have to type in yes in another step to confirm that you know what you're doing and accepting a possible loss of your working changes by overwriting the files.

  • You can also trigger this command directly from the file explorer context menu by right-clicking a catalogue folder under content/ (i.e. content/{catalogId}). The catalogId is prefilled from the folder name. The data type selection is pre-checked based on which subfolders (components, items, materials) already exist locally and whether texture files (.png, .jpg, .jpeg) are present in the materials folder.

• The Download Catalogue Data will also download so-called catalog response JSONs. Those are useful when sideloading content. Those are the same files as those you'd download by exporting JSONs in the catalog import/export section. However, since they are using the public access, they do not contain labels but the english labels and also no prices.

Configurator interaction features

• If a component definition JSON file is open, you can open the component in configurator in the web browser using Ctrl+Alt+R or Cmd+Alt+R. If neither RubensCLI nor the Rubens Local Content Server is running, it will be open in the live configurator using the live version of the component in the live catalog. You can set the Configurator URL and the init data Configurator Arguments in the settings.
  • If RubensCLI or Rubens Local Content Server are running, the open component in configurator command opens the current local version of the component definition in the browser.

Rubens Local Content Server

The Rubens Local Content Server is a way to load your current working data in the configurator. It is a server running at localhost with a defined Rubens Local Content Server Default Port Number setting, which serves configurator.html, planner.html and JavaScript files that manage a local configurator or planner instance with local content.

• Currently, the RLCS supports sideloading of component, item and material JSON definitions from your content folder and textures image files that are linked in the materials. If either of those three assets are requested by the configurator and the asset file is found at the expected path based on its type and id, the file is loaded to the configurator instance.

• RLCS also supports the Rubens Room Planner with local content loading. Access it at http://localhost:{port}/planner. This feature is in active development and further functionalities will be added. Feel free to submit feature requests for planner functionality through our service desk or your Roomle representative to prioritize their development.

  • Currently, the RLCS planner mode is useful to tweak behaviour of component definitions in existing stored or new blank plans.
  • Start with an id URL parameter set to an itemId (e.g. ?id=your_catalog:shelf_item). Component IDs (component@...) are not valid for the planner and are rejected. You can also provide an existing stored plan hash ID.
  • The planner loads local content through the same sideloading mechanism as the configurator — components, items, and materials are served from your local content/ folder.
  • Display messages from the Rubens engine are shown as an overlay at the bottom left, the same as in the configurator.
  • Hot reload is not supported. When you save a file, the server notifies the browser but the planner cannot reload in place — you must refresh the page manually.
  • The planner page is intentionally missing configurator development features: it shows the room planner full-screen without interaction buttons. Configuration copy/paste, part list display, and random interaction are not available in the planner UI.

Note that, since Q4 2025, Chrome-based browsers block loading textures from the Rubens Local Content Server due to browser security restrictions. Because online pages cannot access local files in this scenario, the setting Rubens Local Content Server Provide Textures was added to let you enable or disable texture serving through the RLCS. With this setting disabled, the configurator can still work in Chrome with local material definitions, but local textures will not be loaded. If you need local textures, use Firefox or another browser that does not enforce this restriction in the same way. This setting is disabled by default.

• Material definitions and textures can be loaded with the RLCS. To load an image file, use the textureObject.image attribute inside the material's data.json file. Use the @material/ placeholder to link a file inside the folder of the material. Use @content/ placeholder for local path within the content folder.

  • Note: When modifying a texture file, you might need to refresh the configurator page for the changes to be applied.

  • E.g. @material/RGB.jpeg will link the file RBG.jpeg that is in the same folder as the data.json file.

  • E.g. @content/my_catalog/materials/my_material/XYZ.png will link a file at the relative path starting in the content folder.

• RLCS ignores the id, externalIdentifier and catalog of the material and item JSON files and while loading, they are replaced by the ID that is requested. The ID taken from the request defines the path and if the file is found, the entries are replaced. This is useful if you copy or create the files, so that you don't need to worry about these three atrributes inside the files.

• The RLCS supports the following file structure. This structure is strict and if files are misplaced, they will be ignored.

  {project-root}/                           <--- your working folder
  ├── content/                              <--- folder storing all catalogs
  │   ├── {catalogId}/                      <--- folder with name matching a catalogId
  │   │    ├── _responses/                  <--- created by the Download Catalog Data command, optionally git-ignored
  │   │    │  ├── catalogId_allItems.json
  │   │    │  ├── catalogId_allTags.json
  │   │    │  ├── catalogId_catalog.json
  │   │    │  ├── catalogId_components.json
  │   │    │  ├── catalogId_materials.json
  │   │    │  └── catalogId_textures.json
  │   │    ├── components/                  <--- folder with component definitions
  │   │    │   └── *.json                   <--- component definitions as JSON files
  │   │    ├── items/                       <--- folder with item definitions
  │   │    │   └── *.json                   <--- item definitions as JSON files
  │   │    └── materials/                   <--- folder with material definitions
  │   │        ├── {materialId_1}           <--- folder with the same name as the externalId of the material
  │   │        │   ├── data.json            <--- material definition as JSON file (must be called data.json)
  │   │        │   ├── RGB.png              <--- RGB texture map of the material
  │   │        │   └── XYZ.png              <--- XYZ texture map of the material
  │   │        └── {materialId_2}
  │   │            └── data.json
  │   ├── {catalogId}_draft{N}/             <--- draft catalogs are handled as any other catalog
  │   │   └── ...
  │   ├── {anotherCatalogId}/               <--- another catalog in its own folder
  │   │   └── ...
  │   └── metadata.json                     <--- data about the project and RLCS server-side settings
  └── rubens_content_server/                <--- override RLCS local files and settings; see docs below
  

  • Example data paths relative to your {project-root}:

    • component sofas:exampla_main: ./content/sofas/components/exampla_main.json
    • item sofas:exampla_corner: ./content/sofas/items/exampla_corner.json
    • material sofas:leather_325: ./content/sofas/materials/leather_325/data.json

  • Component definition will be scaffolded for you when creating a new blank file. For an example item and material definitions, reach out to the response files. Every entry in the items or the material array should be one file.

• Multiple instances of the RLCS can be created as long as the server is open at a different port number. If you need to use more projects simultaneously, you can set their port numbers in the metadata.json path under contentServer.port setting.

• The RLCS can start and end using the Roomle: Start Rubens Local Content Server and Roomle: Stop Rubens Local Content Server commands. The server can start automatically based on the Automatic Rubens Local Content Server Start setting. By default, the server will start automatically as long as you have your port defined in the project metadata.json file and the port number is different from the default port number of the settings.

• Server will run on the address http://localhost:{port}. You can add initData arguments behind it, therefore your address could look like: http://localhost:55000/?id=component@your:component&highlighting=always. To launch a component, just open a component definition and use the Roomle: Run Configurator with current componentId (which is assigned to default hotkeys Ctrl+Alt+R) or use the server address with an id argument.

• If you save a component, item or material definition, the content server will send a message to all open browsers to clear the configurator cache and reload the current running configuration. There is a Rubens Local Content Server Reload Collision Timeout value in the settings which ensures that unnecessary high amount of reloads is triggered at once. File save operation will trigger a reload even if the file is unchanged.

• You can ignore certain components by their ids from being watched for changes in the metadata's contentServer.excludedComponentIdPatterns. Use a componentId with a * wildcard to represent any substring.

• You can expose client-side source into your working directory using the Roomle: Get Rubens Local Content Server Local Files. This will offer you to download the files from the extension package. If a file is non-existent in your working directory, it will be taken from the package. Those files include:

  • configurator.html / planner.html: HTML entry files for the configurator and planner respectively.
  • favicon.jpg: Web browser title icon.
  • configurator.js / planner.js: Entry point scripts that instantiate the Rubens configurator or planner, set up callbacks and wire up the UI.
  • client.js: WebSocket connection to the RLCS server and local content fetching via onCheckExternalCache.
  • helpers.js: Settings resolution, singleton state (configurator instance, WebSocket) and shared utilities.
  • ui.js: DOM element registry, display message system and UI utility functions.
  • utils.js: Configurator interaction logic — configuration and part list operations, random interactions, watcher panel, button wiring.
  • styles.css: Styles for the configurator page overlay and interaction buttons.
  • settings.project.js: Project-relevant settings. Use to fill in your configurator ID, launch componentId/itemId, content modifiers etc. This file should be included in your version control.
  • settings.user.js: User-relevant settings. Exclude this from version control (gitignore etc.).
  • All those files contain further documentation in their comments explaining how to use them. 3 levels of settings are merged in the following priority: user > project > fallback, where fallback contains a minimum working setting for the configurator.
  • You can modify all those files based on your needs. However, keep in mind, that the files might undergo breaking changes and that you might have to download the files from a newer extension package and reimplement your changes.

• Components can be modified during the sideloading. See the settings.project.js file. You can define a setting in the settings object and use it in the applyComponentModifier function.

• The Rubens Local Content Server configurator page has some extra functions beyond the standard configurator implementation. Those include:

  • Configuration:
    • Show: Calls await RoomleConfigurator.getCurrentConfiguration() and pretty-prints it into a new tab. The children arrays are also moved to the end of the objects to improve legibility as opposed to the default getCurrentConfiguration call.
    • Copy: Like show, but puts the configuration string into your clipboard. Also stores the configuration into an internal variable for later retrieval.
    • Paste: Gets the stringified configuration from the clipboard and calls RoomleConfigurator.loadConfiguration({clipboard});.
    • Paste Last Copied: Pastes the last configuration that has been copied using the Copy button. Useful if you put something else into the clipboard in the meantime. This is reset with the client page refresh.
  • Part List:
    • You can retrieve the last part list status coming from the onPartListUpdate callback in the (window.)RoomleConfigurator.partList value.
    • Show: Shows the prettified part list as JSON in a new tab.
    • Copy: Copy the part list to the clipboard.
    • Display: Displays the part list content in the background of the configurator. This is useful for seeing how the part list reacts to the changes in real time. Part list entries show their componentId and runtimeId and are colored red if the entry contains either of settings.partListWarnKeywords. If a component is selected, which is also a main component (in means of part list grouping main component), the displayed part list will be filtered to see which entries are coming from that component.
    • status: If part list contains a substring (JavaScript substring function implementation, case sensitive) defined in client settings at settings.partListWarnKeywords, a red warning shows. This means there is either a value, articleNr or label present with such a substring. Green OK shows if no such word is contained.
  • Random Interaction:
    • This is useful for quick testing.
    • Once: Collects all possible values of all parameters of all components and the global context in the configurator scene, randomly chooses one value and sets it. Selected parameter and value is shown in the label next to the buttons.
    • Loop: Does the same in a loop in an interval defined in the settings.randomInteractionsLoopInterval (3 seconds by default). You can watch as the configurator changes or for console errors (no further functionalities are implemented at this point).
      • If settings.randomInteractionsLoopStopOnPartListWarn is set to true (it is by default), the random interaction loop will stop as soon as a part list warn keyword is detected.
      • You can set the amount of these attempts using the settings.randomInteractionsLoopsCount. If set to -1, the loop will be infinite, but still interruptible by the stop on part list warning.
  • Scene:
    • When you select a component, its component and runtime ids are shown in the label inside the scene.
    • Based on the watchers in the setting files, you can display certain parameters with matching keys of components with matching ids. See example in the settings.project.js file. This can show values of visible parameters of the selectable component, not its subComponents. Improvements to this function will be made in an undisclosed future.

• Component Modifiers can be used to inject some code to the components on the fly. We provide two basic ones, where you can use a debugGeometry next to the standard geometry and they are merged together (debugGeometry is not a Rubens feature, it is ignored in live data - you can safely keep it in your component definitions, although it adds to file size). Another modifier is to display parameter keys in front of parameter labels and values of valueObjects in front of their labels. This is highly useful in development. More modifiers will come in the next versions of the extension. You can also write your own modifier, where the function provides a component definition as a JSON object which you can process using vanilla JavaScript.

• Display messages from the Rubens engine are shown as an overlay at the bottom left of the screen for a brief time period, so that you don't need to always open the browser console side-by-side to catch content errors. Each message is shown for a duration defined in the settings under kernelMessageDisplayTime in milliseconds (10 seconds by default), then disappears. You can filter which messages appear by their error code using the ignoreKernelMessagesDisplayByCode array, which accepts codes in the format '[1331]'.

• Dock Hierarchy Navigation panel is shown if a component having parent or children is selected. You can navigate to the parent or to the children using the buttons.

• Color Schemes (Skins), e.g. for a dark mode, can be defined as a colorSchemes export in settings.fallback.js, settings.project.js and settings.user.js (merged in that priority, same as the other settings). Each entry is a named scheme, e.g.:

  export const colorSchemes = {
      dark: {
          DEFAULT_BACKGROUND: '#333333',
          PRIMARY: '#0d00ff',
          SELECTION: '#00ff00',
          PREVIEW_DOCKING_COLOR: '#ff6600',
          RLCS_TEXT: '#dddddd',
      },
  }
  

  • See ROOMLE_COLORS for available color keys.
  • RLCS_TEXT is RLCS-specific and colors the text of the RLCS overlays (Display messages, Scene watch panel, Dock Hierarchy Navigation panel and the part list display).
  • Activate a scheme with the ?rlcs_skin=<name> URL argument, e.g. http://localhost:55000/?rlcs_skin=dark. If omitted, a default setting (the default live configurator shceme) is used. An unknown skin name logs an error to the browser console listing the available skin names.
  • You can also use the Roomletool: Configurator Arguments setting for this.

Content Dynamic Analyzer

• If the Rubens Local Content Server is running and the Use Dynamic Analyzer setting is enabled, the RLCS will collect content dependencies of the root component and store them in ${catalogId}/_content_tool_data/dynamic_analyzer.json.

• Dependencies are collected per root componentId. The starting component of the configurator will provide a list of all asset IDs that were requested and a list of all articleNrs the configurator produced during the test run. This will NOT give a full list of all possible articleNrs — such functionality is, unfortunately, not universally possible. This is most useful with the "Loop Random Interactions" feature.

• Those dependencies can be further analyzed. The files with them can be freely modified (i.e. by deleting entries inside) or deleted (to clean them up), as long as the VS Code editor is not running. If they are deleted while the editor is running, they will be retrieved from internal memory.

• Whenever a new dependency is detected, the file with the snapshot of the internal cache will be exported, unless another new entry arrives within the time period defined in the Dynamic Dependency Analyzer Export Timeout setting. When this time passes and no new dependency arrives in the meantime, the file is updated.

Component Translations Import/Export

• You can export all labels objects from component definitions into a CSV file using the Roomle: Export Translations command. This will prompt you for a project (defined in the metadata.json) or for dependencies of the currently open component.

• This will export the labels from the specific paths in all collected component definitions, which are:

  • labels object
  • parameters[].labels objects
  • parameters[].valueObjects[].labels objects
  • parameterGroups[].labels objects
  • data.*.translations.{translation_key} objects

• This WILL NOT EXPORT anything from the label scripts or any values of internal variables. The correct way is to keep string literals outside of the scripts and have them all in data.*.translations. You can utilize the getTranslationFromData code snippet for getting such translations.

• The columns of the CSV files are:

  • path - JSON path to the labels object
  • sameAs - link to another translation row
  • ISO 639-1 language codes

• The rows with the defined labels and without sameAs values are listed first in the file. The rest of the lines have the sameAs values defined, but do not define any labels. This is useful for linking multiple entries to the same translation. The sort of the lines itself is not relevant. If a line has a sameAs value, its labels are ignored.

• After careful modification of the CSV file, which doesn't break or change any paths, you can import the translations back into the component definitions using the Roomle: Import Translations command. This will then apply the translations back into the component definitions.

Rubens CLI integration

• RubensCLI has been deprecated in favour of the Rubens Local Content Server. You can still use it; please refer to the Rubens Documentation.

Errors and Feature Suggestions

If you have any suggestions or find any errors, we'll be glad if you find your time to report them at Roomle ServiceDesk.