Variables & Expressions (Beta)

Getting started

System Requirements

Importing

Design process

Materials and Textures

Lighting and Environment

3D Configurator

Variables & Expressions (Beta)

Scene and project settings

Version History

Augmented Reality (WebAR)

Sharing, exporting, embedding

Performance analyzer

Optimizing a shared project

Project cloning

Embedding to other software

Export options

Other

Figma Plugin - Vectary 3D Studio Lite

Model API

Floating UI Configurators

Ecommerce

Variables & Expressions (Beta)

The ability to use variables within Studio greatly enhances flexibility in configuring interactivity for projects, enabling the creation of complex solutions and systems.

This feature is currently in Beta as we actively refine the experience with variables and expressions. Despite ongoing improvements, it is already highly functional and enhances project capabilities significantly.

What are Variables?

Vectary enables users to create and manage variables that can be utilized across various Studio settings. These variables represent data elements such as numbers, text, or formulas, which can be created directly within Studio or imported from external sources like Google Sheets. A variable can store a specific value or use expressions to dynamically determine its value based on other parameters.

Variables are also available for use in Slider and Input (new elements of Floating UI)

All variables are centralized for easy access and management:

To delete or rename a variable, right-click on its name

Expressions

Expressions provide a dynamic method for calculating parameter values using functions, binary operators, and variables.

This approach facilitates the creation of procedural effects and enables the implementation of complex solutions.

Most input fields in the UI support expressions (a detailed list can be found here), allowing for real-time modification of various settings, parameters, and text.

Let's consider a simple example using Variables and Expressions:

Task: create a configuration that allows parametric changes to the length and width of the tabletop.

Step 1: Create a simple table using primitives

Step 2: Create variables Width and Length (assign a value of 100 to each as the base size)

Step 3: Assign the created variables to the dimensions along the X and Y axes (replace the value with the variable name)

Step 4: To ensure the position of the table legs changes synchronously with the table dimensions, an expression using the variable must be assigned for the position value of each leg:

Leg 1: -width/2+5 (X) -length/2+5 (Y)

Leg 2: -width/2+5 (X) length/2-5 (Y)

Leg 3: width/2+5 (X) length/2+5 (Y)

Leg 4: width/2-5 (X) -length/2+5 (Y)

Almost done, only the UI for resizing remains to be created.

Step 5: Add a Floating UI to the scene and create a Text element along with a Slider element. The Text element will dynamically display the table size, while the Slider will be used to adjust the size.

Step 6: Setup the Text element using an expression so that the table size is dynamically displayed based on the size selected by the end user

Use the following expression: Width ${width}

Step 7: Setup the Slider element to allow the end user to adjust the dimensions of the table

Specify the variable Width, set the Range and Step:

Step 8: Repeat steps 6 and 7 for the length

Done! The Preview mode can now be activated to check the result:

Syntax

The syntax for expressions is inspired by JavaScript. While it resembles JavaScript in many ways, it is not a full implementation of the language. Instead, it is a minimalistic subset specifically tailored for defining expressions in this context.

This approach ensures simplicity and ease of use while maintaining the flexibility needed for powerful expressions. Users familiar with JavaScript will find the syntax intuitive, but it's important to note that certain JavaScript features may not be available.

Data types

Type	Input	Description	Example
variables	variable name
string	`"hello”` or `'hello’`
number	`896.45`	integer float
boolean	true false
template string	`text` `${}` `text`	everything is interpreted as a string, except what is inside `${}` it is an embedded expression	Use this to utilize variables and expressions for a Text element (Floating UI) or 3D text.
datasets	`IDENTIFIER[SELECTOR]`	Datasets are referenced using the syntax: `IDENTIFIER[SELECTOR]`	`Data["A1"]` Multidimensional selection is supported for rows and columns: `Data[0][1]`
unary expressions	minus `-` negation `!`

Supported data structures

Our expression language supports the following data structures:

Arrays

Arrays can contain elements of mixed types, for example: [1, 2, "A", "B", true]
Colors and vectors are represented as arrays:

[1, 0, 0] represents the color RGB(255, 0, 0)
[5, 10, 3] represents a 3D vector, Vector3(5, 10, 3)

Objects or classes are not used; only arrays are employed to maintain simplicity

Array Indexing

Elements within an array can be accessed using zero-based indexing:

Example: [1, 2, 3, 4, 5, 6][0] evaluates to 1
Syntax: [array content][index]

Binary operators

