raycaster

NOTE: This version of the documentation tracks unstable development happening on A-Frame’s master branch. If you wish to try it out, grab the unstable build. Otherwise, head to the documentation for the current 1.6.0 version

The raycaster component provides line-based intersection testing with a raycaster. Raycasting is the method of extending a line from an origin towards a direction, and checking whether that line intersects with other entities.

The raycaster component uses the three.js raycaster. The raycaster checks for intersections at a certain interval against a list of objects, and will emit events on the entity when it detects intersections or clearing of intersections (i.e., when the raycaster is no longer intersecting an entity).

We prescribe that the set of objects that the raycaster tests for intersection is explicitly defined via the objects selector property described below. Raycasting is an expensive operation, and we should raycast against only targets that need to be interactable at any given time.

The cursor component and laser-controls components both build on top of the raycaster component.

Example

<a-entity id="player" >
  <a-entity collider-check raycaster="objects: .collidable; showLine:true;" position="0 1 0"></a-entity>
</a-entity>
<a-entity class="collidable" geometry="primitive: box"  position="0 1 -3"></a-entity>

Whenever an entity adds or removes the class collidable, the raycaster will refresh its list of objects it is raycasting against.

AFRAME.registerComponent('collider-check', {
  dependencies: ['raycaster'],

  init: function () {
    this.el.addEventListener('raycaster-intersection', function () {
      console.log('Player hit something!');
    });
  }
});

Properties

Events

The raycaster component is useful because of the events it emits on entities. It will emit events on both the raycasting entity and the intersected entities.

Intersection Object

The event detail contains intersection objects. They are returned straight from three.js Raycaster.intersectObjects.:

Members

Methods

Selecting Entities to Test for Intersection

Raycasting is a relatively expensive operation. We heavily recommend and prescribe setting the objects property which will filter what entities the raycaster is listening to for intersections. Selective intersections are good for performance to limit the number of entities to test for intersection since intersection testing is an operation that many times per second.

To select or pick the entities we want to test for intersection, we can use the objects property. If this property is not defined, then the raycaster will test every object in the scene for intersection. objects takes a query selector value:

<a-entity raycaster="objects: .clickable" cursor></a-entity>
<a-entity class="clickable" geometry="primitive: box" position="1 0 0"></a-entity>
<a-entity class="not-clickable" geometry="primitive: sphere" position="-1 0 0"></a-entity>

In that example, we can remove or add entities to the raycast list by setting or removing the clickable class (el.classList.toggle('clickable')). Another good way to filter is using data attributes instead of classes ([data-raycastable] and el.setAttribute('data-raycastable', '')).

Listening for Raycaster Intersection Data Change

When we want to listen for change to the intersection data (e.g., listen to change of the actual point of intersection), we can use the .getIntersection (el) method, which takes an entity and returns intersection data if the raycaster is currently intersecting the entity. Below is an example component of doing so in the tick handler:

AFRAME.registerComponent('raycaster-listen', {
	init: function () {
    // Use events to figure out what raycaster is listening so we don't have to
    // hardcode the raycaster.
    this.el.addEventListener('raycaster-intersected', evt => {
      this.raycaster = evt.detail.el;
    });
    this.el.addEventListener('raycaster-intersected-cleared', evt => {
      this.raycaster = null;
    });
  },

  tick: function () {
    if (!this.raycaster) { return; }  // Not intersecting.

    let intersection = this.raycaster.components.raycaster.getIntersection(this.el);
    if (!intersection) { return; }
    console.log(intersection.point);
  }
});

// <a-entity id="raycaster" raycaster></a-entity>
// <a-entity geometry material raycaster-listen></a-entity>

Now on every frame, the entity will check its intersection data and do something with it (e.g., draw a sphere at the point of intersection).

Manually Refreshing the Target Entities of the Raycaster

The raycaster component keeps a local array of objects and entities that the raycaster tests against for intersection. This array defaults to every 3D object in the three.js Scene. If the objects property is specified, then building this array requires running query selectors and additional filtering.

By default with autoRefresh set to true, the raycaster component will automatically refresh this list when it detects entities or components are added and removed. While it is more friendly to auto-refresh, more advanced developers may want to disable autoRefresh and control when the raycaster is refreshed for performance.

To manually refresh the list of objects that the raycaster component tests against, call the .refreshObjects() method:

var raycasterEl = AFRAME.scenes[0].querySelector('[raycaster]');
raycasterEl.components.raycaster.refreshObjects();

A-Frame will call .refreshObjects() automatically when an entity is appended or detached from the scene, but it will not get called during normal DOM mutations (e.g., some entity changes its class).

Customizing the Line

If showLine is set to true, the raycaster will configure the line given the raycaster’s origin, direction, and far properties. To customize the line appearance provided by the showLine: true property, we can use the lineColor and lineOpacity:

<a-entity raycaster="showLine: true; far: 100; lineColor: red; lineOpacity: 0.5"></a-entity>

The line length is the raycaster’s far property when the raycaster is not intersecting any entity. By default, the far property defaults to 1000 meters meaning the line drawn will be 1000 meters long. When the raycaster intersects an object, the line will get truncated to the intersection point so it doesn’t shoot straight through.