Installation
Note: This documentation is for the old 1.2.0 version of A-Frame. Check out the documentation for the current 1.6.0 version
This installation section offers several ways to get started with A-Frame, although most methods don’t require any actual installation since A-Frame is primarily HTML and JavaScript.
Code Editors in the Browser
The fastest way is to start playing from within the browser.
Remix on Glitch
Glitch provides an online code editor with instant deployment and hosting of web sites. The editor supports both front-end and back-end code as well as multiple files and directories. Glitch lets us remix (i.e., copy) existing projects and make them our own and instantly host and deploy changes for everyone to see.
Hit Remix on this A-Frame project, mess with the HTML in
index.html
, and see your site published live on each change! The base A-Frame
Glitch, for example, is published at aframe.glitch.me
, but we will provide your
own custom URL name.
Below are a few other A-Frame Glitches for starters:
- aframe-aincraft - Minecraft demo.
- aframe-gallery - 360° image gallery.
- aframe-registry - Showcase of various components.
- aframe-vaporwave - Retro-futuristic scene.
- networked-aframe - Multiuser.
Other Code Editors
Below are a couple of A-Frame starter kits on other browser-based code editors. Both support remixing or forking:
Local Development
Use a Local Server
For the options below, we should develop projects using a local server so that files are properly served. Options of local servers include:
- Downloading the Mongoose application and opening it from the same directory as your HTML file.
- Running
python -m SimpleHTTPServer
(orpython -m http.server
for Python 3) in a terminal in the same directory as your HTML file. - Running
npm install -g live-server && live-server
in a terminal in the same directory as your HTML file.
Once we are running our server, we can open our project in the browser using
the local URL and port which the server is running on (e.g.,
http://localhost:8000
). Try not to open the project using the file://
protocol which does not provide a domain; absolute and relative URLs may not
work.
Download the Boilerplate on GitHub
The boilerplate contains:
- A simple HTML file that links to the current version of A-Frame
- An optional local development server
- An easy deployment workflow for GitHub Pages to share with the world
We can grab the boilerplate in one of two ways:
Fork on GitHub
(Note this is marked as ‘discontinued’, the Aframe version packaged with this is 0.5)
Include the JS Build
To include A-Frame in an HTML file, we drop a <script>
tag pointing to the
CDN build:
<head> |
If we want to serve it ourselves, we can download the JS build:
Production Version 1.2.0 Minified Development Version 1.2.0 Uncompressed with Source Maps
Install from npm
We can also install A-Frame through npm:
$ npm install aframe |
Then we can bundle A-Frame into our application. For example, with Browserify or Webpack:
require('aframe'); |
If you use npm, you can use angle
, a command line interface for
A-Frame. angle
can initialize a scene template with a single command:
npm install -g angle && angle initscene |
Cordova Development
A-Frame is compatible with Cordova apps. Currently, network access is required as A-Frame and its dependencies load assets from CDN sources.
Cordova A-Frame Showcase App (demo)
Installation
Install the cordova-plugin-xhr-local-file plugin. This is needed because
Cordova runs from file://
, and XHR requests to local file://
assets (JSON fonts, 3D models, etc) will fail without this plugin.
cordova plugin add cordova-plugin-xhr-local-file |
In your index.html
, adjust as follows:
<head> |
Discussion
deviceready
The most important difference between a browser environment and a Cordova environment is waiting for the deviceready
event
before rendering your scene.
The sample above shows a pure DOM+JS approach, but you can also use a framework like React:
document.addEventListener('deviceready', () => { |
Layout
Depending on your target device, you may find that A-Frame’s default CSS causes certain buttons and controls to appear out of position or too close to the edge of the phone screen. Supply your own CSS overrides to adjust positioning to fit the target device.