Note: This documentation is for the old 0.2.0 version of A-Frame. Check out the documentation for the current 0.5.0 version
The cursor component defines interaction with other entities through clicking and gazing, by using the raycaster component to determine which object has been clicked. When the mouse is clicked, the closest visible entity intersecting the cursor will have a DOM
click event triggered. Note the cursor component only defines the behavior. To define the appearance, you might apply the geometry component.
For example, we define a cursor in the shape of a ring positioned on the center of the screen. To have the cursor fixed on the screen, we place it as a child of a camera entity. Whenever the cursor clicks on the cube, we can listen the the click event. This might feel familiar to web developers.
|fuse||Whether cursor should also be fuse-based.||false on desktop, true on mobile|
|maxDistance||Maximum distance to check for intersections on entities for clicks.||5|
|timeout||How long to wait (in milliseconds) to trigger a click event if fuse-based.||1500|
The cursor will add states to the cursor entity on certain events.
|fusing||Added when the cursor is fusing on another entity.|
|hovering||Added when the cursor is hovering over another entity.|
The cursor will add states to the target entity on certain events.
|hovered||Added when target entity is being hovered by the cursor.|
|click||Triggered when an entity is clicked.|
|mousedown||Triggered on mousedown of the canvas.|
|mouseup||Triggered on mouseup of the canvas.|
If the cursor is set to be fuse-based, the cursor will trigger a click if the user gazes at one entity for a set amount of time. Imagine a laser strapped to the user’s head, and the laser extends out into the scene. After the timeout, whatever entity the laser intersects first will be clicked.
Fuse-based interactions can feel natural for VR and do not require any additional input devices other than the headset.
To add visual feedback to the cursor in order to display indication when the cursor is clicking or fusing, we can use the animation system. When the cursor adds a state to the entity, the animation system will pick up added state with the
begin attribute and play.
To play with an example of a cursor with visual feedback, check out the Cursor with Visual Feedback example on Codepen.
The raycaster currently picks up non-visible entities. This issue will be addressed in a later release.