Events (for API)

Overview

Events enable two-way communication between your embedded 3D project and your website through the Model API.

With Events, your website can:

• Send data to the scene — trigger interactions, update variables, control behavior

• Receive data from the scene — react to user actions, track state changes

Events are configured in Interactions (Interact mode):

• Event listener trigger — receives events from your website

• Send event action — sends events to your website

┌─────────────────────┐                              ┌─────────────────────┐
│                     │                              │                     │
│    Your Website     │    dispatchEvent("name")     │   Vectary Scene     │
│                     │  ──────────────────────────► │                     │
│                     │     Trigger: Event listener  │                     │
│                     │                              │                     │
│                     │    addEventListener("name")  │                     │
│                     │  ◄────────────────────────── │                     │
│                     │     Action: Send event       │                     │
│                     │                              │                     │
└─────────────────────┘                              └─────────────────────┘

Event names must be unique — duplicate names are not allowed, even across different interaction types.

How Events Carry Values

Events and Variables are connected by name. Understanding this link is essential:

Direction	How values work
Website → Scene	The value you send with dispatchEvent("name", value) is stored in a Variable called name
Scene → Website	The Send event action transmits the current value of a Variable with the same name

Example: If you have an event called price and a Variable called price with value 99, when the scene sends this event, your website receives 99.

If no Variable with a matching name exists, the event sends undefined.

Receiving Events from the Scene

To send data from the scene to your website:

1. In Studio (Interact mode):

• Create a Variable (e.g., selected_color with value "red")

• Create an Interaction:

  • Trigger: On click → your object

  • Action: Send event → selected_color

2. In your code:

api.addEventListener("selected_color", (value) => {
  console.log(value); // "red"
});

The event fires when the trigger condition is met (e.g., user clicks the object).

Sending Events to the Scene

To send data from your website to the scene:

1. In Studio (Interact mode):

• Create an Interaction:

  • Trigger: Event listener → width

  • Action: Whatever should happen (Transform, Set variable, Play animation, etc.)

2. In your code:

api.dispatchEvent("width", 150);

The value 150 is automatically stored in a Variable called width, making it available in expressions.

Debugger

The Debugger lets you test events directly in Studio without writing code. It simulates API calls from your website.

To use the Debugger:

1. Enter Preview mode

2. Open the Debugger tab (appears if at least one event exists)

3. Enter a value for any event

4. Click the radio button to dispatch it

The Debugger also displays all Variable values and updates in real-time — useful for verifying your Interactions work correctly.

Embed code

Once you create an event, the Share popup automatically generates ready-to-use code.

The generated code includes:

• iframe embed with your project

• API initialization

• addEventListener() calls for events used in Send event actions

• dispatchEvent() calls for events used in Event listener triggers

<iframe
  id="VECTARY_EMBED_ID"
  src="https://app.beta.vectary.com/p/{model_id}"
  frameborder="0"
  width="100%"
  height="480"
></iframe>

<script type="module">
  import { VctrModelApi } from "https://app.beta.vectary.com/studio-lite/scripts/api.js";
  const modelApi = new VctrModelApi("VECTARY_EMBED_ID");
  await modelApi.init();

  // Example of listening to events sent from Vectary
  modelApi.addEventListener("event_name_1", value => { 
    console.log(value);
  });

  // Example of sending an event to Vectary
	modelApi.dispatchEvent('event_name_2', 'hello');
</script>

To update the code, synchronize the project in Share popup

For further details, refer to the Model API docs.