NOTE: This version of the documentation tracks unstable development happening on A-Frame’s
masterbranch. If you wish to try it out, grab the unstable build. Otherwise, head to the documentation for the current 0.7.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).
|autoRefresh||Whether to automatically refresh raycaster’s list of objects to test for intersection using mutation observers to detect added or removed entities and components.||true|
|direction||Vector3 coordinate of which direction the ray should point from relative to the entity’s origin.||0, 0, 0|
|enabled||Whether raycaster is actively checking for intersections.||true|
|far||Maximum distance under which resulting entities are returned. Cannot be lower then
|interval||Number of milliseconds to wait in between each intersection test. Lower number is better for faster updates. Higher number is better for performance.||100|
|near||Minimum distance over which resuilting entities are returned. Cannot be lower than 0.||0|
|objects||Query selector to pick which objects to test for intersection. If not specified, all entities will be tested.||null|
|origin||Vector3 coordinate of where the ray should originate from relative to the entity’s origin.||0, 0, 0|
|recursive||Checks all children of objects if set. Else only checks intersections with root objects.||true|
|showLine||Whether or not to display the raycaster visually with the line component.||false|
|useWorldCoordinates||Whether the raycaster origin and direction properties are specified in world coordinates.||false|
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.
|raycaster-intersected||Emitted on the intersected entity. Entity is intersecting with a raycaster. Event detail will contain
|raycaster-intersected-cleared||Emitted on the intersected entity. Entity is no longer intersecting with a raycaster. Event detail will contain
|raycaster-intersection||Emitted on the raycasting entity. Raycaster is intersecting with one or more entities. Event detail will contain
|raycaster-intersection-cleared||Emitted on the raycasting entity. Raycaster is no longer intersecting with one or more entities. Event detail will contain
|intersectedEls||Entities currently intersecting the raycaster.|
|objects||three.js objects to test for intersections. Will be
|raycaster||three.js raycaster object.|
|refreshObjects||Refreshes the list of objects based off of the
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
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
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
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.