A-Frame

A-Frame is designed to work across a wide variety of hardware and interaction modes. Supported platforms include:

VR Experiences

• Desktop VR: Using a headset connected to a PC.
• Mobile VR: Using a mobile device with a headset.
• Standalone VR: Using standalone headsets (e.g., Meta Quest series).

Flat (Non-VR) Experiences

• Desktop Flat: Using a mouse and keyboard.
• Mobile Flat: Using a 'magic window' (device orientation/gyroscope).

Augmented Reality (AR)

• AR Headsets: e.g., Magic Leap, HoloLens.
• Mobile AR: Using 'magic window', ARKit, or ARCore.

In the Entity-Component-System (ECS) pattern, a component is a reusable, modular chunk of data used to add appearance, behavior, or functionality to an entity (a 3D object in the scene). Components encapsulate Three.js and JavaScript logic into modules that can be applied declaratively via HTML.

Components are analogous to CSS: just as CSS rules modify the appearance of HTML elements, component properties modify the appearance and behavior of entities.

A-Frame is a web framework for building virtual reality (VR) experiences. It is built on top of [three.js] and uses an Entity-Component Architecture.

This architecture provides a declarative, composable, and extensible structure where HTML elements act as entities that can be augmented with various components. This allows developers to access the full power of JavaScript, DOM APIs, and WebGL while maintaining a simple markup-based workflow.

A-Frame is built on top of [three.js]. The two scene graphs map to each other as follows:

• An <a-scene> maps one-to-one with a THREE.Scene.
• An <a-entity> maps to one or more THREE.Object3D instances (often a THREE.Group acting as a root).
• When entities are nested in A-Frame, their corresponding three.js objects follow the same parent-child hierarchy.
• Every three.js object created via A-Frame maintains a reference to its owning A-Frame entity via the .el property.

When multiple mixins (or a mixin and the entity itself) define properties for the same component, those properties are merged. For example, if one mixin defines geometry="primitive: box" and another defines geometry="height: 10", an entity using both will have a single geometry component containing both the primitive and the height.

Example of merging properties from multiple mixins and the entity itself:

<a-scene>
  <a-assets>
    <a-mixin id="box" geometry="primitive: box"></a-mixin>
    <a-mixin id="tall" geometry="height: 10"></a-mixin>
    <a-mixin id="wide" geometry="width: 10"></a-mixin>
  </a-assets>

  <a-entity mixin="wide tall box" geometry="depth: 2"></a-entity>
</a-scene>
<!-- Equivalent to: <a-entity geometry="primitive: box; height: 10; depth: 2; width: 10"></a-entity> -->

When calculating an entity's final state in the scene, A-Frame applies transformations in the following order:

1. scale
2. rotation
3. position/translation

A-Frame implements the Entity-Component-System (ECS) architecture using web standards:

• Entities: Represented by <a-entity> elements and their prototype. They are the containers for components.
• Components: Represented by HTML attributes on <a-entity>. Components are objects containing a schema, lifecycle handlers, and methods. They are registered using AFRAME.registerComponent(name, definition).
• Systems: Represented by <a-scene> attributes. Systems manage groups of entities and are registered using AFRAME.registerSystem(name, definition).

This architecture allows for highly modular and decoupled development, where components can be composed to create complex behaviors without needing to know about each other.

The highRefreshRate property attempts to switch to a higher frame rate than the browser default. This requires WebXR supportedFrameRates and updateTargetFrameRate support. Currently, this is primarily supported on the Oculus Browser.

Refresh Rate Mapping:

The tracked-controls component is the foundational base for all A-Frame controller components. It handles the low-level interaction with the WebXR/Gamepad API by:

• Grabbing a Gamepad object via an ID or prefix.
• Applying pose (position and orientation) to the entity to track motion.
• Monitoring the Gamepad object for changes to emit low-level events like axischanged, buttonchanged, buttondown, buttonup, touchstart, and touchend.

While tracked-controls provides the motion and raw input, specific controller components (like vive-controls or meta-touch-controls) build on top of it to provide semantic button mappings (e.g., triggerdown) and visual models.

Standard <iframe> elements cannot be displayed within WebGL and will not appear in VR.

To render HTML/CSS content in a scene, you must use a technique that paints to a <canvas> and uses that canvas as a texture. Community components for this include:

• aframe-html-shader
• aframe-htmlmesh

Child entities inherit the world-space position of their parents. The position value set on a child entity is relative to its parent's local coordinate system, not the world origin.

For example:

<a-entity id="parent" position="1 2 3">
  <a-entity id="child1"></a-entity>
  <a-entity id="child2" position="2 3 4"></a-entity>
</a-entity>

• #child1 has a local position of 0 0 0, resulting in a world-space position of 1 2 3.
• #child2 has a local position of 2 3 4, resulting in a world-space position of 3 5 7 (calculated by adding the parent's position to the child's local position).