Scripting Basics

Scripting Basics

Spark AR Studio supports JavaScript for adding logic and interactivity to your effects. This guide will cover the basics to help get you started with scripting.

Spark AR studio will open your scripts with the default editor assigned to JavaScript/TypeScript files on your macOS or Windows operating system. If you don't already have one installed, you can download an editor such as Visual Studio Code and set it as the default app for opening JavaScript/TypeScript files.

Before you Start

Below are some important points to consider when scripting in Spark AR Studio:

Creating a Script

To create a new script click the + Add Asset button within the Assets panel and then select Script.

A new script file will appear in the Assets panel.

Opening a Script

To open a script double-click on the script file in the Assets panel.

The script file will open in the default editor associated with JavaScript files on your computer.

Editing a Script

To edit a script make the changes within the script editor and save them before returning to Spark AR Studio.

The changes in your script will be reflected in Spark AR Studio.

Scripting Fundamentals

New scripts are pre-populated with code covering some fundamentals of scripting in Spark AR Studio.

// Welcome to scripting in Spark AR Studio! Helpful links:
// Scripting Basics -
// Reactive Programming -
// Scripting Object Reference -
// Changelogs -

// How to load in modules
const Diagnostics = require('Diagnostics');
const Scene = require('Scene');

// How to access scene objects (uncomment line below to activate)
// const directionalLight = Scene.root.find('directionalLight0');

// How to access class properties (uncomment line below to activate)
// const directionalLightIntensity = directionalLight.intensity;

// How to log messages to the console (uncomment line below to activate)
// Diagnostics.log('Console message logged from the script');

Loading Modules

Scripting is broken down into modules with each module implementing a particular functionality. To be able to access the APIs belonging to a module, we need to load it into a script using the require method.

// How to load in modules
const Diagnostics = require('Diagnostics');
const Scene = require('Scene');

In the example above we are loading in the Diagnostics and Scene modules and storing them in variables for use later on in the code.

For a complete list of modules, each with their own code example, check out the Scripting Object Reference.

Accessing Scene Objects

To access an object you have in your scene you can use the find method of the root property provided by the Scene module.

// How to access scene objects
const directionalLight = Scene.root.find('directionalLight0');

In the example above we are accessing the directional light in the scene by referencing it by name and storing it within a variable.

The find method will throw an exception if more than one scene object is found with the same name.

Alternatively, you can chain the child method of the root property to access objects using their relative path.

const directionalLight = Scene.root.child('Device').child('Camera').child('Focal Distance').child('directionalLight0');

This method avoids the issue of accessing an object that shares the same name as another object but adds code complexity.

Editing Scene Object Properties

Once you have access to a scene object, you can then access it's properties and methods.

// How to access class properties
const directionalLightIntensity = directionalLight.intensity;

In the example above we use the directionalLight variable we created previously to access the light's intensity property.

Logging to the console

Messages can be logged from a script to the Console within Spark AR Studio using the Diagnostics module.

// How to log messages to the console (uncomment line below to activate)
Diagnostics.log('I am a console message logged from the script');

In the pre-populated script the Diagnostics.log line needs to be un-commented in order to run.

Code Autocomplete

Scripts can be edited in the editor of your choice such as Atom or Sublime, however VS Code additionally supports autocomplete functionality via IntelliSense.

On MacOS please make sure you have installed Spark AR Studio in the /Applications directory for autocomplete to function properly.

Code Suggestion

Methods and properties will be suggested as you type.

Inline documentation

You can view the documentation for the highlighted method or property.

Type checking

If you pass the wrong type or number of arguments to a method you will be warned.

Objects accessed from the scene, e.g. Scene.root.find('directionalLight0'), do not currently support autocomplete.

Next Steps

Now you've mastered the basics it's time to learn about reactive programming, the scripting model used in Spark AR Studio to create relationships between objects, assets and values.

Was this article helpful?