Note: This documentation is for the old 0.8.0 version of A-Frame. Check out the documentation for the current 1.5.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 entites.
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).
<a-entity id="player" collider-check>
|Whether to automatically refresh raycaster’s list of objects to test for intersection using mutation observers to detect added or removed entities and components.
|Vector3 coordinate of which direction the ray should point from relative to the entity’s origin.
|0, 0, 0
|Whether raycaster is actively checking for intersections.
|Maximum distance under which resulting entities are returned. Cannot be lower then
|Number of milliseconds to wait in between each intersection test. Lower number is better for faster updates. Higher number is better for performance.
|Minimum distance over which resuilting entities are returned. Cannot be lower than 0.
|Query selector to pick which objects to test for intersection. If not specified, all entities will be tested.
|Vector3 coordinate of where the ray should originate from relative to the entity’s origin.
|0, 0, 0
|Checks all children of objects if set. Else only checks intersections with root objects.
|Whether or not to display the raycaster visually with the line component.
|Whether the raycaster origin and direction properties are specified in world coordinates.
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.
|Emitted on the intersected entity. Entity is intersecting with a raycaster. Event detail will contain
el, the raycasting entity, and
intersection, an object containing detailed data about the intersection.
|Emitted on the intersected entity. Entity is no longer intersecting with a raycaster. Event detail will contain
el, the raycasting entity.
|Emitted on the raycasting entity. Raycaster is intersecting with one or more entities. Event detail will contain
els, an array with the intersected entities, and
intersections, an array of objects containing detailed data about the intersections.
|Emitted on the raycasting entity. Raycaster is no longer intersecting with one or more entities. Event detail will contain
clearedEls, an array with the formerly intersected entities.
The event detail contains intersection objects. They are returned straight from
|distance between the origin of the ray and the intersection
|point of intersection, in world coordinates
|index of the intersected face
|indices of vertices comprising the intersected face
|the intersected object
|U,V coordinates at point of intersection
|Entities currently intersecting the raycaster.
|three.js objects to test for intersections. Will be
scene.children if not
objects property is not specified.
|three.js raycaster object.
|Refreshes the list of objects based off of the
objects property to test for intersection.
We usually don’t want to test everything in the scene for intersections (e.g., for collisions or for clicks). Selective intersections are good for performance to limit the number of entities to test for intersection since intersection testing is an operation that will run over 60 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
<a-entity raycaster="objects: .clickable" cursor></a-entity>
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
var raycasterEl = AFRAME.scenes.querySelector('[raycaster]');
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
showLine is set to
true, the raycaster will configure the line given the
far properties. To customize the line
appearance provided by the
showLine: true property, we configure the line
<a-entity raycaster="showLine: true; far: 100" line="color: orange; opacity: 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.