# aframe-extras: the component library that removed its own physics movement

> aframe-extras is an MIT licensed add-on collection for A-Frame VR, with controls for six input methods, model loaders, pathfinding, and a set of primitives. Its most instructive decision is a removal: kinematic-body was deleted in v7.0.0 because physics-driven locomotion glitched, and the recommended answer is a navigation mesh.

**c-frame/aframe-extras** — Add-ons and helpers for A-Frame VR.

- Repository: https://github.com/c-frame/aframe-extras
- Website: https://c-frame.github.io/aframe-extras/examples/
- Stars: 1,019 · Forks: 305
- Language: JavaScript
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/c-frame-aframe-extras

## Controls, loaders, pathfinding, primitives, and a few odds

aframe-extras is a collection of A-Frame components and helpers, published to npm as aframe-extras and currently at version 7.7.0. The source tree is organised by category, and the categories tell you what kind of project this suits.

Under controls/ you find six files: movement-controls, checkpoint-controls, gamepad-controls, keyboard-controls, touch-controls and trackpad-controls. Under loaders/ there are animation-mixer, collada-model-legacy, fbx-model and object-model. The misc/ folder holds checkpoint, cube-env-map, grab, mesh-smooth, normal-material and sphere-collider. Under pathfinding/ are nav-mesh and nav-agent, and under primitives/ are a-grid, a-ocean and a-tube.

The runtime dependencies explain the shape of it: three at 0.164.0, three-pathfinding at 1.3.0 for the navigation work, and nipplejs for the virtual joystick.

Two things are worth noticing before you dive in. The tree in the README lists misc/mesh-smooth.js, while the removed components table says mesh-smooth was removed in 7.0.0. And several components and examples rely on a separate project, aframe-physics-system, which is not part of this repository. The second point matters, because it means a piece of the standard example set needs a second install.

The examples directory is a good map of what people build with it: a castle, an island, checkpoints, tubes, an FBX model scene, animation examples, and a Vive example.

## The controls are six ways of moving a person, not one system

The control set is worth reading as a menu of input devices rather than as a single movement system. There is a keyboard-controls component for desktop, a gamepad-controls component for a gamepad, touch-controls for a screen, trackpad-controls for a headset touchpad, movement-controls for the general case, and checkpoint-controls, which is a different kind of component since it deals with positions rather than input.

That distinction between the components is what makes the library usable. A desktop demo and a room scale VR session want different things from the same scene, and having both implementations in the same package means you choose rather than write.

The touch component pulls in nipplejs, which is the virtual thumbstick overlay used on mobile. If you only ship a desktop build, that dependency is dead weight, and the package supports partial imports so you can avoid it, which is a real difference between this library and a single-file A-Frame component that pulls everything in.

The primitives are the other category that saves real work. a-grid, a-ocean and a-tube are declarative elements for the three things that show up in nearly every VR scene, a floor, a sea and a tunnel, and they exist as A-Frame primitives so you can use them from HTML rather than from JavaScript.

## Pathfinding is the answer the project gives you instead of physics

The removed components table is the most useful part of the README, because it records decisions rather than features.

kinematic-body was removed in 7.0.0, and the stated reason is blunt: using physics for movement is unstable and performs poorly. The longer explanation says that when you want to stop players passing through obstacles, use a navigation mesh instead wherever possible. The component constrained player movement using physics and depended on aframe-physics-system, and the conclusion is that using physics for locomotion is not VR friendly and is often glitchy even for traditional 3D.

That is why the pathfinding/ directory exists with nav-mesh and nav-agent in it, and why three-pathfinding is a runtime dependency. The move from a physics body to an agent on a navigation mesh is the recommended replacement, and it is a different mental model: you constrain the player to a walkable surface instead of resolving a collision every frame.

Two more removals follow the same pattern. jump-ability went because it depended on kinematic-body, so removing the base component took the whole stack with it. a-hexgrid went because it was based on another repository that is no longer maintained and does not work with recent versions of THREE.js. And mesh-smooth went because it was intended for JSON models while the JSON loader is no longer part of this repository.

## Three ways to load it, and the one that needs a bundler

The simplest route is a script tag pointing at a jsDelivr build, pinned to a release tag.

```html
<script src="https://cdn.jsdelivr.net/gh/c-frame/aframe-extras@7.7.0/dist/aframe-extras.min.js"></script>
```

You can replace the version with another tag or with a commit hash if you want a build from the master branch, and the README suggests using the latest commit hash in that case. For partial builds, there are subpackages such as aframe-extras.controls.min.js, so you can ship only the parts you use.

The npm route is the one for a project with a build step.

```bash
npm install --save aframe-extras
```

```javascript
// index.js
import 'aframe-extras';
// or specific packages
import "aframe-extras/controls/index.js";
import "aframe-extras/pathfinding/index.js";
```

The package exposes subpaths for each category through its exports map, covering controls, loaders, misc, pathfinding and primitives, which is what makes those partial imports work.

There is a condition on the npm route that catches people out. Once installed, you need to compile your JavaScript with something like webpack, with three defined as external, and the README points at webpack.config.js in this repository as an example. The library expects a three instance to be present in the page, so bundling your own copy of three alongside A-Frame is a common source of trouble.

## A-Frame and extras versions are pinned to each other

The compatibility table in the README is short and should be read as a contract rather than as a suggestion.

