3D Objects

Related references:

• Scene API / Object Query and Basic Properties
• Scene API / Transform Properties
• Scene API / Event Listeners

In the advanced Web API, most capabilities are centered around an "object handle".

Get an Object

The most common entry point is to fetch by name:

const obj = await api.getObject('rabbit');

If you already know the object name in the scene, this is the most direct way.

You can also retrieve all objects at once:

const objects = await api.getAllObjects();

Naming Recommendation

If you plan to manipulate objects frequently from the host page, give them clear names in the scene editor first.

A Handle Is Not a Native 3D Object

getObject() does not return an Object3D you can manipulate directly. It returns a handle that communicates across the iframe boundary.

So code like this does not work:

const obj = await api.getObject('rabbit');
obj.position.x = 1; // wrong

The correct approach is:

const obj = await api.getObject('rabbit');
await api.setPosition(obj, 1, 0, 0);

Basic Properties

Name

const name = await api.getObjectName(obj);

await api.setObjectName(obj, 'rabbit-main');

Visibility

const visible = await api.getObjectVisible(obj);

await api.setObjectVisible(obj, !visible);

Render Order

// Read the current render order
const renderOrder = await api.getRenderOrder(obj);

// Set the current render order
await api.setRenderOrder(obj, 10);

This is useful when you need one object to stay more reliably in front of others.

Disable Click

// Check whether clicking is disabled
const isDisableClick = await api.getDisableClick(obj);

// Disable clicking
await api.setDisableClick(obj, true);

This prevents the object from being clicked.

Transform Properties

Position

const [x, y, z] = await api.getPosition(obj);

await api.setPosition(obj, x, y + 0.2, z);

Rotation

const [x, y, z, order] = await api.getRotation(obj);

// Note: the values are radians, not degrees
await api.setRotation(obj, 0, Math.PI / 2, 0, 'YXZ');

Quaternion

const [x, y, z, w] = await api.getQuaternion(obj);

await api.setQuaternion(obj, 0, 0, 0, 1);

Scale

const [x, y, z] = await api.getScale(obj);

await api.setScale(obj, 1.2, 1.2, 1.2);

Look at a Point

await api.lookAt(obj, 0, 0, 0);

Get Size

const [width, height, depth] = await api.getSize(obj);

The size comes from a runtime bounding-box calculation, which makes it useful for layout decisions, hit-area estimation, and dynamic scaling.

Traverse Child Objects

const children = await api.getChildren(obj);

const mesh = await api.getChildByProperty(obj, 'name', 'rabbit-head');

This set of APIs is especially useful for glTF models, because their materials, events, and other behavior often need to be applied to internal child nodes.

Object Events

You can listen for object-level events. Current support includes:

• click - fires when the object is clicked. Event bubbling is supported. Because of asynchronous behavior, stopping propagation is not currently supported.

Supported object types: all 3D object types.

const obj = await api.getObject('rabbit');

function onClick(event) {
  const { type, name, object, target } = event;
  // type - click
  // name - the name of the clicked child 3D object, or the object itself
  // object - the handle of the clicked child 3D object, or the object itself
  // target - the object currently listening for the click event
  // The click event bubbles upward through parents until the root scene.
}

await api.on('click', onClick, obj);

• play - fires when audio, video, animation, or animated images start playing

Supported object types: video, model, animated image, and audio.

const obj = await api.getObject('rabbit');

function onPlay(event) {
  // Different object types and different media play types expose different info fields.
  const { type, target, ...info } = event;
}

await api.on('play', onPlay, obj);

• pause - fires when audio, video, animation, or animated images pause

Supported object types: video, model, animated image, and audio.

const obj = await api.getObject('rabbit');

function onPause(event) {
  const { type, target, ...info } = event;
}

await api.on('pause', onPause, obj);

• ended - fires when audio, video, animation, or animated images finish naturally

Supported object types: video, model, animated image, and audio.

const obj = await api.getObject('rabbit');

function onEnded(event) {
  const { type, target, ...info } = event;
}

await api.on('ended', onEnded, obj);

• replay - fires when video, animation, or animated images replay

Supported object types: video, model, animated image, and audio.

const obj = await api.getObject('rabbit');

function onReplay(event) {
  const { type, target, ...info } = event;
}

await api.on('replay', onReplay, obj);

• plus some object-specific events. See the event notes under each object type for details.

Recommended Pattern

In real projects, a reliable approach is:

1. wait for loadSceneEnd or sceneStart
2. get object handles with getObject() or getAllObjects()
3. cache those handles in host-layer state
4. drive all later updates through the API