Plugins

Overview

Plugins provide a flexible way to extend and customize player behavior using custom JavaScript that can be attached to Items or Assets. Unlike custom scripts which run only when configurations change, Plugins respond to player lifecycle events such as when the player or scene is loaded. This makes them compatible with Static Publishing and better suited for advanced use cases like animations, scene manipulation, and deeper player interactions.

Plugins:

• Run when specific player events are triggered

• Execute only if the subscribed event occurs

• Can be reused across multiple Items and Assets

• Are compatible with Static Publishing

Plugins are created and managed through the platform UI, similar to other reusable logic components.

---

When to Use Plugins

Use Plugins when:

• Logic needs to run on player or scene load

• Behavior depends on lifecycle events

• Animations or scene manipulation are required

• Functionality should be reused across multiple Items or Assets

Use custom scripts when:

• Logic is tied to configuration changes

• Scene manipulation is needed

In general:

• Plugins → event-driven, player-level behavior

• Custom Scripts → configuration-driven logic

---

How Plugins Work

Plugins operate by registering event handlers that are triggered by the player at specific lifecycle moments.

At a high level:

1. The plugin is loaded with the player

2. The plugin registers handlers for specific events

3. The player emits those events during execution

4. The plugin logic runs in response

Plugins run independently of rule evaluation, which allows them to execute consistently and regardless of whether Static Publishing is enabled.

---

Creating a Plugin

Plugins are created and managed in the platform and can be attached to Items or Assets.

Registering Hooks

Use api.hook() to register a handler:

api.hook('eventName', handler);

• eventName: lifecycle event

• handler: function executed when the event fires

Handlers can be synchronous or asynchronous.

Basic Example

// Plugin code runs once when initialized
// Receives api: { assetId, player, callApi, hook }

// Register hook handlers using api.hook()
api.hook('loaded', () => {
  console.log('Asset loaded: ', api.assetId);
  console.log('Received data: ', api.player);
  // Perform side effects, no return value needed
});

In this example:

• The plugin listens for the loaded event

• When triggered, the handler runs the custom logic

Note: Plugins have access to a restricted version of the player API. Only supported public methods are available.

Built-in Hook Points

Hook	When Called
loaded	After scene graph evaluation completes

---

Plugin Behavior

• Event handlers are triggered only when the hook event is emitted

• Handlers execute sequentially in the order they were registered

• Each handler receives the same event data and is awaited before the next runs

• If a handler fails, other handlers will still run

• Multiple plugins can run for the same Asset, and their handlers are scoped to that Asset only

• If the same plugin is associated with the Item and Asset, it will execute once per association

• Plugins are automatically cleaned up when the associated Asset is unloaded