Object Lifecycle Management

Related reference: Scene API / Object Hierarchy and Lifecycle

Objects created at runtime are not only about "create and show". You also need to distinguish when they enter the scene, when they are removed, and when they are truly destroyed.

Four Core Actions

createXxx

const image = await api.createImage(arrayBuffer);

All createXxx() methods are object-creation APIs. The exact method name depends on the object type. See Dynamic Content Creation for details.

add

Add a newly created object to the current scene so it becomes visible:

await api.add(image);

Objects returned by createXxx() are not visible immediately, so they all need one add() call.

Visibility can also be controlled with the object's visible property through api.setObjectVisible().

remove

Remove the object from the current scene tree without releasing the underlying resources, making it invisible:

await api.remove(image);

This means video, animation, and similar resources may continue running even though they are no longer visible.

This is useful for temporary hiding or re-parenting.

destroyObject

Fully destroy the object and release its resources:

await api.destroyObject(image);

Once destroyed, the previously saved handle can no longer be used. It is a good idea to remove it from your own state immediately.

remove() vs destroyObject()

Method	Removed from scene	Releases resources	Can be added again
remove()	Yes	No	Yes
destroyObject()	Yes	Yes	No

If you still plan to reuse the object later, prefer remove(). If you are sure it is no longer needed, use destroyObject().

clear

Remove and destroy all objects in the current scene:

await api.clear();

This is rarely needed and is a very dangerous operation. It invalidates every object handle you have already obtained.

If you only want to destroy the objects you created at runtime, store that list yourself and run remove() / destroyObject() only for those objects.

A Simple Host-Layer Wrapper

let dynamicObjects = [];

async function addObject(handle) {
  await api.add(handle);
  dynamicObjects.push(handle);
}

async function removeObject(handle) {
  await api.remove(handle);
  dynamicObjects = dynamicObjects.filter(o => o !== handle);
}

async function destroyAllDynamicObjects() {
  while (dynamicObjects.length) {
    const handle = dynamicObjects.pop();
    await api.remove(handle);
    await api.destroyObject(handle);
  }
}

Recommended Cleanup Timing

When the Host Page Is Being Destroyed

When the host page itself is about to unmount:

1. clean up any object events you registered
2. destroy dynamic objects
3. close the iframe last

When Switching Scenes

If you repeatedly open different sceneId values in the same iframe:

• do not reuse object handles from the old scene
• do not reuse advanced API objects from the old scene

Parent / Child Management

Add a Child Object

const group = await api.createGroup();
const image = await api.createImage(arrayBuffer);

await api.add(group);
// Add image to the child list of group.
// Since group is already in the scene tree, image does not need another api.add call.
await api.addChild(group, image);

Any 3D object can have child objects, including cameras, images, videos, and models.

Audio is not a 3D object, so it cannot be added as a child.

Remove a Child Object

await api.removeChild(group, image);

Get the Child List

const children = await api.getChildren(obj); // Array