Before you start

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

• JavaScript ES6 and TypeScript are both supported.
• You can split scripts across multiple files.

Creating a script

To create a new script click + 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 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 Meta Spark Studio.

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

Scripting fundamentals

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

  //==============================================================================
  // Welcome to scripting in Meta Spark 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]
  })();

Loading Modules

Scripting is broken down into modules with each module implementing a particular functionality.

To load in a module's API to a JavaScript file you use 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.

In a TypeScript file the syntax changes slightly:

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

Accessing Scene Objects

To access an object you have in your scene you can 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'),
  ]);
          

In the example above we are accessing objects in the scene by referencing them by name and storing them within variables.

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

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

The findByPath method allows usage of the wildcard character * to match any child name, and double wildcard ** to match any set of children.

  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];
  });
          

Note that if you store the reference as a const variable with the findByPath method as in the previous examples, the object must be modified within scope.

Attempting to modify it outside of scope will throw an error, as seen 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;
          

You can either modify the object within the findByPath method's scope as seen below or use the findFirst method shown previously to create globally-accesible references.

  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;
  });
          

Editing 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; 

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 Meta Spark 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');

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.

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.

Next steps

Now you've mastered the basics, it's the ideal time to start coding along at your own pace with our short video tutorial series.