Skip to main content
Version: 5.x

Scripting Introduction

Helper Scripts

Lens Studio comes with a number of helper scripts to help you add interactivity without you having to write your own code.

  • Behavior Script: allows your to define triggers (e.g. mouth opens) and responses (play animation)
  • Tween Manager: allows you to add tweens and animations to objects in your scene

Asset Library

You can find even more helper scripts, custom components and other assets in the Asset Library.

The term custom components refers to a bundle that has one main script asset and all it's dependencies.

Scripting Example

For a step-by-step guide to creating and running your first script, please refer to the Scripting Example.

API Reference

For a detailed technical reference of all classes and methods available in Lens Studio, please refer to the Scripting API in the navigation menu.


Script Assets

Script Assets (referred to as Scripts) are text files that contain the code you write for your Lens. Scripts are written in Javascript or TypeScript. Here's an example of a very basic script:

print('Hello, World!');

While Lens Studio scripts are written in JavaScript, there are some practices specific to the Lens Studio environment with which you should become familiar. To learn more, please refer to the section on Writing Scripts.

A basic script. When triggered, this script will print "Hello, World!" to the Logger.

Adding a Script Asset

There are two ways to add Scripts to your Lens Studio project. You can:

  • Create an empty script file
  • Import an existing script file

Creating an Empty Script

You can add an empty script in the Asset Browser panel by selecting

+ -> JavaScript or TypeScript Component

Importing an Existing Script

You can import an existing script in the Asset Browser panel by clicking

+ -> Import Asset

Script Asset Inspector

The Script Asset Inspector is present when you click on a Script Asset. Here you’ll be able to change the icon, description, and version. You can also set the default value of input variables, excluding Scene Object and Component references.

Hidden Script Input Fields

You can hide script input fields from being displayed in the scene by clicking the eye icon beside the input. These inputs won’t be visible in the Script Component Inspector and will always use their default value.

Exporting Scripts

You can right-click on the Script Asset and select Export in the drop down menu to export it. You have an option to export as Editable or Locked.

Exporting will bundle all referenced resources inside the asset. In case of exporting as Editable, whoever you share the file with will be able to see and edit the Script Asset. You can right-click and select Unpack for Editing in the drop down menu to unpack all assets stored in the bundle.


Writing Scripts in Lens Studio

Lens Studio scripts are written in an implementation of standard JavaScript or TypeScript, but there are a few practices specific to the Lens Studio environment that you'll need to be aware of as you write scripts for your Lenses.

Declaring Script Input Fields

To declare a script input field in your script, you'll need to use the @input keyword.

//@input float intensity = 1.0
//@input string objectName
//@input Component.AudioComponent music
//@input float[] delayTimes

In this example, we declared four script input fields:

  • A number named intensity with a default value of 1.0
  • A string named objectName
  • A reference to an Audio Component named music
  • A list of floats named delayTimes

Script input fields defined in script are editable in the object's Script component via the Inspector panel.

You can learn more about available property types in the Scripting Input Type Reference.

You can learn more about customizing your script's UI in the Custom UI Guide.

Accessing a Script Input Field

Defined script input fields become members of the pre-defined object script. You can access a property defined in your script using the keyword script.

//@input string hello = "Hello, World!"
print(script.hello);

You can learn more about the script object in the Scope section below.

Scope

Variables and functions you declare in script are accessible in three layers of scope.

Local Scope

All functions and variables you declare with let or const in a script are locally scoped by default. In other words, they can be accessed only from the script in which they're defined.

Script Scope

You can use the script object to access and modify properties defined in a Script. The same script object is shared between all Scripts on a Script Component.

Global Scope

You can create global properties and functions available to all scripts by using the pre-defined global object.

global.myMessage = 'Hello, World!';
global.sayHello = function (message) {
global.myMessage = message;
print(global.myMessage);
};

In this example, global.myMessage and global.sayHello can now be accessed from any other Script in the project.

Please note that in order to properly access global properties and methods assigned in another script, the properties need to be declared in a script that's already been triggered. To learn more about script triggering and event ordering, please refer to the Event Guide.

Scripting Tools

Lens Studio has built-in tools for writing and debugging Scripts. You can also use an external text editor to write Scripts.

Logging

See the Debugging Guide for information on logging in Lens Studio or on device.

Script Editor

Scripts can be edited directly in Lens Studio's Script Editor.

To edit a script, double-click a Script in the Asset Browser panel. Once opened, the Script Editor will show up. Press Cmd + S on Mac or Ctrl + S on Windows to save the script.

You can also open your script by default in an External Editor.

Was this page helpful?
Yes
No

AI-Powered Search