Environment Setup for Making Roomle Content

This document will guide you to setup your environment for the effective scripting of Roomle Rubens content using Visual Studio Code and conversion of meshes using Blender.

If you find any inaccuracies in this document, something is not working or you have a problem you need to solve, please, don't hesitate to tell us!

Mesh Conversion

Blender

Blender is a free 3D modelling tool. You can get it at the blender.org website. You need to install the Roomle Blender Add-On in order to be able to get the meshes in a correct status to Rubens Admin and also to be able to use them in Component Definitions (more on that later). For installation instructions, please refer to the add-on readme file.

Component Definition Scripting

There are three different levels of your possibilities that depend on if you just need to write a simple content or fix a simple bug, or if you need to develop a complex content project.

Without Any Tools

Technically you do not need to install anything and you can just type the component definition in the Rubens Admin or in the configurator test site. This is however reasonable only if you need to do the most simple work. You only need the web browser and possibly a text tool. However, with this method you will quickly reach its limits and for actual content development, you should use the VS Code + Rubens CLI.

To understand the usage of test site, please refer to Hello world example.

VS Code + loader snippets

This is considered to be a lighter way of setting up the environment in cases where you are not able or allowed to install Rubens CLI or its software dependencies.

You need to install:

• Visual Studio Code - https://code.visualstudio.com/ and following extensions:

  • Roomle Component Tool

  • Live Server

• Web browser that supports JavaScript snippets

You will write code in the Visual Studio Code editor and then feed it to the instance of the https://www.roomle.com/t/cp site using a custom-writte loader snippet, which fetches the data from the HTTP server provided by the Live Server extension.

VS Code + Rubens CLI + Git

This is a recommended way for content developers. Rubens CLI is a node.js package that mimics the RAPI backend with data stored locally on your drive. Git is recommended for version control. To use it, please install:

• Visual Studio Code - https://code.visualstudio.com/ with extension:

  • Roomle Component Tool

• node.js - https://nodejs.org/, known compatible versions:

  • node 16.18.1

  • npm 8.19.2

• Git - https://git-scm.com/

To install Rubens CLI with the Roomle Component Tool extension:

1. open the root folder of your project

   • This should also be the root folder of your GIT repository.

2. trigger the Command Palette by pressing Ctrl+Shift+P or Cmd+Shift+P

3. launch the Roomle: Install Rubens CLI command

4. define the version of the Rubens CLI you want to install - you probably want to keep the option latest

5. follow the prompts in the Terminal panel that just opened

If you checked out a repository from Git with Rubens CLI installed via command line interface:

1. open Terminal, PowerShell or Command line

2. navigate to the repository root folder

3. run npm install command

To install the Rubens CLI to a new folder via the command line interface:

1. open Terminal, PowerShell or Command line

2. navigate to your content projects folder

3. run npx @roomle/create-rubens-content@latest

4. define name of the project, which will also be the folder name

5. wait for the package to install

6. open the new folder in VS Code

7. also initialize a Git repository in this folder as well

To install the Rubens CLI to an existing project folder: Follow the same steps as if you'd install it to a new folder. The project name must be the same as the folder name. Keep in mind, that you might need to change the folder structure and that you should not have any uncommited changes or unmerged branches to avoid big merge conflicts.

Q&A

Do I need to use Visual Studio Code?

The VS Code will be used to write the code, so you actually do not have to, but we only provide language support extension for VS Code and we do not plan to support other code editors at the moment.

What does the Roomle Component Tool extension do?

This extension provides languaged support for the Roomle Component Definition language, which is basically RoomleScript written in JSON structure. It provides with syntax highlighting, code formatting, outline and static analysis. For further details, check the extension itself, which provides the documentation on how to use it.

Does the Roomle Component extension send any data?

No, the extension does not send anything anywhere.

Are there further good VS Code extensions that will help me with content development?

We can recommend those:

• Bracket Lens

  • Shows content before opening bracket at long code blocks. You can improve it for RoomleScript language by adding following to the VS Code user settings under bracketLens.languageConfiguration.brackets.

{
    "opening": "\": \"",
    "closing": "\"",
    "headerMode": "smart",
    "inters": []
},
{
    "opening": "BeginObjGroup",
    "closing": "EndObjGroup",
    "headerMode": "smart",
    "inters": []
}

• Highlight-words - keyword highlighter.

  • Allows you to select a piece of text and have all its occurences highlighted.

• Edit csv

  • Some RuAd import data are in the CSV format. This renders CSV files as tables.

• Rainbow CSV

  • Allows easy column distinguishing by applying a different colour at each.

• Project Manager

  • Switches between multiple Git repositories.