```text
A-Frame  | Extras
v1.7.x   | v7.x.x
v1.4.0   | v7.0.0
v1.3.0   | v7.0.0
v1.2.0   | v7.0.0
v1.1.0   | v6.1.1
```

So the current line of extras, 7.x, goes with A-Frame 1.7.x, and the earlier A-Frame versions are pinned to the extras release that was current for them, which is 7.0.0 for 1.2.0 through 1.4.0, and 6.1.1 for A-Frame 1.1.0. Extras tracks A-Frame rather than the other way round, and the pairing is not approximate.

The practical consequence is that upgrading A-Frame is not a decision you make in isolation. If you are on A-Frame 1.4.0 with extras 7.0.0, moving to A-Frame 1.7.x means moving extras to the 7.x line as well, and the changelog is where you check what changed in between.

The build itself is webpack. The package scripts expose a dev server, an unminified dist build and a minified production build, and the compiled output is committed in the dist/ directory, which is what the script tag above actually downloads.

## A live examples site is the fastest way to evaluate it

The examples are not decoration. A live set of usage examples is published at the project's documentation site, and the repository ships the same set under examples/.

The list of them maps onto the component categories in a useful way. There is a castle and an island, which are the scenes you would build with the grid, ocean and tube primitives. There is a checkpoints scene for the checkpoint components. There is an FBX model scene, which is the loader in action. There are animation examples, which pair the animation-mixer loader with the controls. There is a Vive example, which shows the headset-specific input path. And there is an environment map example, which is where cube-env-map fits.

The reason to go to the examples rather than the source is that A-Frame scenes are declarative. A component is a behaviour attached to an element, and reading a working scene tells you how the elements are wired in a way that reading the component source does not.

The site is also the fastest way to see the library's limits. If a scene needs behaviour that none of the components provide, you are writing A-Frame components yourself, and at that point the value of the library is the parts you did not have to write.

## Releases in April, pushes in June, and a pinned three

The version history is regular but not fast. v7.7.0 was published on 2026-04-01, preceded by v7.6.1 on 2025-12-08 and v7.6.0 on 2025-07-05. The repository is not archived and the last push was on 2026-06-24, so work continues between releases rather than stopping.

The licence is MIT, which permits commercial use but requires keeping the copyright and licence notice with copies.

The dependency pin deserves a note. The package depends on three at 0.164.0, and the removed a-hexgrid component was dropped because it did not work with recent versions of THREE.js. That is a reminder that a WebVR library is coupled to the three.js release cycle underneath it, and that a three upgrade in your own project is a compatibility event for the extras as well, especially for anything using the loaders.

A CHANGELOG.md sits in the repository, and given the removals in 7.0.0 and the A-Frame version pairing, it is the file to read when you plan to move between major A-Frame lines rather than reading the component source.

## Conclusion

aframe-extras fits a team building an A-Frame scene that has already decided it wants the community's control components, pathfinding and model loaders rather than hand written ones, and that is content to stay on A-Frame 1.7.x. It does not fit a project that wanted physics to drive the player, since that route was removed for good reasons, and it does not fit a team on an older A-Frame without checking the compatibility table first. Verify three things before you build on it: that your A-Frame version matches the extras version you install, because the two are pinned to each other, that the components you want are not on the removed list, since kinematic-body, jump-ability, a-hexgrid and mesh-smooth were all deleted in 7.0.0, and that your bundler treats three as an external, because the library expects a three instance that it does not carry.

## FAQ

### Which A-Frame version works with aframe-extras?

The compatibility table pairs A-Frame 1.7.x with extras 7.x.x, A-Frame 1.4.0, 1.3.0 and 1.2.0 with extras 7.0.0, and A-Frame 1.1.0 with extras 6.1.1. The pairing is exact rather than approximate, so upgrading A-Frame means moving extras with it.

### How do I add aframe-extras to an A-Frame page?

Include the built file from the dist folder with a script tag, for example the jsDelivr URL for version 7.7.0, and every component is registered for you. You can replace the version with another tag or a commit hash, or use a partial build such as aframe-extras.controls.min.js if you do not need everything.

### How do I use aframe-extras with npm and webpack?

Run npm install --save aframe-extras and then import the whole package or a subpath such as aframe-extras/controls/index.js. You have to compile the JavaScript with something like webpack and define three as an external, and the repository's webpack.config.js is given as an example.

### Why was the kinematic-body component removed?

It was removed in 7.0.0 because using physics for movement is unstable and performs poorly, and the project says to use a navigation mesh instead wherever possible, which is what the nav-mesh and nav-agent components in the pathfinding folder are for. The jump-ability component was removed at the same time because it depended on kinematic-body.

### Do I need another package to use aframe-extras?

Several components and examples rely on aframe-physics-system, which is a separate project. The extras package itself pulls in three at 0.164.0, three-pathfinding at 1.3.0 and nipplejs for the virtual joystick.

## Sources

- [c-frame/aframe-extras on GitHub](https://github.com/c-frame/aframe-extras)
- [License: MIT](https://github.com/c-frame/aframe-extras/blob/master/LICENSE)
- [Project website](https://c-frame.github.io/aframe-extras/examples/)
- [README](https://github.com/c-frame/aframe-extras/blob/master/README.md)
- [Releases](https://github.com/c-frame/aframe-extras/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/c-frame-aframe-extras