Skip to main content
Version: 4.55.1

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.

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.

Script Editor

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 bounce
  • range: (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.

Script Editor


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));
Was this page helpful?
Yes
No

AI-Powered Search