Touch

Galacean's touch is based on Pointer, which smooths out the differences between Mouse and Touch, making touch unified in both concept and interface.

Pointer

In Galacean, whether it's a mouse on a PC, a stylus or a finger on a mobile device, when it performs the corresponding behavior within the touch range (Down, Move, etc.), it will be instantiated as a Pointer. You can get all the currently active touch points in the InputManager.

It should be noted that each touch point is independent of each other, they respond to the corresponding events and callback the corresponding hook functions.

Lifecycle

Each touch point will start its life in PointerDown or PointerMove, and leave the stage in PointerLeave or PointerCancel. In Galacean, you can get the real-time status of this touch point through Pointer.phase.

Touch Buttons

Referring to the W3C standard and Microsoft related documentation, Galacean defines touch buttons as follows:

Combining touch buttons can easily detect the behavior of touch points triggered in this frame:

Touch Callbacks

You only need to add touch callbacks to an Entity with a Collider component to enable interaction with rendered objects. Touch callbacks are integrated into the engine's script lifecycle, allowing users to easily add the following events. The hook functions will carry the Pointer instance that triggered the callback.

⚠️ Touch callbacks depend on the physics engine. Please ensure the physics engine is initialized before using this feature.

Example:

• The leftmost cube responds to Enter and Exit events, changing color when the mouse moves over it and when the mouse leaves.
• The middle cube responds to Drag events, allowing you to drag the cube anywhere in space with the mouse.
• The rightmost cube responds to Click events (first down, then up), changing color when the mouse clicks on it.

Raycasting

Touch callbacks are implemented based on raycasting. Customizing raycasting is also very simple, just follow these steps.

Refer to Collider Component for adding a collider component. The code logic for implementing the detection part is as follows:

// 假设当前有一个活动的触控点
const pointer = inputManager.pointers[0];
// 通过触控点得到由相机发射的射线
const ray = camera.screenPointToRay(pointer.position, new Ray());
// 射线与场景的碰撞体进行碰撞检测
const hitResult = new HitResult();
if (scene.physics.raycast(ray, 100, hitResult)) {
  console.log("Hit entity", hitResult.entity);
}

The following example provides a more intuitive understanding of this process. The main camera is equipped with auxiliary lines, and the side view camera can fully observe the process of the main camera's raycasting detecting the collider.

Compatibility

As of February 2024, the compatibility of PointerEvent across different platforms has reached 96.35%.

Design ideas can be referenced at: https://github.com/galacean/engine/wiki/Input-system-design.

⚠️ If you encounter compatibility issues on a platform, you can raise an issue at https://github.com/galacean/polyfill-pointer-event.

QA

Touch works fine on PC but behaves abnormally on mobile devices

On mobile devices, touch interactions trigger the default behavior of HTML elements. Once the default behavior is triggered, the touch interaction is removed from the element (PointerCancel). This can be resolved by setting the touchAction of the listening source. If the listening source is the default canvas:

(engine.canvas._webCanvas as HTMLCanvasElement).style.touchAction = "none";

Right-click operation fails, context menu pops up

This is caused by the default behavior triggered by the right-click. You can add the following code to prevent it:

document.oncontextmenu = (e) => {
  e.preventDefault();
};