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:
- JavaScript
- TypeScript
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.
@component
export class NewScript extends BaseScriptComponent {
onAwake() {
print('Hello World');
}
}
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.
- JavaScript
- TypeScript
//@input float intensity = 1.0
//@input string objectName
//@input Component.AudioComponent music
//@input float[] delayTimes
@component
export class TypeScript extends BaseScriptComponent {
@input('float')
intensity: number = 1.0;
@input
objectName: string;
@input
@allowUndefined
music: AudioComponent;
@input('float[]')
delayTimes: number[];
onAwake() {}
}
In this example, we declared four script input fields:
- A
number
namedintensity
with a default value of 1.0 - A
string
namedobjectName
- A reference to an Audio Component named
music
- A
list
offloats
nameddelayTimes
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
.
- JavaScript
- TypeScript
//@input string hello = "Hello, World!"
print(script.hello);
@component
export class NewScript extends BaseScriptComponent {
@input
hello: string;
onAwake() {
print(this.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.
- JavaScript
- TypeScript
global.myMessage = 'Hello, World!';
global.sayHello = function (message) {
global.myMessage = message;
print(global.myMessage);
};
declare namespace global {
var myMessage: string;
function sayHello(message: string): void;
}
@component
export class GlobalExample extends BaseScriptComponent {
onAwake() {
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.