# Technical Documentation: aframevr/aframe > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/aframevr/aframe) ### Overview (README.md)

A-Frame

A web framework for building browser based 3D, AR and VR experiences.

Site — Docs — Examples — School — Community

## Examples

*Find more examples on [the homepage](https://aframe.io), [A Week of A-Frame](https://aframe.io/blog/), and [WebVR Directory](https://webvr.directory).* ## Features :eyeglasses: **Virtual Reality Made Simple**: A-Frame handles the 3D and WebXR boilerplate required to get running across platforms including mobile, desktop, and all headsets (compatible with a WebXR capable browser) just by dropping in ``. :heart: **Declarative HTML**: HTML is easy to read and copy-and-paste. Since A-Frame can be used from HTML, A-Frame is accessible to everyone: web developers, VR and AR enthusiasts, educators, artists, makers, kids. :electric_plug: **Entity-Component Architecture**: A-Frame is a powerful framework on top of three.js, providing a declarative, composable, reusable entity-component structure for three.js. While A-Frame can be used from HTML, developers have unlimited access to JavaScript, DOM APIs, three.js, WebXR, and WebGL. :zap: **Performance**: A-Frame is a thin framework on top of three.js. Although A-Frame uses the DOM, A-Frame does not touch the browser layout engine. Performance is a top priority, being battle-tested on highly interactive WebXR experiences. :globe_with_meridians: **Cross-Platform**: Build VR and AR applications for any headset compatible with a WebXR capable browser. Don't have a headset or controllers? No problem! A-Frame still works on standard desktop and smartphones. :mag: **Visual Inspector**: A-Frame provides a built-in visual 3D inspector with a workflow similar to a browser's developer tools and interface similar to Unity. Open up any A-Frame scene and hit ` + + i`. :runner: **Features**: Hit the ground running with A-Frame's built-in components such as geometries, materials, lights, animations, models, raycasters, shadows, positional audio, tracked controllers. Get even further with community components such as particle systems, physics, multiuser, oceans, mountains, speech recognition, or teleportation! ## Usage ### Example Build VR and AR scenes in the browser with just a few lines of HTML! To start playing and publishing now, remix the starter example on: [](https://glitch.com/~aframe) ```html

``` With A-Frame's [entity-component architecture](https://aframe.io/docs/1.8.0/introduction/entity-component-system.html), we can drop in community components from the ecosystem (e.g., ocean, physics) and plug them into our objects straight from HTML: [See example](https://aframe.io/aframe/examples/docs/community-components/) ```html

``` ### Builds To use the latest stable build of A-Frame, include [`aframe.min.js`](https://aframe.io/releases/1.8.0/aframe.min.js): ```js ``` To check out the stable and master builds, see the [`dist/` folder](dist/). ### npm ```sh npm install --save aframe # Or yarn add aframe ``` ```js import AFRAME from 'aframe'; // e.g., with Webpack or Vite. ``` ## Local Development ```sh git clone https://github.com/aframevr/aframe.git # Clone the repository. cd aframe && npm install # Install dependencies. npm start # Start the local development server. ``` And open in your browser [http://localhost:8080](http://localhost:8080). If you want to test the examples in VR, you need to run it with https: ```sh npm run start:https ``` Look at the "On Your Network (IPv4)" line in the console, and copy and paste the url to https://hmd.link service. Then open the browser in your headset and type hmd.link in the address bar then click on the copied url that will show up if you're connected to the same network as your machine. You will see a message about the page being dangerous because we're using a self-signed certificate, you can ignore that warning and continue to the page. ### Generating Builds ```sh npm run dist ``` ## Questions For questions and support, [ask on StackOverflow](https://stackoverflow.com/questions/ask/?tags=aframe). ## Stay in Touch - Hang out with the [community](https://aframe.io/community/) - [Follow @aframevr on X](https://x.com/aframevr). And get in touch with the maintainers! - [Diego Marcos](https://x.com/dmarcos) - [Don McCurdy](https://x.com/donrmccurdy) - [Kevin Ngo](https://x.com/andgokevin) ## Contributing Get involved! Check out the [Contributing Guide](CONTRIBUTING.md) for how to get started. You can also support development by [buying a gorgeous A-Frame t-shirt with exclusive designs](https://cottonbureau.com/products/a-frame-og#/9479538/tee-men-standard-tee-vintage-black-tri-blend-s) ## License This program is free software and is distributed under an [MIT License](LICENSE). --- ### Introduction Index (`docs/introduction/index.md`) --- title: Introduction section_title: Introduction type: introduction layout: docs order: 1 parent_section: docs section_order: 1 installation: true examples: - title: Hello, World! src: https://glitch.com/edit/#!/aframe?path=index.html --- [three.js]: https://threejs.org ## Getting Started [glitch]: http://glitch.com/~aframe A-Frame can be developed from a plain HTML file without having to install anything. A great way to try out A-Frame is to **[remix the starter example on Glitch][glitch]**, an online code editor that instantly hosts and deploys for free. Alternatively, create an `.html` file and include A-Frame in the ``: ```html

``` [Installation]: ./installation.md [school]: https://aframe.io/school/ The [Installation] page provides more options for getting started with A-Frame. To get started learning A-Frame, check out [A-Frame School][school] for visual step-by-step lessons to complement the documentation. ## What is A-Frame? [github]: https://github.com/aframevr/ [community]: https://aframe.io/community/ :a:-Frame is a web framework for building virtual reality (VR) experiences. A-Frame is based on top of HTML, making it simple to get started. But A-Frame is not just a 3D scene graph or a markup language; the core is a powerful entity-component framework that provides a declarative, extensible, and composable structure to [three.js]. Originally conceived within Mozilla and now maintained by the co-creators of A-Frame within [Supermedium](https://supermedium.com), A-Frame was developed to be an easy yet powerful way to develop VR content. As an [independent open source project][github], A-Frame has grown to be one of the [largest VR communities][community]. A-Frame supports most VR and AR devices such as Meta Quest, Apple Vision Pro, PICO lineup, Lynx-R1 or Valve Index Although A-Frame supports the whole spectrum, A-Frame aims to define fully immersive interactive VR experiences that go beyond basic 360° content, making full use of positional tracking and controllers.

## Features :eyeglasses: **VR Made Simple**: Just drop in a `

## Integration with the 2D Page Embedded scenes can be visually integrated and can interact with the rest of the 2D page. Some things we could do: - Use CSS `z-index` to put an HTML element above or under the scene - Use a transparent `` or no background to overlay `` on top of the page, with underlying HTML elements visible - Use interaction with HTML elements (e.g., buttons, forms) to affect the scene ## Using I-Frames Only one `` can exist on a page. Alternatively, we can use an ` ## Where Does A-Frame Want to Take WebXR? A-Frame aims for highly immersive and interactive VR content with native-like performance. For this, A-Frame believes the minimum viable bar will trend towards positionally-tracking headsets with positionally-tracked controllers. This is the paradigm in which A-Frame wants to innovate as well as discover new grounds that are specific to the VR Web (e.g., link traversal, decentralization, identity). Contrast this type of content against flat and static 360° content and menus. At the same time, A-Frame wants everyone to be able to get involved with VR content creation. A-Frame supports all major headsets with their controllers. Fortunately with the large community and contributors, A-Frame is able to both look far towards the future as well as satisfy the needs of today's VR landscape. ## Which Platforms Does A-Frame Support? A-Frame supports almost all platforms through browsers. General platforms that A-Frame supports include: - VR on desktop with a headset - VR on mobile with a headset - VR on standalone headset - Flat on desktop (i.e., mouse and keyboard) - Flat mobile (i.e., magic window) Some other platforms that have been shown to work with A-Frame include: - Augmented reality (AR) on AR headsets (e.g., Magic Leap, HoloLens) - Augmented reality (AR) on mobile (i.e., magic window, ARKit, ARCore) ## Which VR Headsets Does A-Frame Support? A-Frame supports most headsets through browsers. Some VR headsets that A-Frame supports include: - HTC Vive - Oculus Rift - Meta Quest - Meta Quest 2 - Meta Quest 3 - Meta Quest Pro - Oculus Go - Valve Index - Vive Focus - Apple Vision Pro For general hardware recommendations (not requirements): - [Oculus Rift Hardware Recommendations](https://www.oculus.com/en-us/oculus-ready-pcs/) - [HTC Vive Hardware Recommendations](https://www.vive.com/us/ready/) - For smartphones, an iPhone 6 for iOS and at least a Galaxy S6 for Android ## Which Browsers Does A-Frame Support? A-Frame supports VR for any browser that implements the [WebXR specification][w3c], and flat 3D for most browsers. Large browser vendors are slowly moving to the WebXR specification, though it does not have much front-facing changes to A-Frame developers, involving mostly renaming of APIs. - Firefox - Oculus Browser - Samsung Internet - Microsoft Edge - Chrome (WebXR under origin trials) - Exokit (experimental early support) [webvrpolyfill]: https://github.com/googlevr/webvr-polyfill A-Frame supports most modern mobile browsers that don't have WebXR support through the [WebVR polyfill][webvrpolyfill]. Note that these browsers do not have official WebXR support, and we are using a polyfill; it is important to lower the expectations that these browsers will provide a quality experience and not have quirks: - Safari for iOS - Chrome for Android - Firefox for iOS - Samsung Internet - UC Browser For flat or plain 3D support, A-Frame supports all modern browsers, specifically those that support WebGL including: - Firefox - Chrome - Safari - Edge - Internet Explorer 11 --- ### Introduction Writing A Component (`docs/introduction/writing-a-component.md`) --- title: Writing a Component type: introduction layout: docs parent_section: introduction order: 8 examples: [] --- [component]: ../core/component.md [ecs]: ../introduction/entity-component-system.md [emit]: ./javascript-events-dom-apis.md#emitting-an-event-with-emit Components of A-Frame's [entity-component framework][ecs] are JavaScript modules that can be mixed, matched, and composed onto entities to build appearance, behavior, and functionality. We can register component in JavaScript and use it declaratively from the DOM. Components are configurable, reusable, and shareable. Most code in an A-Frame application should live within components. [vehicleimage]: https://cloud.githubusercontent.com/assets/674727/21803890/0d44f0c2-d6e1-11e6-8b4f-7fb14c05a492.jpg ![vehicleimage] Image by Ruben Mueller from vrjump.de This guide will take it pretty slow. We recommend skimming over the [Component API documentation][component] before going through this guide as that documentation will be more concise. Note that components should be defined before `` like: ```html ``` [learning]: #learning-through-components-in-ecosystem We'll go over examples on writing components. The examples will do mostly trivial things, but will demonstrate data flow, API, and usage. To see examples of non-trivial components, see the [Learning Through Components in Ecosystem section][learning]. ## Example: `hello-world` Component [init]: ../core/component.md#init Let's start with the most basic component to get a general idea. This component will log a simple message once when the component's entity is attached using the [`.init()` handler][init]. ### Registering the Component with `AFRAME.registerComponent` Components are registered with `AFRAME.registerComponent()`. We pass the name of the component, which will be used as the HTML attribute name in the component's representation in the DOM. Then we pass the **component definition** which is a JavaScript object of methods and properties. Within the definition, we can define **lifecycle handler methods**. One of which is [`.init()`][init], which is called once when the component is first plugged into its entity. In the example below, we just have our `.init()` handler log a simple message. ```js AFRAME.registerComponent('hello-world', { init: function () { console.log('Hello, World!'); } }); ``` ### Using the Component from HTML Then we can use our `hello-world` component declaratively as an HTML attribute. ```html

``` Now after the entity is attached and initialized, it will initialize our `hello-world` component. The wonderful thing about components is that they are called only after the entity is ready. **We don't have to worry about waiting for the scene or entity to set up**, it'll just work! If we check the console, `Hello, World!` will be logged once after the scene has started running and the entity has attached. ### Using the Component from JS Another way to set a component, rather than via static HTML, is to set it programmatically with `.setAttribute()`. The scene element can take components too, let's set our `hello-world` component on the scene programmatically: ```js document.querySelector('a-scene').setAttribute('hello-world', ''); ``` ## Example: `log` Component Similar to the `hello-world` component, let's make a `log` component. It'll still only just do `console.log`, but we'll make it able to `console.log` more than just `Hello, World!`. Our `log` component will log whatever string its passed in. We'll find out how to pass data to components by defining configurable properties via the schema. ### Defining Properties with the Schema The **schema** defines the **properties** of its component. As an analogy, if we think of a component as a function, then a component's properties are like its function arguments. A property has a name (if the component has more than one property), a default value, and a **property type**. Property types define how data is parsed if its passed as a string (i.e., from the DOM). For our `log` component, let's define a `message` property type via the `schema`. The `message` property type will have a `string` property type and have a default value of `Hello, World!`: ```js AFRAME.registerComponent('log', { schema: { message: {type: 'string', default: 'Hello, World!'} }, // ... }); ``` ### Using Property Data from a Lifecycle Handler The `string` property type doesn't do any parsing on the incoming data and will pass it to the lifecycle method handlers as is. Now let's `console.log` that `message` property type. Like the `hello-world` component, we write a `.init()` handler, but this time we won't be logging a hardcoded string. The component's property type values are available through `this.data`. So let's log `this.data.message`! ```js AFRAME.registerComponent('log', { schema: { message: {type: 'string', default: 'Hello, World!'} }, init: function () { console.log(this.data.message); } }); ``` [inlinecss]: http://webdesign.about.com/od/beginningcss/qt/tipcssinlinesty.htm Then from HTML, we can attach the component to an entity. For a multi-property component, the syntax is the same as [inline css styles][inlinecss] (property name/value pairs separated by `:` and properties separated by `;`): ```html

``` ### Handling Property Updates So far, we've been using just the `.init()` handler which is called only once at the beginning of the component lifecycle with only its initial properties. But components often have their properties updated dynamically. We can use the `.update()` handler to handle property updates. [methodsimage]: https://cloud.githubusercontent.com/assets/674727/21803913/2966ba7e-d6e1-11e6-9179-8acafc87540c.jpg ![methodsimage] Lifecycle method handlers. Image by Ruben Mueller from vrjump.de To demonstrate this, we'll have our `log` component only log whenever its entity [emits an event][emit]. First, we'll add an `event` property type that specifies which event the component should listen on. ```js // ... schema: { event: {type: 'string', default: ''}, message: {type: 'string', default: 'Hello, World!'}, }, // ... ``` [addeventlistener]: ./javascript-events-dom-apis.md#adding-an-event-listener-with-addeventlistener Then we'll actually move everything from our `.init()` handler to our `.update()` handler. The `.update()` handler is also called right after `.init()` when the component is attached. Sometimes, we have most of our logic in the `.update()` handler so we can initialize *and* handle updates all at once without repeating code. What we want to do is [add an event listener][addeventlistener] that will listen to the event before logging a message. If the `event` property type is not specified, we'll just log the message: ```js AFRAME.registerComponent('log', { schema: { event: {type: 'string', default: ''}, message: {type: 'string', default: 'Hello, World!'} }, update: function () { var data = this.data; // Component property values. var el = this.el; // Reference to the component's entity. if (data.event) { // This will log the `message` when the entity emits the `event`. el.addEventListener(data.event, function () { console.log(data.message); }); } else { // `event` not specified, just log the message. console.log(data.message); } } }); ``` [remove an event listener]: ./javascript-events-dom-apis.md#removing-an-event-listener-with-removeeventlistener Now that we've added our event listener property, let's handle an actual property update. When the `event` property type changes (e.g., as a result of `.setAttribute()`), we need to remove the previous event listener, and add a new one. But to [remove an event listener], we need a reference to the function. So let's first store the function on `this.eventHandlerFn` whenever we attach an event listener. When we attach properties to the component via `this`, they'll be available throughout all the other lifecycle handlers. ```js AFRAME.registerComponent('log', { schema: { event: {type: 'string', default: ''}, message: {type: 'string', default: 'Hello, World!'} }, init: function () { // Closure to access fresh `this.data` from event handler context. var self = this; // .init() is a good place to set up initial state and variables. // Store a reference to the handler so we can later remove it. this.eventHandlerFn = function () { console.log(self.data.message); }; }, update: function () { var data = this.data; var el = this.el; if (data.event) { el.addEventListener(data.event, this.eventHandlerFn); } else { console.log(data.message); } } }); ``` Now that we have the event handler function stored. We can remove the event listener whenever the `event` property type changes. We want to only update the event listener when the `event` property type changes. We do this by checking `this.data` against the `oldData` argument provided by the `.update()` handler: ```js AFRAME.registerComponent('log', { schema: { event: {type: 'string', default: ''}, message: {type: 'string', default: 'Hello, World!'} }, init: function () { var self = this; this.eventHandlerFn = function () { console.log(self.data.message); }; }, update: function (oldData) { var data = this.data; var el = this.el; // `event` updated. if (data.event !== oldData.event) { // Remove the previous event listener, if it exists. if (oldData.event) { el.removeEventListener(oldData.event, this.eventHandlerFn); } // Add listener for new event, if it exists. if (data.event) { el.addEventListener(data.event, this.eventHandlerFn); } } if (!data.event) { console.log(data.message); } } }); ``` Now let's test our component with an updating event listener. Here's our scene: ```html

``` Let's have our entity [emit the event][emit] to test it out: ```js var el = document.querySelector('a-entity'); el.emit('anEvent'); // >> "Hello, Metaverse!" ``` Now let's update our event to test the `.update()` handler: ```js var el = document.querySelector('a-entity'); el.setAttribute('log', {event: 'anotherEvent', message: 'Hello, new event!'}); el.emit('anotherEvent'); // >> "Hello, new event!" ``` ### Handling Component Removal [remove]: ./javascript-events-dom-apis.md#removing-a-component-with-removeattribute Let's handle the case where the [component unplugs from the entity][remove] (i.e., `.removeAttribute('log')`). We can implement the `.remove()` handler which is called when the component is removed. For the `log` component, we remove any event listeners the component attached to the entity: ```js AFRAME.registerComponent('log', { schema: { event: {type: 'string', default: ''}, message: {type: 'string', default: 'Hello, World!'} }, init: function () { var self = this; this.eventHandlerFn = function () { console.log(self.data.message); }; }, update: function (oldData) { var data = this.data; var el = this.el; if (oldData.event && data.event !== oldData.event) { el.removeEventListener(oldData.event, this.eventHandlerFn); } if (data.event) { el.addEventListener(data.event, this.eventHandlerFn); } else { console.log(data.message); } }, /** * Handle component removal. */ remove: function () { var data = this.data; var el = this.el; // Remove event listener. if (data.event) { el.removeEventListener(data.event, this.eventHandlerFn); } } }); ``` Now let's test out the remove handler. Let's remove the component and check that emitting the event no longer does anything: ```html

``` ```js var el = document.querySelector('a-entity'); el.removeAttribute('log'); el.emit('anEvent'); // >> Nothing should be logged... ``` ### Allowing Multiple Instances of a Component [multiple]: ../core/component.md#multiple Let's allow having multiple `log` components attached to the same entity. To do so, we enable [multiple instancing with the `.multiple` flag][multiple]. Let's set that to `true`: ```js AFRAME.registerComponent('log', { schema: { event: {type: 'string', default: ''}, message: {type: 'string', default: 'Hello, World!'} }, multiple: true, // ... }); ``` The syntax for an attribute name for a multiple-instanced component has the form of `__`, a double-underscore with an ID suffix. The ID can be whatever we choose. For example, in HTML: ```html

``` Or from JS: ```js var el = document.querySelector('a-entity'); el.setAttribute('log__helloworld', {message: 'Hello, World!'}); el.setAttribute('log__metaverse', {message: 'Hello, Metaverse!'}); ``` Within the component, if we wanted, we can tell between different instances using `this.id` and `this.attrName`. Given `log__helloworld`, `this.id` would be `helloworld` and `this.attrName` would be the full `log__helloworld`. And there we have our basic `log` component! ## Example: `box` Component [usingthree]: ./developing-with-threejs.md For a less trivial example, let's find out how we can add 3D objects and affect the scene graph by writing a component that [uses three.js][usingthree]. To get the idea, we'll just make a basic `box` component that creates a box mesh with both geometry and material. [geometry]: ../components/geometry.md [material]: ../components/material.md [boximage]: https://cloud.githubusercontent.com/assets/674727/20326452/b7f94966-ab3d-11e6-95e1-47cabf425278.jpg ![boximage] Image by Ruben Mueller from vrjump.de **Note:** this is just a 3D equivalent of writing a `Hello, World!` component. A-Frame provides [geometry][geometry] and [material][material] components if we actually wanted to make a box in practice. ### Schema and API Let's start with the schema. The schema defines the API of your component. We'll make the `width`, `height`, `depth`, and `color` configurable through the properties. The `width`, `height`, and `depth` will be number types (i.e., floats) with a default of 1 meter. The `color` type will have a color type (i.e., a string) with a default of gray: ```js AFRAME.registerComponent('box', { schema: { width: {type: 'number', default: 1}, height: {type: 'number', default: 1}, depth: {type: 'number', default: 1}, color: {type: 'color', default: '#AAA'} } }); ``` Later, when we use this component via HTML, the syntax will look like: ```html

``` ### Creating the Box Mesh [mesh]: https://threejs.org/docs/index.html#Reference/Objects/Mesh [threegeometry]: https://threejs.org/docs/index.html#Reference/Geometries/BoxGeometry [threematerial]: https://threejs.org/docs/index.html#Reference/Materials/MeshStandardMaterial [setobject3d]: ./developing-with-threejs.md#setting-an-object3d-on-an-entity Let's create our three.js box mesh from the `.init()`, and we'll later let the `.update()` handler handle all the property updates. To create a box in three.js, we'll create a [`THREE.BoxGeometry`][threegeometry]. Generators such as `BoxGeometry` now create a BufferGeometry. See the [three.js manual](https://threejs.org/manual/#en/custom-buffergeometry) to learn about creating a custom `BufferGeometry`. (The less-performant `Geometry` class is not available in recent versions of three.js nor A-Frame.) We'll also need a [`THREE.MeshStandardMaterial`][threematerial], and finally a [`THREE.Mesh`][mesh]. Then we set the mesh on our entity to add the mesh to the three.js scene graph [using `.setObject3D(name, object)`][setobject3d]: ```js AFRAME.registerComponent('box', { schema: { width: {type: 'number', default: 1}, height: {type: 'number', default: 1}, depth: {type: 'number', default: 1}, color: {type: 'color', default: '#AAA'} }, /** * Initial creation and setting of the mesh. */ init: function () { var data = this.data; var el = this.el; // Create geometry. this.geometry = new THREE.BoxGeometry(data.width, data.height, data.depth); // Create material. this.material = new THREE.MeshStandardMaterial({color: data.color}); // Create mesh. this.mesh = new THREE.Mesh(this.geometry, this.material); // Set mesh on entity. el.setObject3D('mesh', this.mesh); } }); ``` Now let's handle updates. If the geometry-related properties (i.e., `width`, `height`, `depth`) update, we'll just recreate the geometry. If the material-related properties (i.e., `color`) update, we'll just update the material in place. To access the mesh to update it, we use `.getObject3D('mesh')`. ```js AFRAME.registerComponent('box', { schema: { width: {type: 'number', default: 1}, height: {type: 'number', default: 1}, depth: {type: 'number', default: 1}, color: {type: 'color', default: '#AAA'} }, init: function () { var data = this.data; var el = this.el; this.geometry = new THREE.BoxGeometry(data.width, data.height, data.depth); this.material = new THREE.MeshStandardMaterial({color: data.color}); this.mesh = new THREE.Mesh(this.geometry, this.material); el.setObject3D('mesh', this.mesh); }, /** * Update the mesh in response to property updates. */ update: function (oldData) { var data = this.data; var el = this.el; // If `oldData` is empty, then this means we're in the initialization process. // No need to update. if (Object.keys(oldData).length === 0) { return; } // Geometry-related properties changed. Update the geometry. if (data.width !== oldData.width || data.height !== oldData.height || data.depth !== oldData.depth) { el.getObject3D('mesh').geometry = new THREE.BoxGeometry(data.width, data.height, data.depth); } // Material-related properties changed. Update the material. if (data.color !== oldData.color) { el.getObject3D('mesh').material.color = new THREE.Color(data.color); } } }); ``` ### Removing the Box Mesh Lastly, we'll handle when the component or entity is removed. In this case, we'll want to remove the mesh from the scene. We can do so with the `.remove()` handler and `.removeObject3D(name)`: ```js AFRAME.registerComponent('box', { // ... remove: function () { this.el.removeObject3D('mesh'); } }); ``` And that wraps up the basic three.js `box` component! In practice, a three.js component would do something more useful. Anything that can be accomplished in three.js can be wrapped in an A-Frame component to make it declarative. So check out the three.js features and ecosystem and see what components you can write! ## Example: `follow` Component Let's write a `follow` component where we tell one entity to follow another. This will demonstrate the use of the `.tick()` handler which adds a continuously running behavior that runs on every frame of the render loop to the scene. This will also demonstrate relationships between entities. ### Schema and API First off, we'll need a `target` property that specifies which entity to follow. A-Frame has a `selector` property type to do the trick, allowing us to pass in a query selector and get back an entity element. We'll also add a `speed` property (in m/s) to tell specify how fast the entity should follow. ```js AFRAME.registerComponent('follow', { schema: { target: {type: 'selector'}, speed: {type: 'number'} } }); ``` Later, when we use this component via HTML, the syntax will look like: ```html

``` ### Creating a Helper Vector Since the `.tick()` handler will be called on every frame (e.g., 90 times per second), we want to make sure its performant. One thing we don't want to do is be creating unnecessary objects on each tick such as `THREE.Vector3` objects. That would help lead to garbage collection pauses. Since we'll need to do some vector operations using a `THREE.Vector3`, we'll create it once in the `.init()` handler so we can later reuse it: ```js AFRAME.registerComponent('follow', { schema: { target: {type: 'selector'}, speed: {type: 'number'} }, init: function () { this.directionVec3 = new THREE.Vector3(); } }); ``` ### Defining a Behavior With the `.tick()` Handler Now we'll write the `.tick()` handler so the component continuously moves the entity towards its target at the desired speed. A-Frame passes in the global scene uptime as `time` and time since the last frame as `timeDelta` into the `tick()` handler, in milliseconds. We can use the `timeDelta` to calculate how far the entity should travel towards the target this frame, given the speed. To calculate the direction the entity should head in, we subtract the entity's position vector from the target entity's position vector. We have access to the entities' three.js objects via `.object3D`, and from there the position vector `.position`. We store the direction vector in the `this.directionVec3` we previously allocated in the `init()` handler. Then we factor in the distance to go, the desired speed, and how much time has passed since the last frame to find the appropriate vector to add to the entity's position. We translate the entity with `.setAttribute` and in the next frame, the `.tick()` handler will be run again. The full `.tick()` handler is below. `.tick()` is great because it allows an easy way to hook into the render loop without actually having a reference to the render loop. We just have to define a method. Follow along below with the code comments: ```js AFRAME.registerComponent('follow', { schema: { target: {type: 'selector'}, speed: {type: 'number'} }, init: function () { this.directionVec3 = new THREE.Vector3(); }, tick: function (time, timeDelta) { var directionVec3 = this.directionVec3; // Grab position vectors (THREE.Vector3) from the entities' three.js objects. var targetPosition = this.data.target.object3D.position; var currentPosition = this.el.object3D.position; // Subtract the vectors to get the direction the entity should head in. directionVec3.copy(targetPosition).sub(currentPosition); // Calculate the distance. var distance = directionVec3.length(); // Don't go any closer if a close proximity has been reached. if (distance < 1) { return; } // Scale the direction vector's magnitude down to match the speed. var factor = this.data.speed / distance; ['x', 'y', 'z'].forEach(function (axis) { directionVec3[axis] *= factor * (timeDelta / 1000); }); // Translate the entity in the direction towards the target. this.el.setAttribute('position', { x: currentPosition.x + directionVec3.x, y: currentPosition.y + directionVec3.y, z: currentPosition.z + directionVec3.z }); } }); ``` ## Learning Through Components in Ecosystem There are a large number of components in the ecosystem, most of them open source on GitHub. One way to learn is to browse the source code of other components to see how they're built and what use cases they provide for. Here are a few places to look: [corecomponents]: https://github.com/aframevr/aframe/tree/master/src/components [paintercomponents]: https://github.com/aframevr/a-painter/tree/master/src/components [weekofaframe]: https://aframe.io/blog/ [officialsite]: https://aframe.io/ [community]: https://aframe.io/community/ [npmcomponents]: https://www.npmjs.com/search?q=keywords:aframe&page=1&ranking=optimal [aframetwitter]: https://twitter.com/aframevr/ - [A-Frame core components][corecomponents] - Source code of A-Frame's standard components. - [A-Painter components][paintercomponents] - Application-specific components for A-Painter. - [**A Week of A-Frame** Weekly Series][weekofaframe] - [Official Site][officialsite] - [Community][community] - [Components on npm][npmcomponents] - [Twitter][aframetwitter] ## Publishing a Component [angle]: https://www.npmjs.com/package/angle Many components in practice will be application-specific or one-off components. But if you wrote a component that could be useful to the community and is generalized enough to work in other applications, you should publish it! For a component template, we recommend using [`angle`][angle]. `angle` is a command-line interface for A-Frame; one of its features is to set up a component template for publishing to GitHub and npm and also to be consistent with all the other components in the ecosystem. To install the template: ```sh npm install angle && angle initcomponent ``` `initcomponent` will ask for some information like the component name to get the template set up. Write some code, examples, and documentation, and publish to GitHub and npm! --- ### Primitives A Box (`docs/primitives/a-box.md`) --- title: section_title: Primitives type: primitives layout: docs parent_section: docs order: 1 section_order: 5 source_code: src/extras/primitives/primitives/meshPrimitives.js --- The box primitive creates shapes such as boxes, cubes, or walls. ## Example ```html

``` ## Attributes | Attribute | Component Mapping | Default Value | | -------- | ----------------- | ------------- | | alpha-test | material.alphaTest | 0 | | ambient-occlusion-map | material.ambientOcclusionMap | None | | ambient-occlusion-map-intensity | material.ambientOcclusionMapIntensity | 1 | | ambient-occlusion-texture-offset | material.ambientOcclusionTextureOffset | 0 0 | | ambient-occlusion-texture-repeat | material.ambientOcclusionTextureRepeat | 1 1 | | anisotropy | material.anisotropy | 0 | | blending | material.blending | normal | | color | material.color | #FFF | | depth | geometry.depth | 1 | | depth-test | material.depthTest | true | | depth-write | material.depthWrite | true | | displacement-bias | material.displacementBias | 0.5 | | displacement-map | material.displacementMap | None | | displacement-scale | material.displacementScale | 1 | | displacement-texture-offset | material.displacementTextureOffset | 0 0 | | displacement-texture-repeat | material.displacementTextureRepeat | 1 1 | | dithering | material.dithering | true | | emissive | material.emissive | #000 | | emissive-intensity | material.emissiveIntensity | 1 | | env-map | material.envMap | None | | flat-shading | material.flatShading | false | | height | geometry.height | 1 | | mag-filter | material.magFilter | linear | | material-fog | material.fog | true | | material-visible | material.visible | true | | metalness | material.metalness | 0 | | metalness-map | material.metalnessMap | None | | metalness-texture-offset | material.metalnessTextureOffset | 0 0 | | metalness-texture-repeat | material.metalnessTextureRepeat | 1 1 | | min-filter | material.minFilter | linear-mipmap-linear | | normal-map | material.normalMap | None | | normal-scale | material.normalScale | 1 1 | | normal-texture-offset | material.normalTextureOffset | 0 0 | | normal-texture-repeat | material.normalTextureRepeat | 1 1 | | offset | material.offset | 0 0 | | opacity | material.opacity | 1 | | repeat | material.repeat | 1 1 | | roughness | material.roughness | 0.5 | | roughness-map | material.roughnessMap | None | | roughness-texture-offset | material.roughnessTextureOffset | 0 0 | | roughness-texture-repeat | material.roughnessTextureRepeat | 1 1 | | segments-depth | geometry.segmentsDepth | 1 | | segments-height | geometry.segmentsHeight | 1 | | segments-width | geometry.segmentsWidth | 1 | | shader | material.shader | standard | | side | material.side | front | | spherical-env-map | material.sphericalEnvMap | None | | src | material.src | None | | transparent | material.transparent | false | | vertex-colors-enabled | material.vertexColorsEnabled | false | | width | geometry.width | 1 | | wireframe | material.wireframe | false | | wireframe-linewidth | material.wireframeLinewidth | 2 | --- ### Primitives A Camera (`docs/primitives/a-camera.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/a-camera.js --- The camera primitive determines what the user sees. We can change the viewport by modifying the camera entity's position and rotation. ## Example ```html

``` ## Attributes | Attribute | Component Mapping | Default Value | |-----------------------|--------------------------------|---------------| | far | camera.far | 10000 | | fov | camera.fov | 80 | | look-controls-enabled | look-controls.enabled | true | | near | camera.near | 0.5 | | reverse-mouse-drag | look-controls.reverseMouseDrag | false | | wasd-controls-enabled | wasd-controls.enabled | true | ## Manually Positioning the Camera A camera is situated by default at the average height of human eye level (1.6 meters). When used with controls that receive rotation or position (e.g. from a VR device) this position will be overridden. ```html ``` When moving or rotating the camera relative to the scene, use a camera rig. By doing so, the camera's height offset can be updated by roomscale devices, while still allowing the tracked area to be moved independently around the scene. ```html

``` --- ### Primitives A Circle (`docs/primitives/a-circle.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/meshPrimitives.js --- The circle primitive creates circles surfaces using the [geometry][geometry] component with the type set to `circle`. ## Example ```html

``` ## Attributes | Attribute | Component Mapping | Default Value | | -------- | ----------------- | ------------- | | alpha-test | material.alphaTest | 0 | | ambient-occlusion-map | material.ambientOcclusionMap | None | | ambient-occlusion-map-intensity | material.ambientOcclusionMapIntensity | 1 | | ambient-occlusion-texture-offset | material.ambientOcclusionTextureOffset | 0 0 | | ambient-occlusion-texture-repeat | material.ambientOcclusionTextureRepeat | 1 1 | | anisotropy | material.anisotropy | 0 | | blending | material.blending | normal | | color | material.color | #FFF | | depth-test | material.depthTest | true | | depth-write | material.depthWrite | true | | displacement-bias | material.displacementBias | 0.5 | | displacement-map | material.displacementMap | None | | displacement-scale | material.displacementScale | 1 | | displacement-texture-offset | material.displacementTextureOffset | 0 0 | | displacement-texture-repeat | material.displacementTextureRepeat | 1 1 | | dithering | material.dithering | true | | emissive | material.emissive | #000 | | emissive-intensity | material.emissiveIntensity | 1 | | env-map | material.envMap | None | | flat-shading | material.flatShading | false | | mag-filter | material.magFilter | linear | | material-fog | material.fog | true | | material-visible | material.visible | true | | metalness | material.metalness | 0 | | metalness-map | material.metalnessMap | None | | metalness-texture-offset | material.metalnessTextureOffset | 0 0 | | metalness-texture-repeat | material.metalnessTextureRepeat | 1 1 | | min-filter | material.minFilter | linear-mipmap-linear | | normal-map | material.normalMap | None | | normal-scale | material.normalScale | 1 1 | | normal-texture-offset | material.normalTextureOffset | 0 0 | | normal-texture-repeat | material.normalTextureRepeat | 1 1 | | offset | material.offset | 0 0 | | opacity | material.opacity | 1 | | radius | geometry.radius | 1 | | repeat | material.repeat | 1 1 | | roughness | material.roughness | 0.5 | | roughness-map | material.roughnessMap | None | | roughness-texture-offset | material.roughnessTextureOffset | 0 0 | | roughness-texture-repeat | material.roughnessTextureRepeat | 1 1 | | segments | geometry.segments | 32 | | shader | material.shader | standard | | side | material.side | front | | spherical-env-map | material.sphericalEnvMap | None | | src | material.src | None | | theta-length | geometry.thetaLength | 360 | | theta-start | geometry.thetaStart | 0 | | transparent | material.transparent | false | | vertex-colors-enabled | material.vertexColorsEnabled | false | | wireframe | material.wireframe | false | | wireframe-linewidth | material.wireframeLinewidth | 2 | ## Parallelizing to the Ground To make a circle parallel to the ground, rotate it around the X-axis: ```html ``` [geometry]: ../components/geometry.md --- ### Primitives A Cone (`docs/primitives/a-cone.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/meshPrimitives.js --- The cone primitive creates a cone shape. ## Example ```html

``` ## Attributes | Attribute | Component Mapping | Default Value | | -------- | ----------------- | ------------- | | alpha-test | material.alphaTest | 0 | | ambient-occlusion-map | material.ambientOcclusionMap | None | | ambient-occlusion-map-intensity | material.ambientOcclusionMapIntensity | 1 | | ambient-occlusion-texture-offset | material.ambientOcclusionTextureOffset | 0 0 | | ambient-occlusion-texture-repeat | material.ambientOcclusionTextureRepeat | 1 1 | | anisotropy | material.anisotropy | 0 | | blending | material.blending | normal | | color | material.color | #FFF | | depth-test | material.depthTest | true | | depth-write | material.depthWrite | true | | displacement-bias | material.displacementBias | 0.5 | | displacement-map | material.displacementMap | None | | displacement-scale | material.displacementScale | 1 | | displacement-texture-offset | material.displacementTextureOffset | 0 0 | | displacement-texture-repeat | material.displacementTextureRepeat | 1 1 | | dithering | material.dithering | true | | emissive | material.emissive | #000 | | emissive-intensity | material.emissiveIntensity | 1 | | env-map | material.envMap | None | | flat-shading | material.flatShading | false | | height | geometry.height | 1 | | mag-filter | material.magFilter | linear | | material-fog | material.fog | true | | material-visible | material.visible | true | | metalness | material.metalness | 0 | | metalness-map | material.metalnessMap | None | | metalness-texture-offset | material.metalnessTextureOffset | 0 0 | | metalness-texture-repeat | material.metalnessTextureRepeat | 1 1 | | min-filter | material.minFilter | linear-mipmap-linear | | normal-map | material.normalMap | None | | normal-scale | material.normalScale | 1 1 | | normal-texture-offset | material.normalTextureOffset | 0 0 | | normal-texture-repeat | material.normalTextureRepeat | 1 1 | | offset | material.offset | 0 0 | | opacity | material.opacity | 1 | | open-ended | geometry.openEnded | false | | radius-bottom | geometry.radiusBottom | 1 | | radius-top | geometry.radiusTop | 0.01 | | repeat | material.repeat | 1 1 | | roughness | material.roughness | 0.5 | | roughness-map | material.roughnessMap | None | | roughness-texture-offset | material.roughnessTextureOffset | 0 0 | | roughness-texture-repeat | material.roughnessTextureRepeat | 1 1 | | segments-height | geometry.segmentsHeight | 18 | | segments-radial | geometry.segmentsRadial | 36 | | shader | material.shader | standard | | side | material.side | front | | spherical-env-map | material.sphericalEnvMap | None | | src | material.src | None | | theta-length | geometry.thetaLength | 360 | | theta-start | geometry.thetaStart | 0 | | transparent | material.transparent | false | | vertex-colors-enabled | material.vertexColorsEnabled | false | | wireframe | material.wireframe | false | | wireframe-linewidth | material.wireframeLinewidth | 2 | --- ### Primitives A Cubemap (`docs/primitives/a-cubemap.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/core/a-cubemap.js --- [envMap]: ../components/material.md#environment-maps [material]: ../components/material.md#built-in-materials [probe-light]: ../components/light.md#probe [cube-texture]: https://threejs.org/docs/#api/en/textures/CubeTexture The cubemap primitive is used to create a [CubeTexture][cube-texture] environment map from 6 square images. This can then be used as an [envMap][envMap] in the [material component][material], or on a [probe light][probe-light]. ## Example ```html

``` ## Attributes No attributes. The cubemap is configured by creating 6 child elements beneath it. --- ### Primitives A Cursor (`docs/primitives/a-cursor.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/a-cursor.js --- The cursor primitive is a reticle that allows for clicking and basic interactivity with a scene on devices that do not have a hand controller. The default appearance is a ring geometry. The cursor is usually placed as a child of the camera. Read the [cursor component documentation](../components/cursor.md) for detailed information about how the cursor works and how to use the cursor. ## Example ```html

``` ## Attributes | Attribute | Component Mapping | Default Value | |--------------|--------------------|---------------| | far | raycaster.far | 1000 | | fuse | cursor.fuse | false | | fuse-timeout | cursor.fuseTimeout | 1500 | | interval | raycaster.interval | 100 | | objects | raycaster.objects | 100 | --- ### Primitives A Curvedimage (`docs/primitives/a-curvedimage.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/a-curvedimage.js --- The curved image primitive creates images that bend around the user. Curved images arranged around the camera can be pleasing for legibility since each pixel sits at the same distance from the user. They can be a better choice than angled flat planes for complex layouts because they ensure a smooth surface rather than a series of awkward seams between planes. Under the hood, a curved image is a double-sided open-ended cylinder with textures mapped to the inside of the cylinder. ## Example ```html

``` ## Attributes | Attribute | Component Mapping | Default Value | | -------- | ----------------- | ------------- | | color | material.color | #FFF | | height | geometry.height | 1 | | metalness | material.metalness | 0 | | opacity | material.opacity | 1 | | open-ended | geometry.openEnded | true | | radius | geometry.radius | 2 | | repeat | material.repeat | None | | roughness | material.roughness | 0.5 | | segments-height | geometry.segmentsHeight | 18 | | segments-radial | geometry.segmentsRadial | 48 | | shader | material.shader | flat | | side | material.side | double | | src | material.src | None | | theta-length | geometry.thetaLength | 270 | | theta-start | geometry.thetaStart | 0 | | transparent | material.transparent | true | ## Fine-Tuning Ensuring that the image is not distorted by stretching requires us to carefully set the `height`, `radius`, and `theta-length` attributes relative to the image aspect ratio. According to this formula: S = r * θ We need to calculate `r` or `θ` for `S` to match the `height` value preserving the original aspect ratio of the image. In this formula, `θ` is set in radians and `radius` and `S` properties are set in meters.

Arc formula

In degrees, `thetaStart` defines where to start the arc and `thetaLength` defines where the arc ends. Once those values are fine-tuned to avoid distortion, we can use `scale` to safely adjust the distance of the curved image relative to the user. --- ### Primitives A Cylinder (`docs/primitives/a-cylinder.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/meshPrimitives.js --- The cylinder primitive is used to create tubes and curved surfaces. ## Examples The cylinder primitive is versatile and can be used to create different kinds of shapes: ```html

``` In degrees, `thetaStart` defines where to start the arc and `thetaLength` defines where the arc ends. Also, we can create a tube by making the cylinder open-ended, which removes the top and bottom surfaces of the cylinder such that the inside is visible. Then, we need a double-sided material to render properly: ```html ``` ## Attributes | Attribute | Component Mapping | Default Value | | -------- | ----------------- | ------------- | | alpha-test | material.alphaTest | 0 | | ambient-occlusion-map | material.ambientOcclusionMap | None | | ambient-occlusion-map-intensity | material.ambientOcclusionMapIntensity | 1 | | ambient-occlusion-texture-offset | material.ambientOcclusionTextureOffset | 0 0 | | ambient-occlusion-texture-repeat | material.ambientOcclusionTextureRepeat | 1 1 | | anisotropy | material.anisotropy | 0 | | blending | material.blending | normal | | color | material.color | #FFF | | depth-test | material.depthTest | true | | depth-write | material.depthWrite | true | | displacement-bias | material.displacementBias | 0.5 | | displacement-map | material.displacementMap | None | | displacement-scale | material.displacementScale | 1 | | displacement-texture-offset | material.displacementTextureOffset | 0 0 | | displacement-texture-repeat | material.displacementTextureRepeat | 1 1 | | dithering | material.dithering | true | | emissive | material.emissive | #000 | | emissive-intensity | material.emissiveIntensity | 1 | | env-map | material.envMap | None | | flat-shading | material.flatShading | false | | height | geometry.height | 1 | | mag-filter | material.magFilter | linear | | material-fog | material.fog | true | | material-visible | material.visible | true | | metalness | material.metalness | 0 | | metalness-map | material.metalnessMap | None | | metalness-texture-offset | material.metalnessTextureOffset | 0 0 | | metalness-texture-repeat | material.metalnessTextureRepeat | 1 1 | | min-filter | material.minFilter | linear-mipmap-linear | | normal-map | material.normalMap | None | | normal-scale | material.normalScale | 1 1 | | normal-texture-offset | material.normalTextureOffset | 0 0 | | normal-texture-repeat | material.normalTextureRepeat | 1 1 | | offset | material.offset | 0 0 | | opacity | material.opacity | 1 | | open-ended | geometry.openEnded | false | | radius | geometry.radius | 1 | | repeat | material.repeat | 1 1 | | roughness | material.roughness | 0.5 | | roughness-map | material.roughnessMap | None | | roughness-texture-offset | material.roughnessTextureOffset | 0 0 | | roughness-texture-repeat | material.roughnessTextureRepeat | 1 1 | | segments-height | geometry.segmentsHeight | 18 | | segments-radial | geometry.segmentsRadial | 36 | | shader | material.shader | standard | | side | material.side | front | | spherical-env-map | material.sphericalEnvMap | None | | src | material.src | None | | theta-length | geometry.thetaLength | 360 | | theta-start | geometry.thetaStart | 0 | | transparent | material.transparent | false | | vertex-colors-enabled | material.vertexColorsEnabled | false | | wireframe | material.wireframe | false | | wireframe-linewidth | material.wireframeLinewidth | 2 | --- ### Primitives A Dodecahedron (`docs/primitives/a-dodecahedron.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/meshPrimitives.js --- ## Example ```html ``` ## Attributes | Attribute | Component Mapping | Default Value | | -------- | ----------------- | ------------- | | alpha-test | material.alphaTest | 0 | | ambient-occlusion-map | material.ambientOcclusionMap | None | | ambient-occlusion-map-intensity | material.ambientOcclusionMapIntensity | 1 | | ambient-occlusion-texture-offset | material.ambientOcclusionTextureOffset | 0 0 | | ambient-occlusion-texture-repeat | material.ambientOcclusionTextureRepeat | 1 1 | | anisotropy | material.anisotropy | 0 | | blending | material.blending | normal | | color | material.color | #FFF | | depth-test | material.depthTest | true | | depth-write | material.depthWrite | true | | detail | geometry.detail | 0 | | displacement-bias | material.displacementBias | 0.5 | | displacement-map | material.displacementMap | None | | displacement-scale | material.displacementScale | 1 | | displacement-texture-offset | material.displacementTextureOffset | 0 0 | | displacement-texture-repeat | material.displacementTextureRepeat | 1 1 | | dithering | material.dithering | true | | emissive | material.emissive | #000 | | emissive-intensity | material.emissiveIntensity | 1 | | env-map | material.envMap | None | | flat-shading | material.flatShading | false | | mag-filter | material.magFilter | linear | | material-fog | material.fog | true | | material-visible | material.visible | true | | metalness | material.metalness | 0 | | metalness-map | material.metalnessMap | None | | metalness-texture-offset | material.metalnessTextureOffset | 0 0 | | metalness-texture-repeat | material.metalnessTextureRepeat | 1 1 | | min-filter | material.minFilter | linear-mipmap-linear | | normal-map | material.normalMap | None | | normal-scale | material.normalScale | 1 1 | | normal-texture-offset | material.normalTextureOffset | 0 0 | | normal-texture-repeat | material.normalTextureRepeat | 1 1 | | offset | material.offset | 0 0 | | opacity | material.opacity | 1 | | radius | geometry.radius | 1 | | repeat | material.repeat | 1 1 | | roughness | material.roughness | 0.5 | | roughness-map | material.roughnessMap | None | | roughness-texture-offset | material.roughnessTextureOffset | 0 0 | | roughness-texture-repeat | material.roughnessTextureRepeat | 1 1 | | shader | material.shader | standard | | side | material.side | front | | spherical-env-map | material.sphericalEnvMap | None | | src | material.src | None | | transparent | material.transparent | false | | vertex-colors-enabled | material.vertexColorsEnabled | false | | wireframe | material.wireframe | false | | wireframe-linewidth | material.wireframeLinewidth | 2 | --- ### Primitives A Gltf Model (`docs/primitives/a-gltf-model.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/a-gltf-model.js --- The glTF model primitive displays a 3D glTF model created from a 3D modeling program or downloaded from the web. ## Example ```html

``` ## Attribute [gltf]: ../components/gltf-model.md | Attribute | Component Mapping | Default Value | |-----------|------------------------|---------------| | src | [gltf-model][gltf].src | null | --- ### Primitives A Icosahedron (`docs/primitives/a-icosahedron.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/meshPrimitives.js --- ## Example ```html ``` ## Attributes | Attribute | Component Mapping | Default Value | | -------- | ----------------- | ------------- | | alpha-test | material.alphaTest | 0 | | ambient-occlusion-map | material.ambientOcclusionMap | None | | ambient-occlusion-map-intensity | material.ambientOcclusionMapIntensity | 1 | | ambient-occlusion-texture-offset | material.ambientOcclusionTextureOffset | 0 0 | | ambient-occlusion-texture-repeat | material.ambientOcclusionTextureRepeat | 1 1 | | anisotropy | material.anisotropy | 0 | | blending | material.blending | normal | | color | material.color | #FFF | | depth-test | material.depthTest | true | | depth-write | material.depthWrite | true | | detail | geometry.detail | 0 | | displacement-bias | material.displacementBias | 0.5 | | displacement-map | material.displacementMap | None | | displacement-scale | material.displacementScale | 1 | | displacement-texture-offset | material.displacementTextureOffset | 0 0 | | displacement-texture-repeat | material.displacementTextureRepeat | 1 1 | | dithering | material.dithering | true | | emissive | material.emissive | #000 | | emissive-intensity | material.emissiveIntensity | 1 | | env-map | material.envMap | None | | flat-shading | material.flatShading | false | | mag-filter | material.magFilter | linear | | material-fog | material.fog | true | | material-visible | material.visible | true | | metalness | material.metalness | 0 | | metalness-map | material.metalnessMap | None | | metalness-texture-offset | material.metalnessTextureOffset | 0 0 | | metalness-texture-repeat | material.metalnessTextureRepeat | 1 1 | | min-filter | material.minFilter | linear-mipmap-linear | | normal-map | material.normalMap | None | | normal-scale | material.normalScale | 1 1 | | normal-texture-offset | material.normalTextureOffset | 0 0 | | normal-texture-repeat | material.normalTextureRepeat | 1 1 | | offset | material.offset | 0 0 | | opacity | material.opacity | 1 | | radius | geometry.radius | 1 | | repeat | material.repeat | 1 1 | | roughness | material.roughness | 0.5 | | roughness-map | material.roughnessMap | None | | roughness-texture-offset | material.roughnessTextureOffset | 0 0 | | roughness-texture-repeat | material.roughnessTextureRepeat | 1 1 | | shader | material.shader | standard | | side | material.side | front | | spherical-env-map | material.sphericalEnvMap | None | | src | material.src | None | | transparent | material.transparent | false | | vertex-colors-enabled | material.vertexColorsEnabled | false | | wireframe | material.wireframe | false | | wireframe-linewidth | material.wireframeLinewidth | 2 | --- ### Primitives A Image (`docs/primitives/a-image.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/a-image.js --- The image primitive shows an image on a flat plane. ## Example ```html

``` ## Attributes | Attribute | Component Mapping | Default Value | | -------- | ----------------- | ------------- | | color | material.color | #FFF | | height | geometry.height | 1 | | metalness | material.metalness | 0 | | opacity | material.opacity | 1 | | repeat | material.repeat | None | | roughness | material.roughness | 0.5 | | segments-height | geometry.segmentsHeight | 1 | | segments-width | geometry.segmentsWidth | 1 | | shader | material.shader | flat | | side | material.side | front | | src | material.src | None | | transparent | material.transparent | true | | width | geometry.width | 1 | ## Fine-Tuning Ensuring that the image is not distorted by stretching requires us to appropriately set the `width` and `height` preserving the original aspect ratio of the image. This properties are set in meters, don't confuse with pixels. For example, a 2:1 image: ```html ``` --- ### Primitives A Light (`docs/primitives/a-light.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/a-light.js --- A light changes the lighting and shading of the scene. ## Examples ```html

``` ## Attributes | Attribute | Component Mapping | Default Value | | ------------ | ----------------- | ------------- | | angle | light.angle | 60 | | color | light.color | #fff | | decay | light.decay | 1 | | distance | light.distance | 0.0 | | envmap | light.envMap | null | | ground-color | light.groundColor | #fff | | intensity | light.intensity | 1.0 | | penumbra | light.penumbra | 0.0 | | type | light.type | directional | | target | light.target | null | ## Differences with the Default Lighting When we add a light, A-Frame will remove the default lighting setup (i.e., one directional light from the top-left, and one small ambient light). --- ### Primitives A Link (`docs/primitives/a-link.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/a-link.js --- The link primitive provides a compact API to define links that resembles the traditional `` tag. ## Attributes | Attribute | Component Mapping | Default Value | |-----------------------|--------------------------------|---------------| | href | link.href | | | title | link.title | | | src | link.src | | --- ### Primitives A Obj Model (`docs/primitives/a-obj-model.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/a-obj-model.js --- > We recommend glTF for distributing assets in production over the web. Check > out using the [glTF model primitive](a-gltf-model.md). You can > either instead export to COLLADA and use [the > converter](https://cesiumjs.org/convertmodel.html) or try out the [OBJ > converter](https://github.com/AnalyticalGraphicsInc/OBJ2GLTF). The .OBJ model primitive displays a 3D Wavefront model. ## Example ```html

``` ## Attribute | Attribute | Component Mapping | Default Value | |-----------|-------------------|---------------| | mtl | obj-model.mtl | null | | src | obj-model.obj | null | ## Troubleshooting See [Introduction → 3D Models → Troubleshooting](../introduction/models.md#troubleshooting). --- ### Primitives A Octahedron (`docs/primitives/a-octahedron.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/meshPrimitives.js --- ## Example ```html ``` ## Attributes | Attribute | Component Mapping | Default Value | | -------- | ----------------- | ------------- | | alpha-test | material.alphaTest | 0 | | ambient-occlusion-map | material.ambientOcclusionMap | None | | ambient-occlusion-map-intensity | material.ambientOcclusionMapIntensity | 1 | | ambient-occlusion-texture-offset | material.ambientOcclusionTextureOffset | 0 0 | | ambient-occlusion-texture-repeat | material.ambientOcclusionTextureRepeat | 1 1 | | anisotropy | material.anisotropy | 0 | | blending | material.blending | normal | | color | material.color | #FFF | | depth-test | material.depthTest | true | | depth-write | material.depthWrite | true | | detail | geometry.detail | 0 | | displacement-bias | material.displacementBias | 0.5 | | displacement-map | material.displacementMap | None | | displacement-scale | material.displacementScale | 1 | | displacement-texture-offset | material.displacementTextureOffset | 0 0 | | displacement-texture-repeat | material.displacementTextureRepeat | 1 1 | | dithering | material.dithering | true | | emissive | material.emissive | #000 | | emissive-intensity | material.emissiveIntensity | 1 | | env-map | material.envMap | None | | flat-shading | material.flatShading | false | | mag-filter | material.magFilter | linear | | material-fog | material.fog | true | | material-visible | material.visible | true | | metalness | material.metalness | 0 | | metalness-map | material.metalnessMap | None | | metalness-texture-offset | material.metalnessTextureOffset | 0 0 | | metalness-texture-repeat | material.metalnessTextureRepeat | 1 1 | | min-filter | material.minFilter | linear-mipmap-linear | | normal-map | material.normalMap | None | | normal-scale | material.normalScale | 1 1 | | normal-texture-offset | material.normalTextureOffset | 0 0 | | normal-texture-repeat | material.normalTextureRepeat | 1 1 | | offset | material.offset | 0 0 | | opacity | material.opacity | 1 | | radius | geometry.radius | 1 | | repeat | material.repeat | 1 1 | | roughness | material.roughness | 0.5 | | roughness-map | material.roughnessMap | None | | roughness-texture-offset | material.roughnessTextureOffset | 0 0 | | roughness-texture-repeat | material.roughnessTextureRepeat | 1 1 | | shader | material.shader | standard | | side | material.side | front | | spherical-env-map | material.sphericalEnvMap | None | | src | material.src | None | | transparent | material.transparent | false | | vertex-colors-enabled | material.vertexColorsEnabled | false | | wireframe | material.wireframe | false | | wireframe-linewidth | material.wireframeLinewidth | 2 | --- ### Primitives A Plane (`docs/primitives/a-plane.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/meshPrimitives.js --- [geometry]: ../components/geometry.md The plane primitive creates flat surfaces using the [geometry][geometry] component with the type set to `plane`. ## Example ```html

``` ## Attributes | Attribute | Component Mapping | Default Value | | -------- | ----------------- | ------------- | | alpha-test | material.alphaTest | 0 | | ambient-occlusion-map | material.ambientOcclusionMap | None | | ambient-occlusion-map-intensity | material.ambientOcclusionMapIntensity | 1 | | ambient-occlusion-texture-offset | material.ambientOcclusionTextureOffset | 0 0 | | ambient-occlusion-texture-repeat | material.ambientOcclusionTextureRepeat | 1 1 | | anisotropy | material.anisotropy | 0 | | blending | material.blending | normal | | color | material.color | #FFF | | depth-test | material.depthTest | true | | depth-write | material.depthWrite | true | | displacement-bias | material.displacementBias | 0.5 | | displacement-map | material.displacementMap | None | | displacement-scale | material.displacementScale | 1 | | displacement-texture-offset | material.displacementTextureOffset | 0 0 | | displacement-texture-repeat | material.displacementTextureRepeat | 1 1 | | dithering | material.dithering | true | | emissive | material.emissive | #000 | | emissive-intensity | material.emissiveIntensity | 1 | | env-map | material.envMap | None | | flat-shading | material.flatShading | false | | height | geometry.height | 1 | | mag-filter | material.magFilter | linear | | material-fog | material.fog | true | | material-visible | material.visible | true | | metalness | material.metalness | 0 | | metalness-map | material.metalnessMap | None | | metalness-texture-offset | material.metalnessTextureOffset | 0 0 | | metalness-texture-repeat | material.metalnessTextureRepeat | 1 1 | | min-filter | material.minFilter | linear-mipmap-linear | | normal-map | material.normalMap | None | | normal-scale | material.normalScale | 1 1 | | normal-texture-offset | material.normalTextureOffset | 0 0 | | normal-texture-repeat | material.normalTextureRepeat | 1 1 | | offset | material.offset | 0 0 | | opacity | material.opacity | 1 | | repeat | material.repeat | 1 1 | | roughness | material.roughness | 0.5 | | roughness-map | material.roughnessMap | None | | roughness-texture-offset | material.roughnessTextureOffset | 0 0 | | roughness-texture-repeat | material.roughnessTextureRepeat | 1 1 | | segments-height | geometry.segmentsHeight | 1 | | segments-width | geometry.segmentsWidth | 1 | | shader | material.shader | standard | | side | material.side | front | | spherical-env-map | material.sphericalEnvMap | None | | src | material.src | None | | transparent | material.transparent | false | | vertex-colors-enabled | material.vertexColorsEnabled | false | | width | geometry.width | 1 | | wireframe | material.wireframe | false | | wireframe-linewidth | material.wireframeLinewidth | 2 | ## Parallelizing to the Ground To make a plane parallel to the ground or make a plane the ground itself, rotate it around the X-axis: ```html ``` --- ### Primitives A Ring (`docs/primitives/a-ring.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/meshPrimitives.js --- The ring primitive creates a ring or disc shape. ## Example ```html

``` ## Attributes | Attribute | Component Mapping | Default Value | | -------- | ----------------- | ------------- | | alpha-test | material.alphaTest | 0 | | ambient-occlusion-map | material.ambientOcclusionMap | None | | ambient-occlusion-map-intensity | material.ambientOcclusionMapIntensity | 1 | | ambient-occlusion-texture-offset | material.ambientOcclusionTextureOffset | 0 0 | | ambient-occlusion-texture-repeat | material.ambientOcclusionTextureRepeat | 1 1 | | anisotropy | material.anisotropy | 0 | | blending | material.blending | normal | | color | material.color | #FFF | | depth-test | material.depthTest | true | | depth-write | material.depthWrite | true | | displacement-bias | material.displacementBias | 0.5 | | displacement-map | material.displacementMap | None | | displacement-scale | material.displacementScale | 1 | | displacement-texture-offset | material.displacementTextureOffset | 0 0 | | displacement-texture-repeat | material.displacementTextureRepeat | 1 1 | | dithering | material.dithering | true | | emissive | material.emissive | #000 | | emissive-intensity | material.emissiveIntensity | 1 | | env-map | material.envMap | None | | flat-shading | material.flatShading | false | | mag-filter | material.magFilter | linear | | material-fog | material.fog | true | | material-visible | material.visible | true | | metalness | material.metalness | 0 | | metalness-map | material.metalnessMap | None | | metalness-texture-offset | material.metalnessTextureOffset | 0 0 | | metalness-texture-repeat | material.metalnessTextureRepeat | 1 1 | | min-filter | material.minFilter | linear-mipmap-linear | | normal-map | material.normalMap | None | | normal-scale | material.normalScale | 1 1 | | normal-texture-offset | material.normalTextureOffset | 0 0 | | normal-texture-repeat | material.normalTextureRepeat | 1 1 | | offset | material.offset | 0 0 | | opacity | material.opacity | 1 | | radius-inner | geometry.radiusInner | 0.8 | | radius-outer | geometry.radiusOuter | 1.2 | | repeat | material.repeat | 1 1 | | roughness | material.roughness | 0.5 | | roughness-map | material.roughnessMap | None | | roughness-texture-offset | material.roughnessTextureOffset | 0 0 | | roughness-texture-repeat | material.roughnessTextureRepeat | 1 1 | | segments-phi | geometry.segmentsPhi | 10 | | segments-theta | geometry.segmentsTheta | 32 | | shader | material.shader | standard | | side | material.side | front | | spherical-env-map | material.sphericalEnvMap | None | | src | material.src | None | | theta-length | geometry.thetaLength | 360 | | theta-start | geometry.thetaStart | 0 | | transparent | material.transparent | false | | vertex-colors-enabled | material.vertexColorsEnabled | false | | wireframe | material.wireframe | false | | wireframe-linewidth | material.wireframeLinewidth | 2 | --- ### Primitives A Sky (`docs/primitives/a-sky.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/a-sky.js examples: - title: Adding a Sky src: https://glitch.com/edit/#!/aframe-adding-a-sky?path=index.html - title: Changing the Sky src: https://glitch.com/edit/#!/aframe-changing-the-sky?path=index.html --- The sky primitive adds a background color or 360° image to a scene. A sky is a large sphere with a color or texture mapped to the inside. ## Example An equirectangular image as a background: ```html

``` A plain color as a background: ```html ``` ## Attributes | Attribute | Component Mapping | Default Value | | -------- | ----------------- | ------------- | | color | material.color | #FFF | | metalness | material.metalness | 0 | | opacity | material.opacity | 1 | | phi-length | geometry.phiLength | 360 | | phi-start | geometry.phiStart | 0 | | radius | geometry.radius | 500 | | repeat | material.repeat | None | | roughness | material.roughness | 0.5 | | segments-height | geometry.segmentsHeight | 32 | | segments-width | geometry.segmentsWidth | 64 | | shader | material.shader | flat | | side | material.side | back | | src | material.src | None | | theta-length | geometry.thetaLength | 180 | | theta-start | geometry.thetaStart | 0 | | transparent | material.transparent | false | ## Equirectangular Image To be seamless, images should be [equirectangular](https://en.wikipedia.org/wiki/Equirectangular_projection). We can find some sample equirectangular images on [Flickr](https://www.flickr.com/groups/equirectangular/). To take an equirectangular photo, check out this [360-degree photography guide](http://ngokevin.com/blog/360-photography/). --- ### Primitives A Sound (`docs/primitives/a-sound.md`) --- title: type: primitives layout: docs parent_section: primitives source_code: src/extras/primitives/primitives/a-sound.js --- The sound primitive wraps the [sound component](../components/sound.md). ## Example ```html