Basic Structures

The following examples will guide you through the essential steps of plugin creation. For a deeper dive, we invite you to check out our educational plugins on Github. These are designed to provide a hands-on learning experience and serve as inspiration for your own creations.

Before you get started, take a look at Building Plugins to learn more about implemeting the core files needed for plugins, such as a module.json

Building Core Services

1. In your plugin’s main directory, create a subfolder for your core service. Add the standard module.json file to the folder, as well as to create a main.js file. Your file structure should look like this now:

• 📁 ModuleDir
  • 📁 PluginA
    • 📄 module.json
    • 📄 main.js

2. In main.js, import CoreService from the "LensStudio:CoreService" module.

import CoreService from "LensStudio:CoreService"

3. Extend the CoreService class and populate the descriptor. Add any required startup logic to the constructor.

import CoreService from 'LensStudio:CoreService';

export class ExampleCoreService extends CoreService {
  static descriptor() {
    return {
      id: 'Com.Snap.ExampleCoreService',
      interfaces: CoreService.descriptor().interfaces,
      name: 'This is an example core service',
      description: 'No details',
      dependencies: [Editor.Model.IModel],
    };
  }

  constructor(pluginSystem) {
    super(pluginSystem);
  }
  start() {
    const model = this.pluginSystem.findInterface(Editor.Model.IModel);
  }

  stop() {}
}

4. Add logic to start( ) and stop( ).

• start( ) : void: Called when Lens Studio launches and the service starts running.
• stop( ) : void: Called when the core service terminates, i.e., Lens Studio closes or the core service is disabled from the Plugins Preferences.

When you make a change to your plugin scripts, disable and re-enable the plugin in the Plugins Preferences for the change to take effect in Lens Studio.

For a more flushed out example, checkout the example plugins repository on Github.

Building Presets

1. In your PluginsDirectory folder, create a subfolder for your preset. Add the standard module.json file to the folder. Additionally, create a main.js file.

2. In main.js, import Preset from LensStudio:Preset.

   import Preset from 'LensStudio:Preset';

3. Extend the Preset class and populate the descriptor. Add any required startup logic to the constructor.

import Preset from 'LensStudio:Preset';

export class ExamplePreset extends Preset {
  static descriptor() {
    return {
      id: 'Com.Company.ExamplePreset',
      interfaces: Preset.descriptor().interfaces,
      name: 'Example Preset',
      description: 'This is an example preset',
      icon: Editor.Icon.fromFile(import.meta.resolve('icon.svg')),
      section: 'General',
      entityType: 'Component',
    };
  }
  constructor(pluginSystem) {
    super(pluginSystem);
  }
  create(destination) {
    //...
  }
}

import.meta.url is part of the native JS spec with regards to finding the url location of a module. Learn more here.

4. Add logic to create(destination) or createAsync(destination).

• create(destination) : Entity: Called when a user adds the preset to the Scene Hierarchy, Asset Browser, or Inspector from the + menu.

You should return the newly created Entity from this function. For Component type of presets, return the newly added component instance. For SceneObject type of presets, return the newly created SceneObject instance. For Asset type of presets, return the imported Asset instance. If for any reason nothing is created, return null.

The destination parameter will be evaluated depending on the entityType parameter in the descriptor function. The table below outlines the current expected preset behavior for each entityType:

entityType	Destination type	Menu preset is added to	Behavior when preset is added to project
Asset, or derived type. See LS Docs	Editor.Path	Asset Browser + menu	Asset is added to the Asset Browser panel, depending on the destination value the asset will be placed under different directories.
Component, or derived type. See LS Docs	SceneObject	Inspector panel + menu and + Add Component menu	The component is added to the selected destination Scene Object.
SceneObject	SceneObject | null	Scene Hierarchy + menu	The destination scene object is the selected scene object when the action is executed. Thus it could be null. The developer is responsible to create any new Scene Object that might be needed for subsequent operations.

• async createAsync (destination) : Entity: In some cases, you might need to use the asynchronous version of the create function, such as when you are importing a texture for use in a material. In these situations, you should leverage the createAsync method and use keywords like async or await to handle the asynchronous operation properly.

async createAsync(destination) {
    //assume we have saved the reference to pluginSystem in the constructor
    const model = this.pluginSystem.findInterface(Editor.Model.IModel);
    const assetManager = model.project.assetManager;
    return assetManager.importExternalFileAsync(absolutePath, destination, Editor.Model.ResultType.Packed);
}

Building Panel & Dialog

import PanelPlugin from "LensStudio:PanelPlugin";
import * as Ui from "LensStudio:Ui";

export class MyPanel extends PanelPlugin {

    static descriptor () {
        id: "Com.example.name",
        interfaces: PanelPlugin.descriptor().interfaces,
        name: "Name",
        description: "Your description text",
        dependencies: [Ui.IGui]
    }

    constructor(pluginSystem){
        super(pluginSystem);
    }

    createWidget(parentWidget){
        const widget = Ui.Widget.create(parent);

        //...

        return widget;
    }
}

Permissions

Some APIs will require permissions.

Below is a list of the LensStudio: module-based APIs that you may import, along with the permission categories that need to be specified in the module.json file if you intend to use them.

Module	Description	Permission(s) required
LensStudio:FileSystem	Enables interactions and modifications to the file system.	filesystem
LensStudio:Subprocess	Enables spawning of child processes.	subprocess
LensStudio:Network	Enables making HTTP network requests and receiving responses.	network
LensStudio:RemoteServiceModule	Enables access to the Snapchat authentication token of the current user.	[network, snap_auth_token]
LensStudio:AssetLibrary	Enables access to the asset library.	asset_library
LensStudio:App	View information about the application, such as the app version.	None
LensStudio:Serialization	Ability to serialize data from various formats (currently YAML) into Lens Studio's internal format used by various components (e.g. DockManager).	None
LensStudio:Shell	Ability to integrate with desktop applications, such as opening an URL from the default browser.	shell
LensStudio:Ui	Enable accessing the UI namespace which includes functions and classes for creating and utilizing UI widgets and layouts. It is a must-have if your plugins work with widgets and UI elements.	None
LensStudio:AssetUtils.js*	Provides utility functions for managing assets, creating materials, and handling textures. Includes functions for finding/creating assets and working with shader graphs.	None
LensStudio:HierachyUtils.js*	Provides utility functions for managing scene hierarchy, including searching for objects, managing cameras, and handling scene object creation/manipulation.	None
LensStudio:GeneralUtils.js*	Provides general utility functions.	None

* Available from Lens Studio 5.3 onwards.