Name	Symbol	Example
add	`+`
subtract	`-`
multiply	`*`
divide	`/`
equals	`==`	`5==6` (false)
not equals	`!=`	`5!=6` (true)
less than	`<`
more than	`>`

Name	Symbol	Example
less than or equal to	`<=`
more than or equal to	`=>`
AND	`&&`
OR	`\|\|`
nullish coalescing	`??`
negation	`!`
mod	`%`
range	`:`

Functions

Returns	Syntax	Description	Example
A random number	`RAND()` no parameters	Generates a random number	`RAND()` will output a random value between 0 and 1, e.g. `0.625` `RAND()*10` will output a random value between 0 and 10, e.g. `6.25`
Rounded number	`ROUND(value, digits)` value (Number): the number to be rounded. digits (Integer): the number of decimal places to round to.	Rounds a number to the specified number of decimal places	Example: `ROUND(3.14159, 2)` → `3.14`
Number of characters in the string, including spaces	`LEN("value")` value (String): the input string whose length is to be determined	Returns the length of a string	`LEN("hello")` will output a value of `5`
Either `trueValue` or `falseValue`depending on the condition	`IF(condition,trueValue,falseValue)` condition (Expression): A logical expression that evaluates to true or false trueValue (Any): The value returned if the condition is true falseValue (Any): The value returned if the condition is false	Returns one value if a condition is true and another value if it is false	`IF` `(temperature` `<` `10,` `“cold”, “hot")` if `temperature` `=` `5` , the result is "cold", but if `temperature` `=` `15` , the result is "hot".
Result of the evaluated expression	`EVAL` `(expression)`	Re-evaluates a string as an expression and returns the result. expression (String): a valid expression in string format to be evaluated.	`EVAL(”5 + 5”) = 10`
Numeric value represented by the string, or an error if the conversion is not possible	`TO_NUMBER(value)`	Converts a string to its numerical representation, if possible.	TO_NUMBER(”5”) returns the number representation of the string, in this case 5, if possible. If the input is not a valid number (e.g., "abc"), it returns an error.
Time passed between frames as a floating-point number, typically measured in seconds	`DELTA_TIME`	Retrieves the time elapsed between the current frame and the previous frame. Commonly used in “on update” interactions to ensure smooth and consistent motion or timing.	If `DELTA_TIME` returns `0.016` (16 milliseconds), it can be used for animations or movement calculations: `position += speed * DELTA_TIME`
Value from the target range that corresponds to the key in the lookup range	`XLOOKUP(dataset, key, lookupRange, targetRange)` `dataset (Array)` the dataset containing the lookup and target ranges. `key (Any)` the value to search for in the lookup range. `lookupRange (Array)` the range where the key will be searched. `targetRange (Array)` the range from which the corresponding value will be returned.	Searches for a key in a lookup range and returns the corresponding value from a target range.	`XLOOKUP`(salesData, "Product A", salesData["Products"], salesData["Revenue"]) → Returns the revenue associated with "Product A"
Value of the specified property from the target entity, which could include objects, settings, or other accessible data types	`GET(target, propertyName)`	Retrieves the value of a specified property from a target entity. This can be used to access various attributes, settings, or metadata across different types of objects or entities.	`GET(OBJ("Box"), "position")` → Retrieves the position of the object named "Box”
Reference to the specified object, which can then be used in other functions or operations	`OBJ(name)` name (String) the name of the object to retrieve	Retrieves a reference to an object by its name. This is used to interact with specific objects.	OBJ("Box") → Retrieves the object named "Box" for further interaction
	`UI`	Same as above
	`VAR`	Same as above
	`PARENT_OF`	Same as above
	`CHILDREN_OF`	Same as above
