# 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.

![](/files/OmBaEEJ4wzD0XgOmXNil)

#### 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

```javascript
// 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

{% hint style="info" %}
Note: Plugins have access to a restricted version of the player API. Only supported public methods are available.
{% endhint %}

#### **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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://community.threekit.com/platform-documentation/project-data/logic/plugins.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.