Joystick

The Joystick is a component that provides a virtual, on-screen joystick for user input. Its primary output is the direction property, a vec2 vector with values from -1 to 1 representing the handle's position.

Key Features

• Configurable Behavior: Adjust the deadZone, handleSmoothingFactor, and positioning (Free or Fixed).
• Custom Visuals: Apply custom materials to the joystick's plate and handle.
• Scripting Control: Dynamically show, hide, or create the component via its API.
• Event-Driven: Subscribe to the directionUpdateEvent to react to input changes.

Installing the Component

The Joystick custom component is available in the Lens Studio Asset Library. Press Install or Update and then add it to the Asset Browser panel by clicking the + button and looking up Joystick.

Basic Setup

1. Add to Scene - Drag the Joystick component into the desired Screen Transform hierarchy.
2. Configure Position - Set Fixed if you want the joystick to stay in one place, or Free if you want it to appear where the user first touches the screen.
3. Set Interactive Area - If using Free positioning, optionally assign an Interactive Area to limit where the joystick can be activated.

Component Inputs

Property	Type	Description
renderOrder	number	Sets the render order for all visual
deadZone	number	The radius of the central area where no input is registered. Relative to plate size. The handle must be moved beyond this distance from the center to generate input.
handleSmoothingFactor	number	Controls the smoothness of the handle's movement. A lower value results in smoother, more delayed movement, while a higher value is more responsive.
enableOnStart	boolean	If true, the joystick is shown when the component starts. If false, it must be shown programmatically.
positionConfig	enum	Determines how the joystick is positioned. • Free: Appears at the user's initial touch location. • Fixed: Remains in a fixed position on the screen.
interactiveArea	InteractionComponent	(Only shown if positionConfig is Free) Constrains the Free joystick to a specific screen area. If unassigned, the joystick can be activated from anywhere.
customizeVisuals	boolean	If true, the material properties below become available to override the default appearance.
plateMaterial	Material	(Only shown if customizeVisuals is true) Sets a custom material for the joystick's background plate.
handleMaterial	Material	(Only shown if customizeVisuals is true) Sets a custom material for the joystick's handle.
duplicateMaterials	boolean	(Only shown if customizeVisuals is true) If true, the assigned materials are cloned, allowing for unique modifications at runtime without affecting other objects.

Scripting API

The Joystick component can be controlled and interacted with via its scripting API.

Static Methods

Method	Description
static create(hostingObject: SceneObject, config: JoystickConfig): Joystick	Creates a new Joystick component and adds it to the given hosting object.

Properties

Property	Type	Description
direction	vec2	Gets the current direction of the joystick. Components are in the range [-1, 1].

Methods

Method	Description
setPlateMaterial(material: Material): void	Sets the material for the joystick's plate.
setHandleMaterial(material: Material): void	Sets the material for the joystick's handle.
setRenderOrder(value: number): void	Sets the render order for all visual elements of the joystick.
getRenderOrder(): number	Gets the render order for all visual elements of the joystick.
show(withAnimation?: boolean): void	Shows the joystick. If withAnimation is true (default), appears with animation.
hide(withAnimation?: boolean): void	Hides the joystick. If withAnimation is true (default), disappears with animation.

Events

Property	Type	Description
directionUpdateEvent	EventSubscription<vec2>	An event that is triggered when the joystick's direction changes. The event payload is a vec2 representing the direction.

EventSubscription Interface:

Method	Description
add(listener: (data: T) => void): void	Adds a listener function to the event.
addOnce(listener: (data: T) => void): void	Adds a listener that is called only once.
remove(listener: (data: T) => void): void	Removes a specific listener.
listenerCount(): number	Returns the number of attached listeners.

Usage Example

This example rotates a 3D object based on joystick input.

TypeScript

import { Joystick } from 'Joystick.lsc/Joystick';

@component
export class JoystickExample extends BaseScriptComponent {
  @input
  private readonly joystick!: Joystick;
  @input
  private readonly objectToRotate!: SceneObject;

  onAwake() {
    this.joystick.directionUpdateEvent.add((direction: vec2) => {
      const direction3D = new vec3(direction.x, 0, direction.y);
      this.objectToRotate
        .getTransform()
        .setLocalRotation(quat.lookAt(direction3D, vec3.up()));
    });
  }
}

JavaScript

// @input Component.Joystick joystick
// @input SceneObject objectToRotate

script.joystick.directionUpdateEvent.add(function (direction) {
  var direction3D = new vec3(direction.x, 0, direction.y);
  script.objectToRotate
    .getTransform()
    .setLocalRotation(quat.lookAt(direction3D, vec3.up()));
});