aframe-core

A-Frame Core

A DOM-based Entity-Component System to declaratively create 3D and VR worlds in the browser.

This library is specific to the core A-Frame library. For more information about the A-Frame project as a whole, head over to the A-Frame site or the aframe repo.

Entity-Component System

Entity-Component System is an architectural pattern commonly used in game engines such as Unity, PlayCanvas, an Unreal Engine 4+.

There's only one basic element called an entity that defines a scale, a position, and a rotation in the scene. Components encapsulate logic and data that can be attached to entities to extend their functionality, appearance, and behavior. In A-Frame, entities are represented by <a-entity> DOM elements and components as their attributes. This is what a simple scene with a cube and a camera looks like:

<a-scene>
    <a-entity camera="fov: 45"></a-entity>
    <a-entity position="0 0 -10" rotation="45 30 0"
              geometry="primitive: box; height: 4; width: 4; depth: 4"
              material="color: green"></a-entity>
</a-scene>

Usage

NOTE: For folks creating scenes and third-party components and elements, we recommend getting started by instead using the aframe library, a set of core resuable elements.

Proceed below if you would like to use the minimal set of primitive components and elements available here in aframe-core.

CodePen

If you want to get started immediately, just fire up this CodePen example scene!

Downloads

To get started, simply include these files in your project:

• aframe.min.js

Or if you'd prefer the unminified version for local development (with source maps):

• aframe-core.js

Also, be sure to check out these awesome examples:

• aframe-core examples (source)
• aframe examples (source)

npm

First install from npm:

npm install aframe-core

And in your Browserify/Webpack modules, simply require the module:

require('aframe-core')

Local installation and development

Alternatively, you can clone this repository to work locally on this project.

git clone https://github.com/aframevr/aframe-core.git
cd aframe-core
npm install

To start the local development server:

npm start

And fire up http://localhost:9001!

Running tests

After you have cloned the repo and installed the dependencies, simply run the tests like so:

npm test

Browser console logging

If you'd like to see helpful logs, warnings, and errors, you can enable logging from the console of your favourite developer tools:

localStorage.logs = 1

And to disable:

localStorage.logs = 0

Maintainers

Ensure you have cloned the repo and installed the dependencies.

Developing alongside the other aframe packages (e.g., aframe)

If you want to make changes to the aframe library and test with aframe-core, you'll need to run these commands to link things up correctly.

Linking

When you are in the directory of your aframe-core repo checkout:

npm link

When you are in the directory of your aframe repo checkout:

npm link aframe-core

Now when you make changes to aframe-core, those changes will get reflected when a bundle gets built (the page is refreshed or a aframe file is changed), so you can test the aframe-core dependency against aframe without having to manually push things to npm for testing (which is a big no no!).

Unlinking

You'll need to npm unlink when you are done testing things and want to actually use the npm-published versions, not your versions that are locally linked.

From your aframe-core directory:

npm unlink

From your aframe directory:

npm unlink aframe-core

Releasing and publishing a new version to npm

To increment the preminor version of the package (e.g., 0.1.19 to 0.1.20) and create a git tag (e.g., v0.1.20):

npm run release:bump

NOTE: npm versions cannot be unpublished.

Once the package is 100% ready to go, to push the new version to npm (e.g., 0.1.20) and to the new tag to GitHub (e.g., v0.1.20):

npm run release:push

Updating dist files

npm run dist
git commit -am 'Bump dist'

Publishing to GitHub Pages

To publish to https://aframevr.github.io/aframe-core/:

npm run ghpages

To publish to https://your_username.github.io/aframe-core/:

npm run ghpages your_username

License

This program is free software and is distributed under an MIT License.