This is the 20th day of my participation in the August More Text Challenge

Spark AR is Facebook’s free AR creation platform that enables users to create interactive AR experiences for Facebook and Instagram. More than 400,000 creators in 190 countries have used Spark AR to create their own AR creations

Since the software requires no coding knowledge to use, anyone can now lead the world by creating the next crazy viral Instagram AR effects with little experience in the AR world.

Specialized AR filter designers can cost anywhere from $1,000 to $30,000.

Spark AR Studio supports JavaScript to add logic and interactivity to your effects. This article covers the basics to help you get started with scripting.

Spark AR Studio opens your scripts using the default editor assigned to JavaScript/TypeScript files in macOS or Windows operating systems. If you don’t already have it installed, you can download an editor, such as Visual Studio Code, and set it as the default application that opens JavaScript/TypeScript files.

Prior to the start

Here are some points to consider when writing scripts in Spark AR Studio:

  • Supports JavaScript ES6 and TypeScript.
  • Scripts can be split across multiple files.

Create a script

To create a new script, click the + Add Asset button in the Assets panel, and then select Script. You can choose to create a new JavaScript or TypeScript file.

A new script file will appear in the Asset panel.

Open the script

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

The script file opens in the default editor associated with the JavaScript file on your computer.

Edit the script

To edit the scripts, make the changes in the script editor and save them before returning to Spark AR Studio.

Changes in the script will be reflected in Spark AR Studio.

The script based

The new script presets some basic scripting code in Spark AR Studio.

The following example comes from a pre-populated JavaScript file. The content of a newly created TypeScript file is slightly different.

/ / = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
  // Welcome to scripting in Spark AR Studio! Helpful links:
  //
  // Scripting Basics - https://fb.me/spark-scripting-basics
  // Reactive Programming - https://fb.me/spark-reactive-programming
  // Scripting Object Reference - https://fb.me/spark-scripting-reference
  // Changelogs - https://fb.me/spark-changelog
  //
  // For projects created with v87 onwards, JavaScript is always executed in strict mode.
  / / = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
  
  // How to load in modules
  const Scene = require('Scene');
  
  // Use export keyword to make a symbol available in scripting debug console
  export const Diagnostics = require('Diagnostics');
  
  // Enables async/await in JS [part 1]
  (async function() {
  
  // To use variables and functions across files, use export/import keyword
  // export const animationDuration = 10;
  
  // Use import keyword to import a symbol from another file
  // import { animationDuration } from './script.js'
  
  // To access scene objects
  // const [directionalLight] = await Promise.all([
  // Scene.root.findFirst('directionalLight0')
  // ]);
  
  // To access class properties
  // const directionalLightIntensity = directionalLight.intensity;
  
  // To log messages to the console
  // Diagnostics.log('Console message logged from the script.');
  
  // Enables async/await in JS [part 2]}) ();Copy the code

Load module

Scripts are broken down into modules, each of which implements a specific function.

To load the module’s API into a JavaScript file, use the require method.

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

In the example above, we loaded the Diagnostics and Scene modules and stored them in variables for later use in our code.

In TypeScript files, the syntax changes slightly:

  // How to load in modules in a TypeScript file
  import Scene from 'Scene';
  import Diagnostics from 'Diagnostics';
Copy the code

Accessing scene objects

To access objects in the scene, use the findFirst method of the root property provided by the Scene module.

  // Store a reference to a single scene object
  const focalDistance = await Scene.root.findFirst('Focal Distance');
  
            
  // Store references to multiple scene objects 
  const [directionalLight, plane] = await Promise.all([
      Scene.root.findFirst('directionalLight0'),
      Scene.root.findFirst('plane0'),]);Copy the code

In the example above, we access the objects in the scenario by referring to them by name and storing them in variables.

If no object is found, the findFirst method returns None. If there are more objects with the same name, either one will be used. Use findAll to findAll occurrences of a given object.

Alternatively, you can use the findByPath method of the root property to access objects using their relative paths.

  Scene.root.findByPath('Device/Camera/Focal Distance/plane0').then((results) = > {
      const plane = results[0];
  });
          
Copy the code

The findypath method allows the wildcard * to match any subname and the double wildcard ** to match any set of subnames.

  Scene.root.findByPath('*/*/*/plane0').then((results) = > {
      // If there are multiple scene objects matching the given path, multiple results may be returned
      const plane = results[0];
  });
          
Copy the code

Note that if you store references as const variables using the findByPath method as in the previous example, you must modify the object in scope.

Attempting to modify it out of scope will throw an error, as shown in the following example.

  Scene.root.findByPath('Device/Camera/Focal Distance/plane0').then((results) = > {
      const plane = results[0];
  });
  
  // Will throw an error, as we are trying to modify the plane const outside of the scope it is defined in
  plane.width = 0.3;
Copy the code

You can modify objects within the findypath method, as shown below, or you can create globally accessible references using the findFirst method shown earlier.

  Scene.root.findByPath('Device/Camera/Focal Distance/plane0').then((results) = > {
      const plane = results[0];
  
      // Since the plane const is modified within scope, no error is thrown
      plane.width = 0.3;
  });
Copy the code

Objects accessed from a scene, such as scene.root.findfirst (‘directionalLight0’), do not currently support auto-completion.

Edit scene object properties

Once you have access to a scene object, you can access its properties and methods.

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

In the above example, we use the directionalLight variable we created earlier to access the light intensity properties.

  • Log in to the console

You can use the Diagnostics module to log messages from the script to the console in Spark AR Studio.

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

In the preset script, the diagnose.log line needs to be uncommented to run.

Code completion

Scripts can be edited in an editor of your choice, such as Atom or Sublime, but VS Code supports auto-completion through intellisense.

Code advice

Methods and properties will be suggested as you type.

Inline documentation

You can view the documentation for highlighted methods or properties.

Type checking

If you pass the wrong type or number of arguments to a method, you will receive a warning.

Objects accessed from the scene, such as scene.root.find (‘directionalLight0’), do not currently support auto-completion.

The next stage

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