Script Modules

Script Modules allow you to encapsulate code to use throughout your project.

Script Modules are especially useful when combining functionality abstracted from scene objects. Since a module isn't used as a regular script in a script component, it doesn't have access to the script property, which is available when a script is added to a scene object. Modules do have access to the global scene object.

One of the advantages of using modules instead of regular scripts is that a module, once required, becomes immediately available. That means there is no need to respect the initialization order of the script components, which is required if you want to get access to a script component's properties from another script component.

Syntax

Script Modules in Lens Studio use CommonJS syntax. Export a module using module.exports and import a module using the require function.

Creating a Module

To create a module, define the module.exports object in a ScriptAsset:

MathModule.js

function sum(a, b) {
  return a + b;
}
module.exports = sum;

To specify the module.exports object's properties, either explicitly define the object:

MathModule.js

function sum(a, b) {
  return a + b;
}

function diff(a, b) {
  return a - b;
}

module.exports = {
  sum: sum,
  diff: diff,
};

Or define the properties of the exports object directly:

MathModule.js

module.exports.sum = sum;
module.exports.diff = diff;

Or define an entire prototype of a JavaScript object:

MathModule.js

function String(sourceString) {
  this.source = sourceString;
}

String.prototype.push = function (character) {
  this.source = this.source + character;
  return this.source;
};

String.prototype.pop = function () {
  this.source = this.source.slice(0, -1);
  return this.source;
};

module.exports = String;

To turn an existing ScriptAsset into a module, add the module.exports object definition which specifies the data you intend to export:

ExistingModule.js

// ScriptAsset data
// …
module.exports = {...} // The exported data

Using a Module

Require a module to use it in other scripts:

Script.js

const math = require(“./MathModule”);
var result = math.sum(1, 2); // Calculates the sum of the given digits
print(result); // Result: 3

It is possible to omit the “./” prefix, along with any other path prefix, since Lens Studio only uses the filename. Including the path prefix allows external script editors to support autocompletion of the requested module's properties.

In this case, the math variable receives the exports object defined in MathModule.js. Required modules are shown in the Inspector panel:

Module scripts should not be added to scene objects as script components. Modules are project resources and should only be stored as resources.

Lens Studio treats all modules as if they are in one folder. While you can organize the modules of a project by placing them in different folders, you only need to reference their names in order to access them.

For example, in the image above, ModuleA and ModuleB are stored in different folders, but they're accessed the same way:

Script.js

const moduleA = require(“./ModuleA”);
const moduleB = require(“./ModuleB”);

Follow this syntax to access a specific property of a module's exported object:

const sum = require(./“MathModule”).sum;
const diff = require(./“MathModule”).diff;

Avoid cyclic requirements. Cyclic require occurs when module B requires module A and module A, in turn, requires module B. Cyclic require is not allowed in Lens Studio.

In general, don't design your module to execute logic upon the module's request. It's better practice to keep logic in the form of functions and objects that are explicitly used after the module's request.

A required module will execute once after it has been required for the first time.

Limitations

Script modules cache differently than other exports. When a module is required, it's not cached like in other environments. For example, “require.cache” is not available in Lens Studio.

Asset Library Modules

We've prepared some useful modules in the Asset Library.

External Modules

Requiring modules is standard practice for development in JavaScript. That means Lens Studio allows for general purpose external modules not limited to Lens development. Keep in mind that some modules might not fit the Lens development process. For example, some modules could be designed to work with file systems and other platform dependent features. Others could be written in non-CommonJS syntax.