Best Practices

Use the Yeoman Generator

You can use the Yeoman Generator to accelerate your plugin development process. The generator will generate the necessary files as well as boilerplate code to help you get started.

Utils Modules

Starting from Lens Studio 5.3, we introduced the Utils Modules, which include a set of high-level utility functions and assets that significantly simplify common tasks such as creating materials, importing images as textures, and creating or finding specific components or scene objects in the hierarchy. They are divided into three categories: AssetUtils, HierarchyUtils, and GeneralUtils. You can import them into your plugin like this:

import * as AssetUtils from 'LensStudio:AssetUtils.js';
import * as HierarchyUtils from 'LensStudio:HierarchyUtils.js';
import * as GeneralUtils from 'LensStudio:GeneralUtils.js';

Check out the official API site for the provided functions and examples.

Sharing Resources Between Your Plugins

Accessing resources or code from another plugin that is not part of a tightly coupled group (where one module.json represents a single plugin entity) is strongly discouraged. This practice creates dependencies among plugins. Given that the Plugin Manager permits the individual activation or deactivation of plugins, these loose dependencies can cause unpredictable behavior if any referenced plugin is not available.

In cases where you are exporting multiple plugins through a single module.json, these plugins can be seen as tightly coupled. You might want to share resources or code between these plugins. Alternatively, in some cases, you may want to break your plugins into smaller reusable components, or have a floating utility directory that gets used by all of the tightly coupled plugins.

For example, when creating a Render Mesh Visual, you might want to use the Uber PBR material preset. You can do this by importing the preset, and then creating an instance of it, passing in this.pluginSystem as its argument.

import { UberPBRMaterialPreset } from '../../Assets/UberPBRMaterial/UberPBRMaterial.js';
export function createRenderMeshVisualComponent(model, destinationObject) {
  const renderMeshVisualComponent =
    destinationObject.addComponent('RenderMeshVisual');
  const pbrMaterialPreset = new UberPBRMaterialPreset(this.pluginSystem);
  const pbrMaterial = pbrMaterialPreset.create(destination);
  renderMeshVisualComponent.materials = [pbrMaterial];
  return renderMeshVisualComponent;
}

When calling a function outside of the plugin class, you can use apply to pass in the this object:

create(destination) {
    //assume we have saved the reference to pluginSystem in the constructor
    const model = this.pluginSystem.findInterface(Editor.Model.IModel)
    return createRenderMeshVisualComponent.apply(this, [model, destination])
}

In many cases, it might also make sense to just expose some functions that multiple plugins can call, without calling the plugin itself!

Explicitly Holding References in Plugin Systems

In plugin systems, references to objects must be explicitly held to prevent them from being garbage collected when they go out of scope. This is a fundamental difference compared to web JavaScript environments. Failing to hold references will result in the object being destroyed, and no exceptions will be thrown.

Below are a few examples of explicitly holding references to avoid unexpected behaviors.

setTimeout and setInterval

A common scenario where this issue arises is when using setTimeout or setInterval. In plugin scripting, if a setTimeout is created without holding the reference, the returned Timeout object will be garbage collected when the code runs out of scope. This effectively kills the timer and prevents the callback from being executed. To avoid this, ensure that you hold the reference to the Timeout object.

{
    constructor() {
        const myTimeout = setTimeout(() => {
            console.log("Hello World!");
        }, 100);

        // The Timeout object must be saved
        // You can either save it to the plugin instance:
        this.myTimeout = myTimeout;
    }
}

UI Events and Connections

The same logic applies when working with UI events, such as click events (technically, Editor.Connection). To prevent the listeners from being destroyed, save the event or connection object in an instance-scoped variable.

{
    constructor() {
        this.connections = \[\];
    }

    createWidget(parent) {
        const connection = button.onClick.connect(() => {
            //do something...
        });

        //save the reference of the new connection event.
        this.connections.push(connection);
    }
}

TCP Sockets

When establishing a TCP client connection to a TCP server, it is crucial to store the returned Socket object. A common practice is to store the Socket object in an array that lives in the instance scope.

this.sockets = [];
this.server.onConnect.connect((socket) => {
  this.sockets.push(socket);
});

This is by no means an exhaustive list of cases when explicitly holding references are needed. By understanding and applying these concepts, you can ensure that your plugin system operates correctly and avoids unexpected behavior caused by premature garbage collection of important objects and references.