Custom Touch Forwarding

Related references:

If the host page overlays its own buttons, hint layers, or guides, those layers may block clicks inside the iframe. In that case, you can forward host-layer coordinates into the scene.

The current advanced API method is:

await api.dispatchTouchEvent(x, y);

Typical Scenarios

the host layer places a transparent overlay above the iframe
you want to centralize click analytics before deciding whether the scene should also receive the click
you need custom hit-testing logic

Basic Usage

overlay.addEventListener('click', async (event) => {
  await api.dispatchTouchEvent(event.clientX, event.clientY);
});

Note: x and y should be coordinates inside the iframe, not host-page coordinates.

If the overlay and iframe have exactly the same size and position, you can pass the values directly. Otherwise you need to convert coordinates between the two spaces.

What It Actually Does

dispatchTouchEvent():

receives screen coordinates from the host page
converts them into a ray based on the iframe container size
performs one internal object hit test

So what you should pass in is iframe-page coordinates, not raw host-page coordinates.

Using It Together with Object Events

This is commonly paired with api.on('click', ...):

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

await api.on('click', ({ target }) => {
  console.log('Internal object clicked', target);
}, target);

Notes

x and y must be numbers
if the iframe container is hidden or its width or height is 0, the event will not take effect
this only forwards a click; it does not simulate a full touch gesture system

Recommendation

If you only need a few custom buttons, it is usually better to place them away from critical interaction areas. Use dispatchTouchEvent() only when the host layer really needs to take over the click chain.

Custom Touch Forwarding ​

Typical Scenarios ​

Basic Usage ​

What It Actually Does ​

Using It Together with Object Events ​

Notes ​