Pointer events

You can capture pointer events from the mouse or touch to interact with 3D objects in your world. This can be done with the PointerEvents service which can be injected in other services, actors or components.

Using the PointerEvents service

To use the PointerEvents service, inject it in in your game code. In the following example we do it in the game service, but you may use it in any other service or actor. The PointerEvents service has many methods to subscribe to different types of events. In the example we are simply passing in the entire scene to detect clicking on any object. However, the methods support passing in specific objects, actors or actor types.

import { GameInstance, Service, PointerEvents, inject, World } from '@hology/core/gameplay';

@Service()
class Game extends GameInstance {
  private pointerEvents = inject(PointerEvents)
  private world = inject(World)

  onStart() {
    this.pointerEvents.onClickObject3D(this.world.scene).subscribe((event) => {
      console.log("Clicked at point: ", event.intersection.point)
    })
  }
}

Events

The following events can be subscribed to.

• click - The object was clicked, meaning that the touch or mouse down event started and ended on the same object.

• pointer down - The touch or mouse down event started on the object.

• pointer up - The touch or mouse up event event ended on the object.

• pointer enter - The touch or mouse pointer was moved onto the object. This event is only emitted once until the pointer leaves the object.

• pointer leave - The touch or mouse pointer moved away from the object.

• pointer move - The touch or mouse pointer is moving over the object. The event is emitted whenever the pointer moves.

Targets

When subscribing to events you can use different targets

• Object3D - Any 3D object in the scene can be used for events.

• Actor - A specific actor instance.

• Actor type - An actor class to capture events from any instance of that type.

Methods

The following methods exist on the PointerEvents service for different types of events and targets.

• onPointerEnterObject3D

• onPointerEnterActor

• onPointerEnterActorType

• onPointerLeaveObject3D

• onPointerLeaveActor

• onPointerLeaveActorType

• onClickObject3D

• onClickActor

• onClickActorType

• onPointerDownActor

• onPointerDownActorType

• onPointerDownObject3D

• onPointerUpActor

• onPointerUpActorType

• onPointerUpObject3D

• onPointerMoveActor

• onPointerMoveActorType

• onPointerMoveObject3D

Event object

When an event happens, your callback function will receive an object containing information about the event.

• object / actor - Depending on if you are using the Object3D or Actor variant, you will receive either the object or actor that was interacted with.

• intersection - Information about the intersection of the raycast with the object.

  • distance: number - distance between the origin of the ray and the intersection

  • point: Vector3 - point of intersection, in world coordinates

  • face: Face - intersected face

  • object: Object3D - the intersected object

  • uv: Vector2 - U,V coordinates at point of intersection

  • uv2: Vector2 - Second set of U,V coordinates at point of intersection