Contextual reference to the current object, component, or environment	`SELF`
In an interaction, returns the trigger	`TRIGGER`	In an interaction, returns the trigger or event that initiated the action.	Interaction: trigger ”on click”, action “set variable” → TRIGGER() will return the object name clicked
Scalar value representing the dot product of the two vectors. A positive result indicates alignment, zero indicates perpendicularity, and a negative result indicates opposing directions	`DOT(v1, v2)` `v1 (Vector)` the first input vector `v2 (Vector)` the second input vector	Calculates the dot product of two vectors. The dot product is a scalar value that represents the magnitude of one vector projected onto another.	`DOT([1, 0, 0], [0, 1, 0])` → 0 (vectors are perpendicular)
Vector that is perpendicular to both input vectors	`CROSS(v1, v2)`	Calculates the cross product of two vectors. The cross product results in a new vector that is perpendicular to both input vectors and represents the area of the parallelogram formed by the vectors.	`CROSS([1, 0, 0], [0, 1, 0]) → [0, 0, 1]` a vector perpendicular to both input vectors
Scalar value representing the length of the vector	`MAGNITUDE(vector)`	Calculates the magnitude (length) of a vector. The magnitude represents the distance of the vector from the origin in space.	`MAGNITUDE([3, 4, 0])` → 5 (calculated as √(3² + 4² + 0²))
Unit vector with the same direction as the input vector but a magnitude of 1	`NORMALIZE(vector)`	Converts a vector into a unit vector (a vector with a magnitude of 1) while maintaining its direction.	`NORMALIZE([3, 4, 0])` → [0.6, 0.8, 0] (calculated by dividing each component by the magnitude, √(3² + 4² + 0²) = 5).
A value or vector between `v1` and v2 based on the interpolation factor `factor`	`LERP(v1, v2, factor)` `v1 (Number or Vector)` the starting value or vector of the interpolation `v2 (Number or Vector)` the ending value or vector of the interpolation `factor (Number)` the interpolation factor, a value between 0 and 1, where 0 represents `v1` and 1 represents `v2`	Performs linear interpolation between two values or vectors based on a given ratio.	`LERP([0, 0], [10, 10], 0.5)` → [5, 5] (halfway between the two vectors)

List of inputs

A list of fields where variables and expressions can be used. This list will continuously expand, with the ultimate goal of enabling support across all fields.

Design mode
Variables
Transformations (Design mode)	Position, Rotation, Scale
Color	HEX (Solid), RGB (Solid), Tiling, Offset, Rotation, HEX (Overlay), RGB (Overlay)
Roughness	Intensity, Tiling, Offset, Rotation
Metalness	Intensity, Tiling, Offset, Rotation
Opacity	Intensity, Tiling, Offset, Rotation
Emission	Intensity, Tiling, Offset, Rotation
Normal map	Intensity, Tiling, Offset, Rotation
Texture Transformations	Tiling, Offset, Rotation
Environment	Intensity, Rotation
Background color (solid)	Hue, Saturation, Brightness, HEX, RGB
Lights	Intensity
3D text	Text
Floating UI - Text	Text
Floating UI - Button	Text
Floating UI - Input	Variable
Floating UI - Slider	Variable
Interact mode
Action - Set variable
Condition - Expression
Action - Transformation	all 9 transformation inputs, Duration, Delay
Action - Cameras	Duration, Delay
Actions - Animated texture, Animation, Download image, Interactions, Materials, Open link, Sounds, Upload image, Variants, Visibility	Delay

Tips

Spaces are ignored — spaces are ignored in expressions unless they are inside a string or template string.

Variable name as text — typing quotation marks before and after a variable name treats it as regular text rather than referencing the variable.
Variable name in the expression — referencing a variable name in an expression calculates its value like any other number if the variable is of type number.

if the value of the variable is 10, than typing position + 100 will output result of 110

Colors in UI

Regular text or number	`Black`
Variables	`Purple`
Functions, true/false	`Blue`
Operators	`Teal`
Invalid/incorrect value	`Red`
Expression	`Yellow`
String	`Green`

Data import

Data can be imported from Google Sheets or CSV files. This functionality allows you to operate with existing datasets, making them available for use in variables and expressions after import.

To import data, add a new tab in Variables & Data

Google Sheet (CSV from link)

Data from a Google Sheet can be imported into Vectary, and any changes made to the Google Sheet will be automatically updated in real-time in Vectary. To begin this process, simply copy the link:

File ➞ Share ➞ Publish to web ➞ Comma-separated values (.csv) ➞ copy link

Then paste this link into Vectary:

Variables & Data ➞ create a new tab ➞ СSV from link ➞ sync button 🔄

Right-clicking on the tab opens a context menu with actions:

Change link
Refresh (sync data)
Rename tab
Delete tab

CSV from file

To import a file, create a new tab and select CSV from file:

Right-clicking on the tab opens a context menu with actions:

Reupload file
Rename tab
Delete tab

On this page

Variables & Expressions (Beta)
What are Variables?
Expressions
Syntax
Data types
Supported data structures
Binary operators
Functions
List of inputs
Tips
Data import
Google Sheet (CSV from link)
CSV from file