Untitled

📰Getting Started | ⭐**Updates |** 📝 Guides | 🔢 API | ❓FAQ

Guides Overview

This API enables you to load static copies of other experiences on top of your current one, allowing you to combine multiple experiences into a larger one!

This feature is especially helpful if you want to transfer functionality between experiences (say, a global UI experience) or if you want to break your experience down into parts so you don’t need to edit the whole thing at once.

How to Embed

In any script, call the function below. When you call it, the experience will begin to asynchronously load in the background, and it will pop up when done.

You can specify whether the embedded experience should be parented under an element or not by providing a reference in the second parameter.

const referenceToParentElement = this;

// if you want the embedded experience parented under an element
var embedId = system.experiences.embedExperience(referenceToParentElement, "experience ID");

// if you want the embedded experience instantiated at root level, without a parent
var embedId = system.experiences.embedExperience(null, "experience ID");

This function will return a unique ID at the time it is called. If you want to unload the embedded experience later, you will need to save this ID, so make sure to store it!

<aside> 💡 The embedded experience will load asynchronously, but receiving the ID as a return value will happen immediately, even if the embedded experience is not done loading yet.

</aside>

You can chain together multiple embeds of the same experience / or different ones in a row. Just make sure to keep track of all the different IDs! Each call of embedExperience will return a unique value.

How to Unload an Embed

Provided that you have saved the ID of your embed, pass it into this function and the system will unload that specific embed instance, completely destroying it.

// earlier...
var embedId = system.experiences.embedExperience(self, EXPERIENCE_ID);

// now I want to unload the experience that was embedded from the above call.
system.experiences.unloadEmbed(embedId);

If an embed is currently loading and you call unloadEmbed in the middle of it, the load will be aborted and nothing will happen.

Alternate Unload Method

If you somehow lose the ID of the embed, you can also destroy an embed by calling the function below from any element in the hierarchy of an embed:

const self = this;

self.destroyOriginalRoot();

And the entire embed will be unloaded from the root element it came from.

You don’t need to call it on the root element specifically - any element within the embed will do! You just need a concrete element reference.

<aside> ⚠️ This method may be deprecated in the future and is not recommended - keep track of your embed IDs!

</aside>

Unload all Embeds

Need to get rid of ALL experiences you embedded? No worries! Call this function:

system.experiences.unloadAllEmbeds();

Limit to Only one Embed of an Experience at a Time

Sometimes you may want to limit an experience to only one instance, say for a global manager or data storage where there should only be one active copy.

Call this function:

const referenceToParentElement = this;

// parent
system.experiences.embedExperienceIfNotLoaded(referenceToParentElement, "experience ID");

// no parent
system.experiences.embedExperienceIfNotLoaded(null, "experience ID");

If an instance of that experience is currently loaded, or is currently in the process of being loaded, you will be prevented from embedding it.

“Singleton” Override

An object that exhibits the above behavior is known as a “Singleton”, in which there can only be one instance of this object at a time.

While you can use the function above to create this behavior, you can also add a flag to experiences to globally override all.

To do this, add a boolean schema value to the experience’s Root element Advanced tab named “Singleton”:

Untitled

Untitled

If checked:

If not checked:

This is helpful if you don’t want “Singleton” specification to be left up to the script doing the embedding, and rather have it be an inherent property of the experience.

Callback on Load

If you want something to happen when an embed is done loading, write a function and pass it into these variants of the embedding functions as the final parameter:

const referenceToParentElement = this;

// also works without parent
var embedId = system.experiences.embedExperience(referenceToParentElement, "experience ID", onLoadCallback);

embedId = system.experiences.embedExperienceIfNotLoaded(referenceToParentElement, "experience ID", onLoadCallback);

// get exact embed ID, unique GUID generated for each embed instance, a reference to the root
function onLoadCallback(embedId, guid, root)
{
	log.info("loaded successfully!");
	log.info("embedId: " + embedId);
}

<aside> 💡 The root reference here is different from the usual element references you can get from self and doesn’t have any accessible parameters, but it can be passed into multiplayer.networkHierarchy. See the Multiplayer API docs.

</aside>

The embed ID will be passed into the callback function.

<aside> ⚠️ Note that the callback will be invoked when the general data load / element hierarchy creation is complete, but not necessarily when assets / scripts are done loading (in the current version).

You can guarantee that all elements will be present, but not any of the user content attached to the element.

</aside>

Permissions

Normally, you can only embed experiences that have been shared with your Enklu account.

If you would like an experience to be embeddable by anyone, mark it as Published from the sharing menu.

Experience Embedding Helper Tools

The Embedded Experience Helper Tool is a command-line program designed to interact with trellis to scrape and organize hierarchical embedded experience trees and associated asset data.

Link:

Next: Audio

Sidebar Table of Contents

Untitled