Scripting Example
Introduction
This guide will walk you through the process of creating a simple script in Lens Studio. You'll learn how to create a Script resource, connect your script to a Scene Object using the Script Component, and finally trigger the script from a Lens Event.
The script you create in this guide will add an oscillating bounce movement to a 3D object.
Related Guides
This walk-through touches on concepts from the following guides:
Project Setup
To follow this guide, you'll need to set up a Lens Studio project that has a Scene Object with a Mesh Visual
component. You can use any mesh you like.
Prepare the Script Resource
With our Scene Object ready, we can now prepare a Script Resource.
To learn more about Script Resources, visit the Scripting Overview.
Create a Script Resource
In the Resources
panel, select + -> Script
.
Give the newly created script a name that describes what the script does. Rename it to Bounce
.
Open the Script
You can open the Bounce
script in either Lens Studio's internal editor, or the external text editor of your choice.
Internal Editor
To open your script in the built-in Lens Studio editor, double-click your Script in the Resources
panel. This will open up the Script Editor.
External Editor
To open your script in an external editor, click on your script in the Resources
panel and in your Inspector
panel, press Open In > Open External Editor
.
Connect the Script
Scripts in Lens Studio are triggered by assigning them to Events on a Script Component.
Add the Script Component
Select your Scene Object.
In the Inspector
panel, select Add Component -> Script
.
Select the Script Resource
On the Script Component you just added, select Add Script
.
In the selection dialog that pops up, select the Bounce
script you created earlier.
Using the Script
component's event dropdown, Set the Bounce script's event to Frame Updated
.
Write the Script
We can now write the code for our project. This code will continuously bounce a 3D object up and down.
This section breaks down each part of the script's code. The completed script is provided at the end of this guide.
Define the Properties
Properties are variables used by a script that can be edited live in the Lens Studio Inspector
panel.
For this script, we will define two properties:
speed
: (float) The speed at which the object will bouncerange
: (float) The range of the object's bounce
Add the following line to your script:
//@input float speed = 1.0
//@input float range = 10.0
The Script Component you added to your Scene Object should now be updated with these two properties. Note that the Inspector
panel view reflects the default values defined in the script.
To learn more about properties, visit the Scripting Overview
Create Property Widgets
It's possible to create a custom Inspector interface for your Script Component properties. This is especially useful when you have properties that need tuning.
In the case of the Bounce script, it would be handy to adjust the speed
and range
properties of the bouncing motion using sliders.
To create the custom UI, update the property definitions in your script as follows:
//@input float speed = 1.0 {"widget": "slider", "min": 0, "max": 10.0, "step": 0.01}
//@input float range = 10.0 {"widget": "slider", "min": 0, "max": 30.0, "step": 0.01}
You should now see the speed
and range
properties represented as sliders in the Inspector
panel.
To learn more about the different UI elements you can add to Script Components, visit the Custom Script UI guide.
Complete the Script
Let's complete the script. Add the following code to your Bounce script, below the property definitions:
// Calculate the new height of the Scene Object and store it in newY.
var newY = Math.sin(getTime() * script.speed) * script.range;
// Set the new local position of the Scene Object to [0, newY, 0].
script
.getSceneObject()
.getTransform()
.setLocalPosition(new vec3(0, newY, 0));
Because we bound this script to the Frame Updated
event in the Inspector, this code will run every frame, adding an incremental change in position to the Scene Object's transform.
Preview the Lens
Press the Refresh button in the Preview
panel to reload the scene. You should now see the Scene Object bouncing up and down in the Preview
panel.
Completed Script: Bounce.js
Here's the completed Bounce.js
script.
// Bounce.js
// Event: Frame Updated
// Properties:
//@input float speed = 1.0 {"widget": "slider", "min": 0, "max": 10.0, "step": 0.01}
//@input float range = 10.0 {"widget": "slider", "min": 0, "max": 30.0, "step": 0.01}
var newY = Math.sin(getTime() * script.speed) * script.range;
script
.getSceneObject()
.getTransform()
.setLocalPosition(new vec3(0, newY, 0));