controllers

The controllers component provides a complete system for VR controller interaction in A-Frame scenes. It automatically creates and manages left and right hand controllers with raycasters, visual cursors, and event handling for all controller buttons.

Example

Below is an example of adding controllers to a scene. The controllers will automatically appear when using a compatible VR headset with controllers.

<a-scene>
  <!-- Add them to a rig entity -->
  <a-entity id="rig" position="0 1.6 0" controllers="
    leftColor: #03FCC6;
    rightColor: #018A6C;
    cursorSize: 0.01;
    raycastLength: 10
  ">
    <a-camera></a-camera>
  </a-entity>
  
  <!-- Interactive objects will respond to controller events -->
  <a-box position="0 1.5 -5" color="#03FCC6" vr-interactive></a-box>
</a-scene>

Props

Property	Type	Default	Description
leftEnabled	boolean	true	Whether to enable the left controller
rightEnabled	boolean	true	Whether to enable the right controller
leftColor	color	#cfc7c6	Color of the left controller ray and cursor
rightColor	color	#cfc7c6	Color of the right controller ray and cursor
cursorSize	number	0.01	Size of the cursor sphere at the end of the ray (in meters)
raycastLength	number	10	Maximum length of the controller raycast (in meters)

Controller Events

The component forwards controller button events to intersected objects. Any object with class "interactive" or "clickable" can receive these events:

Event	Description
triggerdown	Fired when trigger button is pressed
triggerup	Fired when trigger button is released
gripdown	Fired when grip button is pressed
gripup	Fired when grip button is released
abuttondown	Fired when A button is pressed (right hand)
abuttonup	Fired when A button is released
bbuttondown	Fired when B button is pressed (right hand)
bbuttonup	Fired when B button is released
xbuttondown	Fired when X button is pressed (left hand)
xbuttonup	Fired when X button is released
ybuttondown	Fired when Y button is pressed (left hand)
ybuttonup	Fired when Y button is released
menudown	Fired when menu button is pressed
menuup	Fired when menu button is released
trackpaddown	Fired when trackpad/thumbstick is pressed
trackpadup	Fired when trackpad/thumbstick is released

Usage Tips

Making Objects Interactive

For advanced interactivity with visual feedback and custom event handling, consider using the vr-interactive component:

<!-- Basic vr-interactive usage -->
<a-entity 
  geometry="primitive: box" 
  material="color: blue"
  vr-interactive
></a-entity>

<!-- Customized vr-interactive with specific button handling -->
<a-entity
  geometry="primitive: sphere"
  material="color: green"
  vr-interactive="
    enabledButtons: trigger, grip;
    highlightColor: #FFFF00;
    scaleOnClick: 0.8;
  "
></a-entity>

For more basic event handling, you can use A-Frame's event system:

<a-entity id="myObject" class="interactive" 
          geometry="primitive: box" 
          material="color: blue"
          event-set__triggerdown="_event: triggerdown; material.color: yellow"
          event-set__triggerup="_event: triggerup; material.color: blue">
</a-entity>