Skip to main content
Version: 5.x

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 Asset

With our Scene Object ready, we can now prepare a Script Asset.

To learn more about Script Assets, visit the Scripting Introduction.

Create a Script Asset

In the Asset Browser panel, select + -> JavaScript.

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 Asset Browser panel. This will open up the Script Editor.

External Editor

To open your script in an external editor, click on your script in the Asset Browser panel and press Open in 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 Bounce from under the Project Components category.

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 Script Input Fields

Script Input Fields 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 inputs. Note that the Inspector panel view reflects the default values defined in the script.

To learn more about script input fields, visit the Script Introduction page.

Create Property Widgets

It's possible to create a custom Inspector interface for your Script Component inputs. This is especially useful when you have inputs that need tuning.

In the case of the Bounce script, it would be handy to adjust the speed and range inputs 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 inputs definitions:

function bounce() {
// 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));
}

Bind Script to Event

Because we bound this script to the Frame Updated event, this code will run every frame, adding an incremental change in position to the Scene Object's transform.

var updateEvent = script.createEvent('UpdateEvent');
updateEvent.bind(bounce);

To learn more about the lifecycle of script events, visit the Script Events page.

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
// 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}

function bounce() {
var newY = Math.sin(getTime() * script.speed) * script.range;
script
.getSceneObject()
.getTransform()
.setLocalPosition(new vec3(0, newY, 0));
}

var updateEvent = script.createEvent('UpdateEvent');
updateEvent.bind(bounce);
Was this page helpful?
Yes
No

AI-Powered Search